Agent Sandbox — Design Document Index

Version: v2.0 | Last Updated: 2026-09-24

This document serves as the entry point and index for all Agent Sandbox design documentation. Detailed designs live in the specialized topic documents under design/.

Project Overview

Agent Sandbox (agent-sandbox on PyPI) is a Python SDK for the Alibaba Cloud FC Agent Sandbox service. It is the runtime client: create, use and kill sandboxes. Templates are built and deployed with abx template build|deploy. Method names are E2B-shaped to ease migration; it is not a drop-in replacement (see Migrate from E2B).

This repository holds the Python SDK as two lock-step PyPI distributions — agent-sandbox (client-sdk/, import agent_sandbox) and agent-sandbox-server (server-sdk/, import agent_sandbox.server, the container-side runtime). The abx CLI is a Node.js/TypeScript project in the cli repository, which holds the CLI's own design and guide documents (see Related: the abx CLI).

Core Principles

1. E2B-shaped, not E2B-compatible — E2B-style method names and a small migration helper (from agent_sandbox.compat import Sandbox) ease migration for existing E2B users; the wire protocol and configuration are the platform's own
2. AI-First — MCP Server as a first-class citizen, coding agents hosted through the Agents API
3. Zero Configuration Defaults — Works out of the box; from install to first sandbox in ≤ 3 lines of code

Quick Start

pip install agent-sandbox
export ABX_SANDBOX_API_KEY=your-api-key

from agent_sandbox import Sandbox

async with await Sandbox.create(template="base") as sb:
    result = await sb.run_code("print('Hello, Agent Sandbox!')")
    print(result.text)

Architecture Overview

The SDK follows a strict layered architecture — lower layers never import upper layers:

graph TB
    subgraph Upper["Upper Layers"]
        Agent["Agent/MCP — MCP server, tool defs"]
        Decl["Declarative — @sandbox decorator"]
        Compat["Compat — E2B migration helper"]
    end
    subgraph Core["Core Layers"]
        L3["API — Sandbox, files, code, commands, network, server client"]
        L2["Protocol — Sandbox lifecycle, filesystem, process, terminal, port"]
        L1["Transport — HTTP, WebSocket, auth, codec, streaming"]
        L0["Models + Utils — Pydantic models, errors, config, async bridge"]
    end

    Agent --> L3
    Decl --> L3
    Compat --> L3
    L3 --> L2 --> L1 --> L0

For the full architecture breakdown, see Architecture Design.

Design Topic Index

Each topic below has its own dedicated design document with complete specifications.

Core Design

Templates

AI & Agent Integration

Server & Infrastructure

Maintainer Design Documents (English only)

Working design documents for the provider, capability, server-v2 and agents-API workstreams. They have no Chinese counterpart.

Implementation Status

Related Resources

Related: the abx CLI

The abx CLI (Node.js / TypeScript, npm @agent-sandbox/cli) is documented in the cli repository; its design index is DESIGN.md. Most relevant to SDK readers: CLI Architecture, CLI Command System and Templates Catalog.