Skip to main content

​
Static Methods

​
Sandbox.create(opts?)

Create a new sandbox. HTTP API →
​
template
string
default:"base"
Template name
​
timeout
number
default:"300"
Idle timeout in seconds
​
apiKey
string
API key (falls back to OPENCOMPUTER_API_KEY env var)
​
apiUrl
string
API URL (falls back to OPENCOMPUTER_API_URL env var)
​
envs
Record<string, string>
Environment variables
​
metadata
Record<string, string>
Arbitrary metadata
​
cpuCount
number
CPU cores (max 4)
​
memoryMB
number
Memory in MB (max 2048)
​
image
Image
Declarative image definition (see Image)
​
snapshot
string
Name of a pre-built snapshot
​
onBuildLog
(log: string) => void
Build log callback (when using image)
Returns: Promise<Sandbox> 
const sandbox = await Sandbox.create({ template: "my-stack", timeout: 600 });

​
Sandbox.connect(sandboxId, opts?)

Connect to an existing sandbox. HTTP API →
​
sandboxId
string
required
Sandbox ID
​
apiKey
string
API key
​
apiUrl
string
API URL
Returns: Promise<Sandbox> 
const sandbox = await Sandbox.connect("sb-abc123");

​
Sandbox.createFromCheckpoint(checkpointId, opts?)

Create a new sandbox from a checkpoint. HTTP API →
​
checkpointId
string
required
Checkpoint ID
​
timeout
number
default:"300"
Idle timeout
Returns: Promise<Sandbox> 
const forked = await Sandbox.createFromCheckpoint("cp-abc123");

​
Sandbox.createCheckpointPatch(checkpointId, opts)

Create a patch for a checkpoint. HTTP API →
​
checkpointId
string
required
Target checkpoint
​
script
string
required
Bash script
​
description
string
Description
Returns: Promise<PatchResult> 
const result = await Sandbox.createCheckpointPatch("cp-abc", { script: "apt install -y curl" });

​
Sandbox.listCheckpointPatches(checkpointId, opts?)

HTTP API → Returns: Promise<PatchInfo[]>

​
Sandbox.deleteCheckpointPatch(checkpointId, patchId, opts?)

HTTP API → Returns: Promise<void>

​
Instance Methods

​
sandbox.kill()

Terminate the sandbox. HTTP API → Returns: Promise<void>

​
sandbox.isRunning()

Check if the sandbox is running. Returns: Promise<boolean>

​
sandbox.hibernate()

Snapshot VM state and stop. No compute cost while hibernated. HTTP API → Returns: Promise<void>

​
sandbox.wake(opts?)

Resume a hibernated sandbox. HTTP API →
​
timeout
number
default:"300"
Idle timeout after wake
Returns: Promise<void>

​
sandbox.setTimeout(timeout)

Update the idle timeout. HTTP API →
​
timeout
number
required
New timeout in seconds
Returns: Promise<void>

​
sandbox.createCheckpoint(name)

Create a named checkpoint. HTTP API →
​
name
string
required
Checkpoint name (unique per sandbox)
Returns: Promise<CheckpointInfo>

​
sandbox.listCheckpoints()

HTTP API → — Returns: Promise<CheckpointInfo[]>

​
sandbox.restoreCheckpoint(checkpointId)

Revert in-place to a checkpoint. HTTP API → Returns: Promise<void>

​
sandbox.deleteCheckpoint(checkpointId)

HTTP API → — Returns: Promise<void>

​
sandbox.createPreviewURL(opts)

HTTP API →
​
port
number
required
Container port (1–65535)
​
domain
string
Custom domain
​
authConfig
Record<string, unknown>
Auth configuration
Returns: Promise<PreviewURLResult>

​
sandbox.listPreviewURLs()

HTTP API → — Returns: Promise<PreviewURLResult[]>

​
sandbox.deletePreviewURL(port)

HTTP API → — Returns: Promise<void>

​
Properties

​
sandboxId
string
Sandbox ID (readonly)
​
status
string
Current status (readonly)
​
agent
Agent
Agent sessions
​
exec
Exec
Command execution
​
files
Filesystem
File operations
​
pty
Pty
Terminal sessions
​
commands
Exec
Deprecated — alias for exec

​
Types

interface SandboxOpts {
  template?: string;
  timeout?: number;
  apiKey?: string;
  apiUrl?: string;
  envs?: Record<string, string>;
  metadata?: Record<string, string>;
  cpuCount?: number;
  memoryMB?: number;
  image?: Image;
  snapshot?: string;
  onBuildLog?: (log: string) => void;
}

interface CheckpointInfo {
  id: string;
  sandboxId: string;
  orgId: string;
  name: string;
  sandboxConfig: object;
  status: string;       // "processing" | "ready" | "failed"
  sizeBytes: number;
  createdAt: string;
}

interface PatchInfo {
  id: string;
  checkpointId: string;
  sequence: number;
  script: string;
  description: string;
  strategy: string;     // "on_wake"
  createdAt: string;
}

interface PatchResult {
  patch: PatchInfo;
}

interface PreviewURLResult {
  id: string;
  sandboxId: string;
  orgId: string;
  hostname: string;
  customHostname?: string;
  port: number;
  cfHostnameId?: string;
  sslStatus: string;
  authConfig?: object;
  createdAt: string;
}