Enterprise AI Agent Sandbox

Un marco de seguridad para integrar ejecución en sandbox en flujos de trabajo de IA agéntica. Coloca el conector en cualquier carpeta donde se ejecuten Claude Code, Codex, Cursor u otros agentes de IA: todos los comandos privilegiados se escalan a un aprobador humano, se ejecutan fuera del contexto del agente y la salida se devuelve al modelo para que pueda continuar.

Arquitectura

El Conector de Carpeta integra el sandbox en tu proyecto:

• Los hooks de Claude Code interceptan llamadas a herramientas, escalan operaciones privilegiadas a un aprobador humano y devuelven la salida capturada dentro de una decisión deny para que la herramienta nunca se ejecute con privilegios de agente

• El servidor MCP (run_privileged, check_request, sandbox_status) proporciona el mismo bucle a través del Model Context Protocol — funciona con Claude Code, Codex, Cursor, Windsurf

• La cola de carpeta (.sandbox/escalations/) es el bus: las operaciones atómicas de archivos (os.replace, os.rename) coordinan la aprobación entre cuatro procesos no relacionados (subproceso de hook, servidor MCP, terminal de aprobador, panel de control)

• El motor de políticas clasifica comandos de shell, escrituras de archivos, solicitudes de red y lecturas: cuatro desencadenantes de escalación con humano en el bucle como nivel superior.

Related MCP server: Approval Gate

Inicio Rápido

# 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

Cómo Funciona

1. El agente intenta ejecutar un comando — el hook PreToolUse de Claude Code lo intercepta

2. El hook clasifica y escala — los comandos de shell que no están en la lista de permitidos van a la cola de carpeta

3. Un humano aprueba en sandbox watch — el aprobador ejecuta el comando fuera del agente

4. La salida regresa al modelo — envuelta en permissionDecision:"deny" con stdout en la cadena de razón

5. El agente continúa — recibió el resultado, nunca tuvo privilegio en sí mismo

El canal MCP funciona de manera idéntica: run_privileged devuelve un resultado de herramienta con la salida capturada.

Hitos

• ✅ Hito 0 — Fundamentos (correcciones de errores, contención de rutas, rehidratación de auditoría)

• ✅ Hito 1 — El bucle (hook PreToolUse, cola de carpeta, aprobación CLI)

• ✅ Hito 2 — Canal MCP (run_privileged, check_request, sandbox_status)

• ✅ Hito 3 — Registro de carpeta (originales restaurables, auditoría encadenada, PostToolUse)

• ✅ Hito 4 — Otros desencadenantes (clasificador completo, decisiones recordadas, contexto SessionStart)

• ✅ Hito 5 — Superficies (rutas REST, desinstalación, documentación)

Todos los hitos completados. Consulta docs/CONNECTOR.md para la referencia técnica completa.

Pruebas

# 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

Estructura del Proyecto

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
└── ...

Decisiones Clave de Diseño

• La carpeta es el bus: Las operaciones atómicas de archivos en NTFS coordinan cuatro procesos independientes (sin estado en memoria, sin puertos abiertos, sobrevive a reinicios)

• deny lleva la salida: La herramienta nunca se ejecuta en el agente; la salida se pega de nuevo en la cadena de razón

• Aprobación primero en CLI: Sin interfaz gráfica, funciona a través de SSH, sin dependencia de navegador

• Cierre ante fallos: Los errores internos bloquean en lugar de permitir silenciosamente

• Autoprotección no removible: .sandbox/** en denegaciones de escritura y \.sandbox en denegaciones de shell se reinyectan en cada carga de políticas: el agente no puede eliminar sus propias restricciones

Licencia

[Por determinar]