English | 中文
Create sandboxes, execute code and commands, and work with remote files from Python. This repository contains the client SDK and the runtime used inside sandbox application images.
Website · Documentation · Examples
Preview release: Agent Sandbox is currently in preview and may introduce breaking changes. The stable 1.0.0 release is expected on November 15, 2026. Stay tuned!
Use Python 3.10+ in a virtual environment:
python -m pip install --index-url https://pypi.org/simple --upgrade --pre agent-sandbox-client python -m pip check
--pre opts into preview releases. The package imports as agent_sandbox. Standard clients, ProviderSandbox and the application HTTP ServerClient run on the client; agent-sandbox-server runs inside the application image. See installation for a pinned version, optional extras and source setup. The PyPI name agent-sandbox belongs to a different project.
Configure your Express Sandbox API key, API URL and sandbox domain using ABX_SANDBOX_API_KEY, ABX_SANDBOX_BASE_URL and ABX_SANDBOX_DOMAIN. Use values for the same account and region; see authentication and permissions for their source and setup.
from agent_sandbox.code_interpreter import Sandbox sandbox = Sandbox.create(template="code-interpreter-v1") try: sandbox.files.write("/tmp/input.txt", "hello") print(sandbox.commands.run("cat /tmp/input.txt").stdout) print(sandbox.run_code("1 + 1").text) finally: sandbox.kill()
This example needs an interpreter-enabled template. kill() deletes the sandbox when the work finishes, including on failure.
| Entry point | Use it for |
|---|---|
from agent_sandbox import Sandbox, AsyncSandbox |
Synchronous or asynchronous Express lifecycle, commands and files |
from agent_sandbox.code_interpreter import Sandbox, AsyncSandbox |
Code execution with persistent interpreter contexts |
from agent_sandbox import ProviderSandbox |
Asynchronous provider plugins and template application services |
Use await with AsyncSandbox and ProviderSandbox. Provider operations and interpreter availability depend on the selected backend and template; see SDK usage.
Express is built in. Installable provider plugins connect ProviderSandbox to other backends. Follow provider setup before using one.
Application templates package browser tools, coding agents and other services. Launch a template with the abx CLI, then use its returned sandbox ID and the template startup guide to connect from Python. Named application commands require that service to be running.
| Package | Runs where | Guide |
|---|---|---|
agent-sandbox-client |
Your application | Client SDK |
agent-sandbox-server |
Inside a sandbox image | Server SDK |
The server exposes registered application commands over HTTP. Template authors install the server in their images and define the service startup. Client and server packages share a version; see the server API guide for command registration and authentication.
| Task | Guide |
|---|---|
| Run agents through one Gateway endpoint | Managed Agents API |
| Make your first API calls | Getting started |
| Look up methods and models | API reference |
| Configure credentials and endpoints | Authentication |
| Invoke registered application functions | Explicit arguments and authentication |
| Configure file and process behavior | File and command controls |
| Move existing E2B code | Migration guide |
| Resolve errors | Troubleshooting |
See the full documentation index, examples and changelog.
The abx CLI provides terminal operations, template builds and launches. Install it separately when your workflow requires it.
Join the Agent Sandbox 开发者工具交流群 on DingTalk to discuss usage and share feedback. Join the group or search for group number 213605001586.
Scan the QR code with DingTalk:
See CONTRIBUTING.md for the development environment and checks for both packages. Report SDK and runtime issues in this repository.
Apache-2.0. See NOTICE for attribution.