AIO Sandbox — 架构与原理

30 秒导读: AIO Sandbox 是一个把「浏览器 + 终端 + 文件系统 + 代码执行 + MCP 工具」全装进一个 Docker 容器的运行环境,专门给 AI agent 用。它们共享同一个文件系统(浏览器下载的文件,终端立刻能 ls 到),并统一通过一个 :8080 端口、一套 /v1/... HTTP API 操作。可以把它想成「一台给 AI 远程操控的电脑」。

1. 这是什么(零基础也能懂)

一句话定义: AIO(All-In-One)Sandbox 是一个预装好浏览器、Shell、文件工具、Python/Node 运行时和 MCP 服务的 Docker 镜像,启动后通过 HTTP API 把这些能力暴露给 AI agent。

它解决谁的什么问题。 假设你在写一个 AI agent,要它「打开网页、下载一个 CSV、用 Python 处理、再把结果存成文件」。传统做法是拼装好几个单一用途的沙箱:一个跑浏览器、一个跑代码、一个跑 shell。麻烦在于——

Traditional sandboxes are single-purpose (browser, code, or shell), making file sharing and functional coordination extremely challenging.（README.md:79)

它们彼此不共享文件系统,浏览器下载的文件代码沙箱看不见,你得手动在沙箱之间搬数据。AIO 的核心卖点就是把它们塞进一个容器、一个文件系统,从根上消掉这道协调成本。

它能做什么(对外能力):

跑 shell 命令(两种模式:交互式 PTY 终端 / 程序化管道,见第 2 章)
读写 / 搜索 / 监听文件,上传下载
执行 Python(Jupyter 内核)和 JavaScript(Node)
完整浏览器:CDP、VNC 远程桌面、像素级 GUI 动作、Playwright 式页面操作(见第 3 章)
一个聚合多个服务的 MCP Hub,直接当 agent 工具用(见第 4 章)
内置 VSCode(code-server)和 Jupyter 的 Web UI
把容器内启动的服务(如 localhost:3000 的前端)通过主端口预览

用起来什么样。 启动就一条 docker run,然后用 SDK 像操作一个远程对象一样调用各能力:

# 示意,基于 README.md:127-144 的真实用法
from agent_sandbox import Sandbox

client = Sandbox(base_url="http://localhost:8080")          # 指向容器
home = client.sandbox.get_context().home_dir                # 拿环境信息

client.shell.exec_command(command="curl -O https://x/data.csv")  # 浏览器/终端共享同一 FS
out = client.jupyter.execute_code(code="import pandas as pd; print(pd.read_csv('data.csv').shape)")
print(out.data)                                              # 同一文件,Python 立刻读到

一句话直觉/类比: 把它当成一台租给 AI 的远程电脑——有桌面(VNC)、有终端、有 IDE、有浏览器,而 :8080 上的 HTTP API 就是这台电脑的「遥控器」。所有 app 共用一块硬盘,所以彼此的产物天然互通。

2. 顶层全景(它大概怎么转)

怎么读这张图: 上半部是「一个对外端口如何分流」,下半部是「所有子系统共享同一个文件系统」。

          AI agent / SDK / curl / 浏览器
                       │  全部打到一个端口
                       ▼
          ┌─────────────────────────────┐
          │   :8080  统一 HTTP 入口       │  ← 鉴权(JWT/API-Key)在这层拦
          └───────────────┬─────────────┘
          按路径前缀分流 │
   ┌──────────┬──────────┼──────────┬───────────┬──────────┐
   ▼          ▼          ▼          ▼           ▼          ▼
 /v1/...    /mcp      /vnc/     /code-server/  /proxy/N/   /cdp/
 REST API   MCP Hub   远程桌面   VSCode Web    预览容器内    Chrome
 （遥控器）  （agent   （人看)    （人用)      起的服务     DevTools
            工具聚合)
   │
   └── shell · bash · file · jupyter · nodejs · code · browser ·
       browser/page · mcp · skills · proxy · sandbox · auth · ...
                       │
                       ▼
          ┌─────────────────────────────┐
          │  共享文件系统(WORKSPACE)     │  ← 所有子系统读写同一块盘
          │  浏览器下载 → 终端可见 → 代码读 │
          └─────────────────────────────┘

部件一句话职责:

部件	干什么	路径前缀 / 入口
统一 HTTP 入口	一个 `:8080` 端口,按路径前缀把请求分到各子系统;鉴权在这层	`:8080`
REST API	agent 操作沙箱的主接口,按子系统分命名空间	`/v1/<子系统>/...`
MCP Hub	把 browser/file/shell/markitdown 等聚合成标准 MCP 工具	`/mcp`
VNC	把容器内的图形桌面 / 浏览器投给人看	`/vnc/index.html`
code-server	浏览器里的完整 VSCode	`/code-server/`
预览代理	把容器内 `localhost:<port>` 的服务通过主端口暴露	`/proxy/<port>/`
CDP	直连 Chrome DevTools Protocol,给 Playwright/Puppeteer 用	`/cdp/`、`/v1/browser/info`
共享文件系统	所有子系统的「同一块硬盘」,`WORKSPACE` 是默认工作目录	`$WORKSPACE`

主线走一遍(高层,不进代码): agent 通过 SDK 把请求打到 :8080 → 入口层先做鉴权 → 按路径前缀(/v1/shell、/mcp、/proxy/3000 …)分给对应子系统 → 子系统在容器内执行(跑命令 / 操作浏览器 / 跑代码),产物落到共享文件系统 → 下一个子系统(可能是另一种能力)直接读到这些产物。「共享文件系统」就是把所有能力黏在一起的胶水。

3. 一个关键的认知:这个 repo 里有什么、没有什么

这点先说清楚,免得你找错地方:

核心运行时(那个真正跑浏览器/终端/代码的服务)不在这个开源 repo 里——它以 Docker 镜像 ghcr.io/agent-infra/sandbox 形式发布(README.md:38-41)。
这个 repo 里的源码是:多语言 SDK(Python / TypeScript / Go,sdk/)、官网与指南文档(website/docs/)、示例(examples/)、以及一个工具评测框架(evaluation/)。
所以本文档的「真实源码引用」主要锚定在 SDK 客户端(它精确反映了服务端 API 契约——SDK 由 Fern 从 API 定义自动生成,sdk/python/agent_sandbox/client.py:1)和指南文档。涉及服务端内部实现细节、容器内进程编排的部分,代码在镜像里看不到,文中会明确标注 (inferred) 或「代码里看不出」。

4. 阅读地图(建议顺序)

章节	讲什么	适合什么时候读
01-runtime-and-entrypoints	容器里有什么、`:8080` 怎么分流、生命周期 hook、JWT/API-Key 鉴权	想搞懂「这台机器怎么开机、怎么进门」
02-shell-bash-code	两套命令执行(PTY Shell vs 管道 Bash)+ 统一代码执行	想让 agent 跑命令 / 跑代码,纠结用哪个接口
03-browser	一个浏览器、四种控制层(CDP/VNC/GUI 动作/页面操作)	做 browser-use / computer-use 类 agent
04-mcp-skills-proxy	MCP Hub、Skills 包、入站预览代理 + 出站代理	想用标准 MCP 接入,或预览容器内 web 服务

5. 巧妙之处(一句话提炼,详见各章)

一个文件系统是整套设计的「主定理」。 跨能力协作的成本被设计成零——浏览器、终端、代码、文件 API 全读写同一块盘(README.md:81、website/docs/en/guide/advanced/workspace.md)。
命令执行故意做成两套:PTY 的 /v1/shell(给人 / REPL / 交互程序)和管道的 /v1/bash(给 agent,stdout/stderr 分离 + 偏移增量读)。这是「人用」与「机器用」两种读写模型的工程化分家(详见第 2 章)。
浏览器有四层控制,从最底的像素 GUI 动作到最高的 Playwright 页面语义,覆盖 computer-use 与 browser-use 两类范式(详见第 3 章)。
入站预览代理让 agent「自己起一个前端服务、再用浏览器访问它」成为闭环(/proxy/<port>/,详见第 4 章)。

6. 代码地图(导航索引)

主题	文件路径	符号名
顶层 SDK 入口(列出全部子系统)	`sdk/python/agent_sandbox/client.py`	`Sandbox`, `AsyncSandbox`
子系统命名空间(20 个)	`sdk/python/agent_sandbox/client.py:106-264`	`sandbox/shell/bash/file/jupyter/nodejs/code/mcp/browser/...` 属性
顶层架构图与卖点	`README.md:69-86`、`README.md:264-276`	—
共享文件系统 / WORKSPACE	`website/docs/en/guide/advanced/workspace.md`	`WORKSPACE`, `exec_dir`
SDK 由 API 定义自动生成	`sdk/fern/generators.yml`、`sdk/python/agent_sandbox/client.py:1`	Fern

7. 横向对比

AIO Sandbox 在 ai-agent-reference 的 agent-runtime 区里属于「给 agent 的执行环境/沙箱」一类。它的取舍是广度优先 + 单容器共享 FS:不追求单一能力做到极致,而是把 browser/shell/code/file 全聚到一台机器、用一个 FS 黏合,再用一个 MCP Hub 统一暴露给 agent。与「只给代码执行的沙箱」或「只给浏览器的沙箱」相比,它换来的是跨能力工作流零搬运成本,代价是单容器内的资源耦合与隔离边界更粗(安全靠把入口端口锁在 localhost + JWT,见第 1 章)。

1. 这是什么(零基础也能懂)​

2. 顶层全景(它大概怎么转)​

3. 一个关键的认知:这个 repo 里有什么、没有什么​

4. 阅读地图(建议顺序)​

5. 巧妙之处(一句话提炼,详见各章)​

6. 代码地图(导航索引)​

7. 横向对比​