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 on a Sandbox0 SandboxVolume. delete() releases the sandbox runtime and deletes the workspace volume by default. Set delete_volume_on_delete=False when serialized session state must resume the same workspace volume after cleanup. Use Sandbox0SandboxClientOptions(volume_snapshot_id="...") for Sandbox0-native volume snapshots; generic OpenAI SDK snapshot specs are not used by this adapter.

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

Bootstrap Mounts At Claim Time

from sandbox0.apispec.models.claim_mount_request import ClaimMountRequest
from sandbox0.apispec.models.create_sandbox_volume_request import CreateSandboxVolumeRequest

volume = client.volumes.create(CreateSandboxVolumeRequest())

sandbox = client.sandboxes.claim(
    "default",
    mounts=[
        ClaimMountRequest(
            sandboxvolume_id=volume.id,
            mount_point="/workspace/data",
        )
    ],
)

for mount in sandbox.bootstrap_mounts:
    print(mount.sandboxvolume_id, mount.state)

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 and avoid rootfs writes while the stage is capturing. Call client.wait_template_ready("python-ready") to wait later. A client-side timeout or interruption stops local waiting but does not cancel image creation on the server.

License

Apache-2.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sandbox0-0.9.6.tar.gz (211.7 kB view details)

Uploaded Aug 2, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

sandbox0-0.9.6-py3-none-any.whl (591.9 kB view details)

Uploaded Aug 2, 2026 Python 3

File details

Details for the file sandbox0-0.9.6.tar.gz.

File metadata

Download URL: sandbox0-0.9.6.tar.gz
Upload date: Aug 2, 2026
Size: 211.7 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.11.15

File hashes

Hashes for sandbox0-0.9.6.tar.gz
Algorithm	Hash digest
SHA256	`476983100d156e48bfc5d54098dc9eec67c15707c450b438e779cb2a71011b96`
MD5	`a8893061c0d5b422e7809a239b7eb22f`
BLAKE2b-256	`9887c1316f720396973a2c4fff2203d074d8ffde592218d644a53b0279f10cd2`

See more details on using hashes here.

File details

Details for the file sandbox0-0.9.6-py3-none-any.whl.

File metadata

Download URL: sandbox0-0.9.6-py3-none-any.whl
Upload date: Aug 2, 2026
Size: 591.9 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.11.15

File hashes

Hashes for sandbox0-0.9.6-py3-none-any.whl
Algorithm	Hash digest
SHA256	`4d859e9d0a7c1bf49dc7c5c47709ab56698bc82884e3c190cb9916b481a6ee9d`
MD5	`bf78f2ef390bf79f1fb11e6021a91aa1`
BLAKE2b-256	`c4737589af817764ff82b631692dd4ac07ed8a765e49ffad44aab2a167bb852f`