AIO 沙盒 - 多合一智能体沙盒环境

🌐 浏览器 | 💻 终端 | 📁 文件 | 🔧 VSCode | 📊 Jupyter | 🤖 MCP

🚀 快速开始

30秒内即可启动并运行：

docker run --security-opt seccomp=unconfined --rm -it -p 8080:8080 ghcr.io/agent-infra/sandbox:latest

适用于中国大陆用户：

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

如需指定版本，可使用 agent-infra/sandbox:${version} 格式，例如使用 1.0.0.150 版本：

docker run --security-opt seccomp=unconfined --rm -it -p 8080:8080 ghcr.io/agent-infra/sandbox:1.0.0.150
# 或者中国大陆用户
docker run --security-opt seccomp=unconfined --rm -it -p 8080:8080 enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:1.0.0.150

运行后，可通过以下地址访问各个功能：

• 📖 文档：http://localhost:8080/v1/docs
• 🌐 VNC 浏览器：http://localhost:8080/vnc/index.html?autoconnect=true
• 💻 VSCode Server：http://localhost:8080/code-server/
• 🤖 MCP 服务：http://localhost:8080/mcp

🎯 什么是 AIO 沙盒？

AIO 沙盒是一个多合一的智能体沙盒环境，将浏览器、Shell、文件操作、MCP 服务以及 VSCode Server 集成于一个 Docker 容器中。基于云原生轻量级沙盒技术构建，为 AI 智能体和开发者提供统一且安全的执行环境。

为什么选择 AIO 沙盒？

传统沙盒通常是单一用途的（仅限于浏览器、代码或 Shell），这使得文件共享和功能协同变得极为困难。而 AIO 沙盒则通过以下方式解决了这一问题：

• ✅ 统一文件系统：在浏览器中下载的文件可立即在 Shell 和文件操作中使用。
• ✅ 多接口支持：VNC、VSCode、Jupyter 和终端在一个统一环境中无缝衔接。
• ✅ 安全执行：沙箱化的 Python 和 Node.js 执行，确保安全性。
• ✅ 零配置：预配置的 MCP 服务器和开发工具，开箱即用。
• ✅ 智能体友好：兼容 MCP 的 API，便于 AI 智能体的无缝集成。

📦 安装

SDK 安装

pip install agent-sandbox

npm install @agent-infra/sandbox

go get github.com/agent-infra/sandbox-sdk-go

基本使用

from agent_sandbox import Sandbox

# 初始化客户端
client = Sandbox(base_url="http://localhost:8080")
home_dir = client.sandbox.get_context().home_dir

# 执行 Shell 命令
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()

import { Sandbox } from '@agent-infra/sandbox';

// 初始化客户端
const sandbox = new Sandbox({ baseURL: 'http://localhost:8080' });

// 执行 Shell 命令
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);

// 浏览器自动化
const screenshot = await sandbox.browser.screenshot();

🌟 核心特性

🔗 统一环境

所有组件运行在同一容器内，共享文件系统，实现无缝工作流：

🌐 浏览器自动化

通过多种接口实现全面的浏览器控制：

• VNC：通过远程桌面进行可视化浏览器交互。
• CDP：利用 Chrome 开发者工具协议进行程序化控制。
• MCP：提供高级别的浏览器自动化工具。

💻 开发工具

集成的开发环境包括：

• VSCode Server：在浏览器中享受完整的 IDE 体验。
• Jupyter Notebook：交互式的 Python 环境。
• 终端：基于 WebSocket 的终端访问。
• 端口转发：用于 Web 应用的智能预览功能。

🤖 MCP 集成

预配置的 Model Context Protocol 服务器：

• 浏览器：用于网页自动化和爬取。
• 文件：用于文件系统操作。
• Shell：用于命令执行。
• Markitdown：用于文档处理。

📚 完整示例

将网页转换为包含嵌入式截图的 Markdown：

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

    # 浏览器：自动化下载 HTML
    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')

    # Jupyter：在沙盒中将 HTML 转换为 Markdown
    c.jupyter.execute_code(code=f"""
from markdownify import markdownify
html = '''{html}'''
screenshot_b64 = "{screenshot_b64}"

md = f"{{markdownify(html)}}\\n\\n![Screenshot](data:image/png;base64,{{screenshot_b64}})"
with open('{home_dir}/site.md', 'w') as f:
    f.write(md)
print("Done!")
""")

    # Shell：列出沙盒中的文件
    list_result = c.shell.exec_command(command=f"ls -lh {home_dir}")
    print(f"沙盒中的文件：{list_result.data.output}")

    # 文件：读取生成的 Markdown
    return c.file.read_file(file=f"{home_dir}/site.md").data.content

if __name__ == "__main__":
    result = asyncio.run(site_to_markdown())
    print(f"Markdown 已成功保存！")

🏗️ 架构

┌─────────────────────────────────────────────────────────────┐
│                    🌐 浏览器 + VNC                        │
├─────────────────────────────────────────────────────────────┤
│  💻 VSCode 服务器  │  🐚 Shell 终端  │  📁 文件操作   │
├─────────────────────────────────────────────────────────────┤
│              🔗 MCP 中心 + 🔒 沙盒融合               │
├─────────────────────────────────────────────────────────────┤
│         🚀 预览代理 + 📊 服务监控          │
└─────────────────────────────────────────────────────────────┘

🛠️ API 参考

核心 API

MCP 服务器

🚢 部署

Docker Compose

version: '3.8'
services:
  sandbox:
    container_name: aio-sandbox
    image: ghcr.io/agent-infra/sandbox:latest
    volumes:
      - /tmp/gem/vite-project:/home/gem/vite-project
    security_opt:
      - seccomp:unconfined
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: "unless-stopped"
    shm_size: "2gb"
    ports:
      - "${HOST_PORT:-8080}:8080"
    environment:
      PROXY_SERVER: ${PROXY_SERVER:-host.docker.internal:7890}
      JWT_PUBLIC_KEY: ${JWT_PUBLIC_KEY:-}
      DNS_OVER_HTTPS_TEMPLATES: ${DNS_OVER_HTTPS_TEMPLATES:-}
      WORKSPACE: ${WORKSPACE:-"/home/gem"}
      HOMEPAGE: ${HOMEPAGE:-}
      BROWSER_EXTRA_ARGS: ${BROWSER_EXTRA_ARGS:-}
      TZ: ${TZ:-Asia/Singapore}
      WAIT_PORTS: ${WAIT_PORTS:-}

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: aio-sandbox
spec:
  replicas: 2
  selector:
    matchLabels:
      app: aio-sandbox
  template:
    metadata:
      labels:
        app: aio-sandbox
    spec:
      containers:
      - name: aio-sandbox
        image: ghcr.io/agent-infra/sandbox:latest
        ports:
        - containerPort: 8080
        resources:
          limits:
            memory: "2Gi"
            cpu: "1000m"

🤝 集成示例

浏览器使用集成

import asyncio

from agent_sandbox import Sandbox
from browser_use import Agent, Tools
from browser_use.browser import BrowserProfile, BrowserSession
from browser_use.llm import ChatOpenAI

sandbox = Sandbox(base_url="http://localhost:8080")
print("sandbox", sandbox.browser)
cdp_url = sandbox.browser.get_info().data.cdp_url

browser_session = BrowserSession(
    browser_profile=BrowserProfile(cdp_url=cdp_url, is_local=True)
)
tools = Tools()


async def main():
    agent = Agent(
        task='访问 https://duckduckgo.com 并搜索 "browser-use founders"',
        llm=ChatOpenAI(model="gcp-claude4.1-opus"),
        tools=tools,
        browser_session=browser_session,
    )

    await agent.run()
    await browser_session.kill()

    input("按 Enter 键关闭...")


if __name__ == "__main__":
    asyncio.run(main())

LangChain 集成

from langchain.tools import BaseTool
from agent_sandbox import Sandbox

class SandboxTool(BaseTool):
    name = "sandbox_execute"
    description = "在 AIO 沙盒中执行命令"

    def _run(self, command: str) -> str:
        client = Sandbox(base_url="http://localhost:8080")
        result = client.shell.exec_command(command=command)
        return result.data.output

OpenAI Assistant 集成

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")


# 定义一个在沙盒中运行代码的工具
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


# 使用 OpenAI
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "计算 1+1"}],
    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)
    print("args", args)
    result = run_code(**args)
    print(result['outputs'][0]['text'])

🤝 贡献

我们欢迎贡献！请参阅我们的 贡献指南 以获取详细信息。

📄 许可证

AIO 沙盒根据 Apache License 2.0 发布。

🙏 致谢

由 Agent Infra 团队用心打造。特别感谢所有贡献者及开源社区。

📞 支持

• 📖 文档
• 💬 GitHub 讨论区
• 🐛 问题追踪器

准备好革新你的 AI 开发工作流了吗？
⭐ 在 GitHub 上为我们加星 • 📚 阅读文档 • 🐛 提交问题

AIO Sandbox 快速上手指南

AIO Sandbox 是一个多合一的 AI Agent 沙箱环境，在单个 Docker 容器中集成了浏览器、终端、文件系统、VSCode Server、Jupyter Notebook 以及 MCP 服务。它专为 AI Agent 和开发者设计，提供统一、安全且零配置的代码执行环境。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux, macOS 或 Windows (需安装 WSL2)
• 核心依赖:
  • Docker (推荐版本 20.10+)
  • 或者兼容的容器运行时 (如 Podman)
• 网络要求:
  • 需要开放端口 8080 (默认)
  • 中国大陆用户建议配置 Docker 镜像加速器或直接使用国内镜像源

2. 安装步骤

无需复杂的编译过程，通过一条 Docker 命令即可启动服务。

🚀 快速启动

中国大陆用户推荐（使用火山引擎镜像源）：

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

国际用户：

docker run --security-opt seccomp=unconfined --rm -it -p 8080:8080 ghcr.io/agent-infra/sandbox:latest

注意: --security-opt seccomp=unconfined 参数用于解除部分系统调用限制，以确保浏览器自动化工具正常运行。

🔌 可选：SDK 安装

如果您需要通过代码控制沙箱，可以选择安装对应语言的 SDK：

• Python: pip install agent-sandbox
• TypeScript/JavaScript: npm install @agent-infra/sandbox
• Golang: go get github.com/agent-infra/sandbox-sdk-go

3. 基本使用

启动容器后，您可以通过以下方式访问和使用沙箱环境。

🌐 方式一：Web 界面访问

直接在浏览器中访问以下地址（替换 localhost 为您的服务器 IP）：

• 综合文档与 API: http://localhost:8080/v1/docs
• VNC 浏览器界面: http://localhost:8080/vnc/index.html?autoconnect=true
• VSCode 在线开发: http://localhost:8080/code-server/
• MCP 服务监控: http://localhost:8080/mcp

💻 方式二：代码控制 (Python 示例)

安装 SDK 后，您可以轻松执行 shell 命令、操作文件或进行浏览器自动化。

from agent_sandbox import Sandbox

# 1. 初始化客户端
client = Sandbox(base_url="http://localhost:8080")
home_dir = client.sandbox.get_context().home_dir

# 2. 执行 Shell 命令
result = client.shell.exec_command(command="ls -la")
print("文件列表:", result.data.output)

# 3. 读取文件内容
content = client.file.read_file(file=f"{home_dir}/.bashrc")
print("文件内容预览:", content.data.content[:100])

# 4. 浏览器截图自动化
screenshot = client.browser.screenshot()
print("截图获取成功，数据长度:", len(screenshot.data.image))

📝 核心特性速览

• 统一文件系统: 在浏览器下载的文件可直接在 Terminal 或 VSCode 中访问。
• 多接口支持: 同时提供 VNC (视觉交互)、CDP (程序控制) 和 MCP (大模型协议) 接口。
• 预置工具: 内置 Python, Node.js, Jupyter 及常用开发工具，开箱即用。
• 安全隔离: 基于轻量级沙箱技术，确保代码执行的安全性。