Sandbox - OpenComputer

Class Methods

`await Sandbox.create(...)`

Create a new sandbox. HTTP API →

template

str

default:"base"

Template name

timeout

int

default:"300"

Idle timeout in seconds

api_key

str

API key (falls back to OPENCOMPUTER_API_KEY env var)

api_url

str

API URL (falls back to OPENCOMPUTER_API_URL env var)

envs

dict[str, str]

Environment variables

metadata

dict[str, str]

Arbitrary metadata

burst

bool

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

image

Image

Declarative image definition (see Image)

snapshot

str

Name of a pre-built snapshot

on_build_log

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 →

sandbox_id

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 →

checkpoint_id

str

required

Checkpoint ID

timeout

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 →

checkpoint_id

str

required

Target checkpoint

script

str

required

Bash script

description

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 →

timeout

int

required

New timeout in seconds

Returns: None

`await sandbox.create_checkpoint(name)`

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

path

str

required

Absolute path to the file

expires_in

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 →

path

str

required

Absolute path for the destination file

expires_in

int

default:"3600"

URL lifetime in seconds (max: 86400)

Returns: str

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

HTTP API →

port

int

required

Container port (1–65535)

domain

str

Custom domain

auth_config

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

sandbox_id

str

Sandbox ID

status

str

Current status

agent

Agent

Agent sessions

exec

Exec

Command execution

files

Filesystem

File operations

pty

Pty

Terminal sessions

commands

Exec

Deprecated — alias for exec

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

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

`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