Agent Sandbox

English | 中文

为 AI Agent 打造的云沙箱 —— 秒级创建、执行、管理隔离环境。

Agent Sandbox 是基于阿里云函数计算（FC）Agent Sandbox 服务的命令行工具（abx）。 Python SDK 位于 python-sdk 仓库（见 Python SDK）。 模板的构建和部署在这个 CLI 里。运行时客户端是 Python SDK。那边的方法名接近 E2B，便于迁移；CLI 和 SDK 都不是 E2B 协议的直接替代。

特性

• CLI (abx) —— 创建、查看、执行、上传/下载、部署，从终端管理沙箱。
• 模板系统 —— 可复用的沙箱镜像（Python、Node、浏览器自动化、AI Agent Harness……）。
• MCP Server —— 将沙箱操作暴露为 MCP 工具，供 LLM Agent 调用。
• Agent Skill —— 静态 Agent Skills 指南（SKILL.md），适用于 Qoder、Claude Code、Cursor、Qwen Code、Codex。
• 随处可跑 —— Node.js >= 20（npm / npx），或无需任何运行时的独立二进制。

SDK 侧特性（异步优先的 Sandbox API、run / run_code 执行原语、@sandbox 声明式装饰器、会话持久化、E2B 兼容层）见 Python SDK 一节。

安装

需要 Node.js >= 20。

# 从 npm 全局安装
npm install -g @agent-sandbox/cli

# 或免安装直接运行
npx @agent-sandbox/cli --help

独立二进制（无需 Node.js）

abx 同时以预编译独立二进制形式发布，覆盖 macOS（Apple Silicon / Intel）、 Linux（x64 与 arm64）与 Windows（x64，.exe）—— 无需安装 Node.js 环境。二进制文件随每个 版本发布在 GitHub Releases。

macOS / Linux（把 0.3.0 换成目标版本，OS 与 ARCH 自动检测）：

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

# 先下载到当前用户可写的目录，再安装到 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"

# 下载 Release 资产
Invoke-WebRequest `
  -Uri "https://github.com/alibaba-agent-sandbox/agent-sandbox/releases/download/v$VERSION/$asset" `
  -OutFile $asset

# 移动到 PATH 中的目录（不存在则先创建）
$installDir = "$env:LOCALAPPDATA\Programs\abx"
New-Item -ItemType Directory -Force -Path $installDir | Out-Null
Move-Item $asset "$installDir\abx.exe"

校验和、完整平台矩阵与二进制/npm 对比详见 二进制安装（English）。

配合 AI 编码工具使用

仓库内置静态 Agent Skills 指南（SKILL.md），教 Qoder、Claude Code、Cursor、Qwen Code、Codex 等工具如何操作 Agent Sandbox——可先于（或无需）abx CLI 安装：

# 快捷方式（需 Node.js）；把 qoder 换成 claude-code / cursor / qwen-code / codex，
# 加 -g 安装到用户级，加 --list 仅预览
npx skills add agent-sandbox/agent-sandbox --skill agent-sandbox -a qoder -y

没有 Node.js？把 SKILL.md 复制到你的工具技能目录（例如 ~/.qoder/skills/agent-sandbox/SKILL.md）。完整工具目录矩阵、版本锁定、升级、卸载与安全提示见 Agent Skill 安装与分发（English）。

CLI (abx)

# 配置凭证
abx config init                          # 凭证 + 区域（--build / --llm 追加相应部分）
abx config set sandbox_api_key <YOUR_API_KEY>   # 或直接设置单个密钥

# 沙箱生命周期
abx create --template python-base       # 创建沙箱
abx list                                 # 列出运行中的沙箱
abx info <sandbox-id>                    # 查看沙箱详情
abx exec <sandbox-id> -- echo hello       # 执行命令（--cwd/--env/--timeout/--stream/--background）
abx run <sandbox-id> <name> --arg k=v    # 调用沙箱内服务器上注册的具名命令
abx connect <sandbox-id>                 # 逐行命令 REPL（每行一个新进程，不是 PTY）

# 文件传输
abx upload <sandbox-id> ./local.txt /remote/path.txt
abx download <sandbox-id> /remote/path.txt ./local.txt

# 模板管理
abx template list                        # 列出模板
abx template info python-base            # 模板详情
abx template install owner/repo          # 从 GitHub 安装

# 模板部署（阿里云模板 API，已内置于 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

# 模板生命周期：编写 -> 发布 -> 启动
abx template init --adopt ./app --hint "端口 8080"     # 1a. 适配已有项目
abx template init "一个 Python Web 服务"               # 1b. 模板生成写出 ./<name>/（可选）
abx deploy ./app --acr-namespace my-ns                 # 2. 构建、推送 ACR、注册（无需 LLM）
abx create --template <TEMPLATE_ID>                    # 3. 启动沙箱

# MCP 服务
abx mcp start                            # 启动 MCP 工具服务

# 清理
abx kill <sandbox-id>

环境变量： envd 使用直接执行（direct exec）—— Shell 特性（$VAR 展开、管道、重定向）需要 sh -c '...'。用 printenv VAR 读取变量值。详见环境变量指南（中文） | Environment Variables (EN)。

模板

官方与社区模板统一维护在 alibaba-agent-sandbox/awesome-templates 仓库——模板内容、索引与发布的唯一真源。通过远程索引发现与安装：

# 通过远程索引发现模板
$ abx template search web
Name      Description       Tags           Status
node-web  Node.js web app   nodejs, web    official

$ abx template install node-web                                        # 按索引名安装
$ abx template install alibaba-agent-sandbox/awesome-templates//node-web@v1.0.0 # 或锁定版本

examples/templates/（位于 python-sdk 仓库）仅保留一个最小的 python-hello **测试夹具（fixture）**用于离线测试，并非模板发布真源。夹具契约与索引行为 （缓存、离线回退、锁定版本）详见 examples/templates/README.md。

Python SDK

Python SDK —— 异步优先的 Sandbox API、@sandbox 声明式装饰器、会话持久化、E2B 兼容层，以及其分层架构 —— 位于 python-sdk 仓库。快速开始、执行 API（sandbox.run() / sandbox.run_code() / sandbox.custom()）与架构文档均在该仓库维护。

# 客户端 SDK（import agent_sandbox）
pip install agent-sandbox

# 模板镜像内使用的服务端运行时（import agent_sandbox.server）
pip install agent-sandbox-server

agent-sandbox-server 是容器内运行时：模板的 Dockerfile 与 commands.py 通过 pip install agent-sandbox-server 安装它。abx CLI 不再随 Python 包发布（不存在 [cli] extra），请使用 npm install -g @agent-sandbox/cli 安装。

文档

完整文档索引：docs/README.md（双语导航）

教程与指南

参考手册

设计与架构

相关 SDK 文档

Python SDK、沙箱内 Server SDK 与共享的平台契约的文档位于 python-sdk 仓库：文档中心、SDK 使用、架构设计、SDK API 设计、模板系统、Template YAML 规范、声明式用法、会话持久化、从 E2B 迁移 与 examples/。

其他资源

贡献

欢迎贡献！请阅读 贡献指南 了解详情。

许可证

Apache-2.0 —— 版权信息见 NOTICE。