Agentrove
하나의 인터페이스에서 Antigravity, Claude Code, Codex, Copilot, Cursor, Grok, OpenCode 에이전트를 실행하고 오케스트레이션할 수 있는 자체 호스팅 AI 코딩 작업 공간입니다.
License: Apache 2.0
Python 3.12
React 19
Discord
Chat Interface
기능 (What It Does)
- ACP 어댑터를 통해 Antigravity, Claude, Codex, Copilot, Cursor, Grok, OpenCode를 실행합니다.
- 각 작업 공간에 자체 Docker 또는 호스트 샌드박스를 제공합니다.
- 채팅, 코드 에디터, 터미널, 파일 트리, diffs, secrets, git 도구를 하나의 작업 공간에 결합했습니다.
- 빈 폴더, git 클론, 기존 로컬 폴더, 또는 GitHub 저장소에서 오는 작업 공간을 지원합니다.
- 취소 기능, 권한 프롬프트, 대기열 처리된 후속 메시지, 파일 언급, 슬래시 명령어, 첨부 파일을 포함하여 에이전트 세션을 스트리밍합니다.
- 서브 스레드(sub-threads), 고정 채팅(pinned chats), 워크트리 모드(worktree mode), 페르소나(personas), 사용자 지정 지침(custom instructions), 환경 변수 등을 포함합니다.
- 번들된 MCP 서버를 통해 다중 에이전트 워크플로우를 오케스트레이션합니다: 리드 채팅(lead chat)이 설치된 모든 에이전트, 모델 및 페르소나에 작업자 서브 스레드를 병렬 워크트리에서 생성하고 필요에 따라 결과를 검토합니다.
- 채널을 호스팅합니다: 여러 에이전트가 각자의 모델과 페르소나를 가지고 하나의 공유된 작업 공간에서 토론하고 작업하는 그룹 채팅입니다.
- GitHub 지원 저장소 탐색, 풀 리퀘스트(pull request) 검토, PR 생성, 리뷰어 선택 및 git 브랜치/커밋/푸시/풀 도우미 기능을 제공합니다.
- Docker 웹 앱, macOS 데스크톱 앱, 네이티브 iOS 앱 형태로 배포됩니다.
에이전트 오케스트레이션 (Orchestrating Agents)
Agentrove 채팅은 단순한 엔드포인트가 아닙니다. 서로를 구동할 수 있습니다. 번들된 MCP 서버(mcp-server/)는 전체 인스턴스를 도구(tools)로 노출합니다 (send_message, get_messages, list_models, list_personas 등). 따라서 모든 채팅의 에이전트는 이러한 도구를 사용할 수 있게 됩니다. 이는 어떤 채팅이라도 오케스트레이터가 될 수 있음을 의미합니다: 강력한 모델을 사용하는 리드 에이전트가 작업을 분해하고, 각 작업을 올바른 에이전트로 라우팅하며, 돌아오는 결과를 검토하는 방식입니다.
기본 요소들 (The primitives):
- 서브 스레드(Sub-threads) —
send_message(parent_chat_id=…)는 동일한 작업 공간과 브랜치 내에서 리드 채팅 아래에 그룹화된 워커 채팅을 생성합니다. 서브 스레드는 평면적으로 유지됩니다 (중첩 없음): 리드가 분산하고, 워커들이 결과를 보고합니다.
- 턴별 모델 및 페르소나(Per-turn model and persona) — 각 워커는 설치된 모든 에이전트와 모델(
model_id)을 사용하여 어떤 페르소나(사용자 정의 시스템 프롬프트)로도 실행됩니다. 일반적인 구성: 코드베이스 탐색을 위한 읽기 전용 스카우트 페르소나를 가진 빠른 모델, 구현을 위한 코딩 모델, QA를 위한 전담 리뷰어 페르소나(버그 찾기, 구조적 품질). list_models는 각 모델이 지원하는 추론 단계(thinking_modes)를 보고하므로, 리드는 작업별 노력을 조절할 수 있습니다.
- 격리된 워크트리(Isolated worktrees) —
worktree=true를 사용하면 워커에게 자체 Git 워크트리가 할당되어, 여러 병렬 워커가 충돌 없이 동시에 편집할 수 있습니다.
- 폴링 및 후속 조치(Polling and follow-ups) — 리드는 워커의 턴이 완료될 때까지
get_messages를 폴링하고, 그 결과를 실제 코드와 비교하여 판단하며, 워커 자신의 스레드로 재작업을 보냅니다. 후속 조치는 해당 스레드의 이전 모델, 페르소나 및 추론 설정을 상속받습니다.
- 비감독 턴(Unattended turns) — 오케스트레이션된 턴은 에이전트의 전체 실행 모드에서 실행되므로, 워커들이 권한 프롬프트 없이 작업을 완료할 수 있습니다.
일반적인 루프: 리드가 저렴하고 빠른 모델로 탐색을 시작하고, 서브 스레드의 코딩 모델에 정확한 명세(spec)를 전달하며, 리뷰어 페르소나들을 디프(diff, 코드 변경분) 위에서 병렬적으로 분산시키고, 그들의 발견 사항을 분류(triage)한 후, 승인된 수정사항을 위임하고 — 최종 결과를 소유합니다. 모델, 페르소나 및 라우팅 규칙은 모두 사용자가 정의하므로, 동일한 메커니즘이 어떤 플릿(fleet)을 실행하든지 구동됩니다.
채널(Channels)
채널은 사용자님과 여러 에이전트 간의 그룹 채팅입니다. 사이드바에서 하나를 생성하고 작업 공간(선택적으로 브랜치 또는 전용 워크트리)을 선택한 다음, 멤버들을 추가합니다 — 각 멤버는 자체 에이전트와 모델, 표시 이름, 페르소나, 사고 수준 및 권한 모드를 가집니다.
- 공유 대화(Shared conversation) — 모든 멤버가 새로운 채널 메시지를 배치(batches)로 확인하며, 짧은 답글을 게시하거나 건너뜁니다. 따라서 에이전트는 답변하기, 의견 불일치 표시하기, 수정하기, 또는 다른 사람이 놓친 것을 제안할 때만 발언합니다.
- 공유 작업 공간(Shared workspace) — 멤버들은 같은 디렉터리에서 작업하며, 파일을 편집하기 전에 어떤 파일을 변경할 것인지 공지합니다.
- 실시간 상태(Live status) — 상태 행(status row)은 어떤 멤버가 생각 중인지, 타이핑 중인지, 승인을 기다리는지, 또는 재시도하는지를 보여줍니다. 각 답글에는 도구 활동 및 지속 시간이 포함된 접힌("collapsed") "작업 완료(Worked)" 요약이 첨부됩니다.
- 제어(Control) — 파일 첨부, 인라인으로 권한 프롬프트 승인, 그리고 컴포저에서 실행 중인 멤버를 중지할 수 있습니다.
빠른 시작 (Quick Start)
필수 사항:
git clone https://github.com/Mng-dev-ai/agentrove.git
cd agentrove
cp .env.example .env
.env에 SECRET_KEY 설정:
Agentrove 시작:
http://localhost:3000을 엽니다.
Antigravity는 터미널에서 완료되는 Google OAuth를 통해 인증을 지원합니다. 이의 ACP 토큰은 Antigravity CLI 로그인과는 별개로 ~/.gemini/antigravity-acp/에 저장됩니다.
데스크톱 (Desktop)
Agentrove는 또한 Tauri를 사용하여 구축된 macOS 데스크톱 앱을 가지고 있습니다. 이 앱은 사용 가능한 127.0.0.1 포트에 번들된 Python 백엔드 사이드카(sidecar)를 시작하고, 실행 시 프론트엔드를 여기에 연결합니다.
- 릴리스에서 최신 Apple Silicon 빌드를 다운로드하세요.
- 소스에서 빌드:
cd frontend
npm install
npm run desktop:dev
릴리스 빌드는 Developer ID Identity로 서명되고 Notarize됩니다. npm run desktop:build는 환경 변수에서 이를 읽어옵니다 (저장소에는 아무것도 저장되지 않음):
APPLE_SIGNING_IDENTITY="Developer ID Application: Your Name (TEAMID)"
[email protected]
...
CI 환경에서는 또한 `APPLE_CERTIFICATE` (base64 `.p12`)와 `APPLE_CERTIFICATE_PASSWORD`를 설정하여 해당 ID가 임시 키체인에 가져와지도록 합니다. 로컬 서명되지 않은 빌드의 경우, `APPLE_SIGNING_IDENTITY=-` (ad-hoc)로 설정합니다. 기기 페어링 토큰은 macOS Keychain에 저장되며, 이는 앱의 서명과 연결되므로 ad-hoc 빌드는 재빌드할 때마다 키체인 접근 권한을 다시 요청합니다.
Agentrove는 또한 Tauri를 사용하여 네이티브 iOS 앱을 구축합니다. iOS는 로컬 백엔드 사이드카(sidecar)를 실행할 수 없기 때문에, 이 앱은 씬 클라이언트(thin client)입니다. 즉, 이미 호스팅하고 있는 Agentrove 인스턴스(Docker 또는 프로덕션 배포)와 통신하며, 이는 휴대폰에서 `https`/`wss`를 통해 접근 가능합니다. 프로젝트가 오픈 소스이기 때문에, 사용자가 직접 빌드하고 서명해야 하며 — 다른 누구의 서버에도 하드 코딩된 것은 없습니다.
요구 사항: Xcode (iOS SDK 및 시뮬레이터 포함)가 설치된 macOS, Rust iOS 타겟 (`rustup target add aarch64-apple-ios aarch64-apple-ios-sim`), 그리고 CocoaPods.
> 장치가 아직 안정적인 Xcode에 SDK가 없는 iOS 베타 버전을 실행하는 경우, 최신 안정 버전의 Xcode SDK를 대상으로 빌드합니다 (`sudo xcode-select -s /Applications/Xcode.app`) — 구형 SDK로 빌드된 앱도 더 새로운 iOS에서 실행됩니다.
앱을 인스턴스로 연결하기:
```bash
cd frontend
cp .env.mobile.example .env.mobile
npm install
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
시뮬레이터에서 실행하기:
무료 Apple ID로 자신의 iPhone에 설치 — 유료 개발자 계정 불필요 (앱은 7일마다 재서명해야 함):
- Xcode → Settings → Accounts에서 Apple ID를 추가한 다음, Manage Certificates 아래에서 Apple Development 인증서를 생성합니다.
- USB로 iPhone을 연결하고 잠금을 해제한 후 Mac의 신뢰를 설정합니다. 개발자 모드(Settings → Privacy & Security)를 활성화한 다음, 첫 설치 후에는 Settings → General → VPN & Device Management 아래에서 인증서에 대한 신뢰를 설정합니다.
독립적인 .ipa 파일을 빌드하여 연결된 iPhone에 설치합니다. 가장 쉬운 방법은 빌드(build), 서명(sign), 내보내기(export), 설치를 한 단계에서 처리하는 번들러 헬퍼입니다:
cd frontend
npm run ios:install
이 명령어는 사용자의 Apple Development 인증서 팀으로 서명하므로(팀을 재정의하려면 APPLE_DEVELOPMENT_TEAM=<YOUR_TEAM_ID>를 사용), 다른 사람의 팀에 코드가 하드코딩되지 않습니다. 연결된 첫 번째 iPhone/iPad에 설치되며, 해당 장치에 유효한 프로비저닝 프로파일이 아직 없는 경우(새 장치 또는 무료팀 프로필의 7일 경과 등)에는 먼저 장치를 사용자의 팀에 등록하고 프로파일을 생성합니다.
아니면 직접 단계를 실행할 수 있습니다 (iPhone이 연결된 상태에서 Xcode 프로젝트를 열고 이를 실행 대상으로 선택하면, Xcode가 장치를 등록하고 프로비저닝 프로파일을 생성합니다). -c 플래그는 팀 정보를 빌드 서명과 IPA 내보내기 모두에 주입하므로 커밋된 설정 파일에는 남지 않습니다. Xcode 27에서는 CARGO_PROFILE_RELEASE_DEBUG가 릴리스 링크 실패(tauri#16130)를 우회합니다:
CARGO_PROFILE_RELEASE_DEBUG=line-tables-only npm run ios:build -- --export-method debugging \
-c '{"bundle":{"iOS":{"developmentTeam":"<YOUR_TEAM_ID>"}}}'
...
나중에 앱을 업데이트하거나 무료팀의 7일이 지난 후 재서명해야 하는 경우, npm run ios:install을 다시 실행하면 됩니다. 이 독립형 빌드는 Mac에 연결된 상태를 유지하지 않고 휴대폰에서 실행됩니다.
푸시 알림 (Push notifications)
iOS 앱은 백그라운드에 있거나 전화기가 잠겨 있을 때 백엔드로부터 "작업 완료(task completed)" 및 "권한 필요(permission needed)" 푸시 알림을 받습니다. 이를 탭하면 채팅 또는 채널이 열립니다. 잠금 화면의 문구는 일반적이며, Apple로 프롬프트, 코드 또는 답장이 전송되지 않습니다.
푸시 알림을 사용하려면 유료 Apple Developer Program 멤버십이 필요하며, 무료팀 설치로는 이를 받을 수 없습니다. 개발자 포털에서:
- 푸시 알림(Push Notifications) 기능을 사용하여 앱 ID
com.agentrove.desktop을 등록합니다.
- **Apple Push Notifications service (APNs)**가 활성화된 키를 생성하고(팀 범위 지정(Team Scoped), 샌드박스 및 프로덕션 포함)
.p8 파일을 다운로드합니다.
이후 백엔드에 이 값들을 설정합니다. 세 가지 모두 설정되기 전까지는 푸시 기능이 비활성화 상태를 유지합니다:
APNS_KEY="$(awk '{printf "%s\n", $0}' AuthKey_XXXXXXXXXX.p8)"
APNS_KEY_ID=XXXXXXXXXX
APNS_TEAM_ID=<YOUR_TEAM_ID>
...
푸시는 앱 측에서 옵트인(opt-in) 방식입니다. 왜냐하면 무료 팀은 서명할 수 없는 aps-environment 권한(entitlement)이 필요하기 때문입니다. 활성화하여 빌드합니다:
cd frontend
AGENTROVE_IOS_PUSH=1 npm run ios:install
이는 권한을 생성된 Xcode 프로젝트의 권한 파일에 기록합니다(단순히 npm run ios:install를 실행하면 다시 제거됩니다). 앱은 프로비저닝 프로파일에서 샌드박스 또는 프로덕션 APNs 호스트를 가져옵니다.
푸시는 알림(Notifications) 설정을 준수합니다. 앱이 일시 중지된 상태에서 푸시를 탭하면 해당 채팅방이 열리지만, 앱을 콜드 실행(cold-launch)하는 탭은 대신 앱의 시작 페이지를 열 수 있습니다.
프로덕션 (Production)
단일 호스트 Docker 배포 시:
SECRET_KEY=$(openssl rand -hex 32) \
APP_URL=https://yourdomain.com \
ALLOWED_ORIGINS=https://yourdomain.com \
...
최초 시작 직후에 가입합니다: 빈 서버의 첫 번째 계정은 자체적으로 등록할 수 있으며, 이후 등록 기능이 닫힙니다. 더 많은 사람이 가입하도록 하려면 REGISTRATION_OPEN=true로 설정합니다. ADMIN_EMAIL/ADMIN_PASSWORD를 설정하면 시작 시 슈퍼유저(superuser)가 생성되며, 이는 첫 번째 계정으로도 간주됩니다.
스택 (Stack)
- 프론트엔드(Frontend): React 19, TypeScript, Vite, Tailwind CSS, Monaco, xterm.js
- 백엔드(Backend): FastAPI, SQLAlchemy, SQLite, Redis
- 런타임(Runtime): ACP, Docker 또는 호스트 샌드박스, Tauri 데스크톱 사이드카
Discord 서버에 참여하세요.
기여 (Contributing)
기여 및 피드백을 환영합니다.
라이선스 (License)
Apache 2.0. [LICENSE]를 참조하십시오.
