Sandboxes
A sandbox is a full Linux virtual machine in the cloud. Each one has its own filesystem, network stack, and process space — completely isolated from other sandboxes via hardware-level virtualization. Think of it as a disposable laptop that starts in milliseconds and sleeps when idle.
typescript
123456import { Sandbox } from "@opencomputer/sdk"; const sandbox = await Sandbox.create(); const result = await sandbox.exec.run("echo Hello from $(uname -a)"); console.log(result.stdout); await sandbox.kill();
Ask AI about this page
Creating a Sandbox
typescript
123456789const sandbox = await Sandbox.create({ template: "my-custom-template", timeout: 600, cpuCount: 2, memoryMB: 1024, diskMB: 20480, // 20GB workspace (default; larger sizes in closed beta) envs: { NODE_ENV: "production" }, metadata: { project: "my-app" }, });
Parameters
| Parameter | Type | Default | Description |
template | string | "base" | Template for the VM root filesystem |
timeout | number | 300 | Idle timeout in seconds (resets on every operation) |
envs | object | — | Environment variables set inside the VM |
metadata | object | — | Arbitrary key-value pairs stored with the sandbox |
cpuCount | number | — | CPU cores. TypeScript and HTTP API only |
memoryMB | number | — | Memory in MB. TypeScript and HTTP API only |
diskMB | number | 20480 | Workspace disk size in MB (20GB–256GB). See disk sizing note below. |
secretStore | string | — | Secret store name — resolves encrypted secrets and egress allowlist |
image | Image | — | Declarative image definition (see Templates) |
snapshot | string | — | Name of a pre-built snapshot for instant boot |
apiKey | string | — | Defaults to OPENCOMPUTER_API_KEY env var |
apiUrl | string | — | Defaults to OPENCOMPUTER_API_URL env var |
cpuCount, memoryMB, and secretStore are not available in the Python SDK. Use the HTTP API directly for custom resources from Python.Disk sizing (closed beta). Every sandbox ships with a 20GB workspace on
/home/sandbox. You can request up to 256GB via diskMB; any GB above the
20GB baseline is metered per-second at a rate comparable to AWS EBS gp3.
Larger disk limits are gated per-organization during the beta — book a
call to have your
org's ceiling raised.Connecting to an Existing Sandbox
typescript
1const sandbox = await Sandbox.connect("sb-abc123");
Lifecycle
Sandboxes have four states:
| Status | Description |
running | Active, accepting operations |
hibernated | State saved, no compute cost |
stopped | Terminated |
error | Failed |
A rolling idle timeout (default 300s) resets on every operation — exec, file access, agent activity. When the timeout expires, the sandbox auto-hibernates if possible, otherwise stops.
Hibernation & Wake
Hibernation snapshots the VM state and stops it — no cost while hibernated. Wake restores the sandbox, typically fast, with a cold-boot fallback if snapshot restore is unavailable.
typescript
123await sandbox.hibernate(); // ... later ... await sandbox.wake({ timeout: 600 });
Methods
| Method | TypeScript | Python | Description |
| Kill | await sandbox.kill() | await sandbox.kill() | Terminate the sandbox |
| Check status | await sandbox.isRunning() | await sandbox.is_running() | Returns boolean |
| Set timeout | await sandbox.setTimeout(600) | await sandbox.set_timeout(600) | Update idle timeout (seconds) |
| Hibernate | await sandbox.hibernate() | — | Snapshot and stop |
| Wake | await sandbox.wake() | — | Resume from hibernation |
Properties
| Property | TypeScript | Python | Description |
| Sandbox ID | sandbox.sandboxId | sandbox.sandbox_id | Unique identifier |
| Status | sandbox.status | sandbox.status | Current lifecycle state |
| Domain | sandbox.domain | — | Preview URL domain for port 80 |
| Agent | sandbox.agent | sandbox.agent | Agent sessions |
| Exec | sandbox.exec | sandbox.exec | Command execution |
| Files | sandbox.files | sandbox.files | Filesystem |
| PTY | sandbox.pty | sandbox.pty | Interactive terminals |
sandbox.commands is a deprecated alias for sandbox.exec. Use sandbox.exec in all new code.Python Context Manager
The Python SDK supports
async with for automatic cleanup:python
1234async with await Sandbox.create() as sandbox: result = await sandbox.exec.run("echo hello") print(result.stdout) # sandbox.kill() called automatically on exit
Forking from Checkpoints
Create a sandbox from a saved checkpoint — useful for parallel testing from a known-good state:
typescript
1const forked = await Sandbox.createFromCheckpoint("cp-abc123", { timeout: 600 });
See Checkpoints for the full workflow.