TypeScript SDK

npm install @boxd-sh/sdk
# or: bun add @boxd-sh/sdk

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

const c = new Compute({ apiKey: "bxk_..." });

const box = await c.box.create({ name: "my-vm" });
const result = await box.exec(["echo", "hello"]);
console.log(result.stdout);

await box.destroy();
await c.close();

new Compute({ apiKey: "bxk_..." });        // API key (recommended)
new Compute({ token: "eyJ..." });          // direct JWT
new Compute();                             // reads BOXD_API_KEY or BOXD_TOKEN

new Compute({
  apiKey: "bxk_...",
  apiUrl: "http://my-boxd.example.com:9443",
  exchangeUrl: "https://my-boxd.example.com/api/v1/auth/token",
});

const box = await c.box.create({ name: "my-vm" });
const boxes = await c.box.list();
const found = await c.box.get("my-vm");                   // by name or id
const forked = await c.box.fork("my-vm", { name: "f1" });

await box.start();
await box.stop();
await box.reboot();
await box.destroy();
const s = await box.suspend();   // { suspendUs }
const r = await box.resume();    // { resumeUs }

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

const config: BoxConfig = {
  vcpu: 2,                                 // default 2
  memory: "4G",                            // default "8G"
  env: { API_KEY: "secret" },              // env vars exposed to the VM
  restartPolicy: "always",                 // "always" | "never"
  lifecycle: {
    autoSuspendTimeout: 300,               // idle network secs; 0 disables
    autoDestroyTimeout: 0,                 // total lifetime secs; 0 disables
  },
};

const box = await c.box.create({ name: "my-vm", config });

// Simple — collect all output
const r = await box.exec(["python", "script.py"]);
r.stdout;     // string (subprocess fd 1)
r.stderr;     // string (subprocess fd 2)
r.exitCode;   // number
r.success;    // boolean

// With env vars and timeout
await box.exec(["sh", "-c", "echo $FOO"], {
  env: { FOO: "bar" },
  timeoutMs: 30_000,
});

// Streaming — proc.stdout and proc.stderr are separate AsyncIterables
const proc = await box.exec(["cargo", "build"], { stream: true });
for await (const chunk of proc.stdout) process.stdout.write(chunk);
// (read proc.stderr concurrently if you need warnings live, e.g. via Promise.all)
const code = await proc.wait();

// Headless one-shot — close stdin immediately so commands like
// `claude -p`, `jq`, `cat` see EOF and don't hang waiting for input.
const r2 = await box.exec(
  ["claude", "-p", "summarize this PR"],
  { stream: true, closeStdin: true },
);

// Interactive (PTY + stdin) — stdin must stay open for user input.
// `closeStdin: true` is REJECTED with this combination (throws).
const sh = await box.exec(["bash"], { stream: true, pty: true });
sh.stdin.write("echo hello\n");
await sh.stdin.end();

const proc = await box.exec(["claude"], {
  stream: true,
  pty: true,
  cols: process.stdout.columns,
  rows: process.stdout.rows,
});

// Forward local SIGWINCH so resize propagates into the VM's PTY.
process.stdout.on("resize", () => {
  proc.resize(process.stdout.columns, process.stdout.rows);
});

// Forward raw bytes both directions; the local terminal renders ANSI.
process.stdin.setRawMode?.(true);
process.stdin.on("data", (d) => proc.stdin.write(d));
for await (const chunk of proc.stdout) process.stdout.write(chunk);

await box.writeFile("/app/file.txt", "text content");
await box.writeFile("/app/file.bin", new Uint8Array([1, 2, 3]));
await box.writeFile("/app/file.py", { fromPath: "local.py" });    // Node/Bun only
const data = await box.readFile("/app/output.json");              // Uint8Array

await box.proxies();                              // Proxy[]
await box.createProxy("api", 3001);               // api.<vm>.boxd.sh -> port 3001
await box.setProxyPort(3000);                     // change default proxy port
await box.setProxyPort(3001, { name: "api" });    // change a named proxy
await box.deleteProxy("api");

// Snapshot of available console output
for await (const chunk of box.streamLogs()) {
  process.stdout.write(chunk);
}

// Follow (keeps the stream open for new chunks)
for await (const chunk of box.streamLogs({ follow: true })) {
  process.stdout.write(chunk);
}

const t = await c.template.create({
  name: "t1",
  image: "ghcr.io/org/img:tag",
  config: { vcpu: 2, memory: "4G" },
});
await c.template.list();

// createVm accepts a Template object OR a template ID string. Pass an
// optional `config` to override the template's defaults (e.g. bump memory
// for one specific VM).
const box = await c.template.createVm({ template: t, name: "from-t" });
const big = await c.template.createVm({
  template: t.id,
  name: "from-t-big",
  config: { memory: "16G" },
});
await c.template.delete(t.id);

const d = await c.disk.create("data", "10G");
d.id; d.name; d.sizeBytes; d.status;

// attach / detach take a Box instance OR a name/id string
await d.attach(box, "/mnt/data");
await d.attach("my-vm", "/mnt/data", { readOnly: true });
await d.detach("my-vm");

await d.destroy();

// list returns DiskHandle[] — same methods as above
for (const d of await c.disk.list()) {
  console.log(d.name, d.status);
}

await c.domain.bind("app.example.com", box);            // accepts Box, name, or id
await c.domain.bind("app.example.com", "my-vm");
await c.domain.list();                                   // [{ domain, vmId }]
await c.domain.unbind("app.example.com");

const n = await c.network.create();              // server assigns id
const named = await c.network.create("staging");

// `create` returns the new network's id only — `subnet` and `status` come
// back populated once provisioning settles. Re-fetch via `list` to read them.
for (const net of await c.network.list()) {
  console.log(net.id, net.subnet, net.status);
}

const t = await c.token.create(3600);                    // TTL in seconds; 0 = server default
t.token;          // "eyJ..." — save this; list() will not return it
t.expiresAt;      // unix seconds

for (const info of await c.token.list()) {
  console.log(info.jti, info.createdAt, info.expiresAt);
}
await c.token.revoke(info.jti);

// Use the token to authenticate a new client
const c2 = new Compute({ token: t.token });

const me = await c.whoami();
me.userId;              // "gh-username"
me.fingerprints;        // ["SHA256:..."]
me.defaultNetworkId;    // "net-..."

const cfg = await c.config();
cfg.defaultImage;       // "ubuntu:latest"
cfg.zone;               // "boxd.sh"

import { VERSION } from "@boxd-sh/sdk";
console.log("on", VERSION);

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

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

try {
  await c.box.create({ name: "my-vm" });
} catch (e) {
  if (e instanceof BoxdError && e.grpcCode === 8 /* RESOURCE_EXHAUSTED */) {
    // hit per-user quota — e.g. surface a 'wait or upgrade' UI
  }
  throw e;
}

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

{
  await using c = new Compute({ apiKey: "bxk_..." });
  const box = await c.box.create({ name: "job-vm" });
  try {
    await box.exec(["./run.sh"]);
  } finally {
    await box.destroy();
  }
  // c.close() called automatically at scope exit
}