Skip to main content
Glama

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

工作原理

  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 在每次策略加载时都会被重新注入——智能体无法移除自身的约束

许可证

[待定]

Available Tools

5 tools
check_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

    A4/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    With 5 tools, the server is well-scoped for its purpose of gated external operations. Each tool earns its place without redundancy or excess.

    Completeness5/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides a human approval gate for AI agents, enabling interactive inline cards for approving, editing, or rejecting actions before they are executed.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Pauses AI agent execution and routes approval requests to humans via Slack or email, with cryptographically signed proof of the human's decision.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      2
      Apache 2.0