Skip to main content
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

ParameterTypeDefaultDescription
templatestring"base"Template for the VM root filesystem
timeoutnumber300Idle timeout in seconds (resets on every operation)
envsobject—Environment variables set inside the VM
metadataobject—Arbitrary key-value pairs stored with the sandbox
cpuCountnumber—CPU cores (max 4). TypeScript and HTTP API only
memoryMBnumber—Memory in MB (max 2048). TypeScript and HTTP API only
apiKeystring—Defaults to OPENCOMPUTER_API_KEY env var
apiUrlstring—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:
StatusDescription
runningActive, accepting operations
hibernatedState saved, no compute cost
stoppedTerminated
errorFailed
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. 
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

MethodTypeScriptPythonDescription
Killawait sandbox.kill()await sandbox.kill()Terminate the sandbox
Check statusawait sandbox.isRunning()await sandbox.is_running()Returns boolean
Set timeoutawait sandbox.setTimeout(600)await sandbox.set_timeout(600)Update idle timeout (seconds)
Hibernateawait sandbox.hibernate()—Snapshot and stop
Wakeawait sandbox.wake()—Resume from hibernation

​
Properties

PropertyTypeScriptPythonDescription
Sandbox IDsandbox.sandboxIdsandbox.sandbox_idUnique identifier
Statussandbox.statussandbox.statusCurrent lifecycle state
Agentsandbox.agentsandbox.agentAgent sessions
Execsandbox.execsandbox.execCommand execution
Filessandbox.filessandbox.filesFilesystem
PTYsandbox.ptysandbox.ptyInteractive 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 });
See Checkpoints for the full workflow.

Running Commands

Execute shell commands

Working with Files

Read, write, and manage files

Interactive Terminals

PTY sessions for interactive work

Checkpoints

Snapshot, fork, and restore

Templates

Custom VM images

Preview URLs

Expose ports to the internet
CLI: oc sandbox for lifecycle management. Full reference: TypeScript SDK · Python SDK · HTTP API.