Enterprise AI Agent Sandbox

一个安全框架，用于将沙箱化执行接入智能体 AI 工作流。将连接器放入任何运行 Claude Code、Codex、Cursor 或其他 AI 智能体的文件夹中——所有特权命令都会升级给人工审批者，在智能体上下文之外执行，并将输出反馈给模型，使其能够继续工作。

架构

文件夹连接器 将沙箱桥接到你的项目中：

• Claude Code hooks 拦截工具调用，将特权操作升级给人工审批者，并在 deny 决策中返回捕获的输出，使工具永远不会以智能体权限运行

• MCP server（run_privileged、check_request、sandbox_status）通过 Model Context Protocol 提供相同的循环——适用于 Claude Code、Codex、Cursor、Windsurf

• 文件夹队列（.sandbox/escalations/）是总线：原子文件操作（os.replace、os.rename）在四个不相关的进程（hook 子进程、MCP server、审批者终端、仪表盘）之间协调审批

• 策略引擎 对 shell 命令、文件写入、网络请求和读取进行分类——四个升级触发器，以人在回路中作为最高层级

Related MCP server: Approval Gate

快速开始

# Install the connector
python -m pip install -e ".[dev]"

# Initialize a folder
sandbox init . --claude --mcp

# In one terminal: watch for escalations
sandbox watch .

# In another: use Claude Code or the MCP tools as normal
# Privileged commands will appear in the `watch` terminal for approval

工作原理

1. 智能体尝试运行命令 —— Claude Code 的 PreToolUse hook 拦截它

2. Hook 分类并升级 —— 不在白名单中的 shell 命令进入文件夹队列

3. 人工在 sandbox watch 中审批 —— 审批者在智能体外部执行命令

4. 输出返回给模型 —— 包装在 permissionDecision:"deny" 中，stdout 包含在 reason 字符串中

5. 智能体继续 —— 它收到了结果，但自身从未拥有特权

MCP 通道的工作方式相同：run_privileged 返回带有捕获输出的工具结果。

里程碑

• ✅ 里程碑 0 —— 基础（bug 修复、路径包含、审计恢复）

• ✅ 里程碑 1 —— 循环（PreToolUse hook、文件夹队列、CLI 审批）

• ✅ 里程碑 2 —— MCP 通道（run_privileged、check_request、sandbox_status）

• ✅ 里程碑 3 —— 文件夹记录（可恢复的原始文件、链式审计、PostToolUse）

• ✅ 里程碑 4 —— 其他触发器（完整分类器、记忆决策、SessionStart 上下文）

• ✅ 里程碑 5 —— 界面（REST 路由、卸载、文档）

所有里程碑均已完成。 完整技术参考请参阅 docs/CONNECTOR.md。

测试

# Run all tests (117 passing)
python -m pytest -q

# Test the loop with a real hook subprocess and background approver
python -m pytest tests/integration/test_connector_loop.py -v

# Test the MCP channel
python -m pytest tests/integration/test_mcp_tools.py -v

项目结构

src/sandbox/
├── connector/           # Folder connector (queue, hooks, policy, MCP)
├── launcher/            # M1 jailed launcher (job objects, jail, shims)
├── audit/               # Chained audit log with tamper detection
├── broker/              # Non-AI privilege executor
├── fs/                  # Path containment and validation
├── agents/              # Multi-agent sandbox orchestrator
├── api/                 # FastAPI routes and WebSocket
└── ...

关键设计决策

• 文件夹即总线：NTFS 上的原子文件操作协调四个独立进程（无内存状态、无开放端口、重启后依然有效）

• deny 携带输出：工具永远不会在智能体中执行；输出被粘贴回 reason 字符串中

• CLI 优先审批：无头模式，可通过 SSH 工作，不依赖浏览器

• 故障关闭：内部错误会阻止而非静默允许

• 不可移除的自我保护：写入拒绝中的 .sandbox/** 和 shell 拒绝中的 \.sandbox 在每次策略加载时都会被重新注入——智能体无法移除自身的约束

许可证

[待定]