sandbaseai/sandbase-harness

SandBase Harness – AI 에이전트를 위한 로컬 우선 런타임

개요 – SandBase Harness는 AI 에이전트(예: Claude 스타일의 "관리형 에이전트")를 자체 머신이나 인프라에서 안전하게 실행할 수 있는 자체 호스팅 런타임입니다. SDK만으로는 제공되지 않는 프로덕션 수준의 기능(영구 세션, 샌드박스 처리된 도구 실행, 자격 증명 볼트, 감사 추적, 검사용 웹 콘솔)을 추가합니다.

주요 기능

기능	제공 내용
Claude 관리형 에이전트 호환 API	Claude Managed Agents 계약을 미러링한 /v1 HTTP API를 노출하여 기존 Anthropic 스타일 SDK가 즉시 작동합니다.
로컬 우선 스토리지	모든 메타데이터(에이전트, 세션, 환경, 메모리, 파일, API 키 등)는 워크스페이스 내의 SQLite 파일에 저장되며 외부 데이터베이스가 필요 없습니다.
샌드박스 백엔드	생성된 코드를 격리된 환경에서 실행: 로컬 프로세스, Docker 컨테이너(세션당 1개), Kubernetes kubectl exec/cp, 또는 사용자 정의 자체 호스팅 작업자 큐.
도구 거버넌스	MCP 스타일 도구 세트, 권한 정책, 자격 증명 주입, 자동 승인 또는 사람의 확인을 요구할 수 있는 승인 게이트.
세션 재생 및 디버깅	이벤트는 추가 전용 스트림에 기록되며 Server-Sent Events(SSE)를 통해 실시간 디버깅 또는 나중에 재생할 수 있습니다.
모델 무관	OpenAI, Anthropic, MiniMax, DeepSeek V4 및 OpenAI 호환 엔드포인트와 작동합니다.
웹 콘솔	내장 UI(http://127.0.0.1:3000)에서 세션, 설정, API 참조를 표시하고 에이전트 턴을 실시간으로 검사할 수 있습니다.
TypeScript SDK	managed-agents/sdk는 런타임용 타입 클라이언트 헬퍼를 제공합니다.

시작하기

1. Node 22+, npm 10+를 설치(Docker는 선택 사항).
2. 리포지토리를 클론하고 npm ci && npm run build를 실행.
3. 워크스페이스 초기화: node dist/index.js init.
4. 서버 시작: node dist/index.js start.
5. 콘솔을 열고 모델 제공자 API 키를 추가하고 모델을 선택한 후 세션을 생성.
6. UI 또는 CLI를 통해 메시지 전송(예): node dist/index.js chat agent_assistant --message "hello" --tool-approval allow --tool-approval allow 플래그는 에이전트가 실행하려는 모든 도구 호출을 사전 승인합니다.

중요성

• 안전성 – 에이전트가 생성한 코드는 격리된 컨테이너에서 실행되어 호스트의 우발적 손상을 방지합니다.
• 감사 가능성 – 모든 이벤트(모델 요청, 도구 호출, 자격 증명 사용)가 기록되고 재생할 수 있습니다.
• 제어 – 세분화된 권한 정책으로 에이전트가 어떤 도구를 어떤 조건에서 사용할 수 있는지 결정할 수 있습니다.
• 이식성 – 모든 것이 로컬 파일에 존재하므로 워크스페이스를 이동, 백업, 방화벽 뒤에서 클라우드 제어 평면 없이 실행할 수 있습니다.

적용 분야 SandBase Harness는 저수준 모델 SDK(프롬프트 전송만)와 본격적인 오케스트레이션 플랫폼 사이에 위치합니다. 영구 상태, 도구 사용, 엄격한 보안이 필요하고 온프레미스를 유지하려는 자율 에이전트를 구축하는 개발자에게 이상적입니다.

리포지토리의 링크

• 아키텍처 다이어그램 – docs/assets/sandbase-harness-architecture.svg
• API 사양 – docs/api.md
• 공식 TypeScript SDK – managed-agents/sdk
• 호환성 매트릭스 – Claude Managed Agents 계약의 어느 부분이 완전히 지원되는지, 부분적으로 지원되는지, 또는 지원되지 않는지 보여줍니다.
• Codespaces 템플릿 – 원클릭 클라우드 개발 환경을 빠르게 생성.

---

위의 세부 사항은 모두 리포지토리의 README에서 직접 가져온 것이며 추가 기능은 추론되지 않았습니다.