Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

How It Works

Your code talks to a control plane API, which provisions a virtual machine on a worker node. Commands and file operations run inside that VM — I/O streams back over WebSocket. The control plane transparently proxies data-plane requests to the correct worker.
SDK users only need an API key. The SDK handles routing automatically.
  1. Create
    Your code calls the control plane (X-API-Key auth). A VM boots from a golden snapshot in ~300ms.
  2. Operate
    Run commands, read/write files — all execution happens inside the VM. The control plane routes requests to the correct worker automatically.

Virtual Machines

Each sandbox is a real virtual machine with its own Linux kernel, memory, and disk. Isolation is hardware-level (KVM), not namespace-based like containers.
Why not containers? Containers share a kernel. A kernel exploit in one container compromises every other container on the host. KVM-based VMs eliminate that attack surface entirely.

Hibernation

hibernate() snapshots the VM's memory and disk state, then stops it. No compute costs while hibernated. wake() restores the sandbox — the platform attempts a fast snapshot-based resume and falls back to a cold boot from the saved disk state if needed.
The sandbox keeps the same ID across hibernate/wake cycles. A rolling idle timeout (default 300s) auto-hibernates sandboxes that go unused.

Checkpoints & Forking

A checkpoint is a named snapshot of a running sandbox. You can:
  • Restore — revert the sandbox in-place (all changes since the checkpoint are lost)
  • Fork — create a new sandbox from the checkpoint
Forking preserves the filesystem and installed packages. The new sandbox starts with a fresh boot from that disk state — don't assume running processes carry over.
bash
# Checkpoint, then fork two independent sandboxes
oc checkpoint create sb-abc --name ready-state
oc checkpoint spawn cp-xyz   # → sandbox A
oc checkpoint spawn cp-xyz   # → sandbox B
Maximum 10 full checkpoints or 100 disk-only checkpoints per sandbox.

Templates

Templates define the sandbox environment. The default template includes Ubuntu, Python 3, Node.js, and common CLI tools.
For custom environments, use the Image builder to define dependencies programmatically, or create pre-built snapshots for instant reuse:
typescript
// On-demand image (built + cached by content hash)
const image = Image.base().aptInstall(['curl']).pipInstall(['pandas']);
const sandbox = await Sandbox.create({ image });

// Pre-built snapshot (instant boot)
const sandbox = await Sandbox.create({ snapshot: 'my-custom-stack' });
See Templates for the full guide.

Elasticity

Sandboxes can scale memory at runtime via an internal metadata endpoint (http://169.254.169.254/v1/scale) accessible from inside the VM. CPU scales proportionally. This lets workloads request more resources before heavy tasks and release them after. See Elasticity for details.

Networking

Every sandbox gets full outbound internet access via a TAP device with NAT. No firewall or allowlist to configure.
For inbound access, create a preview URL that reverse-proxies public traffic to a port inside the sandbox:
bash
oc preview create sb-abc --port 3000
See Preview URLs for custom domains and auth.
API details: HTTP API Reference.