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

背景

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

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

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

不同功能沙箱共享协作

不同 Agent 在沙盒环境的预装包不同

介绍

• 官网：sandbox.agent-infra.com

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

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

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

AIO（All-in-One）沙箱

• 📦 开箱即用：通过 /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）。

  

AIO Sandbox

Replay：

Replay：

快速上手

云函数部署 AIO Sandbox

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

本地 Docker 启动

系统架构

AIO Sandbox 面向 Agent 提供 Browser、File、Shell、Code 等基础能力，提供可扩展性支持开发者根据 Agent 需求组合与定制专属沙箱（如 AIO Sandbox for 移动端/医疗/法务/金融/科研）。

沙箱定制程度依次递增：

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

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

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

Sandbox 可扩展架构

AIO Sandbox 组件图

浏览器

面向 Agent 的浏览器环境，核心在于提供出 CDP 和 VNC，主流 Browser Use 框架都可以直接使用；

AIO 提供了基于 x11 的浏览器 GUI 视觉操作接口，可以与 CDP 方式组合出更高效、更低风控率的 Browser Use 方案。

AIO Sandbox Browser 架构

CDP

CDP （Chrome Devtools Protocol）是一种用于与 Chrome 或 Chromium 浏览器通信的协议，通过 WebSocket 提供浏览器控制 API，可以执行导航与加载、DOM 操作、JS 执行/调试、网络拦截与模拟、截图与渲染、安全与权限等。

为更直观了解，以下示例是用 CDP 发起一个 navigate 页面导航指令：

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

访问 http://localhost:9222/json/version，其中webSocketDebuggerUrl 就是 CDP 地址：

$ 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"}

与 CDP 建立 WebSocket 连接后，就可以执行浏览器指令：

Navigate www.toutiao.com

GUI 视觉操作

截图

不同于基于 CDP 的截图，视觉的截图  /v1/browser/screenshot 是带 Tabs（即整个浏览器窗口），操作也是面向整个浏览器窗口。

不同于 CDP 的浏览器操作，视觉操作 /v1/browser/actions 上模拟人类行为进行点击、输入、滑动等操作，可以减少目标网站的风控策略。

统一动作空间

将 GUI 操作抽象为可组合的最小原子动作，如移动鼠标、点击、拖动、滚动、按键、输入文本，以及额外的工具函数如等待，尽可能对齐 VLM 视觉模型在执行实际动作的一致性。

接管

当 Browser Use 遇到要登录的情况，一般需要人工接管，需要提供可交互的浏览器界面，目前有两种做法：

1. VNC 接管：AIO Sandbox 提供 /vnc/index.html 页面，用户可直接交互。

两种接管方式的差异大致如下：

命令行解释器

对于 Coding Agent，大部分任务都可以通过命令行执行完成。设计 Shell 模块时，以 OpenHands 的 CmdRunAction （见文末参考2）为执行引擎，配合 tmux，实现多会话（multi-session）执行能力。

文件操作

文件/代码编辑只需要两个工具就足够：

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

• str_replace（精确字符串替换）

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

• undo_edit（撤销）

代码执行

综合权衡语言覆盖与镜像体积，使用 Sandbox Fusion（见文末参考4） 里的 Python 3.10/3.11/3.12 与 Node.js 22 运行时，并为代码执行提供一体化的安全隔离环境。

通过统一入口 /mcp 聚合多个 MCP Server（例如 chrome-devtools-mcp），支持参数级过滤，并可为工具名添加前缀（namespacing）。

/mcp 支持 MCP Servers 过滤

按 search 过滤 MCP Servers，后续将扩展标签（tags）与类别（category）等多维过滤，减少冗余调用并降低模型 token 开销。

AIO Sandbox 正向代理原理

为什么 Chrome 有 --proxy-server 指定代理，为什么要引入 TinyProxy 代理服务器？

在 Chromium 官方文档（见文末参考5）写明不会使用任何嵌入在代理设置里的用户名/密码（例如 http://user:pass@host:port 这种），认证要走单独的质询弹窗，影响整个 Browser Use 使用（如下图）：

带用户名密码代理会出现弹窗

反向代理

AIO Sandbox 反向代理原理

提供两种访问 Sandbox 内部服务端口的方法：

Agent 在沙箱里会产生用户数据，为了在不侵入、不修改任何既有业务路由配置、同时不增加未来扩展的路由配置的心智负担的前提下，实现 AIO Sandbox 全局统一鉴权，在内部 Nginx 网关层设计了“非对称加密+JWT”反向代理架构来实现鉴权：

如何开启（一次配置）

• 生成密钥对

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

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

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

签发 JWT

业务服务用私钥生成一个有效期为 1 小时的 JWT，以下是简化的脚本来生成 JWT，实际中业务后端应使用成熟的 JWT 库：

# 这是一个简化的脚本来生成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}"

使用

1. Header 鉴权

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

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

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脚本模拟客户端拼接URLvnc_url="http://localhost:8080/vnc/index.html?ticket=${ticket}&path=websockify%3Fticket%3D${ticket}"
echo"客户端构建的最终URL: ${vnc_url}"
# 模拟访问 (实际应在浏览器中进行)# curl -I "${vnc_url}"

扩展与生态

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

from agent_sandbox import Sandbox
client = Sandbox(base_url="http://localhost:8080")
# Execute Shellshell_res = client.shell.exec_command(command="ls -la")print(shell_res.data.output) # /home/gem
# Browser Screenshotscreenshot = client.browser.screenshot()print(screenshot)
# Get Browser CDPbrowser_info = client.browser.get_browser_info()cdp_url = browser_info.data.cdp_url # ws://
# Read Filefile_res = client.file.read_file(file="/home/gem/.bashrc")print(file_res.data.content)

browser-use

只需增加 4 行代码接入社区的 browser-use（https://github.com/browser-use/browser-use）：

browser-use + AIO Sandbox

LangGraph-DeepAgents

LangGraph-DeepAgents + AIO Sandbox

from openai import OpenAIfrom agent_sandbox import Sandboximport 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()

目前最佳的公有云部署形态是函数计算，并基于 Sandbox 指定实例访问能力：

一键部署 All-in-One Sandbox 应用--函数服务-火山引擎：

https://www.volcengine.com/docs/6662/1851199

火山引擎- 函数服务 - 一键部署 AIO

总结与展望

AIO Sandbox 提供一体化、可定制的基座环境（Agent Env），使 Agent 能在同一环境内完成浏览、执行代码、运行命令与文件操作等多样化任务，并支持根据不同 Agent 定制专属的领域沙盒。这一沙盒体系也将伴随 Agent 智能上限的提升与开发者创造力的激发，持续进化与扩展。

后续，我们将围绕稳定性、可观测性与生态集成持续打磨，不断完善评测体系与最佳实践，推动 AIO Sandbox 在更多大规模、高要求的 Agent 应用场景中实现稳健落地与高效运行。

附录