API Reference

The complete public surface of @nodeops-createos/sandbox, organized by what you hold and what you call. Everything documented here is exported from the package root; anything not re-exported is internal and may change without notice.

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

The two-object model

The SDK has two stateful objects and three catalog sub-APIs:

• CreateosSandboxClient: the client object. Create it once with createClient(...), passing a base URL and API key. It resolves the catalog (shapes, rootfs, hosts), identity (whoami), creates and looks up sandboxes, and exposes the templates / networks / disks sub-APIs.
• Sandbox: the handle returned by the client. It owns one sandbox id; every per-sandbox operation (run commands, move files, pause / fork / destroy, ingress, attach disks and networks) is a method on it. File operations are available via sandbox.files.

A Sandbox holds a reference to the transport, never the client. You can create a handle to an existing sandbox with client.getSandbox(id) and keep using it after the original client goes out of scope.

TypeScript
Copy
1import { createClient } from "@nodeops-createos/sandbox";
2
3const client = createClient(); // reads CREATEOS_SANDBOX_BASE_URL + CREATEOS_SANDBOX_API_KEY
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}

Pages

Conventions

• ESM-only, zero runtime dependencies. The SDK is a hand-written fetch client. It runs on Node 20+, Bun, Deno, Cloudflare Workers, Vercel Edge, and the browser.
• Optional fields use ?, not | null. When the server omits a field (omitempty), the key is absent rather than null.
• List endpoints are paginated. Client list methods fetch every page for you; the iterate* variants are async generators. The server clamps the page size to 500.
• Sandboxes bill while running. Every example tears down in try { … } finally { await sandbox.destroy(); }. Do the same in your code, or set idle auto-pause via setAutoPause.

See also

• Quickstart: install, authenticate, first sandbox
• How-to guides: task-oriented recipes
• Explanation: the microVM model, lifecycle, and reliability