Client SDK
The Client SDK runs on your machine. It creates a sandbox, connects to one that already exists, and then runs commands, reads and writes files, and calls the code interpreter. The package is agent-sandbox. Import agent_sandbox.
pip install agent-sandbox
from agent_sandbox import Sandbox
async with await Sandbox.create(template="python-base") as sandbox:
result = await sandbox.commands.run("echo hello")
print(result.stdout)
The HTTP service inside the sandbox image is not written with this package. That process is the Server SDK (agent-sandbox-server). The Client SDK reaches it through envd and that service's HTTP API.
Start here
| Guide | What it covers |
|---|---|
| Getting Started | Install, configure, create, run, destroy |
| SDK Usage | commands, files, run_code, named commands |
| Authentication | API key and AK/SK |
| Declarative usage | @sandbox runs a function inside a sandbox |
| Cloud end-to-end practice | Run the examples on the default provider |
| Environment variables | Inject at create, and how the sandbox reads them |
| Session persistence | Connect again by id after the process exits |
| Providers | Switch the sandbox backend |
| Migrate from E2B | Where the method names match, and where they do not |
| MCP integration | Hand sandbox operations to an IDE agent |
| Command and SDK map | Commands next to E2B and OpenSandbox |
| Comparison | How this sits next to E2B, Modal, and Docker Sandbox |
| Troubleshooting | Create, auth, file, and command failures |
Reference: API reference, Configuration, Error codes.
Examples
These scripts run on your machine. See the example index:
examples/quickstart/— create, files, code,@sandboxexamples/compat-demos/— E2B-style and Modal-style callsexamples/agents/— call an Agents API that is already up, or run Codex on a cloud sandboxexamples/scenarios/agent_loop_local.py— start a local server, then create, exec, read, and killexamples/templates/python-hello/call_api.py— HTTP against a template server that is already listening
Code that is copied into the image and started inside the sandbox is the Server SDK.