如何在单一沙箱中运行浏览器、终端和 VSCode 供 LLM 使用
当我首次为自主 AI 代理搭建技术栈时，很快就陷入了一堆不同服务的噩梦。浏览器运行在一个隔离的容器中，Python 解释器在另一个容器中，文件必须通过 S3 或临时卷挂载在它们之间来回传输。结果就是，代理在浏览器中下载了一个 PDF，却无法在 bash 会话中打开它，因为各个文件系统彼此隔离。
agent-infra 团队采取了一种务实的方法。他们构建了 AIO Sandbox 项目（All-in-One Agent Sandbox Environment，即一体化代理沙箱环境），将代理所需的所有基础设施打包到单一 Docker 容器中，共享磁盘。
盒子里有什么
该项目的概念很简单：为 LLM 提供所有必要开发者工具的访问权限，同时将一切与主机系统隔离。在单一镜像中，你获得：
- 无头 Chromium，支持 CDP 协议，可通过 VNC 直接在浏览器中远程访问
- VSCode Server（code-server）和交互式 Jupyter Notebook 用于代码执行
- WebSocket 终端用于运行 bash 命令
- 内置 MCP 服务器（Model Context Protocol），可直接与 Claude、Cursor 或自定义代理集成
- 用于预览端口和 Web 应用程序的代理服务
这种设置的主要优势是统一文件系统。如果代理通过 Playwright 保存截图或下载 CSV 到主目录，它可以立即用 bash 脚本读取该文件，在 Jupyter 中处理它，然后在代码编辑器中打开结果。无需复杂的同步或网络开销。
快速开始
你可以用一条命令在本地启动容器：
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
运行后，端口 8080 提供对完整工具套件的访问：
- API 文档：
http://localhost:8080/v1/docs - 通过 VNC 的浏览器桌面流：
http://localhost:8080/vnc/index.html?autoconnect=true - VSCode 编辑器的 Web 版本：
http://localhost:8080/code-server/ - MCP 端点：
http://localhost:8080/mcp
如果需要将环境部署到生产环境，仓库中包含 Docker Compose 和 Kubernetes 的现成清单。部署到云端时，端口 8080 应隐藏在带有身份验证的反向代理后面，因为代理在容器内执行任意代码。
如何通过代码使用沙箱
作者为 Python、TypeScript 和 Go 提供了官方 SDK。使用 API 非常简单。
安装 Python 包：
pip install agent-sandbox
基本的 shell 和文件操作：
from agent_sandbox import Sandbox
client = Sandbox(base_url="http://localhost:8080")
home_dir = client.sandbox.get_context().home_dir
# Выполняем bash команду
result = client.shell.exec_command(command="ls -la")
print(result.data.output)
# Читаем конфигурационный файл
content = client.file.read_file(file=f"{home_dir}/.bashrc")
print(content.data.content)
# Делаем снимок экрана в браузере
screenshot = client.browser.screenshot()
TypeScript SDK 的签名几乎相同：
import { Sandbox } from '@agent-infra/sandbox';
const sandbox = new Sandbox({ baseURL: 'http://localhost:8080' });
const result = await sandbox.shell.exec({ command: 'ls -la' });
console.log(result.output);
const content = await sandbox.file.read({ path: '/home/gem/.bashrc' });
console.log(content);
端到端场景：从网页到 Markdown 报告
以下示例演示了各组件如何协同工作。脚本通过 Chrome DevTools Protocol 连接到沙箱浏览器，加载页面并截图，然后将 HTML 传递给 Jupyter 内核进行转换并保存最终文件。
import asyncio
import base64
from playwright.async_api import async_playwright
from agent_sandbox import Sandbox
async def site_to_markdown():
c = Sandbox(base_url="http://localhost:8080")
home_dir = c.sandbox.get_context().home_dir
# 1. Браузер: заходим на сайт и забираем разметку
async with async_playwright() as p:
browser_info = c.browser.get_info().data
page = await (await p.chromium.connect_over_cdp(browser_info.cdp_url)).new_page()
await page.goto("https://example.com", wait_until="networkidle")
html = await page.content()
screenshot_b64 = base64.b64encode(await page.screenshot()).decode('utf-8')
# 2. Jupyter: выполняем скрипт конвертации внутри песочницы
c.jupyter.execute_code(code=f"""
from markdownify import markdownify
html = '''{html}'''
screenshot_b64 = "{screenshot_b64}"
md = f"{{markdownify(html)}}\\n\\n"
with open('{home_dir}/site.md', 'w') as f:
f.write(md)
print("Done!")
""")
# 3. Shell: проверяем созданные файлы
list_result = c.shell.exec_command(command=f"ls -lh {home_dir}")
print(f"Файлы в песочнице: {list_result.data.output}")
# 4. File API: забираем готовый markdown
return c.file.read_file(file=f"{home_dir}/site.md").data.content
if __name__ == "__main__":
result = asyncio.run(site_to_markdown())
print("Отчет успешно сохранен")
与现成框架的集成
沙箱可以轻松集成到 LangChain、Browser Use 或标准 OpenAI API 等流行库中。
以下是 OpenAI Chat Completions 中函数调用的样子，用于执行 Python 和 Node.js 代码：
import json
from openai import OpenAI
from agent_sandbox import Sandbox
client = OpenAI(api_key="your_api_key")
sandbox = Sandbox(base_url="http://localhost:8080")
def run_code(code, lang="python"):
if lang == "python":
return sandbox.jupyter.execute_code(code=code).data
return sandbox.nodejs.execute_nodejs_code(code=code).data
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Посчитай факториал числа 12 на Python"}],
tools=[
{
"type": "function",
"function": {
"name": "run_code",
"parameters": {
"type": "object",
"properties": {
"code": {"type": "string"},
"lang": {"type": "string"},
},
},
},
}
],
)
if response.choices[0].message.tool_calls:
args = json.loads(response.choices[0].message.tool_calls[0].function.arguments)
result = run_code(**args)
print(result['outputs'][0]['text'])
这个项目适合谁
如果你正在构建一个需要超越简单文本响应的 AI 助手，这个项目将为你节省大量环境设置时间。它非常适合自主网页抓取、数据分析、代码生成和调试，以及通过 VNC 进行 UI 测试。
一个明显的注意事项：由于安装了 Chromium、Node.js、Python 和 code-server，容器镜像相当大。对于代理只需要 bash 的轻量级任务，这可能有些过度。但如果你需要带有共享文件系统的完整工具栈，AIO Sandbox 看起来是 GitHub 上考虑最周全的解决方案之一。
相关项目