엔터프라이즈 AI 에이전트 샌드박스

에이전트형 AI 워크플로우에 샌드박스 실행을 연결하기 위한 보안 프레임워크입니다. Claude Code, Codex, Cursor 또는 기타 AI 에이전트가 실행되는 모든 폴더에 커넥터를 설치하세요. 모든 권한 있는 명령은 인간 승인자에게 에스컬레이션되고, 에이전트의 컨텍스트 외부에서 실행되며, 출력은 모델에 다시 전달되어 계속 진행할 수 있습니다.

아키텍처

폴더 커넥터는 샌드박스를 프로젝트에 연결합니다:

• Claude Code 훅은 도구 호출을 가로채고, 권한 있는 작업을 인간 승인자에게 에스컬레이션하며, 캡처된 출력을 deny 결정 내부에 반환하여 도구가 에이전트 권한으로 실행되지 않도록 합니다

• MCP 서버 (run_privileged, check_request, sandbox_status)는 Model Context Protocol을 통해 동일한 루프를 제공합니다 — Claude Code, Codex, Cursor, Windsurf와 호환됩니다

• 폴더 큐 (.sandbox/escalations/)는 버스 역할을 합니다: 원자적 파일 작업 (os.replace, os.rename)이 네 개의 독립적인 프로세스(훅 서브프로세스, MCP 서버, 승인자 터미널, 대시보드) 간의 승인을 조정합니다

• 정책 엔진은 셸 명령, 파일 쓰기, 네트워크 요청, 읽기를 분류합니다 — 최상위 계층에 인간 개입이 있는 네 가지 에스컬레이션 트리거가 있습니다

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 훅이 이를 가로챕니다

2. 훅이 분류하고 에스컬레이션합니다 — 허용 목록에 없는 셸 명령은 폴더 큐로 이동합니다

3. 인간이 sandbox watch에서 승인합니다 — 승인자가 에이전트 외부에서 명령을 실행합니다

4. 출력이 모델로 반환됩니다 — stdout이 reason 문자열에 포함된 permissionDecision:"deny"로 래핑됩니다

5. 에이전트가 계속 진행합니다 — 결과를 받았지만, 그 자체로는 권한을 가진 적이 없습니다

MCP 채널도 동일하게 작동합니다: run_privileged는 캡처된 출력이 포함된 도구 결과를 반환합니다.

마일스톤

• ✅ 마일스톤 0 — 기반 (버그 수정, 경로 격리, 감사 재수화)

• ✅ 마일스톤 1 — 루프 (PreToolUse 훅, 폴더 큐, 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/**는 쓰기 거부에, \.sandbox는 셸 거부에 모든 정책 로드 시 재주입됩니다 — 에이전트는 자신의 제약을 제거할 수 없습니다

라이선스

[미정]