Skip to main content
Your code talks to a control plane API, which provisions a Firecracker microVM on a worker node. The response includes a connectURL and short-lived JWT for direct worker access. Commands, file operations, and agent sessions run inside that VM — events and I/O stream back over WebSocket. SDK users only need an API key. The SDK handles worker routing and JWT refresh transparently.
1

Create

Your code calls the control plane (X-API-Key auth). A Firecracker microVM boots in ~150ms.
2

Connect

The response includes connectURL and a sandbox-scoped JWT token. Subsequent operations go directly to the worker (Bearer auth) for lower latency.
3

Operate

Run commands, read/write files, start agent sessions. All execution happens inside the VM.

​
Firecracker microVMs

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. Firecracker VMs eliminate that attack surface entirely — the same isolation model that powers AWS Lambda.

​
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. 
# 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 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: 
// 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.

​
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: 
oc preview create sb-abc --port 3000
See Preview URLs for custom domains and auth.

​
Agent Sessions

An agent session runs the Claude Agent SDK inside the VM as a regular process. The SDK gives Claude bash and file tools, then manages the think → act → observe loop. Events stream to your code over WebSocket as JSON lines. 
const session = await sandbox.agent.start({
  prompt: "Set up a Next.js app with Tailwind CSS",
  onEvent: (event) => console.log(event.type),
});
await session.done;
See Agents for the full guide.
Connection model details: HTTP API Reference.