# createos-sandbox-sdk

> TypeScript SDK for the createos-sandbox control plane — spawn VM
> VM sandboxes, run commands, move files, expose services, attach disks
> and networks. Zero runtime dependencies, ESM-only. Node 20+ / Bun / Deno /
> edge / browser. A hand-written `fetch` client with typed errors, automatic
> retries, NDJSON streaming, runtime detection, and redaction helpers.

## Install

```
npm install createos-sandbox-sdk
```

Not yet published to npm — until the first release, install from a local
checkout. Configure with `CREATEOS_SANDBOX_BASE_URL` (required) and
`CREATEOS_SANDBOX_API_KEY`.

## Docs

The documentation follows the [Diátaxis](https://diataxis.fr/) framework.

- [Docs home](docs/index.md) — start here; the four-quadrant map
- [Quickstart](docs/quickstart.md) — install, authenticate, first sandbox
- [Tutorial](docs/tutorial.md) — build an AI app generator end to end

How-to guides (problem-oriented recipes):

- [Move files in and out](docs/how-to/files.md) — `upload` / `download`
- [Manage lifecycle](docs/how-to/lifecycle.md) — pause, fork, resume, auto-pause, bandwidth
- [Expose a service](docs/how-to/expose-a-service.md) — ingress + preview URLs
- [Disks, networks & templates](docs/how-to/disks-networks-templates.md)
- [Stream command output](docs/how-to/streaming.md) — `streamCommand` event union
- [Handle errors](docs/how-to/error-handling.md) — typed-error narrowing
- [Observability](docs/how-to/observability.md) — `onRequest` / `onResponse` / `onRetry`, redaction

Reference (the API dictionary):

- [Reference index](docs/reference/index.md) — the surface map
- [Client](docs/reference/client.md) — `CreateosSandboxClient`, `createClient`
- [Sandbox](docs/reference/sandbox.md) — the `Sandbox` handle + `SandboxFiles`
- [Sub-APIs](docs/reference/sub-apis.md) — `TemplatesApi`, `NetworksApi`, `DisksApi`
- [Errors](docs/reference/errors.md) — the `CreateosSandboxError` hierarchy
- [Types](docs/reference/types.md) — all wire types and option interfaces
- [Helpers & transport](docs/reference/helpers.md) — poll, runtime, redact, `VERSION`, `CreateosSandboxHttp`

Explanation (understanding-oriented):

- [What is a VM sandbox](docs/explanation/vm-sandboxes.md)
- [The handle model & data flow](docs/explanation/handle-model.md)
- [Lifecycle & state machine](docs/explanation/lifecycle.md)
- [Reliability: retries, timeouts, cancellation](docs/explanation/reliability.md)

- [Examples index](docs/examples.md) — runnable programs, by capability
- [CHANGELOG](CHANGELOG.md) — release history + deprecation policy

## Examples

Runnable, one per directory. Machine-readable index: [examples/manifest.json](examples/manifest.json).

<!-- BEGIN GENERATED: examples (do not edit; run `bun run docs:gen`) -->
- [01-hello-world](examples/01-hello-world/) — Smoke test: create a sandbox, run one buffered command, destroy it.
- [02-code-interpreter](examples/02-code-interpreter/) — Upload a Python script, run it, capture stdout/stderr. Includes a streaming variant.
- [03-dev-server-preview-url](examples/03-dev-server-preview-url/) — Bind an HTTP server and reach it via a per-sandbox ingress preview URL.
- [04-ai-code-agent](examples/04-ai-code-agent/) — Use a sandbox as the code-execution environment for a Claude agent.
- [05-filesystem-snapshots](examples/05-filesystem-snapshots/) — Snapshot/branch a sandbox: pause, fork, resume the clone.
- [06-openai-agents-fc-tools](examples/06-openai-agents-fc-tools/) — Expose sandbox operations as tools to the OpenAI Agents SDK.
- [07-docker-custom-template](examples/07-docker-custom-template/) — Build a custom rootfs template from a Dockerfile, then run containers inside the VM.
- [08-dev-server-git-preview](examples/08-dev-server-git-preview/) — Clone a repo, start a dev server, expose it via a live ingress URL.
- [09-mcp-claude-code](examples/09-mcp-claude-code/) — Run the Claude Code CLI inside a sandbox.
- [10-mcp-browserbase](examples/10-mcp-browserbase/) — Run the Browserbase MCP server in a sandbox, driven by Claude.
- [11-tigerfs-postgres-filesystem](examples/11-tigerfs-postgres-filesystem/) — Run PostgreSQL on a TigerFS filesystem layer in one VM.
- [12-radicle-multi-agent](examples/12-radicle-multi-agent/) — Three networked sandboxes running a Radicle p2p git mesh with role-specialized agents.
- [13-llamaindex-rag](examples/13-llamaindex-rag/) — Build a LlamaIndex vector index; persist it across pause/resume.
- [14-jupyter-singleton](examples/14-jupyter-singleton/) — Keep a persistent Python kernel over a socket; pause and fork two branches.
- [15-acp-hello-world](examples/15-acp-hello-world/) — Run an Agent Client Protocol agent in a sandbox over JSON-RPC.
- [16-firecrawl-scrape-analyze](examples/16-firecrawl-scrape-analyze/) — Scrape pages with Firecrawl, have Claude write analysis code, run it, pull the chart.
- [17-analyze-data-with-ai](examples/17-analyze-data-with-ai/) — Upload a CSV, have Claude write the analysis from its schema, read back the chart.
- [18-text-embeddings-server](examples/18-text-embeddings-server/) — Serve a CPU embeddings model as a long-lived service over ingress.
- [19-batch-inference-fanout](examples/19-batch-inference-fanout/) — Shard a classification job across many sandboxes in parallel.
- [20-google-adk-agent](examples/20-google-adk-agent/) — Drive a Google ADK agent whose tools run inside a VM.
- [21-astro-sandbox](examples/21-astro-sandbox/) — Scaffold an Astro site, run `astro dev`, reach it via ingress.
- [22-opencode-server](examples/22-opencode-server/) — Run the OpenCode headless HTTP server over ingress.
- [25-prometheus-pushgateway](examples/25-prometheus-pushgateway/) — Run a Prometheus Pushgateway, push a metric, scrape it via ingress.
- [26-s3-bucket-mount](examples/26-s3-bucket-mount/) — Query a public S3 bucket via DuckDB httpfs inside a sandbox.
- [27-fastapi-app](examples/27-fastapi-app/) — Serve a FastAPI app over ingress and verify its routes.
- [28-code-server-vscode](examples/28-code-server-vscode/) — Run code-server (VS Code in the browser) over ingress.
- [29-playwright-headless-browser](examples/29-playwright-headless-browser/) — Run Playwright + headless Chromium to scrape and extract the DOM.
- [30-headless-chromium-devtools](examples/30-headless-chromium-devtools/) — Run headless Chrome with the CDP port exposed via ingress.
- [31-git-clone-lsp-typescript](examples/31-git-clone-lsp-typescript/) — Clone a TS repo and drive typescript-language-server over stdio.
- [32-langgraph-sandbox-orchestrator](examples/32-langgraph-sandbox-orchestrator/) — Model sandbox operations as LangGraph nodes with an OpenAI LLM.
- [33-codex-cli](examples/33-codex-cli/) — Run the OpenAI Codex CLI in a sandbox to execute a task.
- [34-openclaw-gateway](examples/34-openclaw-gateway/) — Run the OpenClaw gateway over ingress and verify /v1/models.
- [35-aio-sandbox](examples/35-aio-sandbox/) — All-in-one tour exercising every core primitive in one run.
- [36-self-hosted-agent-worker](examples/36-self-hosted-agent-worker/) — Back a Claude Managed Agent with one persistent sandbox for tool execution.
- [37-self-hosted-sandbox-per-session](examples/37-self-hosted-sandbox-per-session/) — Back a Claude Managed Agent with a fresh sandbox per session.
- [38-s3-disk-ffmpeg-transcode](examples/38-s3-disk-ffmpeg-transcode/) — Register an S3-backed disk, mount at boot, transcode with ffmpeg, detach, destroy.
- [39-bandwidth-recharge](examples/39-bandwidth-recharge/) — Read a sandbox's bandwidth quota and grow it after create with rechargeBandwidth (create no longer accepts bandwidth_quota_bytes).
- [40-idle-auto-pause](examples/40-idle-auto-pause/) — Set an idle auto-pause timeout at create with auto_pause_after_seconds and change it live with setAutoPause(seconds | null) so an idle sandbox stops billing.
- [41-python-pdf-extractor](examples/41-python-pdf-extractor/) — Upload a fillable PDF into a sandbox, pip-install PyMuPDF, extract every form-field name and value to JSON, and download the result — no external API required.
- [42-doc-to-markdown](examples/42-doc-to-markdown/) — Upload a local document (HTML, DOCX, PDF, …) into a createos-sandbox sandbox, convert it to Markdown with Microsoft MarkItDown (pip-installed inside the guest), and download the result.
- [43-crawl4ai-crawler](examples/43-crawl4ai-crawler/) — Install Crawl4AI and Playwright/Chromium inside a VM, crawl a public URL to Markdown, download the output to the host.
- [44-claude-changelog-generator](examples/44-claude-changelog-generator/) — Clone a public git repo inside a sandbox, run the commit log through the Claude Messages API, and download the generated CHANGELOG.md.
- [45-claude-github-wiki](examples/45-claude-github-wiki/) — Clone a public GitHub repo into a sandbox and run a Claude tool-use agent that reads the file tree to answer questions about the codebase.
- [46-mastra-agent](examples/46-mastra-agent/) — Install the Mastra TypeScript agent framework inside a createos-sandbox VM, upload an agent script, run it against an OpenAI-compatible provider, and capture the response.
- [47-effective-agents-patterns](examples/47-effective-agents-patterns/) — Run three LLM agent patterns (prompt-chaining, routing, parallelization) using the Vercel AI SDK inside a createos-sandbox sandbox, with an OpenAI-compatible model proxy.
- [48-agent-governance-mesh](examples/48-agent-governance-mesh/) — Enforce the Microsoft Agent Governance Toolkit across a fleet of networked sandboxes: a policy-engine gov sandbox governs egress-locked agents over a private overlay, with prompt-injection detection, an OWASP prompt-defense gate, a tamper-evident audit log on an S3 disk, a live ingress dashboard, and an SRE kill-switch — provisioning template + network + disk fresh and reaping them all on exit.
- [49-egress-locked-agent-worker](examples/49-egress-locked-agent-worker/) — Back a Claude Managed Agent with a persistent sandbox whose egress is locked to an allowlist — tool calls reach a co-located private service but cannot exfiltrate to the public internet.
- [50-cloud-agent-sandbox-tool](examples/50-cloud-agent-sandbox-tool/) — Give a cloud-hosted Claude Managed Agent a run_command tool backed by one createos-sandbox sandbox reused for the whole session, so state survives between tool calls.
- [51-cloud-agent-sandbox-per-call](examples/51-cloud-agent-sandbox-per-call/) — Same cloud Managed Agent, stateless lifecycle: every run_command call spawns a fresh disposable sandbox that is destroyed the moment the command returns.
- [52-self-signal-pause-delete](examples/52-self-signal-pause-delete/) — A workload running inside a sandbox pauses or deletes its own sandbox with selfPause() / selfDelete() — no client or credentials, via a loopback agent reachable only from inside.
- [53-anchor-browser-scrape](examples/53-anchor-browser-scrape/) — Give an OpenAI agent a CreateOS-backed Anchor Browser tool that scrapes a public page from inside the sandbox.
- [54-managed-process-lifecycle](examples/54-managed-process-lifecycle/) — Start long-running pipe processes and interactive PTYs, send input, replay output, wait, and terminate process trees.
- [55-desktop-vnc-connect](examples/55-desktop-vnc-connect/) — Create a graphical desktop sandbox, capture screenshots, drive basic computer controls, and mint a live noVNC URL.
- [56-remote-code-execution](examples/56-remote-code-execution/) — Run Go, Python, and JavaScript submissions in a sandbox and collect stdin, stdout, stderr, exit code, and duration.
- [57-sandbox-access-token](examples/57-sandbox-access-token/) — Delegate one sandbox to a worker, inspect and rotate its token, then revoke it.
<!-- END GENERATED: examples -->

## Surface highlights

- `CreateosSandboxClient` — entry point (catalog, identity, sandbox factory, templates, networks, disks).
- `Sandbox` — stateful handle (lifecycle, commands, files, ingress, network attach/detach).
- `CreateosSandboxError` hierarchy — `CreateosSandboxAuthError`, `CreateosSandboxPermissionError`, `CreateosSandboxNotFoundError`,
  `CreateosSandboxValidationError`, `CreateosSandboxRateLimitError`, `CreateosSandboxServerError`, `CreateosSandboxConnectionError`, `CreateosSandboxTimeoutError`.
- `ClientHooks` — `onRequest`, `onResponse`, `onRetry` with pre-redacted payloads.
- `ExecStreamEvent` — discriminated union from `streamCommand`.

## Source

Public surface lives in `src/index.ts`. The wire types in `src/types.ts`
mirror the createos-sandbox control plane's JSON HTTP API and are the source of
truth for the request/response shapes.