Sandbox Agent

沙盒代理

基于Docker的沙盒代码执行的LangGraph代理。每个会话都在一个隔离的、强化的Docker容器中运行，该容器具有一个持久内核——Python的IPython， vm.createContext Node.js和专用的R环境。支持3个运行时、与提供者无关的LLM配置和视觉（多模式模型的自动检测）。可用作交互式CLI、MCP服务器（Cursor、Claude Desktop）、REST API(艾格拉)，以及React前端。

特性

• Docker隔离 --每个会话都在自己的容器中运行，没有暴露的端口，也没有主机卷
• 硬化容器 --非根用户（UID 65532）、PID限制、内存+交换限制、仅tmpfs可写目录、， no-new-privileges
• 碰撞检测 --检测到OOM杀伤、分叉炸弹、分段故障，并明确报告给特工
• 持久状态 --变量在代码执行之间存活（如Jupyter单元格）
• PostgreSQL检查点 --对话历史记录在重新启动后仍然存在（与Aegra共享）
• 异步支持 --Promise（Node.js）和协程（Python）会自动等待
• 多运行时 --Python、Node.js和R
• 丰富的显示输出 --捕获matplotlib/ggplot图形、Plotly图表、IPython音频、HTML小部件等；自动将图像发送到多模式LLM
• 提供者不可知 --通过以下方式与OpenAI、Anthropic、Google Gemini、Ollama或任何兼容提供商合作 langchain init_chat_model
• 运行时软件包安装 — pip install / npm install / install.packages() 在会话创建时或通过终端
• 6工具 — create_session, execute_code, execute_terminal, import_files, export_files, stop_session
• MCP服务器 --通过模型上下文协议（stdio传输）公开相同的工具
• REST API -完整的LangGraph平台API，通过 艾格拉 使用OpenAPI文档、流媒体、线程管理
• 输入验证 --Pydantic模式在执行前验证所有工具输入，失败时返回结构化错误
• React前端 --SPA聊天、工具可视化、文件上传/下载、设置对话框（React 19+Vite+Tailwind CSS）
• 文件上传 -将文件上载到API以导入沙箱会话(POST /threads/{id}/files/upload)
• 文件导出 --注册文件以供下载（无主机副本）；通过API下载或在交叉会话导入中使用
• 文件导入 --从主机路径、内联内容或其他会话（在同一对话中导出的文件）导入
• 跨会话传输 --从会话A导出，导入到会话B {session_id, path}
• 会话垃圾回收 --空闲超时、最大生存期、线程驱逐、孤立容器清理
• 自动清理 --当代理退出时，所有容器都会停止并被移除

先决条件

• Python 3.11+
• Docker引擎
• LLM提供商的API密钥(CHAT_MODEL_API_KEY)
• PostgreSQL（适用于API/CLI模式-checkpointer+Aegra）
• Node.js 18+和npm（用于React前端）

设置

# Docker — installs (if needed), configures permissions, and builds all 3 images
sudo ./setup-docker.sh

# Install Python dependencies (open a new terminal so the docker group is active)
uv sync

# Install frontend dependencies
cd frontend && npm install && cd ..

# Configure environment
cp .env.example .env
# Edit .env with your CHAT_MODEL_API_KEY, POSTGRES_PASSWORD, and other settings

# Docker images are also built automatically on first use if not already present

PostgreSQL（CLI、API和UI都需要）

PostgreSQL在使用时通过Docker Compose自动启动 localhostCLI检测PostgreSQL是否可访问并自动启动：

# Manual start (if needed)
docker compose up postgres -d

或者通过以下方式指向现有的PostgreSQL实例 POSTGRES_* env变量 .env.

用法

所有命令都使用统一 sandbox-agent 入口点：

uv run sandbox-agent cli       # Interactive CLI (default)
uv run sandbox-agent mcp       # MCP server (Cursor, Claude Desktop)
uv run sandbox-agent api       # REST API (Aegra, no reload)
uv run sandbox-agent api dev   # REST API with hot reload
uv run sandbox-agent ui        # React UI (auto-starts API if needed)

命令行界面

uv run sandbox-agent cli
# or simply
uv run sandbox-agent

CLI作为Aegra REST API之上的瘦客户端运行。要求API正在运行(uv run sandbox-agent api).特征：

• 富有的 带有语法高亮显示的工具I/O的面板（每个运行时词法分析器）
• Markdown渲染流媒体代理输出
• 跨重启的持久线程(~/.local/state/sandbox-agent/cli-thread.json)
• /new 开始新对话的命令
• 通过将模型/提供商/密钥设置传递给API configurable

MCP 服务器

运行MCP服务器（stdio传输）以与Cursor、Claude Desktop或任何兼容MCP的客户端集成：

uv run sandbox-agent mcp

光标或克劳德桌面

添加以下MCP配置：

{
  "mcpServers": {
    "sandbox-agent": {
      "command": "uv",
      "args": ["--directory", "/path/to/sandbox-agent", "run", "sandbox-agent", "mcp"]
    }
  }
}

MCP服务器公开了与CLI代理相同的6个工具，具有相同的行为。它在中维护一个持久的thread_id ~/.local/state/sandbox-agent/mcp-thread.json 为了确保导出URL的一致性。

这 import_files 该工具直接接受文件内容（如文本或base64） file_content/encoding 密钥）、主机路径（通过 source/destination)，或跨会话引用(session_id+path).这 export_files 该工具通过注册文件进行下载 GET /threads/{thread_id}/files/download?session_id=...&path=....

REST API（Aegra）

将代理作为REST API运行，通过 艾格拉 （自托管LangGraph平台替代方案）：

uv run sandbox-agent api       # Production mode (no reload, auto-starts PostgreSQL)
uv run sandbox-agent api dev   # Development mode (hot reload via aegra dev)

如果无法在本地主机上访问PostgreSQL，则生产命令会通过Docker Compose自动启动PostgreSQL。服务器运行在 http://localhost:8000 OpenAPI文档位于 /docs。使用LangGraph SDK或curl创建助手、线程和流运行。与Agent Chat UI、LangGraph Studio和CopilotKit兼容。

自定义端点：

• GET /threads/{thread_id}/files/download?session_id=...&path=... --流式传输从容器导出的文件
• POST /threads/{thread_id}/files/upload --上传文件以供导入沙盒会话
• DELETE /threads/{thread_id} --还清理该线程的Docker会话和存储（通过中间件）
• GET /settings --返回在后端合并的持久化前端设置 .env 默认值
• PUT /settings --将前端设置持久化到PostgreSQL（加密）

反应前端

通过Aegra API与代理商聊天的web UI（React 19+Vite+Tailwind CSS）：

# Install frontend dependencies (if not done during setup)
cd frontend && npm install && cd ..

# Start the UI (auto-starts API + PostgreSQL if needed)
uv run sandbox-agent ui

前端运行在 http://localhost:5173 （带有API代理的Vite dev服务器 :8000).特征：

• 通过侧边栏进行话题管理（创建、恢复、删除对话）
• 使用可扩展的工具块流式传输响应（每次运行时突出显示语法）
• 文件上传和下载支持
• 思维块可视化
• 设置对话框（模型、提供商、API密钥、基本URL、视觉切换）
• 通过服务器端API进行持久设置(GET/PUT /settings)，带后端 .env 默认为回退

程序化

from sandbox_agent.sandbox import SandboxManager

manager = SandboxManager()

info = manager.create_session(
    runtime="python",
    dependencies={"pandas": "2.2.3", "matplotlib": ""},
)
sid = info.session_id

r1 = manager.execute_code(sid, """
import pandas as pd
df = pd.DataFrame({'x': [1, 2, 3], 'y': [4, 5, 6]})
print(df.describe())
""")
print(r1.stdout)

# Variables persist between calls
r2 = manager.execute_code(sid, "df.shape")
print(r2.result)

# Export files from the sandbox (registers for download, no host copy)
manager.execute_code(sid, "df.to_csv('/workspace/output.csv', index=False)")
export = manager.export_files(sid, [{"source": "output.csv"}])
print(export.files[0].session_id, export.files[0].path)

manager.stop_session(sid)

导出文件

export_files 注册文件以供下载和跨会话导入（无主机副本）。文件可通过API获得(GET /threads/{thread_id}/files/download?session_id=...&path=...)以及 import_files 在其他会议中：

# Export a single file
result = manager.export_files(sid, [{"source": "report.pdf"}])

# Export an entire directory
result = manager.export_files(sid, [{"source": "results/"}])

# Export multiple files at once
result = manager.export_files(sid, [
    {"source": "data.csv"},
    {"source": "chart.png"},
    {"source": "/workspace/logs/"},
])

for f in result.files:
    print(f"{f.session_id}:{f.path} ({'OK' if f.success else f.error})")

跨会话文件传输

使用 export_files + import_files 在会话之间移动文件（甚至在不同的运行时之间）：

# Session A (Python): produce data
sid_a = manager.create_session(runtime="python", dependencies={"pandas": ""}).session_id
manager.execute_code(sid_a, """
import pandas as pd
df = pd.DataFrame({'x': [1,2,3], 'y': [4,5,6]})
df.to_csv('/workspace/data.csv', index=False)
""")
export = manager.export_files(sid_a, [{"source": "data.csv"}])
path = export.files[0].path  # /workspace/data.csv

# Session B (R): consume the same data
sid_b = manager.create_session(runtime="r", dependencies={"readr": ""}).session_id
manager.import_files(sid_b, [{"session_id": sid_a, "path": path, "destination": "data.csv"}])
manager.execute_code(sid_b, 'df  API["Aegra REST API
    (LangGraph Platform)"]
    UI --> API
    API --> Agent["LangGraph ReAct Agent"]
    Agent --> Tools["LangChain Tools"]
    MCP --> Core["Core Tool Functions"]

    Tools --> Core
    Core --> SM["SandboxManager
    Docker SDK"]

    SM -->|"docker exec -i + JSON pipe"| Docker

    subgraph Docker ["Docker Containers
    isolated, hardened"]
        direction LR
        PY["Python
        IPython · UNIX socket"]
        JS["Node.js
        vm.createContext · UNIX socket"]
        R["R
        R env · TCP :8765"]
    end

    subgraph Storage ["Persistence"]
        PG["PostgreSQL
        checkpoints, exports"]
    end

    API --> PG
    SM --> PG

在每个容器内，都有一个持久的 内核 （PID 1）保持执行状态 客户端 通过UNIX套接字（Python/Node.js）或TCP（R）连接到它 docker exec 呼叫：

flowchart TB
    SM["SandboxManager"] -->|"docker exec -i"| Client["Client (ephemeral)"]

    subgraph container ["Container"]
        Client -->|"UNIX socket / TCP"| Kernel["Kernel (PID 1, persistent)"]
        Kernel --- State["State
        variables, imports, data"]
    end

测试

# Unit tests (no Docker required)
uv run pytest tests/test_cli.py tests/test_http_app.py -v

# Integration tests (requires Docker)
uv run pytest tests/test_manager.py tests/test_tools.py tests/test_export_files.py tests/test_mcp.py -v

# LangGraph debug trace (requires Docker + LLM API key)
uv run pytest tests/test_langgraph_debug.py -v -s

# API integration tests (requires Docker + running API: uv run sandbox-agent api dev)
uv run pytest tests/test_api.py -v -s

# Full suite
uv run pytest tests/ -v

生产部署

A制作 Dockerfile 和 docker-compose.yml 包括：

# Start PostgreSQL + API
docker compose up -d

# Or build and run manually
docker build -t sandbox-agent-api .
docker run -p 8000:8000 --env-file .env sandbox-agent-api

生产图像使用 aegra serve 具有非根 app 用户。

许可证

麻省理工学院 --爱德华多·拉蒙·雷瑟