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

字节跳动开源2025-10-31 12:21

文章来源｜字节跳动 Web Infra x veFaas 团队

项目地址｜github.com/agent-infra...

引言：AI Agent 在执行复杂任务时，常需在浏览器、代码执行、文件系统之间切换。传统多沙箱方案面临环境割裂、数据搬运、鉴权复杂等问题。AIO Sandbox 通过一个 Docker 镜像整合所有能力，提供统一文件系统与鉴权，并支持镜像定制，提升了 Agent 任务执行与交付效率。

01 背景

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

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

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

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

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

痛点

  1. 🧩 环境割裂：多个单功能沙盒（如 E2B 支持代码执行，Browserbase 支持浏览器）迫使 Agent 通过 NAS/OSS 跨沙箱传输数据，增加延迟与复杂度。如：深度研究 Agent 完成『将一篇论文 Paper 做成 PPT』需在多沙箱间交换数十个中间文件（JSON 配置、图表图片、预览截图等），增加整个 Agent 系统复杂度和开销。
不同功能沙箱共享协作
  1. 🎁 定制困难：不同类型的 Agent 需要预装不同的技术栈，传统沙箱提供统一的预装环境，既无法满足所有 Agent 的个性化需求。
不同 Agent 在沙盒环境的预装包不同

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

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

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

一台配置完善的电脑能显著提升人类的办公效率；同样，一个功能强大的沙箱环境也能提升 Agent 的任务质量与执行速度。

02 介绍

一句话介绍：AIO Sandbox 在一个沙盒内集成浏览器、代码执行、终端、可视化接管、正反向代理、MCP、鉴权等基础功能，可根据需求进行沙盒环境定制，让不同的 Agent"在一个环境容器内中更高效地完成任务"。

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）。

03 示例

指令 回放 使用的AIO功能
Help me design an interesting website to introduce elementary school children to sauropod dinosaurs of the Jurassic and Cretaceous periods. I hope the site is in a cartoon style. 帮我设计一个有趣的网站，为在上小学的孩子介绍侏罗纪和白垩纪时期的蜥脚类恐龙。希望网站是卡通风格的。 Replay - 浏览器操作 - DOM 操作（/v1/browser/info） - 截图（/v1/browser/screenshot） - 视觉操作（/v1/browser/actions） - 执行命令（/v1/shell/exec） - 文本编辑器工具（/v1/file/str_replace_editor） - 端口转发（反向代理）
Search Bytedance Seed1.6 News And Deploy Web 搜索关于字节跳动Seed1.6模型的新闻，然后以现代风格编写一个网页并部署 Replay 同上
Based on this picture, please find the latest information on the Internet and design a modern website for it. 根据这张OSWorld图片，请在互联网上查找最新信息并为其设计一个现代化的网站。 Replay 同上
Goto: poki.com/zh/g/2048, start play 玩Poki 2048游戏 Replay 同上

更多见:seed-tars.com/showcase/ui...

04 快速上手

云端

一键部署 All-in-One Sandbox 应用--函数服务-火山引擎： www.volcengine.com/docs/6662/1...

本地

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

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

05 系统架构

整体

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图像识别）。

基础组件

浏览器

面向 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 页面导航指令：

sql 复制代码 
'/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 地址：

bash 复制代码 
$ 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

注：AIO Sandbox 不直接暴露 CDP 接口 /json/version，而是通过 uvicorn 服务中转 CDP 并增加了心跳检测，避免出现 ws 断连问题。

GUI 视觉操作

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

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

统一动作空间

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

action_type 描述 必需参数 可选参数
MOVE_TO 移动鼠标到指定位置 x, y -
MOVE_REL 移动当前鼠标的相对位置 x_offset, y_offset -
CLICK 点击操作 - x, y, button, num_clicks
MOUSE_DOWN 按下鼠标按钮 - button
MOUSE_UP 释放鼠标按钮 - button
RIGHT_CLICK 右键点击 - x, y
DOUBLE_CLICK 双击 - x, y
DRAG_TO 拖拽到指定位置 x, y -
DRAG_REL 当前鼠标拖拽的相对位置 x_offset, y_offset -
SCROLL 滚动操作 - dx, dy
TYPING 输入文本 text -
PRESS 按键 key -
KEY_DOWN 按下键盘按键 key -
KEY_UP 释放键盘按键 key -
HOTKEY 组合键 keys (数组) 例如：["ctrl", "c"] -
WAIT 等待 duration 时间（秒 s） -

接管

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

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

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

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

对比维度 VNC Canvas + CDP（Chrome DevTools Protocol）
技术原理 远程桌面协议，传输整个屏幕像素 通过 CDP 控制浏览器，Canvas 渲染内容
传输协议 RFB (Remote Framebuffer) WebSocket + CDP
传输内容 完整浏览器画面（有 Tabs） 仅浏览器当前 page 内容（默认没有 Tabs，可以单独实现）
带宽占用 高（10-50 Mbps） 低（1-5 Mbps）
延迟 较高（50-200ms） 较低（10-50ms）
稳定性 不易断连 易断连，需要手动增加与 CDP 心跳，避免断连
CPU占用 高（桌面编码） 低（仅浏览器渲染）
内存占用 高（需要完整桌面环境） 低（仅浏览器进程）
控制范围 整个浏览器 仅浏览器内部页面
自动化能力 基础（鼠标键盘模拟） 强大（DOM操作、网络拦截、JS注入等）
多窗口支持 ✅ 支持 ❌ 仅单个浏览器窗口
文件操作 ✅ 可以操作本地文件 ❌ 受浏览器沙箱限制

命令行解释器

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

文件操作

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

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

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

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

  • str_replace（精确字符串替换）

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

  • undo_edit（撤销）

代码执行

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

MCP Servers 聚合器

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

/mcp 支持 MCP Servers 过滤

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

代理

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

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

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

正向代理

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

AIO Sandbox 正向代理原理

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

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

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

反向代理

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

  1. subdomain 泛域名转发（推荐）：只要满足 _ <math xmlns="http://www.w3.org/1998/Math/MathML"> p o r t − {port}- </math>port−{domain}_ 的域名格式，都会被转发到沙盒内的端口上。
  1. subpath 子路径转发：会遇到非常多问题：对于路由敏感服务（如前端项目）会因为额外的/proxy|absproxy/${端口}路径造成资源匹配 404。

鉴权

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

如何开启（一次配置）

  • 生成密钥对
cs 复制代码 
openssl genrsa -out private_key.pem 2048
openssl rsa -in private_key.pem -pubout -out public_key.pem
echo "密钥对生成完毕！"
  • 启动服务（带公钥开启鉴权），使用环境变量 JWT_PUBLIC_KEY
bash 复制代码 
export JWT_PUBLIC_KEY=$(cat public_key.pem | base64)
JWT_PUBLIC_KEY="${JWT_PUBLIC_KEY}"

签发 JWT

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

ini 复制代码 
# 这是一个简化的脚本来生成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 鉴权
nginx 复制代码 
curl --silent -X GET "http://localhost:8080/v1/sandbox" \
     -H "Authorization: Bearer ${jwt}"
  1. 短时票据鉴权示例（以 VNC 页面访问为例）：直接访问无法通过加 Header 方式完成鉴权，只能通过?ticket=票据以 query 参数方式发起访问。
  • 使用 JWT 从通用端点获取票据（默认有效期是 30s，要增加通过TICKET_TTL_SECONDS环境变量配置）
bash 复制代码 
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 复制代码 
# 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}"

06 扩展与生态

定制镜像

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

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

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

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

bash 复制代码 
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

SDK 集成

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

makefile 复制代码 
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)

更多使用示例参考：agent-infra/sandbox#examplesgithub.com/agent-infra...

browser-use

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

browser-use + AIO Sandbox

完整代码见：文末参考7

LangGraph-DeepAgents

LangGraph-DeepAgents + AIO Sandbox

完整代码见：langgraph-deepagents#main.py

自定义工具集

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

python 复制代码 
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()

部署

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

一键部署 All-in-One Sandbox 应用--函数服务-火山引擎： www.volcengine.com/docs/6662/1...

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

07 总结与展望

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

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

附录

名词解释

参考

  1. Docker：www.docker.com/get-started...

  2. CmdRunAction：github.com/All-Hands-A...

  3. str_replace_editor：docs.claude.com/zh-CN/docs/...

  4. Sandbox Fusion：bytedance.github.io/SandboxFusi...

  5. Chromium 官方文档：chromium.googlesource.com/chromium/sr...

  6. fern：buildwithfern.com/learn/sdks/...

  7. 完整代码：github.com/agent-infra...

  8. UI-TARS-2 Technical Report: Advancing GUI Agent with Multi-Turn Reinforcement Learning：arxiv.org/pdf/2509.02...

  9. AIO Sandbox: All-in-One Sandbox for AI Agents & Developers：medium.com/coding-nexu...

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

  11. Writing effective tools for AI agents---using AI agents：www.anthropic.com/engineering...

  12. Unifying the Computer Use Action Space：scrapybara.com/blog/unifie...

相关推荐
字节跳动数据平台8 小时前
火山引擎多模态数据湖解决方案，以新一代数据基座迎接AI Agent时代
agent
数据智能老司机8 小时前
使用 Python 入门 Model Context Protocol（MCP）——深入解析模型上下文协议（MCP）
llm·agent·mcp
常先森8 小时前
【解密源码】 RAGFlow 切分最佳实践-上传与解析全流程
架构·llm·agent
白衣鸽子9 小时前
ListUtils：Java列表操作的瑞士军刀
后端·开源·设计
星光一影20 小时前
供应链进销存源码uniapp全开源ERP多仓库管理系统pc+app手机端
mysql·elementui·uni-app·开源·php·phpstorm·1024程序员节
DO_Community1 天前
利用腾讯开源 Hunyuan3D 2.1：在 DigitalOcean GPU Droplet 上快速搭建 3D 模型
人工智能·3d·开源·llm·aigc·大语言模型
大模型教程1 天前
解锁 MCP 的力量：9 个令人惊叹的项目，让你重新思考 AI 工程
程序员·llm·agent
热门推荐
01GitHub 镜像站点02UV安装并设置国内源03BongoCat - 跨平台键盘猫动画工具04GitLab 零基础入门指南：从安装到项目管理全流程05Linux下V2Ray安装配置指南06NVIDIA显卡驱动、CUDA、cuDNN 和 TensorRT 版本匹配指南07Labelme从安装到标注：零基础完整指南08安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）09在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）10jdk21下载、安装（Windows、Linux、macOS）