> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opencomputer.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# How It Works

> Architecture and key technical decisions

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.

<Steps>
  <Step title="Create">
    Your code calls the control plane (`X-API-Key` auth). A VM boots from a golden snapshot in \~300ms.
  </Step>

  <Step title="Operate">
    Run commands, read/write files — all execution happens inside the VM. The control plane routes requests to the correct worker automatically.
  </Step>
</Steps>

## 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 theme={null}
# 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 theme={null}
// 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](/sandboxes/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](/sandboxes/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 theme={null}
oc preview create sb-abc --port 3000
```

See [Preview URLs](/sandboxes/preview-urls) for custom domains and auth.

<Tip>
  API details: [HTTP API Reference](/reference/api#base-url--authentication).
</Tip>