<p align="center">
<img src="https://raw.githubusercontent.com/douglasjunior/agent-remote-control/HEAD/.github/assets/banner.svg" alt="Agent Remote Control: your AI dev team, one message away. The CEO agent delegates to the Product Owner, Tech Lead, Developer, Code Reviewer and Git Ops agents while a Discord thread shows each step finishing, up to an opened pull request." width="100%">
</p>
<p align="center">
어디에서든 메시지를 보내면, 사용자가 이미 사용하는 CLI(Command Line Interface)를 통해 *사용자*의 머신에서 실행되는 전문 AI 코딩 에이전트 팀이 요청을 범위 설정하고(scopes), 계획하며, 코드를 작성하고, 검토하고, 풀 리퀘스트(pull request)를 엽니다.
</p>
<p align="center">
<a href="LICENSE"><img src="https://img.shields.io/github/license/douglasjunior/agent-remote-control?style=flat-square&color=7C3AED" alt="MIT License"></a>
<a href="https://agentclientprotocol.com"><img src="https://img.shields.io/badge/protocol-ACP-0EA5E9?style=flat-square" alt="Agent Client Protocol"></a>
<img src="https://img.shields.io/badge/node-%3E%3D24-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js >= 24">
<img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript strict">
<img src="https://img.shields.io/badge/built_with-NestJS-E0234E?style=flat-square&logo=nestjs&logoColor=white" alt="Built with NestJS">
<img src="https://img.shields.io/badge/Discord-bot-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord bot">
<img src="https://img.shields.io/badge/remote_access-WebRTC-0F766E?style=flat-square&logo=webrtc&logoColor=white" alt="Remote access over WebRTC">
<a href="https://github.com/douglasjunior/agent-remote-control/pulls"><img src="https://img.shields.io/badge/PRs-welcome-22C55E?style=flat-square" alt="PRs welcome"></a>
</p>
<p align="center">
<a href="#-quick-start"><b>빠른 시작</b></a> ·
<a href="#-why-agent-remote-control"><b>이유</b></a> ·
<a href="#-web-interface"><b>웹</b></a> ·
<a href="#️-remote-access"><b>원격 접속</b></a> ·
<a href="#-supported-agents"><b>에이전트</b></a> ·
<a href="#-meet-the-team"><b>팀 소개</b></a> ·
<a href="#-how-it-works"><b>작동 방식</b></a> ·
<a href="#-discord-setup"><b>Discord 설정</b></a> ·
<a href="#-contributing"><b>기여</b></a>
</p>
💡 에이전트 원격 제어는 왜 필요한가요?
AI 코딩 에이전트는 사용자가 그 에이전트를 실행하는 터미널 앞에 앉아 있을 때 놀라운 성능을 발휘합니다. Agent Remote Control은 이러한 '책상'이라는 물리적 위치의 제약을 없애줍니다. 이 시스템은 Claude Code, Codex, Copilot, Cursor, Antigravity, OpenCode를 전 세계 어느 브라우저에서든 열 수 있는 웹 인터페이스와 Discord에 연결하고, 전문화된 페르소나 팀으로 묶어 사용자가 휴대폰에서도 실제 저장소(repository)에서 실질적인 작업을 진행할 수 있도록 합니다.
-
📱 어디서든 코딩. 소파 위, 기차 안, 혹은 커피를 사 가는 길에: 브라우저나 Discord만 열 수 있다면 개발을 완료할 수 있습니다.
-
🛰️ 당신의 장치, 단 하나의 링크 거리. 원격 접속 기능을 켜면 서버가 링크를 출력합니다. 이 링크를 휴대폰에서 열고 브라우저는 포트 개방이나 VPN 없이 엔드투엔드 암호화된 WebRTC 채널을 통해 당신의 장치와 통신합니다.
-
👥 단일 에이전트가 아닌 팀. CEO 에이전트가 사용자에게 이야기하고, 요청 범위를 정의하며, 필요에 따라 Product Owner, Tech Lead, Developer, Code Reviewer, QA, Git Ops 에이전트들에게 병렬적으로 작업을 위임합니다.
-
🔌 자신만의 에이전트를 가져오세요. 다섯 가지 에이전트 CLI를 기본으로 지원합니다. /agent로 전환하고, /model로 모델과 노력을 선택하며, /profiles로 각 페르소나를 개별적으로 조정할 수 있으며, 모든 에이전트는 자체 세션을 유지합니다.
-
🏠 셀프 호스팅, 당신의 자격 증명(credentials). 저장소, SSH 키, CLI 로그인은 여전히 사용자의 장치에 남아 있습니다. 중간에 호스팅되는 중개자나 추가 API 키가 필요 없습니다. 이미 가지고 있는 구독을 재사용합니다.
-
👀 실시간 작동 확인. 추론(Reasoning) 및 도구 호출(tool calls)이 발생하는 즉시 웹 피드와 Discord 스레드로 스트리밍됩니다.
-
📋 미션별 보드 제공. 모든 대화는 웹 인터페이스에서 트리 또는 칸반(Kanban) 형태로 기능 및 작업 보드를 유지합니다. 제품 책임자(Product Owner)가 비즈니스 측면을 작성하고, 기술 리드(Tech Lead)가 기술 솔루션을 제시하며, 개발자(Developer)가 구현하고, Git Ops가 풀 리퀘스트(pull request)를 연결하며, 코드 검토자(Code Reviewer)가 이를 검토하고 QA가 실제로 테스트합니다. 각 에이전트가 작업 자체를 읽고 작성하며, 한 번에 하나의 작업을 처리하고 모든 변경 사항의 전체 기록을 유지합니다. 사용자가 직접 작업을 생성하여 간단한 요청을 개발팀으로 바로 보낼 수도 있습니다.
-
🙋 에이전트가 질문하고, 사용자가 답변합니다. 내용이 모호할 경우, 에이전트들이 채팅창에서 한 번에 하나씩 사용자에게 질문합니다.
-
🧵 하나의 스레드, 하나의 작업. 각 서버 스레드는 격리된 세션이며, DM은 연속적인 세션을 유지합니다. 세션은 재시작 후에도 살아남아 중단했던 지점부터 다시 시작할 수 있습니다.
-
🛑 언제든지 방향을 조정하거나 멈출 수 있습니다. Claude Code가 작업하는 동안 후속 조치를 보내 방향을 조정할 수 있고, /cancel를 사용하여 현재 턴(turn)을 중단할 수 있습니다.
-
🌍 사용자의 언어를 구사합니다. 답변은 사용자가 작성한 언어를 따르며, 에이전트들은 서로 영어로 대화합니다.
-
🧱 확장을 염두에 두고 구축되었습니다. 포트 및 어댑터(Ports & Adapters)를 사용한 클린 아키텍처(Clean Architecture): 웹 인터페이스와 Discord는 채널이며, ACP는 에이전트 계약(agent contract)이고, 새로운 채널이나 에이전트는 어댑터만 거치면 연결할 수 있습니다.
🚀 빠른 시작 (Quick Start)
Node.js 24+, Git 및 최소한 하나의 지원되는 에이전트 CLI가 설치되어 로그인해야 합니다. Discord 봇 토큰은 Discord 봇에만 필요하며, 웹 인터페이스는 이것 없이도 작동합니다.
git clone https://github.com/douglasjunior/agent-remote-control.git
cd agent-remote-control
pnpm install
...
브라우저를 사용하려면 Web interface를 따르고, 다른 네트워크에서 접속하려면 Remote access를 이용하세요. Discord를 사용하려면 봇을 서버에 초대하고(step by step), DM을 보내거나 채널에서 언급한 후, 번호가 매겨진 메뉴에서 에이전트(agent), 모델(model), 노력도(effort)를 선택하고 작업이 실행되는 것을 지켜보세요.
[!WARNING]
에이전트는 호스트 머신에서 완전한 자율성으로 실행됩니다. Claude Code는 bypassPermissions 모드에서, Copilot은 allow_all로, Codex와 Cursor는 승인이나 샌드박스 없이 실행됩니다. 이 봇에게 메시지를 보낼 수 있는 사람은 누구나 귀하의 자격 증명(credentials)을 사용하여 명령을 실행할 수 있습니다. 봇은 신뢰하는 사람들과 함께 비공개 서버에 유지하고, 전용 머신, VM 또는 컨테이너에서 실행하는 것을 고려하세요. 이는 **웹 접근 토큰(web access token)**에도 동일하게 적용됩니다. 이 토큰을 가진 사람은 누구나 호스트에서 에이전트를 실행할 수 있으므로, 절대 공유하거나 신뢰할 수 없는 네트워크에 서버 포트를 노출하지 마세요.
🌐 Web interface
Discord 없이 에이전트와 채팅할 수 있는 브라우저 인터페이스입니다. 이는 /ws의 WebSocket을 통해 서버와 통신하는 별도의 앱(packages/web)입니다.
- 서버 시작 (
pnpm dev:server를 사용하거나, 서버와 웹 앱을 함께 시작하려면 pnpm dev를 사용하세요).
- 서버 로그(Web interface access token: ...) 또는
DATA_DIR/web/access-token에서 접근 토큰을 복사합니다. Docker의 경우, docker logs <container>를 실행하세요.
- 웹 앱을 열고 처음 사용할 때 토큰을 붙여넣으세요. URL에
#token=<token> 형식의 프래그먼트도 작동하며, 이는 저장된 후 주소 표시줄에서 제거됩니다.
대화 목록은 왼쪽 사이드바에 표시되며, 각 대화는 메뉴에서 이름 변경 또는 보관 처리할 수 있습니다. 보관된 항목들은 목록 끝의 접힌 그룹으로 이동하며 여전히 열려 있습니다. 헤더의 책 아이콘을 클릭하면 에이전트가 읽는 스킬(skills) 목록이 열리며, 각 스킬을 읽은 역할과 전체 콘텐츠를 확인할 수 있습니다. 사용자 정의 스킬에는 해당 스킬에 대한 변경을 요청하는 대화를 시작하는 "CEO에게 문의하기(Ask the CEO)" 버튼과 삭제(Delete) 버튼이 있습니다. 에이전트가 읽거나 작성한 모든 스킬은 활동(activity), 웹 피드(web feed), 그리고 Discord 스레드에 표시되며, 스쿼드 패널(squad panel)에는 각 역할의 에이전트, 모델 및 노력 정도가 표시됩니다.
| Mode | Command | URL |
|---|
| Development | pnpm dev:web | http://localhost:5173 |
| ... | | |
Rsbuild (dev 및 preview)는 루트 .env의 PORT(기본값 3000)를 사용하여 /ws와 /health를 서버로 프록시합니다. 따라서 브라우저는 단일 오리진을 보고 서버의 오리진 검사를 통과할 수 있습니다. 만약 웹 앱이 대신 서버에 직접 도달하는 경우, 해당 오리진을 WEB_ALLOWED_ORIGINS에 나열해야 합니다. | | |
nginx 예시
server {
listen 80;
server_name arc.example.com;
...
| Variable | Description | Default |
|---|
WEB_ENABLED | 웹 채널을 서버에서 제외하려면 false로 설정합니다. | true |
| ... | | |
🛰️ 원격 액세스 (Remote access)
라우터에 포트를 열 필요도 없고 VPN이 필요하지 않은 전 세계 모든 브라우저에서 서버에 접속할 수 있습니다. 원격 액세스는 **기본적으로 비활성화(off by default)**되어 있습니다. REMOTE_ENABLED=true와 REMOTE_URL을 설정하면, 서버가 시작 시 다음 링크를 출력합니다:
Remote access link: <REMOTE_URL>/i/<instance id>#fp=<certificate fingerprint>&token=<access token>
이를 열면 시그널링 서버(signaling server)로부터 웹 앱이 로드되며, 이는 단지 브라우저를 서버에 소개하는 역할만 합니다. 그 후 네트워크가 허용할 경우 직접 WebRTC 데이터 채널을 통해 통신하고, 그렇지 않은 경우에는 TURN 릴레이(TURN relay)를 통해 통신하며, 어느 쪽이든 양방향으로 종단 간 암호화(end to end encrypted)됩니다. 헤더의 연결 배지에는 이 두 가지 중 어떤 것이 해당 기능을 담당하는지 (또는 로컬 웹 인터페이스의 경우 WebSocket) 표시됩니다.
- 링크를 비공개로 유지하세요. 이 링크는
#token=과 같은 액세스 토큰을 포함합니다.
- 이 링크가 서버를 고정(pin)합니다. 해당 페이지는 링크가 담고 있는 인증서 지문(fingerprint)을 제시하지 않는 모든 서버를 거부하며, 인스턴스 ID는 그 인증서에서 파생되므로 시그널링 서버조차도 귀하의 서버 대신 사용할 수 없습니다.
- 토큰은 브라우저와 귀하의 서버 사이에 머무릅니다. 귀하의 서버가 브라우저에 어떤 비용을 지불하기 전에, 브라우저는 자체 인증서에 바인딩된 코드를 통해 토큰을 가지고 있음을 증명하며, 시그널링 서버는 이 토큰을 학습하지 않고 이를 중계합니다. 잘못된 증명이 있을 때마다 같은 주소에서 오는 다음 증명은 더 오래 기다리게 됩니다.
- 강력한 토큰이 필요합니다.
WEB_ACCESS_TOKEN에 32자 미만의 문자가 포함되어 있으면 원격 액세스가 비활성화됩니다. 생성된 토큰을 사용하려면 이 값을 빈 문자열로 두세요.
- 링크는 재시작 후에도 살아남습니다. 인증서와 키는
DATA_DIR/remote에 저장되므로, 새 링크를 위해 해당 폴더를 삭제하세요.
[!중요]
원격 액세스는 시그널링 서버 운영자를 신뢰합니다. 이 링크가 열리는 페이지는 REMOTE_URL에서 오며, 해당 서버를 운영하는 사람은 액세스 토큰을 읽어낼 수 있는 페이지를 제공할 수 있습니다. 이것이 바로 REMOTE_URL에 기본값이 없는 이유입니다: 신뢰하는 서버로 지정하거나 직접 호스팅하세요.
공개 시그널링 서버. 이 프로젝트의 작성자는 누구나 자신의 위험을 감수하고 사용할 수 있는 TURN 릴레이가 포함된 공개 시그널링 서버를 운영합니다:
REMOTE_URL=https://arc-p2p-server.arc.douglasjunior.work
이 서버는 아무것도 저장하지 않습니다: 데이터베이스도 없으며, 서버와 연결을 메모리에서만 유지하고 협상되는 연결 상태만을 관리합니다. 또한 귀하의 대화 내용을 절대 볼 수 없습니다. 대화 내용은 포함된 릴레이를 통해 브라우저와 귀하의 서버 간에 종단 간 암호화(end to end encrypted)됩니다. 이 서버의 로그는 인스턴스 ID나 속도 제한으로 거부된 주소와 같은 연결 이벤트만 기록할 뿐, 액세스 토큰이나 메시지는 절대 기록하지 않습니다.
[!WARNING]
면책 조항(Disclaimer). 공용 시그널링 서버 및 TURN 릴레이는 이용 가능성, 용량, 성능, 보안 또는 특정 목적에의 적합성을 포함하여 어떠한 종류의 명시적 또는 묵시적 보증 없이 "있는 그대로(as is)" 무료로 제공됩니다. 이들은 예고 없이 변경, 속도 제한(rate limited), 일시 중지 또는 종료될 수 있습니다. 이를 사용한다는 것은 귀하의 접근 토큰(access token)이 기기에서 명령을 실행하는 에이전트들을 제어하는 페이지를 운영자에게 신뢰한다는 의미입니다. 어떠한 경우에도 저자는 귀하의 기기에 대한 무단 액세스(unauthorized access), 데이터 손실 또는 서비스 중단을 포함하여 이들의 사용으로 인해 발생하거나 관련되는 모든 청구, 손해 또는 기타 책임에 대해 책임을 지지 않습니다. 이러한 약관을 수락하지 않는 경우 사용하지 마십시오: 자체 호스팅하기.
| 변수 (Variable) | 설명 (Description) | 기본값 (Default) |
|---|
REMOTE_ENABLED | 시그널링 서버를 통해 이 서버에 접속하려면 true로 설정합니다. | false |
REMOTE_URL | 브라우저가 이 서버를 소개받고 링크의 웹 앱을 제공하는 시그널링 서버의 HTTPS URL입니다. localhost의 경우 일반 HTTP만 가능합니다. | (원격 액세스 시 필수) |
시그널링 서버 및 TURN 릴레이 자체 호스팅하기는 packages/p2p-server, coturn 및 CapRover를 사용한 배포 방법을 다룹니다.
🤖 지원되는 에이전트 (Supported Agents)