Sandbox

Class Methods

`await Sandbox.create(...)`

Create a new sandbox. HTTP API →

str

default:"base"

Template name

int

default:"300"

Idle timeout in seconds

str

API key (falls back to OPENCOMPUTER_API_KEY env var)

str

API URL (falls back to OPENCOMPUTER_API_URL env var)

dict[str, str]

Environment variables

dict[str, str]

Arbitrary metadata

bool

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

Image

Declarative image definition (see Image)

str

Name of a pre-built snapshot

Callable[[str], None]

Build log callback (when using image)

Returns: Sandbox

sandbox = await Sandbox.create(template="my-stack", timeout=600)

Create a Burst Sandbox:

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 →

str

required

Sandbox ID

Returns: Sandbox

sandbox = await Sandbox.connect("sb-abc123")

`await Sandbox.create_from_checkpoint(checkpoint_id, ...)`

Create a new sandbox from a checkpoint. HTTP API →

str

required

Checkpoint ID

int

default:"300"

Idle timeout

Returns: Sandbox

forked = await Sandbox.create_from_checkpoint("cp-abc123")

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

HTTP API →

str

required

Target checkpoint

str

required

Bash script

str

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:

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 →

int

required

New timeout in seconds

Returns: None

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

Create a named checkpoint. HTTP API →

dict

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 →

str

required

Absolute path to the file

int

default:"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 →

str

required

Absolute path for the destination file

int

default:"3600"

URL lifetime in seconds (max: 86400)

Returns: str

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

HTTP API →

int

required

Container port (1–65535)

str

Custom domain

dict

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:

{
    "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.

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

str

Sandbox ID

str

Current status

Agent

Exec

Filesystem

Pty

Exec

Deprecated — alias for exec

Getting Started

Sandboxes

Browser Sessions

Durable Agent Sessions

Reserved Capacity

CLI

Guides

TypeScript SDK

Python SDK

CLI Reference

API Reference

Resources

Self-hosting

Class Methods

`await Sandbox.create(...)`

`await Sandbox.connect(sandbox_id, ...)`

`await Sandbox.create_from_checkpoint(checkpoint_id, ...)`

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

`await Sandbox.list_checkpoint_patches(checkpoint_id, ...)`

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

Context Manager

Instance Methods

`await sandbox.kill()`

`await sandbox.is_running()`

`await sandbox.set_timeout(timeout)`

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

`await sandbox.list_checkpoints()`

`await sandbox.restore_checkpoint(checkpoint_id)`

`await sandbox.delete_checkpoint(checkpoint_id)`

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

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

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

`await sandbox.list_preview_urls()`

`await sandbox.delete_preview_url(port)`

`await sandbox.get_allowed_hosts()`

`await sandbox.close()`

Not Available in Python

Properties

​Class Methods

​await Sandbox.create(...)

​await Sandbox.connect(sandbox_id, ...)

​await Sandbox.create_from_checkpoint(checkpoint_id, ...)

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

​await Sandbox.list_checkpoint_patches(checkpoint_id, ...)

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

​Context Manager

​Instance Methods

​await sandbox.kill()

​await sandbox.is_running()

​await sandbox.set_timeout(timeout)

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

​await sandbox.list_checkpoints()

​await sandbox.restore_checkpoint(checkpoint_id)

​await sandbox.delete_checkpoint(checkpoint_id)

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

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

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

​await sandbox.list_preview_urls()

​await sandbox.delete_preview_url(port)

​await sandbox.get_allowed_hosts()

​await sandbox.close()

​Not Available in Python

​Properties

Class Methods

`await Sandbox.create(...)`

`await Sandbox.connect(sandbox_id, ...)`

`await Sandbox.create_from_checkpoint(checkpoint_id, ...)`

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

`await Sandbox.list_checkpoint_patches(checkpoint_id, ...)`

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

Context Manager

Instance Methods

`await sandbox.kill()`

`await sandbox.is_running()`

`await sandbox.set_timeout(timeout)`

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

`await sandbox.list_checkpoints()`

`await sandbox.restore_checkpoint(checkpoint_id)`

`await sandbox.delete_checkpoint(checkpoint_id)`

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

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

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

`await sandbox.list_preview_urls()`

`await sandbox.delete_preview_url(port)`

`await sandbox.get_allowed_hosts()`

`await sandbox.close()`

Not Available in Python

Properties