Skip to main content

Sandbox0 Python SDK

The official Python SDK for Sandbox0, providing typed models and ergonomic high-level APIs for managing secure code execution sandboxes.

This SDK remains open source. Current Sandbox0 runtime development is closed source. Sandbox0 Cloud is the supported service. Self-hosting is no longer supported. Bring Your Own Cloud (BYOC) is planned and is not available yet. See deployment options.

Installation

pip install sandbox0

Requirements

  • Python 3.9 or later

Files while compute is paused

Use the existing file methods without starting or resuming compute:

sandbox = client.sandbox(sandbox_id)
content = sandbox.read_file("/workspace/output.txt")
sandbox.write_file("/workspace/input.txt", b"next task")

Read, stat, and list work during filesystem-only and memory pauses. Write, mkdir, move, and delete work during filesystem-only pauses; retained memory checkpoints reject offline edits with a conflict. File calls do not trigger auto_resume, and no SDK upgrade or new endpoint is needed. Watch and SSH still require a running runtime. See file access.

RootFS capacity

Template resources.ephemeralStorage sets the initial RootFS filesystem capacity for image imports: the default is 8Gi, and supported values are 300Mi through 1Ti, aligned to 4096 bytes. On deployments with automatic growth enabled, XFS expands online within the configured sparse-device ceiling while the sandbox's processes continue running. Existing generations retain their committed geometry.

Persistent blocks reside in regional object storage. Compute nodes retain bounded caches and write journals; slow or unavailable storage can apply write backpressure. The initial size is distinct from stored data usage and service storage quotas. Automatic growth requires operator enablement; see the deployment guide.

Configuration

Environment Variable Required Default Description
SANDBOX0_TOKEN Yes - API authentication token
SANDBOX0_BASE_URL No https://api.sandbox0.ai API base URL

Quick Start

import os
from sandbox0 import Client, CmdOptions

client = Client(token=os.environ["SANDBOX0_TOKEN"])

# Using context manager for automatic cleanup
with client.sandboxes.open("default") as sandbox:
    # Execute Python code (REPL - stateful)
    result = sandbox.run("python", "print('Hello, Sandbox0!')")
    print(result.output_raw, end="")

CMD Streaming

stream = sandbox.cmd_stream(
    "sh -c 'echo hello && echo warn >&2'",
    CmdOptions(command=["sh", "-c", "echo hello && echo warn >&2"]),
)

for output in stream.iter_outputs():
    print(output.data, end="")

done = stream.wait()
print(f"exit={done.exit_code} state={done.state}")

Usage Windows

Usage windows are immutable, team-scoped usage records. Retain next_cursor to incrementally import only newly recorded windows:

page = client.list_usage_windows(
    cursor=saved_cursor,
    limit=250,
    window_type="sandbox.runtime_mib_milliseconds",
)

for window in page.windows:
    print(window.window_id, window.value, window.unit)

saved_cursor = page.next_cursor

OpenAI Agents SDK Sandbox

Install the optional adapter dependency:

pip install "sandbox0[openai-agents]"

Use Sandbox0SandboxClient anywhere the OpenAI Agents SDK expects a sandbox client:

import os

from agents import Runner
from agents.run_config import RunConfig, SandboxRunConfig
from agents.sandbox import SandboxAgent

from sandbox0_openai_agents import Sandbox0SandboxClient, Sandbox0SandboxClientOptions

client = Sandbox0SandboxClient(
    token=os.environ["SANDBOX0_TOKEN"],
    base_url=os.environ.get("SANDBOX0_BASE_URL"),
)

sandbox_agent = SandboxAgent(
    name="demo",
    instructions="Use the sandbox for filesystem and command execution tasks.",
)

result = Runner.run_sync(
    sandbox_agent,
    "Create hello.txt in the sandbox, then print it.",
    run_config=RunConfig(
        sandbox=SandboxRunConfig(
            client=client,
            options=Sandbox0SandboxClientOptions(template="default"),
        ),
    ),
)
print(result.final_output)

The adapter keeps the OpenAI SDK workspace at /workspace in the Sandbox0 root filesystem. It can create a rootfs snapshot when a session stops and use that snapshot when a replacement sandbox is needed.

LangChain Deep Agents Sandbox

Install the optional Deep Agents adapter dependency:

pip install "sandbox0[deepagents]"

The package registers a Deep Agents Code sandbox provider named sandbox0, so dcode can claim a Sandbox0 default template sandbox directly:

export SANDBOX0_TOKEN=...
dcode --sandbox sandbox0

For custom Deep Agents usage, wrap an existing Sandbox0 sandbox backend:

import os
from sandbox0 import Client
from sandbox0_deepagents import Sandbox0DeepAgentsSandbox

client = Client(token=os.environ["SANDBOX0_TOKEN"])
sandbox = client.sandboxes.claim("default")
backend = Sandbox0DeepAgentsSandbox(sandbox=sandbox)

result = backend.execute("python3 - <<'PY'\nprint('hello')\nPY")
print(result.output)

Documentation

Create A Template From A Sandbox

Capture the current root filesystem of an existing sandbox into a new template:

from sandbox0 import CreateTemplateFromSandboxOptions
from sandbox0.apispec.models.template_from_sandbox_create_request import (
    TemplateFromSandboxCreateRequest,
)
from sandbox0.apispec.models.template_from_sandbox_spec_overrides import (
    TemplateFromSandboxSpecOverrides,
)

template = client.create_template_from_sandbox(
    TemplateFromSandboxCreateRequest(
        template_id="python-ready",
        sandbox_id=sandbox.id,
        spec_overrides=TemplateFromSandboxSpecOverrides(
            display_name="Python Ready",
            tags=["python"],
        ),
    ),
    CreateTemplateFromSandboxOptions(
        idempotency_key="python-ready-v1",
        wait=True,
        timeout_sec=600,
    ),
)

print(template.template_id, template.status.creation.state)

Without wait=True, creation returns as soon as Sandbox0 accepts the request. The rootfs capture point is status.creation.captured_at, not request acceptance, so keep the source sandbox available until capture completes. A running source is briefly write-barriered and remains running afterward. Call client.wait_template_ready("python-ready") to wait later. A client-side timeout or interruption stops local waiting but does not cancel creation of the immutable RootFS base on the server.

Independent sandbox health (unreleased)

# Configure Client(..., timeout=10.0) to bound network requests.
health = client.sandboxes.get_health(sandbox_id)
print(health.runtime.liveness.state, health.execution.state, health.terminal.state)
# Equivalent: client.get_sandbox_health(sandbox_id)

Generations remain exact integers and are validated against the API's int64 range.

Health is returned as separate runtime launch/liveness, execution, terminal, and storage identity/writer/I/O observations. Each includes state, a fixed reason, its evidence source, and the original observation time (null when unobserved). Guest evidence is advisory. A storage identity or writer lease does not prove current storage I/O; that check currently remains unknown.

The query may run bounded fixed guest diagnostics, but never resumes or restarts a sandbox. Paused sandboxes and active lifecycle transitions skip those probes. Unavailable guest diagnostics are a successful observation response, not an API failure or a reason to retry a lifecycle mutation. This API requires a server version with the health endpoint; SDKs do not fall back to guest commands.

License

Apache-2.0

Conditional session receipts can be read without auto-resume or process creation: sandbox.find_conditional_session(original_key, generation). This uses the distinct /sessions/conditional/lookup route and checks the original generation. Errors never fall back to ordinary lookup or creation. A missing receipt does not authorize replay: an earlier create may still be in flight. The result is process information, not credential/storage qualification or proof that the process is still running when a later action begins.

Conditional Session attachment

sandbox.connect_conditional_session(session_id, key, generation, attempt_id, options) opens the distinct /sessions/{session_id}/conditional/ws endpoint, bound to the original conditional creation key, runtime generation and attempt. It accepts the existing Session WebSocket replay options. Every control message is checked against that binding, and generation handover revokes the connection. Errors never trigger an ordinary attachment, retry or auto-resume. Closing the connection detaches without stopping the process. This is not lifecycle, storage or credential qualification.

Reconnect an explicitly memory-restored original attempt

session = sandbox.find_restored_conditional_session(original_key, current_generation, creation_generation)
connection = sandbox.connect_restored_conditional_session(session.id, original_key, current_generation, creation_generation, original_attempt_id, options)

Verify the external memory-restoration lineage and your owned credential/session history first. These helpers explicitly send creation_runtime_generation, which must precede the current generation. They require the original still-running attempt and never create a session, restart an attempt, resume the sandbox or retry through ordinary endpoints. Existing same-generation helpers remain strict. The restored socket can replay the original attempt's earlier-generation events; its controls are bound to the current generation and the original attempt ID. A subsequent handover revokes the socket. Old gateways that discard the optional origin cannot authorize a restored original creation and must return an error.

Explicit snapshot recovery

Use client.sandboxes.restore_snapshot(sandbox_id, expected_runtime_generation=7, snapshot_id=snapshot_id, snapshot_generation_id=snapshot_generation_id, discard_process_state=True, idempotency_key=request_key) to explicitly end old processes and replace writable RootFS. Keep every field and the key after an uncertain reply. find_snapshot_restore_operation and get_snapshot_restore_operation observe the original operation without submitting work. Only succeeded proves fresh runtime launch; restored_rootfs_generation_id alone proves the head change committed.

The get_snapshot_restore_final_capture, read_snapshot_restore_final_capture_file and acknowledge_snapshot_restore_final_capture resource methods preserve stopped-source credential custody. Acknowledge only after durable encrypted owner commit. Helpers never retry, refresh coordinates or fall back to guest execution or disk-only memory recovery. Source and successor generations must fit the contract's safe integer range.

Read original RootFS fork provenance

receipt = client.sandboxes.get_rootfs_fork(
    source_sandbox_id, expected_runtime_generation=7, idempotency_key="original-fork",
)

Keep the original source sandbox, generation (including zero), key and authenticated identity. This performs one GET and never retries or submits a fork. Missing, conflicting and pending results remain errors; a 404 is not proof of cancellation. The receipt requires the original unchanged, never-run paused child and retained storage evidence. Memory forks are excluded. It is not a credential-safety attestation or a state reservation; later mutations need their own identity conditions.

Conditional first launch of a RootFS fork

original = dict(
    fork_operation_id=receipt.operation_id, filesystem_id=receipt.target_filesystem_id,
    head_generation_id=receipt.target_head_generation_id, writer_epoch=receipt.writer_epoch,
    idempotency_key="original-child-launch",
)  # Persist these conditions before submitting.
launch = client.sandboxes.launch_rootfs_fork(receipt.target_sandbox_id, **original)
observation = client.sandboxes.get_rootfs_fork_launch(
    receipt.target_sandbox_id, **original, expected_operation_id=launch.operation_id,
)

Each method sends exactly one request. After a lost reply, query with the same original conditions and key, omitting expected_operation_id if no receipt was received. Never refresh the original writer epoch or fall back to ordinary resume. Completed history retains its digest and time even when current is false after later lifecycle changes. current is an owner snapshot, not a live lease, health check or credential authorization. Pending has no completion proof; neither aborted nor 404 proves physical absence. Helpers validate the returned identity and state-specific evidence and never poll or retry for you.

Metadata

Release files for sandbox0 0.10.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sandbox0 0.10.5
File Size Uploaded Provenance Actions
sandbox0-0.10.5.tar.gz 258.4 kB Without provenance Details for sandbox0-0.10.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sandbox0 0.10.5
File Interpreter ABI Platform Actions
sandbox0-0.10.5-py3-none-any.whl Python 3 none any Details for sandbox0-0.10.5-py3-none-any.whl

Total release size: 900.9 kB

Release files / sandbox0-0.10.5.tar.gz

Download URL sandbox0-0.10.5.tar.gz
Size 258.4 kB
Tags Source
SHA-256 checksum
How to use checksums
a13fe43d85439edc06cfd26a8a09adaea67544ad4123be4c3b4d75bfca0a0761
BLAKE2b-256 checksum
How to use checksums
06a01278a0670f8a1f460d329ee0dc80001a5a67688f1cfc151a573968b04280
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

Release files / sandbox0-0.10.5-py3-none-any.whl

Download URL sandbox0-0.10.5-py3-none-any.whl
Size 642.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f8432b49ee464e2aee0cad378fb9cebcb60c62a2ff70f270026ba36292ae8dd1
BLAKE2b-256 checksum
How to use checksums
199ea77c5b9eeb701878ed2cc1271e2f3d68b0dc10f298dd4773612df434acf9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

Security for sandbox0 0.10.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.10.5 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page