@nodeops-createos/sandbox

TypeScript SDK for CreateOS Sandbox — launch isolated sandboxes, run commands, move files, expose services, and manage disks and networks. createSandbox() returns a stateful Sandbox handle, errors are a typed hierarchy, and the transport retries transient failures automatically.

Zero runtime dependencies. ESM-only. Runs on Node 20+, Bun, Deno, Cloudflare Workers, Vercel Edge, and the browser.

Install

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

Requires Node 20+ (or any runtime with global fetch, ReadableStream, and AbortSignal.any — Bun, Deno, modern edge runtimes).

Quick start

Run untrusted, model-generated Python with a network allowlist, a timeout, and guaranteed cleanup:

import { CreateosSandboxClient } from "@nodeops-createos/sandbox";

// baseUrl from CREATEOS_SANDBOX_BASE_URL, apiKey from CREATEOS_SANDBOX_API_KEY
const client = new CreateosSandboxClient();

const sandbox = await client.createSandbox({
  shape: "s-1vcpu-1gb",
  rootfs: "devbox:1",
  // Egress allowlist: the sandbox reaches PyPI and nothing else.
  egress: ["pypi.org:443", "*.pythonhosted.org:443"],
});

try {
  await sandbox.files.upload("/tmp/script.py", "print(sum(range(10)))\n");

  const { result } = await sandbox.runCommand("python3", ["/tmp/script.py"], {
    timeoutMs: 300_000, // 5 minutes, then the request aborts
  });

  console.log(result.stdout, result.exit_code); // "45\n" 0
} finally {
  await sandbox.destroy(); // always tear down — sandboxes bill while running
}

Omit egress (or pass ["*"]) to allow all outbound traffic. For a sandbox that outlives one command — a dev server, a session an agent returns to — let it pause itself when idle instead of destroying it:

const sandbox = await client.createSandbox({
  shape: "s-1vcpu-1gb",
  rootfs: "devbox:1",
  auto_pause_after_seconds: 300, // idle 5 min → paused, disk + memory preserved
});

// ...later, from anywhere:
await sandbox.resume(); // back to running, processes intact

baseUrl defaults to the production CreateOS Sandbox API; override it via the constructor or CREATEOS_SANDBOX_BASE_URL. createSandbox blocks until the sandbox reaches running. Shapes, quotas, and concurrency caps are listed in Concepts.

Documentation

Full docs follow the Diátaxis framework and live under docs/:

• Quickstart — install, authenticate, first sandbox
• Tutorial — build an AI app generator end to end
• How-to guides — files, lifecycle, services, disks, streaming, errors, observability
• API reference — every class, method, and type
• Explanation — the sandbox model, the handle model, lifecycle, reliability
• Examples — runnable programs, one per directory under examples/

For AI agents and tools: the machine-readable index is llms.txt and the full corpus is bundled in llms-full.txt (llmstxt.org).

About CreateOS

CreateOS is the execution and governance platform for production AI agents and apps. This SDK exposes CreateOS Sandbox for agent runtimes, code execution, preview services, persistent disks, and networked sandbox workflows.

For product updates and engineering notes, read the CreateOS Sandbox docs and blog.

Key facts

• Zero runtime dependencies, ESM-only — a hand-written fetch client.
• Typed errors — a CreateosSandboxError hierarchy with HTTP status → class mapping. See errors.
• Automatic retries — idempotent requests retry on transient failures with backoff, jitter, and Retry-After. See reliability.
• Streaming, ingress, snapshots — NDJSON command streaming, per-sandbox preview URLs, and pause / fork / resume.

The CreateOS Sandbox family

One control plane, three SDKs, a CLI, the public docs and the agent integrations, kept behaviourally in step. A change to any shared surface is expected to ripple across the rest.

repo	what it is	package
createos-go-sdk	Go SDK	github.com/NodeOps-app/createos-go-sdk
createos-python-sdk	Python SDK	createos-sandbox
createos-cli	Go CLI (createos)	—
createos-v2-landing	public docs — apps/docs/src/pages/Sandbox/	—
createos-plugin	integrations monorepo — plugins for 8 agent hosts	—

Working in this repository? AGENTS.md carries the full cross-repo map and the ripple protocol.

Contributing

Working in this repository? See AGENTS.md for the contributor and agent guide. Commits are gated by .pre-commit-config.yaml (lint, format, typecheck, tests, docs-sync).

License

See LICENSE.