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.
import { 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();
Creating a Sandbox
const sandbox = await Sandbox.create({
template: "my-custom-template",
timeout: 600,
cpuCount: 2,
memoryMB: 1024,
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 (max 4). TypeScript and HTTP API only |
memoryMB | number | — | Memory in MB (max 2048). TypeScript and HTTP API only |
apiKey | string | — | Defaults to OPENCOMPUTER_API_KEY env var |
apiUrl | string | — | Defaults to OPENCOMPUTER_API_URL env var |
cpuCount and memoryMB are not available in the Python SDK. Use the HTTP API directly for custom resources from Python.Connecting to an Existing Sandbox
const 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 |
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.
await sandbox.hibernate();
// ... later ...
await sandbox.wake({ timeout: 600 });
hibernate() and wake() are available in the TypeScript SDK and CLI. Python SDK support is planned — use the HTTP API directly.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 |
| 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:
async 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:
const forked = await Sandbox.createFromCheckpoint("cp-abc123", { timeout: 600 });
