Sandbox - OpenComputer

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

burst

boolean

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

cpuCount

number

CPU cores

memoryMB

number

Memory in MB

secretStore

string

Secret store name — resolves encrypted secrets and egress allowlist

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 });

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 →

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

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

port

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 →

path

string

required

Absolute path to the file

opts.expiresIn

number

default:"3600"

URL lifetime in seconds (max: 86400)

Returns: Promise<string>

`sandbox.uploadUrl(path, opts?)`

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

path

string

required

Absolute path for the destination file

opts.expiresIn

number

default:"3600"

URL lifetime in seconds (max: 86400)

Returns: Promise<string>

`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>

`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:

sandboxID

string

Sandbox ID

secretStore

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.

baseSecretStore

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.

egressAllowlist

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.

perSecretAllowedHosts

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

sandboxId

string

Sandbox ID (readonly)

status

string

Current status (readonly)

domain

string

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

agent

Agent

Agent sessions

exec

Exec

Command execution

files

Filesystem

File operations

pty

Pty

Terminal sessions

commands

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;
}

​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)

​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)`

`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