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

Class Methods

await Sandbox.create(...)

Create a new sandbox. HTTP API →
body templatestrdefault: base
Template name
body timeoutintdefault: 300
Idle timeout in seconds
body api_keystr
API key (falls back to OPENCOMPUTER_API_KEY env var)
body api_urlstr
API URL (falls back to OPENCOMPUTER_API_URL env var)
body envsdict[str, str]
Environment variables
body metadatadict[str, str]
Arbitrary metadata
body burstbool
Create a Burst Sandbox. Disk is preserved across infrastructure restarts; processes may restart.
body imageImage
Declarative image definition (see Image)
body snapshotstr
Name of a pre-built snapshot
body on_build_logCallable[[str], None]
Build log callback (when using image)
Returns: Sandbox
python
sandbox = await Sandbox.create(template="my-stack", timeout=600)
Create a Burst Sandbox:
python
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.

await Sandbox.connect(sandbox_id, ...)

Connect to an existing sandbox. HTTP API →
body sandbox_idstrrequired
Sandbox ID
Returns: Sandbox
python
sandbox = await Sandbox.connect("sb-abc123")

await Sandbox.create_from_checkpoint(checkpoint_id, ...)

Create a new sandbox from a checkpoint. HTTP API →
body checkpoint_idstrrequired
Checkpoint ID
body timeoutintdefault: 300
Idle timeout
Returns: Sandbox
python
forked = await Sandbox.create_from_checkpoint("cp-abc123")

await Sandbox.create_checkpoint_patch(checkpoint_id, script, ...)

HTTP API →
body checkpoint_idstrrequired
Target checkpoint
body scriptstrrequired
Bash script
body descriptionstr
Description
Returns: dict

await Sandbox.list_checkpoint_patches(checkpoint_id, ...)

HTTP API → — Returns: list[dict]

await Sandbox.delete_checkpoint_patch(checkpoint_id, patch_id, ...)

HTTP API → — Returns: None

Context Manager

Auto-kills the sandbox on exit:
python
async with await Sandbox.create() as sandbox:
    result = await sandbox.exec.run("echo hello")
    print(result.stdout)
# sandbox.kill() called automatically

Instance Methods

await sandbox.kill()

Terminate the sandbox. HTTP API →
Returns: None

await sandbox.is_running()

Check if the sandbox is running.
Returns: bool

await sandbox.set_timeout(timeout)

Update idle timeout. HTTP API →
body timeoutintrequired
New timeout in seconds
Returns: None

await sandbox.create_checkpoint(name, kind=None, retention_policy=None)

Create a named checkpoint. HTTP API →
body retention_policydict
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: dict

await sandbox.list_checkpoints()

HTTP API → — Returns: list[dict]

await sandbox.restore_checkpoint(checkpoint_id)

Revert in-place to a checkpoint. HTTP API →
Returns: None

await sandbox.delete_checkpoint(checkpoint_id)

HTTP API → — Returns: None

await sandbox.download_url(path, *, expires_in=3600)

Generate a signed download URL. HTTP API → · Guide →
body pathstrrequired
Absolute path to the file
body expires_inintdefault: 3600
URL lifetime in seconds (max: 86400)
Returns: str

await sandbox.upload_url(path, *, expires_in=3600)

Generate a signed upload URL. HTTP API → · Guide →
body pathstrrequired
Absolute path for the destination file
body expires_inintdefault: 3600
URL lifetime in seconds (max: 86400)
Returns: str

await sandbox.create_preview_url(port, domain?, auth_config?)

HTTP API →
body portintrequired
Container port (1–65535)
body domainstr
Custom domain
body auth_configdict
Auth configuration
Returns: dict

await sandbox.list_preview_urls()

HTTP API → — Returns: list[dict]

await sandbox.delete_preview_url(port)

HTTP API → — Returns: None

await sandbox.get_allowed_hosts()

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 secret_store option return an empty allowlist with secretStore omitted — the sandbox has no per-store egress restriction.
Returns: dict with the shape:
python
{
    "sandboxID": "sb-...",
    "secretStore": "my-store",                   # omitted if no store
    "baseSecretStore": "parent-store",           # omitted unless this is a layered fork
    "egressAllowlist": ["api.openai.com", ...],
    "perSecretAllowedHosts": {
        "OPENAI_API_KEY": ["api.openai.com"],
    },
}
For forks that layered an additional secret_store on top of an inherited one, egressAllowlist is the union of both stores' allowlists (matches what the runtime proxy enforces) and baseSecretStore is populated with the inherited parent's name. For sandboxes with a single store (or none), baseSecretStore is omitted.
python
info = await sandbox.get_allowed_hosts()
print(info["egressAllowlist"])          # ['api.openai.com', 'api.anthropic.com']
print(info["perSecretAllowedHosts"])    # {'OPENAI_API_KEY': ['api.openai.com']}

await sandbox.close()

Close HTTP clients. Called automatically by the context manager.

Not Available in Python

These features are TypeScript-only. Use the HTTP API directly:
  • hibernate() / wake()
  • cpuCount / memoryMB on create

Properties

body sandbox_idstr
Sandbox ID
body statusstr
Current status
body agentAgent
Agent sessions
body execExec
Command execution
body filesFilesystem
File operations
body ptyPty
Terminal sessions
body commandsExec
Deprecated — alias for exec