Agent Sandbox

Launch templates: start the complete template and access all declared services.

English | 中文

Standard E2B migration contract

Cloud sandboxes for AI agents — create, execute, and manage isolated environments in seconds.

Agent Sandbox is a Python SDK for sandboxes. The default provider is Alibaba Cloud Express (alicloud-express, Function Compute). OpenSandbox, the container edition, CubeSandbox, and E2B are catalog node plugins in awesome-providers (provider.mjs). Install one with abx provider install alibaba-agent-sandbox/awesome-providers//<id> --allow-unpinned --yes (or python -m agent_sandbox.providers install registry:<id> --yes). After that, both abx --provider <id> and ProviderSandbox.create(provider="<id>") use it. The Python SDK reaches a node provider through the local engine (abx provider engine serve; abx on PATH or ABX_BIN). The CLI loads Express plus installed node, exec and rest plugins. It is the standard sync/async runtime and Template client. Project provider/server template launches use abx template build|deploy from the CLI. The SDK uses E2B-shaped method names so that E2B code ports with few changes; the standard API follows Alibaba-supported E2B behavior (see Migrate from E2B).

This repository (python-sdk) contains the Python SDK, packaged as two lock-step distributions. The abx command-line tool is a separate Node.js project that lives in the agent-sandbox repository (see Related: the abx CLI).

Folder	Distribution	Import path	Purpose
client-sdk/	agent-sandbox-client	agent_sandbox	Sync/async client SDK: Sandbox, AsyncSandbox, ProviderSandbox, files, commands, code interpreter, named commands, declarative @sandbox, Agents API client, MCP server, E2B migration helper
server-sdk/	agent-sandbox-server	agent_sandbox.server	Container-side runtime: the persistent HTTP service (default port 9000) that runs inside a sandbox image

Both distributions share the agent_sandbox namespace (the client owns agent_sandbox/__init__.py, the server only ships agent_sandbox/server/) and are versioned in lockstep with the same version number.

Client SDK runs on your machine: create a sandbox and use it. Guide: Client SDK. Examples: examples/quickstart/, examples/compat-demos/, examples/agents/, examples/scenarios/.

Server SDK runs inside the sandbox image: the HTTP service the image starts. Guide: Server SDK. Examples: examples/templates/python-hello/commands.py, examples/templates/agents-cli/commands.py.

Sites

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.

---

Provider management operations are available through agent_sandbox.providers.commands; see the provider command guide.

Client SDK

• Sync and async standard clients — Sandbox.create() and AsyncSandbox.create(), shell execution, code interpretation, file I/O, port forwarding, and WebSocket streaming.
• Explicit execution entry points — process execution, the standard interpreter client, and template application commands have separate runtime requirements (see Execution API below).
• MCP server — expose sandbox operations as MCP tools for LLM agents.
• Declarative decorator — @sandbox turns a plain function into a remote sandbox execution with automatic serialisation.
• Standard sync/async clients — agent_sandbox exports the standard Sandbox and AsyncSandbox; see Migrate from E2B.

Server SDK

• In-image HTTP service — commands.py imports agent_sandbox.server and calls start(9000).
• Registered commands — @command functions become routes the Client SDK calls with sandbox.run.
• Agents API — Codex and Qwen Code HTTP sessions inside the sandbox. Install a CLI when you call it. Guide: Agents API.
• Templates — the image and template.yaml are built and deployed with abx template build|deploy.

Installation

Use Python 3.10 or newer in a virtual environment. The client installs its matching server dependency automatically. See the installation guide for a pinned version, optional extras and development setup.

python -m pip install --upgrade --pre agent-sandbox-client
python -m pip check

--pre opts into alpha releases. The command-line tool is installed separately: see the abx CLI.

Do not run pip install agent-sandbox; that PyPI name belongs to an unrelated project.

Quick Start

Configure ABX_SANDBOX_API_KEY, ABX_SANDBOX_BASE_URL, ABX_SANDBOX_DOMAIN. Replace E2B imports as described in the migration guide.

from agent_sandbox.code_interpreter import Sandbox

sandbox = Sandbox.create(template="code-interpreter-v1")
try:
    print(sandbox.commands.run("printf hello").stdout)
    print(sandbox.run_code("1 + 1").text)
finally:
    sandbox.kill()

Provider and server extensions

Set ABX_SANDBOX_API_KEY, ABX_SANDBOX_BASE_URL and ABX_SANDBOX_DOMAIN, then create a native instance and execute a process with ProviderSandbox:

import asyncio
from agent_sandbox import ProviderSandbox

async def main():
    sandbox = await ProviderSandbox.create(template="base", provider="alicloud-express")
    try:
        result = await sandbox.commands.run("python3 -c 'print(2 ** 10)'")
        print(result.stdout)  # 1024
    finally:
        try:
            await sandbox.kill()
        finally:
            await sandbox.close()

asyncio.run(main())

This python3 invocation is a process, not a persistent interpreter. Interpreter operations absent from a provider return E8004; the standard code_interpreter.Sandbox above is a separate entry point. close() releases client connections; kill() deletes the instance.

Execution API

Entry point	Purpose	Requirement
ProviderSandbox.commands.run()	Execute a process and read stdout, stderr and exit code	Provider implements process operations
Standard code_interpreter.Sandbox.run_code()	Execute interpreter code	A matching native runtime such as code-interpreter-v1
ProviderSandbox.application_client()	Call application commands registered by a template HTTP service	Start the template service and supply the correct port and application token

Named application commands are registered by the in-sandbox server. Follow template startup to create or connect to that application, preserving provider gateway headers, URL prefixes and query parameters; do not assume base registers hello. See Providers for cross-language plugin execution.

Templates

Official and community templates live in the alibaba-agent-sandbox/awesome-templates repository — the single source of truth for template content, the index, and publishing. The index is consumed by the abx template search|install commands (Related: the abx CLI); the template.yaml contract that templates follow is defined in the Template YAML Spec.

examples/templates/ only keeps a minimal python-hello fixture for offline tests — it is not a publishing source. See examples/templates/README.md for the fixture contract and index behaviour (caching, offline fallback, pinned refs).

Architecture

graph TB
    L5["L5 Agent — MCP server, Agents API client"]
    L4["L4 Declarative — @sandbox decorator"]
    L3["L3 API — Sandbox, Files, Code, Commands"]
    L2["L2 Protocol — envd REST + WebSocket"]
    L1["L1 Transport — HTTP/2, API Key, envd token"]
    GW["Alibaba Cloud FC"]

    L5 --> L4 --> L3 --> L2 --> L1 --> GW

Loading

Lower layers never import upper layers. Full design: docs/en/design/architecture.md.

Documentation

Full documentation index: docs/README.md (bilingual navigation)

Tutorials & Guides

Guide	Link
Getting Started	Getting Started
Best Practices	Best Practices
Accessibility	Accessibility
File and command controls	File and command controls
Hosted agents	Hosted agents
SDK Usage	SDK Usage
Authentication	Authentication
Environment Variables	Environment Variables
Authoring Templates	Authoring Templates
Build & Deploy (CLI)	Build & Deploy
Declarative Usage	Declarative Usage
Binary MCP files	Upload/download
Background MCP tasks	Reconnectable tasks
MCP Integration	MCP Integration
Session Persistence	Session Persistence
Migrate from E2B	Migrate from E2B
Troubleshooting	Troubleshooting

Reference

Document	Link
API Reference	API Reference
Configuration	Configuration
Error Codes	Error Codes
Template YAML Spec	Template YAML Spec

Design & Architecture

Document	Link
Design Index	Design Index
Architecture	Architecture
SDK API Design	SDK API Design
Template System	Template System

Other Resources

Resource	Link
Changelog	CHANGELOG.md
Contributing Guide	CONTRIBUTING.md
License	Apache-2.0
Examples	examples/
SDK skill	agent-sandbox-sdk/SKILL.md — how an agent writes a client and a template

Related: the abx CLI

The abx command-line tool (@agent-sandbox/cli, Node.js) is developed in the agent-sandbox repository. It shares sandboxes, templates and credentials with this SDK. Its installation, command reference, tutorials, MCP server commands and the Agent Skill (SKILL.md) are documented there:

• CLI README — installation (CLI binary installation)
• CLI Tutorial · CLI Reference
• Agent Skill Installation & Distribution

Named commands support native list[str] JSON arguments. See the server API guide for validation and server compatibility.

Contributing

We welcome contributions! Please read the Contributing Guide to get started.

License

Apache-2.0 — see NOTICE for copyright information.

Builtin runtime architecture and Python engine migration.

Provider-owned pause/resume and Snapshot commands share one implementation across CLI and SDK; see the registration and usage guide.

Current API / 当前接口: development contract.