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.
Links
License
Apache-2.0
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file sandbox0-0.9.5.tar.gz.
File metadata
- Download URL: sandbox0-0.9.5.tar.gz
- Upload date:
- Size: 210.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.11.15
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4de0c0abd07abafd8eb4d4f45e0cc2371ae3a8e51753ca1395aa45e01f958de7
|
|
| MD5 |
997448dd227ff9514de626d5772b9add
|
|
| BLAKE2b-256 |
fc834f0bf5c7ef1837447d21dbbb486555e1e4bfe03aed1dbc70070a6f578fd9
|
File details
Details for the file sandbox0-0.9.5-py3-none-any.whl.
File metadata
- Download URL: sandbox0-0.9.5-py3-none-any.whl
- Upload date:
- Size: 590.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.11.15
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ff66c6ad53d67b6af5dbb5f17abed92e5a90a4340ca6fdb873c512a3d98c63e6
|
|
| MD5 |
8cba428cd4f80b6a10742c2b07cdb6b2
|
|
| BLAKE2b-256 |
467e0a63eaf4577ccb26baad35a17a3b513e7c264e5e651cb54ec04519716e41
|
