Sandbox0 Python SDK

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

Installation

pip install sandbox0

Requirements

Python 3.9 or later

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

Sandbox0 docs

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.

License

Apache-2.0

Metadata

Release files for sandbox0 0.10.3

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.3
File	Size	Uploaded	Provenance
sandbox0-0.10.3.tar.gz	191.9 kB	Sep 23, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for sandbox0 0.10.3
File	Interpreter	ABI	Platform	Reset
sandbox0-0.10.3-py3-none-any.whl 524.8 kB Sep 23, 2026 Without provenance	Python 3	none	any	Details

Total release size: 716.7 kB

Release files / sandbox0-0.10.3.tar.gz

Download URL	sandbox0-0.10.3.tar.gz
Size	191.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`b0173e0c3c74d11aac30844cc5683ecb6f08d80035b405df44f4a7ec80708049`
BLAKE2b-256 checksum How to use checksums	`623ecc15de0761263d18df370467facb83c3977ff3ee10ddeeaba58b507e1307`
Upload date	Sep 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.16`

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

Download URL	sandbox0-0.10.3-py3-none-any.whl
Size	524.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`48376309a28ce6e655a387d4ec33a6ffb87e65f4b69f3d90dd52432c29c67e3b`
BLAKE2b-256 checksum How to use checksums	`c2fbf7e2771dc8eef99c91a40147893f6ac2093cec97b250d64dec9c9eb4ff10`
Upload date	Sep 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.16`

Security for sandbox0 0.10.3

Report project as malware

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.