Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Static Methods

Sandbox.create(opts?)

Create a new sandbox. HTTP API →
body templatestringdefault: base
Template name
body timeoutnumberdefault: 300
Idle timeout in seconds
body apiKeystring
API key (falls back to OPENCOMPUTER_API_KEY env var)
body apiUrlstring
API URL (falls back to OPENCOMPUTER_API_URL env var)
body envsRecord<string, string>
Environment variables
body metadataRecord<string, string>
Arbitrary metadata
body burstboolean
Create a Burst Sandbox. Disk is preserved across infrastructure restarts; processes may restart.
body cpuCountnumber
CPU cores
body memoryMBnumber
Memory in MB
body secretStorestring
Secret store name — resolves encrypted secrets and egress allowlist
body imageImage
Declarative image definition (see Image)
body snapshotstring
Name of a pre-built snapshot
body onBuildLog(log: string) => void
Build log callback (when using image)
Returns: Promise<Sandbox>
typescript
const sandbox = await Sandbox.create({ template: "my-stack", timeout: 600 });
Create a Burst Sandbox:
typescript
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 →
body sandboxIdstringrequired
Sandbox ID
body apiKeystring
API key
body apiUrlstring
API URL
Returns: Promise<Sandbox>
typescript
const sandbox = await Sandbox.connect("sb-abc123");

Sandbox.createFromCheckpoint(checkpointId, opts?)

Create a new sandbox from a checkpoint. HTTP API →
body checkpointIdstringrequired
Checkpoint ID
body timeoutnumberdefault: 300
Idle timeout
Returns: Promise<Sandbox>
typescript
const forked = await Sandbox.createFromCheckpoint("cp-abc123");

Sandbox.createCheckpointPatch(checkpointId, opts)

Create a patch for a checkpoint. HTTP API →
body checkpointIdstringrequired
Target checkpoint
body scriptstringrequired
Bash script
body descriptionstring
Description
Returns: Promise<PatchResult>
typescript
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 →
body timeoutnumberdefault: 300
Idle timeout after wake
Returns: Promise<void>

sandbox.setTimeout(timeout)

Update the idle timeout. HTTP API →
body timeoutnumberrequired
New timeout in seconds
Returns: Promise<void>

sandbox.createCheckpoint(name, opts?)

Create a named checkpoint. HTTP API →
body namestringrequired
Checkpoint name (unique per sandbox)
body opts.retentionPolicyobject
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.
body portnumberrequired
Port number
Returns: string (e.g., sb-abc123-p3000.workers.opencomputer.dev)
typescript
const domain = sandbox.getPreviewDomain(3000);
console.log(`https://${domain}`);

sandbox.downloadUrl(path, opts?)

Generate a signed download URL. HTTP API → · Guide →
body pathstringrequired
Absolute path to the file
body opts.expiresInnumberdefault: 3600
URL lifetime in seconds (max: 86400)
Returns: Promise<string>

sandbox.uploadUrl(path, opts?)

Generate a signed upload URL. HTTP API → · Guide →
body pathstringrequired
Absolute path for the destination file
body opts.expiresInnumberdefault: 3600
URL lifetime in seconds (max: 86400)
Returns: Promise<string>

sandbox.createPreviewURL(opts)

HTTP API →
body portnumberrequired
Container port (1–65535)
body domainstring
Custom domain
body authConfigRecord<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>
typescript
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:
body sandboxIDstring
Sandbox ID
body secretStorestring
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.
body baseSecretStorestring
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.
body egressAllowliststring[]
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.
body perSecretAllowedHostsRecord<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

body sandboxIdstring
Sandbox ID (readonly)
body statusstring
Current status (readonly)
body domainstring
Preview URL domain for port 80 (e.g., sb-abc123-p80.workers.opencomputer.dev). Returns empty string if sandbox domain is not configured.
body agentSandboxAgent
Sandbox agent sessions
body execExec
Command execution
body filesFilesystem
File operations
body ptyPty
Terminal sessions
body commandsExec
Deprecated — alias for exec

Types

SandboxOpts
typescript
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
typescript
interface CheckpointInfo {
  id: string;
  sandboxId: string;
  orgId: string;
  name: string;
  sandboxConfig: object;
  status: string;       // "processing" | "ready" | "failed"
  sizeBytes: number;
  createdAt: string;
}
PatchInfo / PatchResult
typescript
interface PatchInfo {
  id: string;
  checkpointId: string;
  sequence: number;
  script: string;
  description: string;
  strategy: string;     // "on_wake"
  createdAt: string;
}

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