AIO Sandbox：为 AI Agent 打造的一体化、可定制的沙箱环境

随着 LLM 的持续演进，AI 的应用形态经历了三代跃迁：

• Chatbot：对话式交互，回答问题

• Copilot：辅助协作，提升效率

• Agent：自主执行，完成任务

Agent 能够自主感知环境、规划步骤、调用工具，能够像人类一样操作计算机：自动浏览网页收集信息、生成并运行代码分析数据、执行系统命令管理文件，甚至通过可视化界面完成复杂的多步骤操作。这种能力使 Agent 的交付成果接近甚至超越人类专业水准。

1. 🧩 环境割裂：多个单功能沙盒（如 E2B 支持代码执行，Browserbase 支持浏览器）迫使 Agent 通过 NAS/OSS 跨沙箱传输数据，增加延迟与复杂度。如：深度研究 Agent 完成『将一篇论文 Paper 做成 PPT』需在多沙箱间交换数十个中间文件（JSON 配置、图表图片、预览截图等），增加整个 Agent 系统复杂度和开销。

2. 🎁 定制困难：不同类型的 Agent 需要预装不同的技术栈，传统沙箱提供统一的预装环境，既无法满足所有 Agent 的个性化需求。

3. 🔒 安全隔离难：既要让 Agent 拿到真实系统能力（网络、文件、浏览器、GPU），又要强隔离避免越权与数据外泄。

4. 🖥️ 可视化交互困难：复杂 Agent 任务需要人工接管，功能沙箱需要集成 VNC、Terminal、VSCode 保持一致体验。分辨率切换、截图与 GUI 视觉操作。

5. 🌐 浏览器环境复杂度高：反自动化与指纹风控，CDP 不稳定性、带用户名密码的代理支持不完善、GUI 操作缺失。

• 官网：sandbox.agent-infra.com

• Github：github.com/agent-infra/sandbox

• API：sandbox.agent-infra.com/api

• 论文：arxiv.org/pdf/2509.02544#S2.SS2

• 📦 开箱即用：通过 /mcp 协议直连沙箱能力，同时提供 API / SDK 定制沙箱工具集。

• 🚀 秒启动：沙盒全服务启动在秒级完成，预缓存/冷启动后达到毫秒级拉起。

• 🌈 定制化：各垂直场景的 Agent 需配套领域工具与依赖；AIO 以统一镜像基座，用约定式路由和服务配置支持按需扩展。

• 🌐 浏览器：集成 Web Infra 的 RS 轻量内核，提供 CDP、截图、纯视觉 GUI 操作、Proxy 代理配置。

• 🔄 人工接管：提供 浏览器 VNC、Code Server、Terminal，支持任务中途人工接管与调试。

• 📡 代理与转发：支持带账密的正向代理；将 {port}-{domain} 泛域名或 /proxy|/absproxy/{port} 路径映射到沙箱内服务（便于预览/演示）。

• 🔒安全鉴权：JWT Bearer 访问控制；对无法携带 Header 的链接提供短时票据（Short-Lived Ticket）。

  

前置需要安装 Docker（见文末参考1），一键本地启动：

docker run --rm -it -p 8080:8080 enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest

• Standard（开箱即用）：通过 /mcp 接入点对 Agent 即插即用，适用于快速 PoC Agent 验证。

• Custom Toolset（工具 / Skills 扩展）：不改镜像，基于 SDK / API 增加或编排工具（如增加 web_search 搜索）；同时扩展出 Skills 实现特定沙盒任务的自动化处理。

• Custom Image（定制镜像）：基于 FROM aio.sandbox 基础镜像，安装特定的基础依赖（如多媒体/图像处理等），挂载自定义服务（例如 /custom_tools/ocr  图像识别）。

'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome' \
    --disable-gpu \
    --user-data-dir=./test \
    --remote-debugging-port=9222 \
    https://www.chromestatus.com

$ curl http://localhost:9222/json/version
{
   "Browser": "Chrome/141.0.7390.66",
   "Protocol-Version": "1.3",
   "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36",
   "V8-Version": "14.1.146.11",
   "WebKit-Version": "537.36 (@95681a3c3d516c397b75ff45b8980c1088666775)",
   "webSocketDebuggerUrl": "ws://localhost:9222/devtools/browser/a6c5f19f-5d24-4bed-ba08-9c15cf5aeedb"
}

2. 前端通过 CDP 连接，在 Canvas 上实时重绘完整浏览器界面；我们把前端部分封装了一个组件 @agent-infra/browser-ui。如下左为实际浏览器，右为 browser-ui 投屏：

1. 文件增改查：封装文件读取/写入/列目录/新建/上传/下载等基础 I/O，配合路径校验与权限控制，覆盖通用文件操作场景。

2. 文本编辑器：实现面向模型的细粒度编辑工具 str_replace_editor（见文末参考3），支持：

• view（查看文件或目录，含行范围）

• str_replace（精确字符串替换）

• insert（按行插入，旧版支持）

• undo_edit（撤销）

在 Agent 沙箱里，一般涉及两类场景，分别对应正反向代理：

1. 正向代理：Browser Use Agent 可访问私有/全球网络

2. 反向代理：Coding Agent 在沙箱内开发的服务对外开放，供用户侧预览

正向代理

使用 TinyProxy 代理服务器，绕过地理限制、访问受限内容或在企业内网中提供安全访问。

1. subdomain 泛域名转发（推荐）：只要满足 ${port}-${domain} 的域名格式，都会被转发到沙盒内的端口上。

2. subpath 子路径转发：会遇到非常多问题：对于路由敏感服务（如前端项目）会因为额外的 /proxy|absproxy/${端口} 路径造成资源匹配 404。

openssl genrsa -out private_key.pem 2048
openssl rsa -in private_key.pem -pubout -out public_key.pem
echo "密钥对生成完毕！"

• 启动服务（带公钥开启鉴权），使用环境变量 JWT_PUBLIC_KEY

export JWT_PUBLIC_KEY=$(cat public_key.pem | base64)
JWT_PUBLIC_KEY="${JWT_PUBLIC_KEY}"

# 这是一个简化的脚本来生成JWT，实际中业务后端应使用成熟的 JWT 库 base64url_encode() { openssl base64 -e -A | tr '+/''-_' | tr -d '='; }
header='{"alg":"RS256","typ":"JWT"}'
exp_time=$(($(date +%s) + 3600))
payload="{\"exp\":${exp_time}}"
to_be_signed="$(echo -n "$header" | base64url_encode).$(echo -n "$payload" | base64url_encode)"
signature=$(echo -n "$to_be_signed" | openssl dgst -sha256 -sign private_key.pem | base64url_encode)
jwt="${to_be_signed}.${signature}"echo "JWT已生成: ${jwt}"

curl --silent -X GET "http://localhost:8080/v1/sandbox" \
     -H "Authorization: Bearer ${jwt}"

2. 短时票据鉴权示例（以 VNC 页面访问为例）：直接访问无法通过加 Header 方式完成鉴权，只能通过 ?ticket= 票据以 query 参数方式发起访问。

• 使用 JWT 从通用端点获取票据（默认有效期是 30s，要增加通过 TICKET_TTL_SECONDS 环境变量配置）

echo"使用JWT换取通用的一次性票据..."

ticket_response=$(curl --silent -X POST "http://localhost:8080/tickets" \
     -H "Authorization: Bearer ${jwt}")
     
ticket=$(echo"$ticket_response" | jq -r .ticket)
expires=$(echo"$ticket_response" | jq -r .expires_in)

echo"获取成功！票据: ${ticket}, 有效期: ${expires}秒"

• 客户端构建并使用 VNC URL：现在，就可以使用获取到的 ${ticket} 变量来构建 VNC URL 并发起访问了。

# Bash脚本模拟客户端拼接URL
vnc_url="http://localhost:8080/vnc/index.html?ticket=${ticket}&path=websockify%3Fticket%3D${ticket}"

echo"客户端构建的最终URL: ${vnc_url}"

# 模拟访问 (实际应在浏览器中进行)
# curl -I "${vnc_url}"

在 AIO 里，会按约定目录方式，自动挂载服务进程（supervisord）和服务路由（Nginx）

• 服务进程目录：/opt/gem/supervisord/*.conf

• 路由目录：/opt/gem/nginx/*.conf

如果在 AIO 镜像基础上定制服务和路由，可参考以下镜像代码：

FROM enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest

# ----------------------
# 安装额外系统依赖（若有）
# installed path: /usr/bin/*
# ----------------------
RUN set -eux; \
    apt-get update; \
    apt-get install -y --no-install-recommends \
        ${your_system_dep} \
        --no-install-recommends; \
    # clean up
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*;

# ----------------------
# npm 安装（若有）
# 
# ----------------------
RUN npm i -g ${your_npm_package}

# ----------------------
# python pip 安装（若有）
# installed path: /usr/local/bin/*
# ----------------------
RUN pip install ${your_python_package}

# 添加自定义 Server 服务
COPY ./supervisord.agent_server.conf /opt/tiger/run/supervisord/agent_server.conf
# 绑定 Nginx 路由
COPY ./nginx.agent_server.conf /opt/gem/nginx/nginx.agent_server.conf

# # 若不需要 AIO 里的服务，可进行删除，例如 Code Server
# ## 删除 Code Server 进程和路由
# RUN rm -rf /opt/gem/supervisord/supervisord.code_server.conf
# ## 删除 Code Server 路由
# RUN rm -rf /opt/gem/nginx/code_server.conf

借助 fern（见文末参考6）将 AIO Sandbox 里的接口文档直接转成 Python / Go / Node.js SDK，以 Python 为例，几行代码串联起 AIO Sandbox 里的核心功能：

from agent_sandbox import Sandbox

client = Sandbox(base_url="http://localhost:8080")

# Execute Shell
shell_res = client.shell.exec_command(command="ls -la")
print(shell_res.data.output) # /home/gem

# Browser Screenshot
screenshot = client.browser.screenshot()
print(screenshot)

# Get Browser CDP
browser_info = client.browser.get_browser_info()
cdp_url = browser_info.data.cdp_url # ws://

# Read File
file_res = client.file.read_file(file="/home/gem/.bashrc")
print(file_res.data.content)

可使用 API / SDK 来组合 Agent 所需要的高阶工具集，例如 link_reader给 url 地址返回页面内容：

from openai import OpenAI
from agent_sandbox import Sandbox
import json

client = OpenAI(
    api_key="your_api_key",
)
sandbox = Sandbox(base_url="http://localhost:8080")

tools = [{
    "type": "function",
    "function": {
        "name": "link_reader",
        "description": "渲染并读取网页，返回标题、正文与最终URL（基于CDP）。",
        "parameters": {
            "type": "object",
            "properties": {
                "url": {"type": "string", "format": "uri"},
                "timeout_ms": {"type": "integer", "default": 30000}
            },
            "required": ["url"]
        }
    }
}]

asyncdeflink_reader(url: str, timeout_ms: int = 30_000) -> dict:
    cdp_url = sandbox.browser.get_browser_info().cdp_url
    asyncwith async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(cdp_url)
        try:
            page = await browser.new_page()
            await page.goto(url, wait_until="networkidle", timeout=timeout_ms)
            title = await page.title()
            text = await page.evaluate("document.body.innerText || ''")
            return {"final_url": page.url, "title": title, "text": text[:8000]}
        finally:
            await browser.close()

1. Docker：

   https://www.docker.com/get-started/

2. CmdRunAction：

   https://github.com/All-Hands-AI/OpenHands/blob/2bbe15a329e35f5156cdafcbe63c3fd54978ff98/openhands/runtime/utils/bash.py#L494-L681

3. str_replace_editor：

   https://docs.claude.com/zh-CN/docs/agents-and-tools/tool-use/text-editor-tool

4. Sandbox Fusion：

   https://bytedance.github.io/SandboxFusion/

5. Chromium 官方文档：

   https://chromium.googlesource.com/chromium/src/%2B/HEAD/net/docs/proxy.md#proxy-credentials-in-manual-proxy-settings

6. fern：

   https://buildwithfern.com/learn/sdks/overview/introduction

7. 完整代码：

   https://github.com/agent-infra/sandbox/blob/b950470e6d70eabf9941b9a98a0affd15dd2e86c/sdk/python/examples/browser-use-integration/main.py

8. UI-TARS-2 Technical Report: Advancing GUI Agent with Multi-Turn Reinforcement Learning：

   https://arxiv.org/pdf/2509.02544

9. AIO Sandbox: All-in-One Sandbox for AI Agents & Developers：

   https://medium.com/coding-nexus/aio-sandbox-all-in-one-sandbox-for-ai-agents-developers-b0a5ca4cf2a8

10. Agentic AI基础设施实践经验系列（二）：专用沙盒环境的必要性与实践方案：

    https://aws.amazon.com/cn/blogs/china/agentic-ai-sandbox-practice/

11. Writing effective tools for AI agents—using AI agents：

    https://www.anthropic.com/engineering/writing-tools-for-agents

12. Unifying the Computer Use Action Space：

    https://scrapybara.com/blog/unified-action-space