Agent Sandbox

English | 中文

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

Agent Sandbox is a Python SDK for the Alibaba Cloud FC Agent Sandbox service. It is the runtime client: create, use and kill sandboxes. Building and deploying templates is done with abx template build|deploy from the CLI. The SDK uses E2B-shaped method names so that E2B code ports with few changes; it is not a drop-in replacement (see Migrate from E2B).

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

Both distributions share the agent_sandbox namespace (the client owns agent_sandbox/__init__.py, the server only ships agent_sandbox/server/) and are released 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.

Client SDK

• Async-first — Sandbox.create(), shell execution, code interpretation, file I/O, port forwarding, and WebSocket streaming.
• Three execution primitives — sandbox.commands.run() (bare shell), sandbox.run_code() (code interpreter), sandbox.run("name", **kwargs) (a command the Server SDK registered).
• 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.
• Session persistence — save and restore sandbox state across runs.
• E2B-shaped methods — agent_sandbox.compat covers part of the E2B surface; 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

# Core client SDK only
pip install agent-sandbox

# Everything (MCP + fast JSON + sessions + declarative + server)
pip install "agent-sandbox[all]"

# Container-side runtime (install this inside your sandbox image)
pip install agent-sandbox-server
pip install playwright                       # only if you enable the browser capability group

# Development (from the repository root; includes test & lint tooling for both packages)
pip install -e ./server-sdk -e "./client-sdk[dev]"

agent-sandbox depends on agent-sandbox-server of the same version, so pip install agent-sandbox also provides agent_sandbox.server (needed locally by the @sandbox decorator's server proxy). The [server] extra is kept as a harmless alias.

The abx CLI is no longer part of the Python package (there is no [cli] extra and no abx console script); it is distributed from the cli repository (see Related: the abx CLI).

Quick Start

import asyncio
from agent_sandbox import Sandbox

async def main():
    async with await Sandbox.create(template="python-base") as sandbox:

        # 1. Bare shell — sandbox.commands.run(cmd)
        proc = await sandbox.commands.run("echo 'Hello from sandbox!'")
        print(proc.stdout)          # Hello from sandbox!
        print(proc.exit_code)       # 0

        # 2. Code interpreter — sandbox.run_code(code)
        result = await sandbox.run_code("print(2 ** 10)")
        print(result.text)          # 1024

        # 3. Named command — sandbox.run(name, **kwargs)
        #    POST /commands/hello on the in-sandbox SandboxServer
        greeting = await sandbox.run("hello", name="Alice")
        print(greeting)             # the registered function's return value

        # 4. File operations
        await sandbox.files.write("/tmp/data.txt", "content")
        content = await sandbox.files.read("/tmp/data.txt")

        # 5. Port access
        url = sandbox.network.get_url(3000)

asyncio.run(main())

Execution API

Three execution methods, each for a distinct use case:

Named commands have one mechanism: server-side registered commands. A command is registered with @sandbox.register (or CommandRegistry) inside the template, and sandbox.run("name", **kwargs) sends POST /commands/name to the in-sandbox SandboxServer. An unknown name raises CommandNotFoundError; await sandbox.list_commands() lists what the server has registered. See Declarative Usage.

Environment variables: envd uses direct exec — shell features ($VAR, pipes, redirects) require sh -c '...'. Use printenv VAR to read a variable. See the Environment Variables guide (EN) | 环境变量指南 (中文) for details.

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, AK/SK"]
    GW["Alibaba Cloud FC"]

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

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

Documentation

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

Tutorials & Guides

Reference

Design & Architecture

Other Resources

Related: the abx CLI

The abx command-line tool (@agent-sandbox/cli, Node.js) is developed in the cli 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 (npm install -g @agent-sandbox/cli)
• CLI Tutorial · CLI Reference
• Agent Skill Installation & Distribution

Contributing

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

License

Apache-2.0 — see NOTICE for copyright information.