Rapa — 자체 호스팅 AI 에이전트 플랫폼

사용자 자신의 기기에서 실행하는 풀스택 AI 에이전트 플랫폼입니다. OpenAI와 호환되는 모든 LLM과 세 가지 모드 — 채팅(Chat) (직접 대화), 에이전트(Agent) (자율적인 도구 사용 루프), 그리고 계획(Plan) (읽기 전용 분석) — 로 대화할 수 있습니다. 이 에이전트는 파일 읽기 및 쓰기, 셸 명령어 실행, 웹 검색, 헤드리스 브라우저 구동, Git 관리, MCP 서버와 통신하는 기능을 수행하며, 모든 작업은 사용자가 지정한 워크스페이스 디렉토리에 한정됩니다.

기본적으로 SQLite를 사용합니다 — 데몬(daemon)이 필요 없고, 클라우드가 필요 없고, Docker가 필요 없습니다. Prisma 제공자만 변경하면 MySQL/PostgreSQL을 호스팅하는 동일한 코드를 실행할 수 있습니다.

주요 특징 (Highlights)

• 세 가지 모드, 하나의 UI — 채팅(Chat), 에이전트(Agent), 그리고 하드 도구 허용 목록(hard tool allowlist)을 갖춘 읽기 전용 플랜(Plan) 모드를 지원합니다.
• 58개의 도구, 11개 카테고리 — 파일 시스템(filesystem), 코드 편집(code editing), 셸(shell), 웹(web), 브라우저 자동화(Playwright), Git, 이미지 생성(image generation), 문서 생성(document generation), 스케줄링(scheduling), 알림/이메일(notifications/email), 그리고 MCP 패스스루(MCP passthrough)를 포함합니다.
• 설계상 작업 공간 범위 한정(Workspace-scoped by design) — 모든 파일 및 셸 액션은 사용자의 작업 공간에 국한됩니다. 심볼릭 링크 이탈(symlink escapes)은 거부되며, 비밀 정보는 자식 프로세스에서 제거되고, 쓰기/셸 도구는 기본적으로 승인이 필요합니다.
• 실제 에이전트 하네스(A real agent harness) — 병렬 읽기 전용 배치(parallel read-only batches), 순차적 쓰기(sequential writes), 파일 복원 기능을 갖춘 컨텍스트 압축(context compaction), 루프/정지 감지(loop/stall detection), 실행 제한(run limits) (토큰/비용/기간), 회로 차단기(circuit breakers), 그리고 선택적 Langfuse 내보내기를 통한 추적(tracing)을 제공합니다.
• 격리된 서브 에이전트(Isolated sub-agents) — spawn_agent는 새로운 컨텍스트의 읽기 전용 자식 에이전트를 실행하여 조사하고 보고하며, 부모의 컨텍스트를 깨끗하게 유지합니다.
• 완료 전에 검증(Verify-before-done) — 에이전트가 코드를 편집할 때, 하네스는 작업 공간의 테스트와 타입 체크를 실행합니다. 실패한 스위트(suite)는 수정 라운드 한 번을 위해

1. Provider 추가 — 설정(Settings) → Provider 선택 (Gemini 권장) → API 키를 붙여넣습니다. 키는 저장 전에 암호화됩니다 (AES-256-GCM).
2. 작업 공간(Workspace) 추가 — 사이드바(sidebar) → 작업 공간 추가(Add Workspace) → 프로젝트 폴더를 선택합니다. 이제 에이전트는 이 폴더 내부에서 읽고 쓸 수 있으며, 각 대화가 자신의 작업 공간을 고정합니다.

설정 (Configuration)

모든 것은 server/.env에 있습니다 (server/.env.example 참조).

에이전트 루프 (The agent loop)

User prompt
  → seed history (대화 메모리, 규칙, 전문가(specialists), AGENTS.md)
  → maxIterations까지 반복:
...

이벤트는 SSE를 통해 브라우저로 스트리밍됩니다 (터미널 PTY의 경우 WebSocket만 사용). 전체 아키텍처, 모듈 맵 및 규칙: AGENTS.md.

도구 개요 (Tools at a glance)

11개 카테고리에 걸친 58개의 도구:

개발 (Development)

npm test                    # 프론트엔드 (66개 테스트)
cd server && npm test       # 백엔드 (571개 테스트)

...

총 637개의 테스트가 있으며, 모두 통과했습니다. 모든 네 가지 게이트(타입 검사(type-check), 린트(lint), 테스트(tests), 커버리지(coverage))는 커밋 전에 녹색으로 실행됩니다. 전체 워크플로우는 CONTRIBUTING.md를 참조하세요.

배포 (Deployment)

개인 기기 (Personal machine, 기본값) — 빠른 시작(Quick Start)과 같이 두 개의 터미널을 사용합니다.

Docker — 볼륨에 있는 SQLite가 별도의 설정 없이 작동합니다:

export APP_SECRET=$(node -e

**호스팅 (다중 사용자)** — Prisma 제공자를 `mysql` 또는 `postgresql`로 전환하고, `DATABASE_URL`을 데이터베이스 주소로 지정하며, `HOST=0.0.0.0` 및 `CORS_ORIGINS`를 설정한 다음, `npx prisma migrate deploy && npm run build && npm start`를 실행합니다.

## 보안 모델 (Security model)

- **작업 공간 경계 (Workspace boundary)** — 절대 경로와 `..`을 거부합니다. `realpath`는 심볼릭 링크(symlinks)를 해석하고 재확인하므로, 작업 공간 외부를 가리키는 링크는 거부됩니다.
- **정제된 셸 환경 (Sanitized shell env)** — 모든 자식 프로세스가 실행되기 전에 `APP_SECRET`, `DATABASE_URL`, 그리고 모든 `*_API_KEY` / `*_SECRET` / `*_PRIVATE_KEY`가 제거(strip)됩니다.
- **저장 시 암호화 (Encrypted at rest)** — 제공자 API 키는 `APP_SECRET`을 사용하여 AES-256-GCM으로 암호화됩니다.
- **승인 게이트 (Approval gates)** — 쓰기/셸/파괴적 도구(destructive tools)는 명시적인 승인을 필요로 합니다. 위험한 패턴의 오버레이(예: `rm -rf /`)는 자동 승인된 명령어에 대해서도 확인됩니다.
- **주입 방어 (Injection defense)** — 신뢰할 수 없는 도구 출력과 작업 공간 지침 파일은 스캔되어 데이터로 래핑되며, 절대로 명령어로 실행되지 않습니다.
- **JWT 인증 (JWT auth)** — 상태 확인/인증(health/auth)을 제외한 모든 경로는 토큰 인증 뒤에 위치하며, IP별 속도 제한이 적용됩니다.

## 일반적인 문제 (Common issues)

- **"등록된 에이전트 도구가 없습니다"** — 도구 가져오기(tool import)가 실패했습니다. 누락된 종속성(dependency)을 확인하려면 백엔드 로그를 확인하세요.
- **"API 키가 누락되었습니다"** — 설정(Settings) → 제공자(provider) → 키 추가(add key) → 활성화되었는지 확인합니다.
- **Windows에서 PTY가 시작되지 않음** — `node-pty`는 VS Build Tools (C++ 워크로드)가 필요합니다. 이것이 없으면 셸은 `child_process.exec`으로 대체됩니다.
- **SQLite "데이터베이스가 잠겼습니다"** — 임의의 노드 프로세스가 파일을 점유하고 있습니다. 해당 프로세스를 중지하고 다시 시작하세요.

## 감사의 글 (Acknowledgements)

이 하네스(harness) 설계는 오픈 에이전트 생태계의 최고 장점들을 활용했습니다. Claude Code의 압축 및 서브-에이전트 패턴, QoderWork의 도구 카탈로그, Odysseus의 대기 감지(stall detection), 그리고 Model Context Protocol 사양을 참고했습니다.

## 라이선스 (License)

[MIT](LICENSE)