Python SDK

pip install opencomputer-sdk

from opencomputer import Sandbox, Image, Snapshots

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

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

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

result = await Sandbox.create_checkpoint_patch("cp-abc", script="apt install -y curl")

patches = await Sandbox.list_checkpoint_patches("cp-abc")

await Sandbox.delete_checkpoint_patch("cp-abc", "pa-xyz")

async with await Sandbox.create() as sandbox:
    result = await sandbox.exec.run("echo hello")
    print(result.stdout)
# sandbox.kill() called automatically

session = await sandbox.agent.start(
    prompt="Build a todo app",
    on_event=lambda e: print(e.type),
)

session = await sandbox.agent.start(prompt="Fix the tests")
events = await session.collect_events()
for event in events:
    if event.type == "result":
        print(event.data)

exit_code = await session.wait()

@dataclass
class AgentEvent:
    type: str
    data: dict[str, Any]

# Usage:
event["message"]      # dict-like access
event.get("message")  # safe access with default
event.type            # attribute access

@dataclass
class AgentSessionInfo:
    session_id: str
    sandbox_id: str
    running: bool
    started_at: str

result = await sandbox.exec.run("npm test", cwd="/app")

session_id = await sandbox.exec.start("node server.js", cwd="/app")

@dataclass
class ProcessResult:
    exit_code: int
    stdout: str
    stderr: str

@dataclass
class ExecSessionInfo:
    session_id: str
    sandbox_id: str
    command: str
    args: list[str]
    running: bool
    exit_code: int | None
    started_at: str
    attached_clients: int

@dataclass
class EntryInfo:
    name: str
    is_dir: bool
    path: str
    size: int = 0

from opencomputer import Image

image = (
    Image.base()
    .apt_install(["curl", "jq"])
    .pip_install(["requests", "pandas"])
    .env({"PROJECT_ROOT": "/workspace"})
    .workdir("/workspace")
)

from opencomputer import Snapshots

snapshots = Snapshots()
# or with explicit config:
snapshots = Snapshots(api_key="...", api_url="...")

{
    "id": str,           # Unique snapshot identifier
    "name": str,         # Snapshot name
    "status": str,       # "building" | "ready" | "failed"
    "contentHash": str,  # SHA-256 hash of the image manifest
    "checkpointId": str, # Linked checkpoint ID
    "manifest": dict,    # The declarative image manifest
    "createdAt": str,    # ISO 8601 creation timestamp
    "lastUsedAt": str,   # ISO 8601 last usage timestamp
}

from opencomputer import SecretStore

store = await SecretStore.create(
    name='my-agent-secrets',
    egress_allowlist=['api.anthropic.com'],
)

stores = await SecretStore.list()

store = await SecretStore.get('store-uuid')

updated = await SecretStore.update(
    'store-uuid',
    name='new-name',
    egress_allowlist=['api.anthropic.com', '*.openai.com'],
)

await SecretStore.delete('store-uuid')

await SecretStore.set_secret('store-uuid', 'ANTHROPIC_API_KEY', 'sk-ant-...')

await SecretStore.set_secret(
    'store-uuid',
    'ANTHROPIC_API_KEY',
    'sk-ant-...',
    allowed_hosts=['api.anthropic.com'],
)

entries = await SecretStore.list_secrets('store-uuid')
# [{'name': 'ANTHROPIC_API_KEY', 'allowedHosts': ['api.anthropic.com'], ...}, ...]

await SecretStore.delete_secret('store-uuid', 'DATABASE_URL')

from opencomputer import Sandbox

sandbox = await Sandbox.create(
    secret_store='my-agent-secrets',
    timeout=600,
)

# Secrets are available as sealed env vars
result = await sandbox.commands.run('echo $ANTHROPIC_API_KEY')
# stdout: "osb_sealed_abc123..." (sealed, not the real key)

# But outbound HTTPS requests get the real value substituted by the proxy
api_result = await sandbox.commands.run(
    'curl -s https://api.anthropic.com/v1/messages -H "x-api-key: $ANTHROPIC_API_KEY" ...'
)
# The proxy replaces the sealed token with the real key before it hits Anthropic