CreateOS Sandbox
CreateOS Sandbox runs full Linux virtual machines that boot in ~30ms (p90). Each sandbox is a Firecracker microVM with its own kernel, root filesystem, and network identity (the isolation of a VM with the startup speed of a container).
Sandboxes are built for workloads that need real, disposable compute:
- Running untrusted or AI-generated code: give an agent a full machine to execute in, without risking your own.
- Ephemeral development environments: spin up a clean box per branch, per task, or per user.
- CI and batch jobs: isolated, reproducible execution that tears down when finished.
- Interactive sessions: shells, notebooks, and preview servers reachable over SSH or HTTPS.
What you get
| Capability | Description | Reference |
|---|---|---|
| Fast boot | A sandbox is ready to run commands within seconds of creation. | Concepts · Quickstart |
| Pause, resume, fork | Snapshot a running VM to durable storage, restore it later, or clone it into independent copies. | REST · SDK · CLI · Concepts |
| Idle auto-pause | Set a timeout from 1 minute to 24 hours and the sandbox pauses itself once both API calls and network traffic go quiet. | REST · SDK · CLI · Guide |
| Wake on request | Hit a paused sandbox's HTTPS URL and it resumes on its own; browsers get a waiting page that reloads until the app answers. | REST · Concepts · Guide |
| Self-signal | Let code inside the sandbox pause or delete its own box with a POST to 127.0.0.1:1029, no API key needed. | REST · pause · delete |
| Run commands | Execute commands and stream output over the API, SDK, or CLI. No SSH key required. | REST · SDK · CLI |
| Managed processes | Start reconnectable commands and shell sessions with retained output, stdin, signals, wait, stop, and PTY resize controls. Retained output is bounded to 1 MiB per process and 32 MiB per sandbox. | REST · CLI · Guide |
| File transfer | Upload and download individual files, or copy directories in and out. | REST · SDK · CLI |
| Private networks | Connect sandboxes so they reach each other over p2p encrypted network, isolated from other tenants. | REST · SDK · CLI |
| VPN access | Join your own machine to a sandbox private network over an encrypted WireGuard tunnel, register the device once, then connect. | Concepts · CLI |
| S3 disks | Mount S3-compatible buckets into a running sandbox and detach them live. | Guide · REST · SDK · CLI |
| Custom images | Build your own root filesystem from a Dockerfile and boot sandboxes from it. | REST · SDK · CLI |
| Public ingress | Expose an HTTP service on a per-sandbox HTTPS URL. | Concepts · SDK · Guide |
| Egress control | Restrict outbound traffic to an allowlist of hosts, IPs, or CIDRs. | REST · SDK · CLI |
| SSH gateway | SSH into a sandbox using keys you attach, open a shell or an ssh -L port-forward through the gateway. | Concepts · SDK · CLI |
| Port forwarding | Forward a local port to a service inside a running sandbox through the control plane, no SSH key required. | CLI |
| Live directory sync | Continuously two-way sync a local directory with one inside the sandbox; one-way and mirror modes too. | CLI |
exec vs process vs PTY
Use the smallest execution surface that matches the job:
| Need | Use | Why |
|---|---|---|
| Run a quick command and get its exit code | exec | It is simple, stateless, and returns buffered or live output for one command. Buffered output is capped at 1 MiB; use streaming exec for larger output. |
| Run a command you may need to inspect later | process | It creates a process ID, retains output, and lets you attach, wait, send input, signal, or stop it later. |
| Start background work without keeping your CLI attached | process start | It returns immediately with a process ID you can reconnect to later. |
| Run a command and follow retained output until it exits | process run | It behaves like a foreground command but still leaves a managed record behind. |
| Open a disposable interactive shell right now | sandbox shell | It gives you an immediate terminal and does not create a reconnectable managed session. |
| Open a shell you can detach from and reattach to | process shell | It creates a managed PTY shell with a process ID. |
| Run a REPL, curses app, full-screen tool, or anything that checks for a TTY | process ... --pty | PTY mode gives the command terminal behavior, combines output into a terminal stream, and supports resize. |
Use exec for scripts, tests, package installs, and simple automation. Use process for long-running servers, agent jobs, background tasks, reconnectable logs, and commands you may need to control after they start. Add --pty only when the program needs terminal semantics; otherwise keep the default pipe process so stdout and stderr stay separate.
Three ways to use it
Everything a sandbox can do is exposed through one REST API. Pick the surface that fits your workflow. They all talk to the same control plane at https://api.sb.createos.sh.
REST API
The HTTP API is the source of truth. Use it directly from any language, or when you need an endpoint the SDK and CLI don't wrap yet.
TypeScript SDK
@nodeops-createos/sandbox is a zero-dependency TypeScript client that runs on Node 20+, Bun, Deno, edge runtimes, and the browser. It gives you typed sandbox handles, streaming, retries, and typed errors.
Bash
CLI
The createos CLI manages sandboxes from your terminal: create, exec, shell in, sync files, tunnel ports, and tear down. The sandbox command group is aliased to sb.
Bash
Authentication
All three surfaces authenticate with a CreateOS API token sent as the X-Api-Key header. Generate a token from your CreateOS dashboard.
Bash
Next steps
- Quickstart: create and run your first sandbox.
- Concepts: the vocabulary: shapes, rootfs, snapshots, networks, disks, and more.
- REST API, SDK, CLI: full references.