Skip to main content

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.

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,
  diskMB: 20480, // 20GB workspace (default; larger sizes in closed beta)
  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. TypeScript and HTTP API only
memoryMBnumber—Memory in MB. TypeScript and HTTP API only
diskMBnumber20480Workspace disk size in MB (20GB–256GB). See disk sizing note below.
secretStorestring—Secret store name — resolves encrypted secrets and egress allowlist
imageImage—Declarative image definition (see Templates)
snapshotstring—Name of a pre-built snapshot for instant boot
apiKeystring—Defaults to OPENCOMPUTER_API_KEY env var
apiUrlstring—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

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
Domainsandbox.domain—Preview URL domain for port 80
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.

​
Related

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.