Agent Sandbox is a sandbox SDK with pluggable providers. The default provider is Alibaba Cloud Express (Function Compute). The same API also has a Modal-style @sandbox decorator, and an in-sandbox Agents API for Codex and Qwen Code. Those CLIs are installed only when you use them.
Scope: this repository documents the Python SDK (
agent-sandbox-client) and the container-side runtime (agent-sandbox-server). TheabxCLI is a separate Node.js project with its own documentation set; see Related: the abx CLI.
| Site | URL |
|---|---|
| Official site | https://www.agent-sandbox.cn |
| Provider registry | https://registry.agent-sandbox.cn |
The installer fetches the catalog index at https://registry.agent-sandbox.cn/providers/index.json. ABX_PROVIDER_REGISTRY overrides that URL.
| Client SDK | Server SDK | |
|---|---|---|
| Where it runs | Your machine | Inside the sandbox image |
| What it does | Create a sandbox and use it | Build the HTTP service the sandbox keeps running |
| Package | agent-sandbox-client |
agent-sandbox-server |
| Import | agent_sandbox |
agent_sandbox.server |
| Start | Client SDK | Server SDK |
| Guide | Description |
|---|---|
| Client SDK | What this side is, and how the guides below fit together |
| Getting Started | Install, configure, first sandbox |
| Express quickstart | Deploy a generation-2 template and call a named command |
| SDK Usage | Commands, files, named commands, template author quick path |
| SDK skill | What a coding agent loads before writing a client or a template |
| Cloud end-to-end practice | Run the quickstart and compat demos on the default provider |
| Authentication | API key / AK-SK |
| Declarative usage | @sandbox decorator |
| MCP integration | Hand sandbox operations to an IDE |
| Session persistence | Local session storage |
| Migrate from E2B | Move from the E2B SDK |
| Providers | Choose, install, and write a provider |
| Environment variables | Injection and reads inside the sandbox |
| Troubleshooting | Common failures |
| Comparison | Next to E2B, Modal, and Docker Sandbox |
| Command and SDK map | Commands and methods next to E2B and OpenSandbox |
| Guide | Description |
|---|---|
| Server SDK | What this side is, and how commands.py starts |
| Authoring templates | template.yaml, capabilities, registered commands, Dockerfile |
| Template server HTTP API | Routes commands.py actually serves |
| Best practices | The server carries no provider; turn groups on only when needed |
| Fine-grained capabilities | Enable routes one endpoint at a time |
| File and command controls | Limit paths and commands |
| Agents API | Codex and Qwen Code HTTP sessions inside the sandbox |
| Hosted agents | How those routes refuse and what they return |
| Build and deploy | abx template build and abx template deploy |
How a change counts as tested: Testing and the Definition of Done.
reference/ — API / Configuration Reference
| Document | Description |
|---|---|
| API Reference | Client SDK public API |
| Configuration | Client SDK environment variables, config files, credential resolution |
| Error Codes | E1xxx–E8xxx error code index |
| Template YAML Spec | Server SDK template definition (template.yaml) |
| Server HTTP API | HTTP API of the Server SDK inside the sandbox |
| Agents API reference | Parameters and responses for each Agents route on the Server SDK |
explanation/ — Concepts & Architecture
| Document | Description |
|---|---|
| Architecture Overview | Layered architecture concepts |
| E2B Compatibility | What the E2B-shaped API shares with E2B, and where it differs |
| Sandbox Lifecycle | Create → Run → Hibernate → Destroy |
Start here only when you are changing the product. Day-to-day use is in the guides above. The user-facing Agents API is Agents API.
| # | Document | Description |
|---|---|---|
| 1 | Architecture Design | Layered architecture overview |
| 2 | SDK API Design | SDK public API specification |
| 3 | Sandbox Lifecycle and Ownership | Owned cleanup, borrowed connections and provider-dependent operations |
| 4 | MCP Server | MCP tool server design (Python server, HTTP app, FC artifact) |
| 5 | Template System | Template resolution, versioning and registry |
| 6 | Server API | In-sandbox HTTP server endpoints |
| 7 | Providers and Credentials | Canonical configuration names, provider plugins, EPP/1 |
| 8 | OpenSandbox provider | Current adapter and the live capability table |
| 9 | Container edition | alicloud-container |
| 10 | CubeSandbox provider | cubesandbox |
| 11 | E2B provider | e2b |
Other maintainer notes are indexed in DESIGN.md.
These pages are reviews or target design, not the current specification.
- Server SDK v2 target design
- Agents API review
- Fine-grained capabilities review
- Providers and credentials review
- OpenSandbox research
- OpenSandbox end-to-end notes
- CLI follow-ups
| Document | Description |
|---|---|
| Design Document | Design topic index and implementation status |
- Use a sandbox (Client SDK): Client SDK → Getting Started → SDK Usage
- Build the service inside the sandbox (Server SDK): Server SDK → Authoring Templates → Template server HTTP API
- Architect: Architecture → Server API
- MCP integration (Cursor/Claude): MCP Integration | MCP Server
- Template source of truth (awesome-templates): alibaba-agent-sandbox/awesome-templates — the single source of truth for official & community template content, the index (
awesome-templates.yaml), and publishing - 中文文档：Chinese docs
The abx CLI (npm @agent-sandbox/cli) is documented in the cli repository: documentation index, Getting Started, CLI Reference, CLI Architecture, CLI Command System, Templates Catalog, Deploy & Build, Agent Skill Installation.
The E2B migration contract defines synchronous Sandbox, asynchronous AsyncSandbox and the interpreter API; provider/server extensions use ProviderSandbox.