sandbox
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: @looppause/mcp
快速开始
# 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工作原理
智能体尝试运行命令 —— Claude Code 的 PreToolUse hook 拦截它
Hook 分类并升级 —— 不在白名单中的 shell 命令进入文件夹队列
人工在
sandbox watch中审批 —— 审批者在智能体外部执行命令输出返回给模型 —— 包装在
permissionDecision:"deny"中,stdout 包含在 reason 字符串中智能体继续 —— 它收到了结果,但自身从未拥有特权
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在每次策略加载时都会被重新注入——智能体无法移除自身的约束
许可证
[待定]
Available Tools
5 toolscheck_requestA
Retrieve the outcome of an escalation (from MCP OR the hook).
Use this after run_privileged returns 'pending', or to pick up a request the Claude Code hook raised.
Inputs: request_id (required), wait_seconds. Returns: object
fetch_urlA
Fetch a URL through the sandbox. A human approves; you get the body.
Network access is gated — the sandbox performs the fetch outside your context so you never make the request directly.
Inputs: url (required), reason. Returns: object
request_path_accessA
Request a file operation OUTSIDE the sandbox folder.
A human approves; the sandbox performs the read or write on your behalf
(you never receive the capability). mode is "read" or "write"; for
"write", pass the file content in content.
Inputs: path (required), mode, reason, content. Returns: object
run_privilegedA
Request a privileged shell command. A human approves; you get the output.
The command runs OUTSIDE the sandbox on your behalf — you never receive root yourself. Returns the captured stdout/stderr on approval.
Inputs: command (required), reason. Returns: object
sandbox_statusA
Show the sandbox root, triggers, and any pending escalations.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct capability: shell execution, file access, network fetch, request status, and sandbox overview. There is no overlap in purpose, and descriptions clearly delineate boundaries.
Most tools follow a verb_noun pattern (run_privileged, request_path_access, fetch_url, check_request), but sandbox_status breaks the pattern by being noun_noun. The deviation is minor and the intent remains clear.
With 5 tools, the server is well-scoped for its purpose of gated external operations. Each tool earns its place without redundancy or excess.
The surface covers all core operations (run, file, fetch) and provides status retrieval via check_request and sandbox_status. No obvious dead ends or missing lifecycle steps for the stated escalation workflow.
Maintenance
Related MCP Connectors
Set up human approval for your AI agents' tool calls.
Preventive human-approval write-gate for AI agents: writes commit only after a human approves.
Human approval for AI agents: ask before a risky action, act only once a person approves.
Give any AI agent a way to ask a person — for approval, a decision, an answer or a review.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides a human approval gate for AI agents, enabling interactive inline cards for approving, editing, or rejecting actions before they are executed.MIT
- AlicenseNot gradedqualityDmaintenancePauses AI agent execution and routes approval requests to humans via Slack or email, with cryptographically signed proof of the human's decision.MIT
- AlicenseAqualityDmaintenanceEnables AI agents to securely use real secrets (API keys, database passwords) by requiring human approval for each release, ensuring secrets never enter the model's context.2Apache 2.0
- AlicenseNot gradedqualityCmaintenanceGates agent tool execution with human approval, audit trails, and replay-resistant permits, enabling safe use of tools in agent loops.MIT