Skip to main content

​
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
​
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)
cpuCount and memoryMB are not available in the Python SDK. Use the HTTP API for custom resources.

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