Agent Sandbox

English | 中文

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

Agent Sandbox is the command-line interface (abx) for the Alibaba Cloud FC Agent Sandbox service. The Python SDK lives in the python-sdk repository (see Python SDK). Template build and deploy live in this CLI. The runtime client is the Python SDK. Method names there are E2B-shaped to ease migration; neither the CLI nor the SDK is an E2B-protocol drop-in.

Features

• CLI (abx) — create, inspect, exec, upload/download, deploy, and manage sandboxes from the terminal.
• Template system — reusable sandbox images (Python, Node, browser automation, AI agent harnesses, …).
• MCP server — expose sandbox operations as MCP tools for LLM agents.
• Agent skill — a static Agent Skills guide (SKILL.md) for Qoder, Claude Code, Cursor, Qwen Code, and Codex.
• Runs anywhere Node runs — Node.js >= 20 (npm / npx), or a standalone binary with no runtime required.

The SDK-side features (async-first Sandbox API, the run / run_code execution primitives, the @sandbox declarative decorator, session persistence, and the E2B compatibility layer) are documented in the Python SDK section.

Installation

Requires Node.js >= 20.

# Install globally from npm
npm install -g @agent-sandbox/cli

# Or run without installing
npx @agent-sandbox/cli --help

Standalone binary (no Node.js required)

abx also ships as a precompiled standalone binary for macOS (Apple Silicon / Intel), Linux (x64 and arm64), and Windows (x64, .exe) — no Node.js installation required. Binaries are published for every release on GitHub Releases.

macOS / Linux (replace 0.3.0 with the release you want; OS and ARCH are auto-detected):

VERSION=0.3.0
OS=$(uname -s | tr '[:upper:]' '[:lower:]')   # darwin or linux
ARCH=$(uname -m); case "$ARCH" in
  x86_64) ARCH=x64 ;;
  arm64|aarch64) ARCH=arm64 ;;
esac

# Download somewhere the current user can write, then install onto PATH.
curl -fsSL -o "$HOME/abx" \
  "https://github.com/alibaba-agent-sandbox/agent-sandbox/releases/download/v${VERSION}/abx-${VERSION}-${OS}-${ARCH}"
chmod +x "$HOME/abx"
sudo mv "$HOME/abx" /usr/local/bin/abx

Windows (PowerShell):

$VERSION = "0.3.0"
$asset = "abx-$VERSION-windows-x64.exe"

# Download the release asset
Invoke-WebRequest `
  -Uri "https://github.com/alibaba-agent-sandbox/agent-sandbox/releases/download/v$VERSION/$asset" `
  -OutFile $asset

# Move it to a directory on your PATH (create it first if needed)
$installDir = "$env:LOCALAPPDATA\Programs\abx"
New-Item -ItemType Directory -Force -Path $installDir | Out-Null
Move-Item $asset "$installDir\abx.exe"

Checksums, the full platform matrix, and binary vs. npm trade-offs: Binary Installation (中文).

Using with AI coding tools

The repository ships a static Agent Skills guide (SKILL.md) that teaches Qoder, Claude Code, Cursor, Qwen Code, and Codex how to operate Agent Sandbox. Install it before (or without) the abx CLI:

# Fast path (requires Node.js); swap qoder for claude-code / cursor / qwen-code / codex,
# add -g for user-level scope, --list to preview
npx skills add agent-sandbox/agent-sandbox --skill agent-sandbox -a qoder -y

No Node.js? Copy SKILL.md into your tool's skills directory (for example ~/.qoder/skills/agent-sandbox/SKILL.md). Full tool matrix, version pinning, upgrades, uninstall, and security notes: Agent Skill Installation & Distribution (中文).

CLI (abx)

# Configure credentials
abx config init                          # credentials + region (--build / --llm add sections)
abx config set sandbox_api_key <YOUR_API_KEY>   # or set one key directly

# Sandbox lifecycle
abx create --template python-base       # create a sandbox
abx list                                 # list running sandboxes
abx info <sandbox-id>                    # inspect a sandbox
abx exec <sandbox-id> -- echo hello       # run a command (--cwd/--env/--timeout/--stream/--background)
abx run <sandbox-id> <name> --arg k=v    # named command registered on the in-sandbox server
abx connect <sandbox-id>                 # line-based command REPL

# File transfer
abx upload <sandbox-id> ./local.txt /remote/path.txt
abx download <sandbox-id> /remote/path.txt ./local.txt

# Template management
abx template list                        # list templates
abx template info python-base            # template details
abx template install owner/repo          # install from GitHub

# Template deployment (Alibaba Cloud template API, bundled with the CLI)
abx template create registry.cn-hangzhou.aliyuncs.com/ns/repo:tag --name my-tpl
abx template deploy ./examples/templates/python-hello \
    --acr-namespace my-ns --acr-repo python-hello

# Template lifecycle: author -> publish -> launch
abx template init --adopt ./app --hint "port 8080" # 1a. adapt an existing project
abx template init "a python web server"             # 1b. template generation writes ./<name>/ (optional)
abx deploy ./app --acr-namespace my-ns              # 2. build, push to ACR, register (no LLM)
abx create --template <TEMPLATE_ID>                 # 3. launch a sandbox

# MCP server
abx mcp start                            # start MCP tool server

# Cleanup
abx kill <sandbox-id>

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. Discover and install them through the remote index:

# Discover templates through the remote index
$ abx template search web
Name      Description       Tags           Status
node-web  Node.js web app   nodejs, web    official

$ abx template install node-web                                        # install by index name
$ abx template install alibaba-agent-sandbox/awesome-templates//node-web@v1.0.0 # or pin a ref

examples/templates/ (in the python-sdk repository) 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).

Python SDK

The Python SDK — the async-first Sandbox API, the declarative @sandbox decorator, session persistence, the E2B compatibility layer, and the layered architecture behind them — lives in the python-sdk repository. The quick start, the execution API (sandbox.run() / sandbox.run_code() / sandbox.custom()) and the architecture documentation are maintained there.

# Client SDK (import agent_sandbox)
pip install agent-sandbox

# Server runtime used inside template images (import agent_sandbox.server)
pip install agent-sandbox-server

agent-sandbox-server is the container-side runtime: template Dockerfiles and commands.py install it with pip install agent-sandbox-server. The abx CLI is no longer shipped with the Python packages (there is no [cli] extra); install it with npm install -g @agent-sandbox/cli.

Documentation

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

Tutorials & Guides

Reference

Design & Architecture

Related SDK documentation

The Python SDK, the in-sandbox server SDK and the shared platform contracts are documented in the python-sdk repository: documentation index, SDK Usage, Architecture, SDK API Design, Template System, Template YAML Spec, Declarative Usage, Session Persistence, Migrate from E2B, and examples/.

Other Resources

Contributing

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

License

Apache-2.0 — see NOTICE for copyright information.