TypeScript SDK

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

const boxd = new Boxd({ apiKey: "bxd_..." });
const machine = await boxd.machines.create({ name: "myapp" });

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

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

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

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

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

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

const machine = await boxd.machines.create({ name: "myapp" });
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();

const machine = await boxd.machines.create({ name: "myapp" });
const one     = await boxd.machines.get(machine.id);   // id or name
const all     = await boxd.machines.list();            // Machine[]
await boxd.machines.delete(machine.id);
await boxd.machines.deleteSelf({ confirm: "myapp" }); // inside a machine: delete the machine this code runs on

await boxd.machines.start(id);
await boxd.machines.stop(id);
await boxd.machines.reboot(id);
await boxd.machines.pause(id);        // standby, in RAM: { suspendUs }
await boxd.machines.resume(id);       // { resumeUs }
await boxd.machines.hibernate(id);    // hibernated, on disk
await boxd.machines.wake(id);

const fork = await boxd.machines.fork(id, { name: "myapp2" });   // live copy of memory and disk
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.setNetworks(id, ["backend"]);      // replaces the whole set
await boxd.machines.setAutoSuspendTimeout(id, 300);    // seconds, 0 disables (the default)
await boxd.machines.setAutoHibernateTimeout(id, 3600);
await boxd.machines.setBotProtection(id, false);       // on by default, see Bot protection
await boxd.machines.setSsh(id, false);                 // nothing answers SSH; exec still works, see SSH below
await boxd.machines.setDeleteAfter(id, 7200);          // delete 2 h from now; resolves to the deadline, see Delete after
await boxd.machines.setDeleteAfterCron(id, "0 18 * * *"); // or at the next 18:00 UTC
await boxd.machines.setDeleteAfter(id, 0);             // clear the timer; resolves to null
for await (const chunk of boxd.machines.logs(id)) {}   // console output (Uint8Array); { follow: true } keeps it open
await boxd.machines.waitUntilReady(id);                // running and exec works
await boxd.machines.suggestName();                     // a free, generated name

await boxd.machines.create({
  name: "myapp",
  image: "ubuntu:24.04",
  env: { API_URL: "https://example.com" },
  cmd: ["/usr/local/bin/start"],
  restartPolicy: "always",                 // "always" | "never"
  networks: ["backend", "cache"],          // machine-to-machine reachability, see Networks
  isolated: false,                         // sandbox, fixed at creation
  deleteAfter: 3600,                       // delete-after timer: seconds from now...
  // deleteAfterCron: "0 18 * * *",        // ...or the next match of a cron expression (UTC)
  config: {
    vcpu: 2,
    memory: "8G",
    autoSuspendTimeout: 300,               // seconds, 0 disables
    autoDestroyTimeout: 0,
    ssh: true,                             // false: nothing answers SSH; leave out for on, or a fork's or snapshot's setting
    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 });

// Create a machine from a snapshot.
await boxd.machines.create({ fromSnapshot: "my-workspace", name: "myapp2" });

// Create a machine from a machine spec. See Machine specs below.
await boxd.machines.create({ name: "mike-dev", org: "acme", spec: Machine.spec().size("2x8").network("eng") });

await boxd.machines.resize(id, { memory: "16G" });   // or { vcpu: 4 }, returns { vcpu, memoryBytes, rebooted }

import { Machine, team, snapshot, github, slack, jira, claude, secrets } from "@boxd-sh/sdk";

const engineering = Machine.spec()
  .from(team("eng"))                     // a team's default snapshot; or snapshot("eng-base")
  .network("eng")
  .label("team", "eng")
  .env("NODE_ENV", "development")
  .packages("apt-get update", "apt-get install -y nginx")
  .with(github({ shared: "eng-bot" }), claude());

const mike = engineering
  .size("2x8")
  .with(slack(), jira({ shared: "jira" }), secrets("NPM_TOKEN"));
const m = await boxd.machines.create({ name: "mike-dev", org: "acme", spec: mike });
m.spec;          // the spec as it stands (updateSpec, and label, network, egress and size edits, change it)
m.createdSpec;   // the spec it was created with, never changed
mike.resolve();  // the same spec as plain data, without creating anything

// Patch: a field left out is untouched, a scalar replaces, maps merge key by
// key (null removes a key), a list replaces the whole list, null removes a field.
await boxd.machines.updateSpec("mike-dev", {
  labels: { owner: "mike", team: null },
  networks: ["eng", "ops"],
  packages: ["apt-get install -y nginx", "npm i -g pnpm"],
});

// Builder: reads the spec, adds with the composition rules, sends the difference.
await boxd.machines.updateSpec("mike-dev", (s) => s.network("ops").env("LOG_LEVEL", "debug"));

// Dry run: the diff, nothing changed.
const diff = await boxd.machines.updateSpec("mike-dev", { size: "4x16" }, { dryRun: true });
for (const c of diff.changes) console.log(c.field, c.apply, c.note, c.warnings);
if (diff.rebootRequired) {
  await boxd.machines.updateSpec("mike-dev", { size: "4x16" }, { reboot: true });
}

// Run the packages again from the one that failed.
await boxd.machines.updateSpec("mike-dev", {}, { retryPackages: true });

// A patch built from a spec you read: nothing applies if the spec changed since.
const { spec } = await boxd.machines.get("mike-dev");
if (spec) {
  await boxd.machines.updateSpec("mike-dev", { networks: [...(spec.networks ?? []), "ci"] }, { expectedSpec: spec });
}

interface MachineSpecUpdate {
  changes: MachineSpecChange[];  // every changed field, in the spec's order
  rebootRequired: boolean;       // a change applies only through a reboot
  rebootRecommended: boolean;    // a change reaches running processes only once they restart
  spec: MachineSpec;             // the spec after the patch (for a dry run, what it would be)
  applied: boolean;              // false for a dry run
  rebooted: boolean;             // the machine was rebooted to apply it
  resizeError: string | null;    // the resize failed after the rest applied (below)
}

interface MachineSpecChange {
  field: string;                 // "labels", "size", "packages", ...
  apply: "live" | "reboot_recommended" | "reboot" | "refused";
  added: string[];               // map keys, list entries or commands added
  removed: string[];
  changed: string[];             // map keys whose value changes (values are never shown)
  before: string | null;         // scalars (size, base, assignTo, isolated)
  after: string | null;
  note: string;                  // what happens on the machine, in one sentence
  warnings: string[];            // what the change won't do
}

await boxd.machines.setNetworks(id, ["backend", "cache"]);  // returns the set now in effect
await boxd.machines.setNetworks(id, []);                    // back to the default network
const { networks, isolated } = (await boxd.machines.get(id)).networking;

await boxd.machines.setEgressAllow(id, ["api.stripe.com", "*.github.com", "203.0.113.0/24"]);
(await boxd.machines.get(id)).egressAllow;    // string[]: empty = unrestricted
await boxd.machines.setEgressAllow(id, ["none"]); // nothing is reachable
await boxd.machines.setEgressAllow(id, []);   // unrestricted again

await boxd.machines.create({ name: "task-1", config: { ssh: false } }); // born with SSH off
await boxd.machines.setSsh(id, true);         // back on, same port
(await boxd.machines.get(id)).ssh;            // boolean

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;     // always the fixed 100 GB allocation, not usage
  };

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

  networking: {            // who it can reach inside the org: see Networks
    networks: string[];    // empty = the org's default network
    isolated: boolean;     // set at creation, a fork always inherits it
  };

  egressAllow: string[];   // the egress allowlist, empty = unrestricted

  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
    desktopUrl: string;      // its live Desktop view in the console
    customDomains: CustomDomain[];   // custom domains bound to this machine
  };

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

  botProtection: boolean;  // browser check before an HTTPS request wakes it, on by default
  ssh: boolean;            // SSH answers on access.sshPort, on by default

  source: MachineSource | null;    // null = booted from an image
  hibernatedAt: Date | null;       // when it went to disk, null = not hibernated
  deleteAt: Date | null;           // when the delete-after timer deletes it, null = no timer
  deleteAfterCron: string | null;  // the cron expression it was set with, if any
  lastConnectedAt: Date | null;    // null = never connected
  bootTimeMs: number | null;       // how long the last boot took

  spec: MachineSpec | null;        // the machine spec it runs under, null = none
  createdSpec: MachineSpec | null; // the spec it was created with
  createdBy: string | null;        // who created it for you (spec assignTo), null = you did
  createdByName: string | null;    // a name to show for createdBy
  requirements: MachineRequirement[]; // the spec's connections and agents, and whether each is met
  packages: MachinePackage[];      // the spec's packages and how each went
}

interface MachineRequirement {
  kind: "connection" | "agent";
  name: string;                    // integration ("slack", "github-app") or agent ("claude", "codex")
  scope: "personal" | "shared";
  tag: string | null;              // the shared connection's name
  met: boolean;                    // connected now
  canFix: boolean;                 // you could connect it
  reason: string | null;           // why this machine can't get it (isolated, shared, ...)
}

interface MachinePackage {
  command: string;
  state: "pending" | "running" | "done" | "failed" | "skipped";
  exitCode: number | null;         // null until it exits, and for a timeout or an interrupted run
  outputTail: string;              // the last 4 KiB of its output; empty from list(), get() has it
  reason: string | null;           // why there is no exit code, or that a restored snapshot ran it
  startedAt: Date | null;
  finishedAt: Date | null;
}

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
}

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
});

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();

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),
);

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");

const listing = await boxd.machines.files.listDir(id, "/home/boxd");   // DirListing
for (const e of listing.entries) e.name, e.isDir, e.sizeBytes, e.permissions, e.modifiedAt;
listing.truncated;                                                       // true past 5,000 entries

await boxd.machines.files.mkdir(id, "/home/boxd/assets");               // the parent must exist
await boxd.machines.files.rename(id, "/home/boxd/a", "/home/boxd/b");
await boxd.machines.files.copy(id, "/home/boxd/src", "/home/boxd/src-copy");   // recursive
await boxd.machines.files.delete(id, "/home/boxd/src-copy");                    // recursive

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);

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");

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");

const backupId = await boxd.machines.backups.trigger(id);   // back up now, returns the new backup id

await boxd.machines.backups.setSchedule(id, { intervalSecs: 86400, retentionSecs: 30 * 86400 });
// or a wall-clock cron schedule instead of a fixed interval:
await boxd.machines.backups.setSchedule(id, { cron: "0 3 * * *", retentionSecs: 30 * 86400 });

const schedule = await boxd.machines.backups.schedule(id);   // null when there's no schedule

const list = await boxd.machines.backups.list(id);
list[0].status;      // "pending" | "ready" | "dedup" | "failed"
list[0].sizeBytes;
list[0].createdAt;

await boxd.machines.backups.restore(id, list[0].id);   // destructive, in-place
await boxd.machines.backups.delete(id, list[0].id);
await boxd.machines.backups.clearSchedule(id);

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

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);

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, domains, boundMachines }]: no values
await boxd.secrets.delete("STRIPE_KEY", { scope: "private" });

await boxd.secrets.set("NPM_TOKEN", "npm_...", { scope: "unattached", org: "acme" });
const m = await boxd.machines.create({ name: "mike-dev", org: "acme", spec: Machine.spec().with(secrets("NPM_TOKEN")) });

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

await boxd.secrets.set("STRIPE_KEY", "sk_live_...", { scope: "all", domains: ["api.stripe.com"] });
(await boxd.secrets.list())[0].domains;   // string[]: empty = a plain secret

await boxd.machines.setEgressAllow(id, ["api.stripe.com", "*.npmjs.org", "203.0.113.0/24"]);
(await boxd.machines.get(id)).egressAllow;   // string[], empty = unrestricted
await boxd.machines.setEgressAllow(id, ["none"]); // an allowlist with nothing in it: nothing is reachable
await boxd.machines.setEgressAllow(id, []);

await boxd.secrets.set("STRIPE_KEY", "sk_live_...", { scope: "all", domains: ["api.stripe.com"] });
await boxd.secrets.list();   // [{ name, scope, domains, boundMachines }]

const domain = await boxd.domains.create({ domain: "app.example.com", machine: machine.id });
domain.status;      // "pending" | "active"
domain.lastError;   // empty once active

await boxd.domains.list();
await boxd.domains.delete("app.example.com");

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

const org = await boxd.orgs.create("Acme");    // you become its owner, interactive login only
await boxd.orgs.rename("Acme Labs", "acme");

const roster = await boxd.orgs.getMembers("acme");
roster.members[0].userId, roster.members[0].role;         // "owner" | "admin" | "member"
roster.members[0].displayName, roster.members[0].githubUsername;
roster.invites[0].email, roster.invites[0].role, roster.invites[0].expiresAt;
roster.invites[0].acceptUrl;                              // interactive login only, empty otherwise

const invite = await boxd.orgs.invite("alice@example.com", { role: "member", org: "acme" });
await boxd.orgs.revokeInvite(invite.token);
await boxd.orgs.setMemberRole("usr_...", "admin", "acme");   // or "member" to demote
await boxd.orgs.removeMember("usr_...", "acme");

await boxd.orgs.setMachineDefaults("acme", { vcpu: 2 });   // or { memory: "8G" }
const d = await boxd.orgs.getMachineDefaults("acme");
d.isSet, d.vcpu, d.memoryBytes, d.ceilingVcpu, d.ceilingMemoryBytes;
await boxd.orgs.clearMachineDefaults("acme");

const l = await boxd.orgs.getMachineLimit("acme");
l.maxVms, l.vmCount, l.isOwner;
l.request;                    // MachineLimitRequest | null: .requestedAt, .maxVms
const r = await boxd.orgs.requestMachineLimit(100, { message: "CI runners", org: "acme" });
r.requestedAt, r.maxVms;

const domain = await boxd.orgs.setDomain("acme", "preview.mysaas.com");   // call only once NS delegation is live
domain.status;    // "pending" | "active"

await boxd.orgs.getDomain("acme");     // null if unset
await boxd.orgs.clearDomain("acme");

const team = await boxd.teams.create("backend", "acme");   // org admin only
await boxd.teams.list("acme");                             // every team for an admin, your own otherwise
const t = await boxd.teams.get(team.id);
t.name, t.orgId, t.isAdmin;                                // isAdmin: you have team-admin authority
t.members[0].userId, t.members[0].role;                    // "admin" | "member"
t.defaultSnapshotId;                                       // null = none

await boxd.teams.addMember(team.id, "usr_...");            // must already be an org member
await boxd.teams.setMemberRole(team.id, "usr_...", "admin");
await boxd.teams.removeMember(team.id, "usr_...");
await boxd.teams.setDefaultSnapshot(team.id, snapshot.id); // a shared snapshot of the org
await boxd.teams.setDefaultSnapshot(team.id, null);        // clear
await boxd.teams.rename(team.id, "platform");
await boxd.teams.delete(team.id);

// One machine over its whole life, or pass { since, until } (Date or unix seconds).
// A deleted machine is found by its id or name ({ org } says where to look).
const u = await boxd.machines.usage("myapp");
u.seconds.running; u.seconds.standby; u.seconds.hibernated; u.seconds.stopped;
u.costMicro / 1e6;   // estimated cost, in u.currency ("eur" | "usd")
u.complete;          // true once all its usage is metered (see below)
u.period.start; u.period.end;
u.vcpuHours; u.ramGibHours; u.diskGibHours;   // what the cost is priced on
u.rates;             // ...at these rates, per unit-hour

// Every machine in an org, most expensive first. Default: the last 28 days.
const r = await boxd.orgs.usage({ since: new Date("2026-09-01") });
r.totalCostMicro; r.currency;
for (const m of r.machines) console.log(m.name, m.status, m.costMicro / 1e6);

// Billing activity: what was actually charged, newest first.
for await (const e of boxd.orgs.billingActivity({ since: new Date("2026-09-01") })) {
  console.log(e.createdAt, e.kind, e.amountMicro / 1e6);   // charges are negative
}

await boxd.machines.delete(id);
// ...a little later, or from a periodic job:
const u = await boxd.machines.usage(id);
if (u.complete) save(id, u.costMicro, u.currency);   // otherwise try again later

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, createdBy, mine
await boxd.apiKeys.delete(key.id);

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;

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

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

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

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