Agent Sandbox — Examples

English | 中文

Examples are split by which package they exercise.

Client SDK scripts run on your machine. They create a sandbox or talk to one that is already up: quickstart/, compat-demos/, agents/, scenarios/, and templates/python-hello/call_api.py.

Server SDK code runs inside the sandbox image. It is commands.py in templates/python-hello/ and templates/agents-cli/. Those files import agent_sandbox.server and call start(9000). They do not create the cloud sandbox.

Prerequisites

1. Install the SDK

# Full install (recommended — includes the declarative decorator, MCP server, ...)
pip install "agent-sandbox[all]"

# Or install selectively
pip install "agent-sandbox[declarative]"   # @sandbox decorator only

# From source (run from the python-sdk repository root)
pip install -e ./server-sdk -e ./client-sdk

# The abx CLI is a separate Node.js project (the `cli` repository)
npm install -g @agent-sandbox/cli

2. Configure Credentials

# Option 1: Environment variable
export ABX_SANDBOX_API_KEY="your-api-key"

# Option 2: CLI config (persisted to ~/.abx/config.toml; requires the abx CLI)
abx config set sandbox_api_key your-api-key

# For the Codex Agent example, also set:
export OPENAI_API_KEY="your-openai-key-here"

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.

Client SDK examples

Directory Structure

examples/
├── quickstart/                # Client SDK — create and use a sandbox
├── agents/                    # Client SDK — call an Agents API or a cloud sandbox
├── compat-demos/              # Client SDK — E2B-style and Modal-style calls
├── scenarios/                 # Client SDK — local create, exec, read, kill
└── templates/                 # Server SDK — commands.py starts inside the image
    ├── python-hello/commands.py
    ├── python-hello/call_api.py   # Client SDK: HTTP to a server that is already up
    └── agents-cli/commands.py

templates/ keeps only the minimal python-hello fixture used by offline tests. Official & community templates — content, index (awesome-templates.yaml), releases and CI — live in the single-source-of-truth repository alibaba-agent-sandbox/awesome-templates; discover and install them with abx template search / abx template install <name>.

Server SDK examples

templates/ — Server SDK

commands.py in python-hello and agents-cli is what the image starts. It imports agent_sandbox.server.

call_api.py is Client SDK. It talks to a server that is already running (GET /health, GET /capabilities, GET /commands, one upload, one shell). The base URL comes from argv or ABX_TEMPLATE_URL; the token comes from ABX_SERVER_TOKEN. Request and response shapes are in the template server HTTP API guide (中文).

Example Catalog

quickstart/ — Client SDK

agents/ — Client SDK

compat-demos/ — Client SDK

Running Examples

# Basic example
python examples/quickstart/01_hello.py

# Data analysis
python examples/quickstart/04_data_analysis.py

# @sandbox decorator
python examples/quickstart/05_decorator_usage.py

# E2B-style API usage
python examples/compat-demos/e2b_data_analysis.py

Core API Reference

Execution Methods

from agent_sandbox import Sandbox

async with await Sandbox.create(template="base", api_key="...") as sandbox:

    # 1. Bare shell — sandbox.commands.run(cmd)
    proc = await sandbox.commands.run("echo hello")
    print(proc.stdout, proc.exit_code)

    # 2. Code interpreter — sandbox.run_code(code)
    code_result = await sandbox.run_code("print(1 + 1)")
    print(code_result.text)   # "2"

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

Note: sandbox.run(name, **kwargs) calls a command registered in the template's server; it never runs a shell string. Use sandbox.commands.run(cmd) for that.

File Operations

    # Write and read files
    await sandbox.files.write("/app/data.txt", "content")
    content = await sandbox.files.read("/app/data.txt")

Network

    # Get public URL for a port
    url = sandbox.network.get_url(3000)

Declarative Decorator

from agent_sandbox.declarative import sandbox

@sandbox(template="code-interpreter", packages=["numpy"])
def compute(n: int) -> float:
    import numpy as np
    return float(np.random.random(n).mean())

result = compute(1000)  # runs in a remote sandbox automatically