SDKs

TypeScript

npm install quivvo-sdk

import { Quivvo } from "quivvo-sdk";

const q = new Quivvo(); // reads QUIVVO_API_KEY

const m = await q.machines.create({ name: "dev" });
const r = await m.exec("uname -a");
console.log(r.exit_code, r.stdout);

for await (const ev of q.machines.execStream("dev", "npm test")) {
  if (ev.event === "stdout") process.stdout.write(ev.data);
}

await q.machines.suspend("dev");

It uses only fetch, so it runs on Node.js 18 or later, Bun, Deno and edge runtimes. Every method takes { signal, timeoutMs, maxRetries } last.

Python

pip install quivvo

from quivvo import Quivvo

q = Quivvo()  # reads QUIVVO_API_KEY

m = q.machines.create(name="dev")
r = m.exec("uname -a")
print(r["exit_code"], r["stdout"])

for ev in q.machines.exec_stream("dev", "npm test"):
    if ev["event"] == "stdout":
        print(ev["data"], end="")

q.machines.suspend("dev")

It needs Python 3.9 or later and uses only the standard library.

What do they cover?

Everything a key can do over the API: machines and their lifecycle, commands (waiting for the result or streaming it), background jobs and their logs, files, ports, snapshots, forks and restores, keys, webhooks, usage, whoami and the catalog. Device sign-in isn't in them: get a key with quivvo login or from API keys, and pass it as apiKey / api_key or set QUIVVO_API_KEY.

How do errors work?

An error the API sends raises QuivvoError, with the same fields as the error object: code, message, retryable, the seconds to wait, docs_url, request_id and owner_action. Branch on code. A request that got no answer raises QuivvoNetworkError, which says whether the request may have reached the server, so you know whether repeating it is safe.

A command that exits non-zero isn't an error: read its exit code. A command is only sent again when the API says it didn't run.