Quickstart

The 30-second tour: install, authenticate, spawn a sandbox, run a command, and tear it down. For a full guided lesson, see the tutorial; for the conceptual picture, start with what a VM sandbox is.

At a glance

Package: @nodeops-createos/sandbox (npm)
Import: import { createClient } from "@nodeops-createos/sandbox"
Base URL: https://api.sb.createos.sh (override with CREATEOS_SANDBOX_BASE_URL)
Auth: API key via the apiKey option or CREATEOS_SANDBOX_API_KEY

1. Install

Shell
1bun add @nodeops-createos/sandbox
2# or: npm install @nodeops-createos/sandbox

The SDK is ESM-only with zero runtime dependencies. It runs on Node 20+, Bun, Deno, Cloudflare Workers, Vercel Edge, and the browser.

2. Get an API key

Provision a key through your createos-sandbox control plane (your operator's identity portal or CLI). The key is per-user; treat it like a database password and keep it out of source control.

The client targets the production control plane by default; set baseUrl (or CREATEOS_SANDBOX_BASE_URL) only to point at a different one. Give it an API key. The simplest path is two environment variables:

Shell
1export CREATEOS_SANDBOX_BASE_URL="https://api.sb.createos.sh"
2export CREATEOS_SANDBOX_API_KEY="sk_…"

TypeScript
1import { createClient } from "@nodeops-createos/sandbox";
2
3const client = createClient(); // reads CREATEOS_SANDBOX_BASE_URL + CREATEOS_SANDBOX_API_KEY
4// or pass them explicitly:
5// createClient({ baseUrl: "https://…", apiKey: "sk_…" });

Confirm the key works before going further:

TypeScript
1console.log(await client.whoami());

4. Spawn a sandbox

TypeScript
1const sandbox = await client.createSandbox({
2  shape: "s-4vcpu-4gb",
3  rootfs: "devbox:1",
4});
5console.log("ready:", sandbox.id, sandbox.status);

createSandbox blocks until the sandbox is running by default. Pass { wait: false } to return as soon as the row exists and poll yourself with waitUntilRunning. Pick a shape from client.listShapes() and a rootfs from client.listRootfs().

5. Run a command

TypeScript
1const result = await sandbox.runCommand("uname", ["-a"]);
2console.log(result.result.stdout);

runCommand buffers stdout/stderr and resolves when the command exits. For long-running commands, stream the output. See How-to: streaming.

6. Tear down

TypeScript
1await sandbox.destroy();

destroy is asynchronous on the server; call sandbox.waitUntilDestroyed() if you need the row reclaimed before continuing.

Put it together

Sandboxes bill while they run, so wrap the work in try / finally and always destroy:

TypeScript
1import { createClient } from "@nodeops-createos/sandbox";
2
3const client = createClient();
4const sandbox = await client.createSandbox({ shape: "s-4vcpu-4gb", rootfs: "devbox:1" });
5try {
6  const out = await sandbox.runCommand("uname", ["-a"]);
7  console.log(out.result.stdout);
8} finally {
9  await sandbox.destroy();
10}

Cost control. A sandbox you forget to destroy keeps billing. Either tear it down in finally, or set an idle auto-pause so it stops billing on its own: createSandbox({ …, auto_pause_after_seconds: 300 }). See How-to: lifecycle.

Troubleshooting

CreateosSandboxAuthError on the first call: the API key is missing or wrong. Verify with await client.whoami().
CreateosSandboxConnectionError: the control plane is unreachable. Check CREATEOS_SANDBOX_BASE_URL and any corporate proxy or firewall.
CreateosSandboxTimeoutError from createSandbox: the sandbox never reached running before the wait budget elapsed. Increase waitTimeoutMs, or pass { wait: false } and poll yourself.
CreateosSandboxServerError with status 503: the host pool is saturated. The SDK already retried with backoff; try again after the suggested Retry-After window. See reliability.

Next steps

Tutorial: build an AI app generator: the full guided lesson
How-to guides: task-oriented recipes
API reference: every class, method, and type
Explanation: the VM model, lifecycle, and reliability
Examples: runnable, copy-pasteable end-to-end programs