TypeScript SDK

The @boxd-sh/sdk package gives you programmatic access to the full boxd API — create and manage machines, run commands in them, stream output, move files, and manage proxies, snapshots, disks, env vars and secrets. It talks to the same API as the CLI, so everything you can do from the terminal you can do from TypeScript. Promise-only, ESM-only. Runs on Node 20+, Bun, and Deno.

Install

npm install @boxd-sh/sdk

bun add @boxd-sh/sdk

Quick start

import { Boxd } from "@boxd-sh/sdk";

const boxd = new Boxd({ apiKey: "bxd_..." });

const machine = await boxd.machines.create({ name: "my-machine" });
await boxd.machines.waitUntilReady(machine.id);

const result = await boxd.machines.exec(machine.id, { command: ["echo", "hello"] });
console.log(result.stdout);

await boxd.machines.delete(machine.id);
await boxd.close();

The client is the only stateful object. Everything else is a namespace of flat methods that return plain data — a Machine is a record of fields, not a handle, and every operation takes the machine id (or name) as its first argument. There are eight namespaces:

Namespace	For
`boxd.machines`	machines, plus `.files`, `.ports`, `.proxies`, `.checkpoints`
`boxd.snapshots`	reusable point-in-time captures
`boxd.disks`	persistent disks
`boxd.env`	environment variables
`boxd.secrets`	secrets (write-only values)
`boxd.orgs`	the organizations you belong to
`boxd.apiKeys`	API keys
`boxd.account`	your identity and cluster defaults

The client

new Boxd();                                        // production
new Boxd({ apiKey: "bxd_..." });
new Boxd({ baseURL: "https://boxd.example.com:9443" }); // any other cluster

baseURL selects the cluster.

Option	Env var	Default
`apiKey`	`BOXD_API_KEY`	—
`token`	`BOXD_TOKEN`	—
`baseURL`	`BOXD_BASE_URL` (or the deprecated `BOXD_API_URL`)	`http://boxd.sh:9443`
`timeout`	—	60000 ms
`maxRetries`	—	2

baseURL accepts an optional scheme that controls TLS:

Value	Transport
`http://host:port`	plaintext
`https://host:port`	TLS
bare `host:port`	TLS, except `localhost` / `127.*`

Failed connections are retried up to maxRetries times with exponential backoff. Timeouts are never retried — the request may already have been applied — and authentication failures are never retried either. Call close() when you’re done, or let the runtime do it:

{
  await using boxd = new Boxd({ apiKey: "bxd_..." });
  await boxd.machines.list();
  // boxd.close() runs at scope exit
}

await using needs Node 20+, Bun, or Deno.

Authentication

new Boxd({ apiKey: "bxd_..." });   // recommended
new Boxd({ token: "..." });        // a token you already hold
new Boxd();                        // BOXD_API_KEY, then BOXD_TOKEN

Credentials are resolved in this order, first match wins:

an explicit token
an explicit apiKey
BOXD_TOKEN
BOXD_API_KEY
automatic, inside a boxd machine (below)

If none of those produce a credential, the first request throws AuthenticationError. Mint a key with boxd auth keys create NAME (see the CLI), in the console, or with boxd.apiKeys.create(). An API key is exchanged for a short-lived session and kept fresh for you. Revoking a key takes effect immediately, so if a key is revoked mid-run the next call fails with AuthenticationError rather than retrying.

Inside a machine

Inside a boxd machine, new Boxd() authenticates automatically — no API key, no configuration:

const boxd = new Boxd();
const mine = await boxd.machines.list();

It also targets the cluster the surrounding machine belongs to, so the same code runs unchanged wherever it is deployed. An explicit baseURL or credential still wins.

Inside a shared machine the SDK can manage the organization’s shared machines, but it cannot read env vars or secrets, and cannot reach machines that are private to another member. Pass an API key for those.

Machines

const machine = await boxd.machines.create({ name: "my-machine" });
const one     = await boxd.machines.get(machine.id);   // id or name
const all     = await boxd.machines.list();            // Machine[]
await boxd.machines.delete(machine.id);

list() returns a plain array. Pass { org: "acme" } for one organization’s machines, or { allContexts: true } for everything you can reach. State:

await boxd.machines.start(id);
await boxd.machines.stop(id);
await boxd.machines.reboot(id);
await boxd.machines.pause(id);        // suspend to RAM — { suspendUs }
await boxd.machines.resume(id);       // { resumeUs }
await boxd.machines.hibernate(id);    // suspend to disk
await boxd.machines.wake(id);

See Suspend & resume for the difference between stop/start (cold) and pause/resume (warm). Everything else:

const fork = await boxd.machines.fork(id, { name: "fork-1" });   // live clone
await boxd.machines.share(id);        // visible to your whole org
await boxd.machines.unshare(id);
await boxd.machines.rename(id, "new-name");            // returns the new name
await boxd.machines.setAutoSuspendTimeout(id, 300);    // seconds; 0 disables
await boxd.machines.setAutoHibernateTimeout(id, 3600);
await boxd.machines.waitUntilReady(id);                // running *and* exec works
await boxd.machines.suggestName();                     // a free, generated name

rename reboots the machine. It is its own call rather than part of an update() for exactly that reason.

create and fork return once the machine is scheduled, not once it is usable. Call waitUntilReady before doing anything that depends on it running — especially before forking it again. It polls for up to 90 seconds by default ({ timeout, pollInterval }, both in milliseconds).

Creating

await boxd.machines.create({
  name: "builder",
  image: "ubuntu:24.04",
  env: { API_URL: "https://example.com" },
  cmd: ["/usr/local/bin/start"],
  restartPolicy: "always",                 // "always" | "never"
  config: {
    vcpu: 2,
    memory: "8G",
    disk: "100G",
    autoSuspendTimeout: 300,               // seconds; 0 disables
    autoDestroyTimeout: 0,
    ssh: true,
    proxies: [{ name: "api", port: 3000 }],
    volumes: [{ diskId: "d_...", mountPath: "/data" }],
  },
});

// In an organization. `shared` makes it visible to every member.
await boxd.machines.create({ org: "acme", shared: true });

// From a snapshot instead of an image.
await boxd.machines.create({ fromSnapshot: "golden", name: "from-golden" });

Every field is optional — create({}) boots the default image at the default size. fork(id, { name, shared, config }) takes the same config; anything you leave out is inherited from the source.

A snapshot restores the machine that was captured, so create({ fromSnapshot }) takes only name, org and config. Passing image, env, cmd, restartPolicy or shared alongside it is a type error — the two ways of creating a machine are separate shapes, and mixing them is rejected before the code runs. Plain JavaScript, which has no compiler to catch it, gets the same refusal at runtime.

Renaming reboots the machine, so it is its own call. Everything else is readable straight off Machine.

The `Machine` record

interface Machine {
  id: string;
  name: string;
  status: MachineStatus;   // "pending" | "starting" | "running" | "suspended" |
                           // "hibernated" | "stopped" | "failed" | "destroyed" | "migrating"
  imageRef: string;        // the image the machine boots
  restartPolicy: string | null;
  createdAt: Date | null;

  resources: {             // the machine's CPU, memory and disk
    vcpu: number;
    memoryBytes: number;
    diskBytes: number;
  };

  org: { id: string; name: string } | null;   // null = your personal quota
  shared: boolean;         // shared with that org, or private to you

  access: {
    sshPort: number | null;  // the port to SSH to; null if it has none yet
    domain: string;          // the domain the machine is addressed under
    url: string;             // the machine's public HTTPS address
  };

  idle: {                  // seconds of inactivity before each action; 0 disables
    suspendAfter: number;
    hibernateAfter: number;
    destroyAfter: number;
  };

  source: MachineSource | null;    // null = booted from an image
  hibernatedAt: Date | null;       // when it went to disk; null = not hibernated
  lastConnectedAt: Date | null;    // null = never connected
  bootTimeMs: number | null;       // how long the last boot took
}

interface MachineSource {
  kind: "fork" | "snapshot";
  name: string;                    // the source machine, or the snapshot name
  version: number | null;          // the snapshot version; a fork has none
  id: string | null;               // the machine or snapshot this came from
}

org is the organization the machine belongs to and is billed to; shared says whether your teammates can see it. A private machine can still be org-billed, so org set with shared: false is normal, not a contradiction — see Organizations. source.id may not resolve if the machine or snapshot it points at was since deleted. A lookup that finds nothing is normal. Every machine status the SDK knows is exported as MACHINE_STATUSES, with isKnownMachineStatus(s) to check one. An unrecognised status is passed through rather than thrown on, so a machine in a newly added state still prints.

Exec

One-shot exec collects the output:

const r = await boxd.machines.exec(id, { command: ["python", "script.py"] });
r.stdout;    // string
r.stderr;    // string
r.exitCode;  // number
r.success;   // boolean — true when the command exited 0

await boxd.machines.exec(id, {
  command: ["sh", "-c", "echo $FOO"],
  env: { FOO: "bar" },
  timeout: 30_000,          // milliseconds
});

An array command is shell-quoted for you; a string is passed through as a shell command line. timeout is in milliseconds and cancels the call — the remote process may keep running. exec also takes tty, cols and rows: under a PTY the terminal layer merges stderr into stdout, so stderr comes back empty and everything lands in stdout. Interactive and PTY sessions use a stream handle, the one stateful object besides the client:

const stream = boxd.machines.streamExec(id, { command: "bash", tty: true });

stream.write("echo hello\n");
for await (const chunk of stream) process.stdout.write(chunk);
const code = await stream.wait();
stream.close();

Without tty, stderr arrives separately on stream.stderr — useful when a tool’s progress goes to stderr and its answer to stdout. With tty, the terminal layer merges the two onto stdout, as terminals do. For TUI apps, pass the initial geometry and forward resizes:

const stream = boxd.machines.streamExec(id, {
  command: "vim",
  tty: true,
  cols: process.stdout.columns,
  rows: process.stdout.rows,
});
process.stdout.on("resize", () =>
  stream.resize(process.stdout.columns, process.stdout.rows),
);

Unset cols/rows fall back to 80×24. resize() on a non-PTY exec is a harmless no-op. Headless one-shots that read stdin (jq, cat, claude -p) hang waiting for input. Pass closeStdin: true to send EOF immediately — or call stream.end() yourself. It is rejected together with tty, where stdin must stay open.

Logs

for await (const chunk of boxd.machines.logs(id)) process.stdout.write(chunk);
for await (const chunk of boxd.machines.logs(id, { follow: true })) { /* ... */ }

follow: true keeps the stream open for new output.

Files

await boxd.machines.files.upload(id, "/app/file.txt", "text content");
await boxd.machines.files.upload(id, "/app/file.bin", new Uint8Array([1, 2, 3]));
await boxd.machines.files.upload(id, "/app/app.py", { fromPath: "local.py" });
const bytes = await boxd.machines.files.download(id, "/app/output.json");

upload returns the number of bytes written; large uploads are chunked for you. download returns a Uint8Array. Paths inside the machine are absolute, or relative to /home/boxd.

Ports

Raw TCP/UDP forwards on a public address — see Port forwarding. Max 3 per machine.

const fwd = await boxd.machines.ports.expose(id, 5432, { protocol: "tcp" });
fwd.dns;          // hostname to connect to
fwd.publicPort;   // port to connect on
fwd.machinePort;  // the port inside the machine
fwd.protocol;     // "tcp" | "udp" | "both"

await boxd.machines.ports.list(id);   // one machine's forwards
await boxd.machines.ports.list();     // every forward you own
await boxd.machines.ports.unexpose(id, 5432);

Re-exposing the same machine port keeps its public port and just updates the protocol; "both" shares one public port across TCP and UDP.

Proxies

HTTPS routes into a machine — see Proxies. The machine argument takes an id or a name, like everywhere else.

await boxd.machines.proxies.create(machine.name, "api", 3000);
const routes = await boxd.machines.proxies.list(machine.name);
routes[0].port;        // number — where traffic actually goes
routes[0].portMode;    // "locked" (you pinned it) | "auto" (detected for you)
routes[0].domain;
routes[0].isDefault;

await boxd.machines.proxies.setPort(machine.name, 3001, { name: "api" });
await boxd.machines.proxies.setPort(machine.name, "auto");   // default route, auto-detected
await boxd.machines.proxies.delete(machine.name, "api");

name and port are both required on create — a named route is always pinned to a port. "auto" is only accepted for a machine’s default route, which is what setPort addresses when you leave name off.

Checkpoints

Per-machine save points, restored in place — see Checkpoints. They are deleted with the machine.

await boxd.machines.checkpoints.create(id, "before-upgrade");   // machine must be running
const points = await boxd.machines.checkpoints.list(id);
points[0].status;      // "pending" | "ready" | "failed"
points[0].available;   // restorable right now
points[0].sizeBytes;
points[0].createdAt;

await boxd.machines.checkpoints.restore(id, "before-upgrade");
await boxd.machines.checkpoints.delete(id, "before-upgrade");

create returns while the capture is still "pending".

Snapshots

Reusable, named captures — see Snapshots. Boot one with machines.create({ fromSnapshot }).

await boxd.snapshots.create(id, "golden");
const snap = await boxd.snapshots.get("golden");
await boxd.snapshots.list();
await boxd.snapshots.delete("golden");

Saving under an existing name adds a version. A Snapshot carries createdAt (the first capture), updatedAt (the most recent one), version, status, sizeBytes, vcpu, memoryBytes and useCount. get, list and delete take an optional { org }.

Disks

const disk = await boxd.disks.create("data", "10G");
await boxd.disks.attach(disk.id, id, "/mnt/data");
await boxd.disks.attach(disk.id, id, "/mnt/data", { readOnly: true });
await boxd.disks.detach(disk.id, id);
await boxd.disks.list();
await boxd.disks.delete(disk.id);

size takes a human string ("10G") or a byte count. A disk is always created writable; read-only is chosen per attachment. A disk can be attached to one machine at a time. status is "creating", "ready" or "destroyed" — it can only be attached once it is "ready". list() also returns each disk’s current attachments. You can mount a disk at create time instead, with config.volumes.

Env vars and secrets

Two namespaces with identical methods — see Env vars & secrets. The difference is what comes back: an env var has a readable value, a secret does not.

await boxd.env.set("API_URL", "https://example.com", { scope: "all" });
await boxd.env.list();       // [{ name, scope, value }]
await boxd.env.delete("API_URL", { scope: "all" });

await boxd.secrets.set("STRIPE_KEY", "sk_live_...", { scope: "private" });
await boxd.secrets.list();   // [{ name, scope }] — no values
await boxd.secrets.delete("STRIPE_KEY", { scope: "private" });

set, delete and move each hand back the server’s confirmation message as a string. Scope decides which machines a value reaches:

Scope	Applies to
`private`	only your own machines in that organization
`shared`	the organization’s shared machines
`all`	every machine in the organization

move changes the scope. It needs from as well as to, because the same name can exist in several scopes at once:

await boxd.secrets.move("STRIPE_KEY", { from: "private", to: "all" });

It is a move between two places, not a field update, so calling it twice fails the second time. Env vars and secrets share one name space per scope, so an existing env var can block a secret moving into that scope, and vice versa. Pass { org: "acme" } to any of these to work in an organization instead of your personal scope.

Organizations

const orgs = await boxd.orgs.list();
orgs[0].slug;        // the org's unique key — pass this wherever a method takes `org`
orgs[0].name;        // display label
orgs[0].isAdmin;
orgs[0].isDefault;   // your default org

API keys

const key = await boxd.apiKeys.create({ name: "ci", org: "acme" });
key.apiKey;      // shown once — store it now
key.expiresAt;   // null = no expiry

await boxd.apiKeys.list();     // id, name, keyPrefix, createdAt, lastUsedAt, expiresAt, org, kind
await boxd.apiKeys.delete(key.id);

Pass expiresIn (seconds) for a key that expires. Every key belongs to exactly one organization: org names it, and omitting org uses your own. kind: "member" (the default) acts as you within that organization; kind: "org" is limited to the organization’s shared machines and requires an org admin to create.

create is the only time the raw key is returned. list shows the prefix only. Deleting a key takes effect immediately.

Account

const me = await boxd.account.get();
me.userId;
me.displayName;           // null falls back to userId
me.sshKeyFingerprints;
me.billing.maxVms;              // your effective quota
me.billing.subscriptionStatus;  // null = never subscribed

await boxd.account.linkSshKey({ pubkey: "ssh-ed25519 AAAA..." });

const cfg = await boxd.account.config();
cfg.defaultImage;
cfg.zone;

linkSshKey takes the verbatim contents of a .pub file and lets you SSH to your machines with it. Pass deviceId to keep one key per device — re-linking from the same device replaces that device’s key instead of accumulating stale ones.

Errors

import { NotFoundError } from "@boxd-sh/sdk";

try {
  await boxd.machines.get("nope");
} catch (e) {
  if (e instanceof NotFoundError) { /* ... */ }
}

Everything thrown extends BoxdError:

Class	Meaning
`AuthenticationError`	the credential was rejected, or none was found
`PermissionDeniedError`	authenticated, but not allowed
`NotFoundError`	no such resource
`ConflictError`	already exists, or the resource is in the wrong state
`RateLimitError`	quota or rate limit reached
`APIStatusError`	any other error returned by the server
`APIConnectionError`	the request never reached the server

Every error carries grpcCode, the numeric status code, for finer-grained handling:

import { BoxdError } from "@boxd-sh/sdk";

try {
  await boxd.machines.create({ name: "my-machine" });
} catch (e) {
  if (e instanceof BoxdError && e.grpcCode === 8 /* RESOURCE_EXHAUSTED */) {
    // hit your quota — surface a 'wait or upgrade' path
  }
  throw e;
}

Update notifications

The SDK prints a one-time console.warn on stderr when a newer release is available:

A new version of @boxd-sh/sdk is available (v0.2.0, you have v0.1.9). Update with:
  npm install @boxd-sh/sdk@latest

It fires at most once per process and never causes a request to fail. The installed version is also exported:

import { VERSION } from "@boxd-sh/sdk";

Getting started

Cloud dev boxes

Preview environments

Agents on boxd

Organizations

Integrations

How it works

Reference

TypeScript SDK

Install

Quick start

The client

Authentication

Inside a machine

Machines

Creating

The `Machine` record

Exec

Logs

Files

Ports

Proxies

Checkpoints

Snapshots

Disks

Env vars and secrets

Organizations

API keys

Account

Errors

Update notifications

Reference

CLI

Python SDK

​Install

​Quick start

​The client

​Authentication

​Inside a machine

​Machines

​Creating

​The Machine record

​Exec

​Logs

​Files

​Ports

​Proxies

​Checkpoints

​Snapshots

​Disks

​Env vars and secrets

​Organizations

​API keys

​Account

​Errors

​Update notifications

​Reference

CLI

Python SDK

Install

Quick start

The client

Authentication

Inside a machine

Machines

Creating

The `Machine` record

Exec

Logs

Files

Ports

Proxies

Checkpoints

Snapshots

Disks

Env vars and secrets

Organizations

API keys

Account

Errors

Update notifications

Reference