一天一个开源项目（第226篇）：AIO Sandbox —— 把浏览器、Shell、文件、MCP、VSCode 塞进同一个容器的 Agent 沙箱

引言

"Agent 需要的不是五个各自为战的工具，而是一个所有工具都能看见同一份文件的环境。"

这是"一天一个开源项目"系列的第 226 篇。今天的项目是 AIO Sandbox。

给 AI Agent 搭执行环境,常常会遇到一个琐碎但很烦人的问题:浏览器自动化用一套容器,代码执行用另一套沙箱,文件存储又是第三个服务。三者之间传文件、传状态,全靠手写胶水代码——浏览器下载的文件,Shell 脚本读不到;Jupyter 生成的结果,又要额外一步搬运才能给浏览器工具用。每接入一个新工具,就多一份集成成本。

AIO Sandbox(项目全名 agent-infra/sandbox)想解决的正是这种"工具孤岛"问题。它把浏览器自动化、Shell 终端、文件操作、MCP 服务、VSCode Server 全部塞进同一个 Docker 容器,核心卖点是一套跨工具共享的统一文件系统——浏览器里下载的文件,立刻就能在 Shell 命令或文件 API 里直接用,不需要任何搬运环节。

6.0k Stars,Apache-2.0 协议,已经跑通了与 Browser Use、LangChain、OpenAI Assistants、MiniMax 等主流框架的集成。

你将学到什么

AIO Sandbox 的分层架构:浏览器/VNC 层、开发工具层、MCP 集成层、基础设施层
"统一文件系统"如何消除工具间的数据搬运成本
内置的四组 MCP Server:browser、file、shell、markitdown
如何用 Docker/Docker Compose/Kubernetes 三种方式部署
与 Browser Use、LangChain、OpenAI Assistants 等框架的实际集成方式

前置知识

熟悉 Docker 基本操作(run、compose)
了解 MCP(Model Context Protocol)的基本概念
可选:了解 Chrome DevTools Protocol(CDP)和浏览器自动化的基本原理

项目背景

项目简介

AIO Sandbox 的官方定位是"一个统一了浏览器、Shell、文件、MCP 操作与 VSCode Server 的一体化 Agent 沙箱环境",基于云原生的轻量级沙箱技术构建。项目文档中明确指出传统沙箱方案的痛点:"传统沙箱通常是单一用途的(浏览器、代码或 Shell),这使得文件共享和功能协调变得极其困难"——AIO Sandbox 正是针对这个痛点给出的统一方案。

团队与项目信息

所属组织:agent-infra
协议:Apache License 2.0
部署方式:Docker 容器(也支持 Kubernetes)
官方 SDK:Python(agent-sandbox)、TypeScript/JavaScript(@agent-infra/sandbox)、Go(agent-sandbox-sdk-go)

项目数据

⭐ GitHub Stars:6,000+
🍴 Forks:534
👀 Watchers:32
📄 协议:Apache-2.0
📊 提交次数:130 Commits(主分支)

主要功能

解决什么问题

没有 AIO Sandbox 的 Agent 环境搭建：
  浏览器自动化 → 用 Playwright/Puppeteer 容器 A
  代码执行     → 用 Jupyter/Sandbox Fusion 容器 B
  文件存储     → 用独立的文件服务 C
  ↑ 三者互不相通，浏览器下载的文件要手动搬运才能给容器 B 用
  ↑ 每接入一个新工具，都要重新写一遍跨容器数据传递逻辑
 
AIO Sandbox 的做法：
  浏览器 + Shell + 文件 + MCP + VSCode 全部塞进同一个容器
  ↓ 统一文件系统作为底层共享层
  浏览器下载文件 → Shell 命令直接读 → Jupyter 直接处理 → 文件 API 直接写回
  ↑ 所有工具看见的是同一份文件系统，无需搬运

使用场景

AI Agent 工具执行与浏览器自动化
- Agent 需要打开网页、点击交互、抓取内容,同时还要执行代码处理抓取结果
网页转 Markdown 的处理流水线
- 官方给出的示例:用 Playwright 通过 CDP 抓取网页 → Jupyter 内的 markdownify 转换 HTML → 文件 API 读回结果,全程在同一个容器内完成
需要可视化调试的 Agent 开发
- 通过 VNC 远程桌面直接观察浏览器自动化的执行过程,或用 VSCode Server 直接调试沙箱内代码
多框架集成的沙箱执行层
- 作为 Browser Use、LangChain、OpenAI Assistants 等框架的统一执行后端,不需要为每个框架单独搭建执行环境

快速开始

Docker 一键启动:

docker run --security-opt seccomp=unconfined --rm -it \
  -e SANDBOX_API_KEY=your-secret-key \
  -p 127.0.0.1:8080:8080 ghcr.io/agent-infra/sandbox:latest

启动后可访问:

/v1/docs —— API 文档
/vnc/index.html —— VNC 远程桌面
/code-server/ —— VSCode Server
/mcp —— MCP 服务入口

国内用户可使用镜像仓库地址替代 ghcr.io。生产环境建议使用固定版本号(如 1.11.0)而非 latest,保证部署可复现。

安装 SDK:

# Python
pip install agent-sandbox
 
# TypeScript/JavaScript
npm install @agent-infra/sandbox
 
# Go
go get github.com/agent-infra/sandbox-sdk-go

核心特性

1. 统一文件系统

跨浏览器、Shell、文件操作、Jupyter 共享同一套文件系统,是整个项目的核心设计——省去了工具间传递文件的胶水代码。

2. 内置四组 MCP Server

MCP Server	核心能力
browser	navigate、screenshot、click、type、scroll
file	read、write、list、search、replace
shell	exec、create_session、kill
markitdown	convert、extract_text、extract_images

3. 多种访问接口

VNC(远程桌面)、VSCode Server、Jupyter Notebook、WebSocket 终端——同一个沙箱可以用最适合当前任务的方式访问。

4. 核心 REST API

/v1/sandbox、/v1/shell/exec、/v1/file/read、/v1/file/write、/v1/browser/screenshot、/v1/jupyter/execute 等接口覆盖了 Agent 常见的执行需求。

5. 三种部署方式

部署方式	适用场景
Docker(单命令)	本地开发、快速试用
Docker Compose	需要数据卷持久化的场景(带 `shm_size: "2gb"` 等配置)
Kubernetes	生产环境集群部署(带资源限制,如 `memory: "2Gi"`、`cpu: "1000m"`)

6. 认证机制

通过 SANDBOX_API_KEY 环境变量启用鉴权,支持 Header、Bearer Token 或 Query 参数三种方式,统一覆盖 API、JupyterLab 和 VNC 访问;不设置该变量则保持开放状态(向后兼容)。

深入剖析

分层架构:从可视化到基础设施的四层堆叠

AIO Sandbox 的架构可以理解为四层堆叠:

浏览器 + VNC 层（可视化）
  ↓
VSCode Server + Shell 终端 + 文件操作 层（开发层）
  ↓
MCP Hub + Sandbox Fusion 层（集成层）
  ↓
Preview Proxy + 服务监控 层（基础设施层）

所有层共享同一个容器和同一套文件系统。这个设计的关键在于:它不是把多个独立服务用网络接口拼起来,而是让它们在同一进程环境和文件系统命名空间内运行。这消除了跨容器/跨服务通信带来的序列化开销和一致性问题——不需要考虑"浏览器容器写的文件,Shell 容器什么时候能读到"这类分布式系统的经典难题。

统一文件系统解决的实际痛点

来看官方给出的典型工作流,能直观理解这个设计解决了什么:

1. 用 Playwright 通过 CDP 连接沙箱的浏览器，抓取一个网页
2. 网页内容 → 直接写入沙箱文件系统
3. 调用 Jupyter 里的 markdownify，把 HTML 转换成 Markdown
4. 转换结果 → 通过文件 API 直接读回

在传统的多容器方案里,第 2 步和第 3 步之间需要一次跨容器的文件传输(可能是 volume mount、对象存储中转,或者 API 调用把文件内容当作 payload 传递)。在 AIO Sandbox 里,这一步就是同一个文件系统里的一次普通文件写入和读取——没有额外的传输层,也没有额外的失败点。

MCP 作为统一接入协议的意义

AIO Sandbox 选择用 MCP 协议封装 browser、file、shell、markitdown 四组工具,而不是各自定义一套 REST API 规范。这个选择的好处是:任何已经支持 MCP 客户端的 Agent 框架(Claude Code、其他 MCP 兼容工具)都能"零配置"地接入这个沙箱的全部能力,不需要为 AIO Sandbox 专门写一层适配代码。这和"每个沙箱都自定义一套私有 API,接入一个新工具就要写一次适配层"的传统模式相比,省掉了大量重复的集成工作。

框架集成的实际接法

README 展示了几种典型框架的接入方式,能看出这个沙箱的设计意图是"作为执行后端被别人调用",而不是自成一套 Agent 框架:

框架	集成方式
browser-use	把 `BrowserSession` 连接到沙箱的 CDP 端点,复用沙箱里的浏览器实例
LangChain	把 `shell.exec_command` 包装成自定义 `BaseTool` 子类接入工具链
OpenAI Assistants / Function Calling	暴露一个 `run_code` 工具,路由到沙箱内的 Jupyter 或 Node.js 执行
MiniMax	通过 OpenAI 兼容 API(`base_url="https://api.minimax.io/v1"`)调用,注意 MiniMax 要求 `temperature > 0`

这种"甘当执行层,不抢框架的位置"的定位,意味着它可以被广泛嫁接到已有的 Agent 生态里,而不需要用户放弃已经在用的编排框架。

与传统单一用途沙箱的对比

维度	传统单一用途沙箱(纯浏览器/纯代码执行)	AIO Sandbox
工具覆盖	通常只覆盖一类能力	浏览器+Shell+文件+MCP+VSCode 一体
跨工具文件共享	❌ 需要手动搬运/额外中转层	✅ 统一文件系统,天然共享
接入协议	各自定义 API	✅ 标准化 MCP 协议
可视化调试	视沙箱类型而定,通常缺失	✅ VNC + VSCode Server 双通道
部署方式	视项目而定	✅ Docker / Compose / K8s 三种规格
定位	独立工具	甘当执行后端,兼容主流 Agent 框架

项目地址与资源

官方资源

🌟 GitHub:https://github.com/agent-infra/sandbox
📄 协议:Apache License 2.0
🐛 Issues:GitHub Issues
💬 社区:GitHub Discussions

总结与展望

核心要点回顾

统一文件系统是核心设计:消除浏览器、Shell、代码执行之间的文件搬运成本,所有工具共享同一份文件系统
同容器架构而非跨容器编排:浏览器、Shell、文件、MCP、VSCode 全部运行在同一个进程环境里,避免分布式一致性问题
MCP 作为统一接入协议:四组内置工具(browser/file/shell/markitdown)都通过 MCP 暴露,兼容已有的 MCP 客户端生态
甘当执行后端:与 Browser Use、LangChain、OpenAI Assistants、MiniMax 的集成都是"被调用"而非"取代",不与已有编排框架竞争
三种部署规格覆盖不同场景:从本地单命令试用到 Kubernetes 生产集群,部署路径完整

适合谁

AI Agent 开发者:需要一个统一的执行环境,而不想为浏览器自动化、代码执行、文件存储分别搭建基础设施
多框架并用的团队:已经在用 LangChain、Browser Use 等框架,想要一个通用的执行后端而不是重新造轮子
需要可视化调试的场景:通过 VNC/VSCode Server 直接观察 Agent 执行过程,而不是只能看日志
MCP 生态的使用者:想要一套开箱即用、覆盖浏览器/文件/Shell 的 MCP Server,不想自己维护

一句话评价

AIO Sandbox 没有试图做一个更聪明的 Agent 框架,而是先解决了一个更基础的问题——让 Agent 用到的工具们,至少能看见同一份文件系统。

欢迎访问 PrimeSkills —— 一个精心策划的 AI Agent 与技能市场，所有内容均经过真实企业级工作流验证。没有噱头，只有真正有效的东西。

更多实用知识和有趣产品，欢迎访问我的个人主页

引言