Sandbox

Static Methods

`Sandbox.create(opts?)`

Create a new sandbox. HTTP API →

string

default:"base"

Template name

number

default:"300"

Idle timeout in seconds

string

API key (falls back to OPENCOMPUTER_API_KEY env var)

string

API URL (falls back to OPENCOMPUTER_API_URL env var)

Record<string, string>

Environment variables

Record<string, string>

Arbitrary metadata

boolean

Create a Burst Sandbox. Disk is preserved across infrastructure restarts; processes may restart.

number

CPU cores

number

Memory in MB

string

Secret store name — resolves encrypted secrets and egress allowlist

Image

Declarative image definition (see Image)

string

Name of a pre-built snapshot

(log: string) => void

Build log callback (when using image)

Returns: Promise<Sandbox>

const sandbox = await Sandbox.create({ template: "my-stack", timeout: 600 });

Create a Burst Sandbox:

const sandbox = await Sandbox.create({
  burst: true,
  timeout: 300,
});

Burst Sandboxes are alpha. They preserve filesystem state across infrastructure restarts, may restart running processes, and are priced roughly 2x cheaper than on-demand sandboxes.

`Sandbox.connect(sandboxId, opts?)`

Connect to an existing sandbox. HTTP API →

string

required

Sandbox ID

string

API key

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 →

string

required

Checkpoint ID

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 →

string

required

Target checkpoint

string

required

Bash script

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 →

number

default:"300"

Idle timeout after wake

Returns: Promise<void>

`sandbox.setTimeout(timeout)`

Update the idle timeout. HTTP API →

number

required

New timeout in seconds

Returns: Promise<void>

`sandbox.createCheckpoint(name, opts?)`

Create a named checkpoint. HTTP API →

string

required

Checkpoint name (unique per sandbox)

object

Optional retention policy. Use { mode: "delete_oldest", maxCount: 10 } for full checkpoints or { mode: "delete_oldest", maxCount: 100 } with kind: "disk_only" to delete the oldest eligible checkpoint of the same type before creating a new one.

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.getPreviewDomain(port)`

Get the preview URL domain for a specific port. No API call — constructs the hostname locally.

number

required

Port number

Returns: string (e.g., sb-abc123-p3000.workers.opencomputer.dev)

const domain = sandbox.getPreviewDomain(3000);
console.log(`https://${domain}`);

`sandbox.downloadUrl(path, opts?)`

Generate a signed download URL. HTTP API → · Guide →

string

required

Absolute path to the file

number

default:"3600"

URL lifetime in seconds (max: 86400)

Returns: Promise<string>

`sandbox.uploadUrl(path, opts?)`

Generate a signed upload URL. HTTP API → · Guide →

string

required

Absolute path for the destination file

number

default:"3600"

URL lifetime in seconds (max: 86400)

Returns: Promise<string>

`sandbox.createPreviewURL(opts)`

HTTP API →

number

required

Container port (1–65535)

string

Custom domain

Record<string, unknown>

Auth configuration

Returns: Promise<PreviewURLResult>

`sandbox.listPreviewURLs()`

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

`sandbox.deletePreviewURL(port)`

HTTP API → — Returns: Promise<void>

`sandbox.getAllowedHosts()`

Return the egress allowlist + per-secret allowed hosts the sandbox’s secrets proxy enforces. Useful for debugging “why is my outbound HTTP call being blocked” without having to cross-reference the secret store config separately. Sandboxes created without a secretStore option return an empty allowlist with secretStore undefined — the sandbox has no per-store egress restriction. Returns: Promise<AllowedHostsInfo>

const info = await sandbox.getAllowedHosts();
console.log(info.egressAllowlist);          // ['api.openai.com', 'api.anthropic.com']
console.log(info.perSecretAllowedHosts);    // { 'OPENAI_API_KEY': ['api.openai.com'] }

The returned AllowedHostsInfo:

string

Sandbox ID

string

Name of the primary secret store the sandbox is bound to (the “winning” store on the row, whose secrets shadow the base store on env-name collisions). Empty when the sandbox was created without a secretStore option.

string

Name of the inherited parent store, present only when a fork layered an additional secretStore on top of an inherited one. Empty for sandboxes created from scratch and for forks without an override.

string[]

Hosts the sandbox can reach via the secrets proxy. For layered forks this is the union of every layered store’s allowlist (base first, primary’s additions appended, deduped) — matches what the runtime proxy actually enforces.

Record<string, string[]>

Optional per-secret restrictions. When the sandbox uses a listed secret in a request, only the listed hosts are reachable for that request. For layered forks, the primary store’s secrets shadow the base on name collisions (matches runtime env-collision behavior).

Properties

string

Sandbox ID (readonly)

string

Current status (readonly)

string

Preview URL domain for port 80 (e.g., sb-abc123-p80.workers.opencomputer.dev). Returns empty string if sandbox domain is not configured.

SandboxAgent

Sandbox agent sessions

Exec

Command execution

Filesystem

File operations

Pty

Terminal sessions

Exec

Deprecated — alias for exec

Types

SandboxOpts

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

CheckpointInfo

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

PatchInfo / PatchResult

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

interface PatchResult {
  patch: PatchInfo;
}

PreviewURLResult

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

Getting Started

Sandboxes

Browser Sessions

Durable Agent Sessions

Reserved Capacity

CLI

Guides

TypeScript SDK

Python SDK

CLI Reference

API Reference

Resources

Self-hosting

Static Methods

`Sandbox.create(opts?)`

`Sandbox.connect(sandboxId, opts?)`

`Sandbox.createFromCheckpoint(checkpointId, opts?)`

`Sandbox.createCheckpointPatch(checkpointId, opts)`

`Sandbox.listCheckpointPatches(checkpointId, opts?)`

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

Instance Methods

`sandbox.kill()`

`sandbox.isRunning()`

`sandbox.hibernate()`

`sandbox.wake(opts?)`

`sandbox.setTimeout(timeout)`

`sandbox.createCheckpoint(name, opts?)`

`sandbox.listCheckpoints()`

`sandbox.restoreCheckpoint(checkpointId)`

`sandbox.deleteCheckpoint(checkpointId)`

`sandbox.getPreviewDomain(port)`

`sandbox.downloadUrl(path, opts?)`

`sandbox.uploadUrl(path, opts?)`

`sandbox.createPreviewURL(opts)`

`sandbox.listPreviewURLs()`

`sandbox.deletePreviewURL(port)`

`sandbox.getAllowedHosts()`

Properties

Types

​Static Methods

​Sandbox.create(opts?)

​Sandbox.connect(sandboxId, opts?)

​Sandbox.createFromCheckpoint(checkpointId, opts?)

​Sandbox.createCheckpointPatch(checkpointId, opts)

​Sandbox.listCheckpointPatches(checkpointId, opts?)

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

​Instance Methods

​sandbox.kill()

​sandbox.isRunning()

​sandbox.hibernate()

​sandbox.wake(opts?)

​sandbox.setTimeout(timeout)

​sandbox.createCheckpoint(name, opts?)

​sandbox.listCheckpoints()

​sandbox.restoreCheckpoint(checkpointId)

​sandbox.deleteCheckpoint(checkpointId)

​sandbox.getPreviewDomain(port)

​sandbox.downloadUrl(path, opts?)

​sandbox.uploadUrl(path, opts?)

​sandbox.createPreviewURL(opts)

​sandbox.listPreviewURLs()

​sandbox.deletePreviewURL(port)

​sandbox.getAllowedHosts()

​Properties

​Types

Static Methods

`Sandbox.create(opts?)`

`Sandbox.connect(sandboxId, opts?)`

`Sandbox.createFromCheckpoint(checkpointId, opts?)`

`Sandbox.createCheckpointPatch(checkpointId, opts)`

`Sandbox.listCheckpointPatches(checkpointId, opts?)`

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

Instance Methods

`sandbox.kill()`

`sandbox.isRunning()`

`sandbox.hibernate()`

`sandbox.wake(opts?)`

`sandbox.setTimeout(timeout)`

`sandbox.createCheckpoint(name, opts?)`

`sandbox.listCheckpoints()`

`sandbox.restoreCheckpoint(checkpointId)`

`sandbox.deleteCheckpoint(checkpointId)`

`sandbox.getPreviewDomain(port)`

`sandbox.downloadUrl(path, opts?)`

`sandbox.uploadUrl(path, opts?)`

`sandbox.createPreviewURL(opts)`

`sandbox.listPreviewURLs()`

`sandbox.deletePreviewURL(port)`

`sandbox.getAllowedHosts()`

Properties

Types