Agent Hub
한국어 | English
Claude Code·Codex CLI 세션을 휴대폰에서 실시간 모니터링하고 질문 답변, 권한 승인, 명령 전송까지 하는 Windows용 P2P 원격 제어 도구입니다.
🔐 클라우드를 거치지 않고 내 기기끼리 직접, 내가 승인한 기기만
자리를 비워도 휴대폰으로 Claude·Codex의 질문에 답하고, 위험한 작업을 승인하고, 명령까지 보냅니다.
NetBird 같은 P2P VPN으로 PC·폰을 직접 연결하면 집·회사·카페·LTE 어디서나 쓸 수 있고(같은 네트워크에 있다면 VPN 없이도 가능), 제어·모니터링 통신은 우리 클라우드를 거치지 않고 내 기기끼리 직접 오갑니다(앱을 닫았을 때 오는 알림만 암호화되어 외부 푸시 서비스를 거칩니다). 어떤 기기가 접근·제어할지는 내가 PC에서 직접 승인·관리합니다.
📖 사용 가이드
NetBird 연결 → 인증서 등록 → 앱 설치(홈 화면 추가) → 기기 인증 → 원격 제어까지, 그림으로 한눈에 따라 하는 가이드를 준비했습니다.
다운로드 & 설치
- 최신 버전 다운로드 페이지에서 **
AgentHub-win-Setup.exe**를 받습니다.
- 받은 파일을 더블클릭해 설치합니다. (관리자 권한 필요 없음)
- 처음 실행할 때 인증서 설치 창이 뜨면 예를 눌러 주세요.
💡 파란 화면으로 "Windows의 PC 보호" 경고가 뜨면 추가 정보 → 실행을 누르면 됩니다. (서명되지 않은 프로그램이라 나타나는 안내입니다.)
Agent Hub는 창 없이 트레이에 상주하는 백그라운드 앱입니다.
- 시작 메뉴·바탕화면 바로가기로 실행하면 기본 브라우저에 화면이 열립니다. 이미 실행 중일 때 다시 실행해도 화면만 열립니다.
- Windows 로그인 시 자동 실행될 때는 화면 없이 트레이에만 조용히 상주합니다.
- 서버가 꺼진 채 PC에서 설치한 앱(PWA)을 열면 서버를 자동으로 켭니다(
agenthub:// — 처음 한 번은 브라우저가 열지 물어봅니다).
- 트레이 아이콘 더블클릭·열기는 앱(PWA)이 설치돼 있으면 앱 창으로 엽니다(이미 열려 있으면 그 창을 앞으로). 앱이 탭으로 열리면 크롬
chrome://apps에서 Agent Hub를 우클릭 → 창으로 열기를 켜세요.
- 트레이 메뉴: 열기 · 업데이트 · 완전 종료
- 화면은 PC와 휴대폰에서 똑같이 쓰는 PWA입니다. PC에서는 Edge·Chrome으로
https://127.0.0.1:<포트>/host(트레이 열기가 여는 주소)를 연 뒤 주소창의 설치 아이콘 → 설치로 앱처럼 쓸 수 있습니다. Agent Hub 자체 루트 인증서가 실행 시 Windows 사용자 신뢰 저장소에 등록되므로 경고 없이 HTTPS로 열립니다.
빠른 시작 (휴대폰 연결)
- PC에서 화면을 엽니다(바로가기 실행 또는 트레이 열기). 상단바에 접속 주소가 표시됩니다. 사설망(LAN) 주소와 VPN(NetBird 등) 주소가 각각 label과 함께 나옵니다. (예:
LAN https://192.168.0.10:47600, VPN https://100.x.x.x:47600)
- 휴대폰에 인증서를 설치하고(
/api/cert, 상단바 ▣ QR로도 받을 수 있음) 브라우저에 그 주소를 입력합니다. 같은 네트워크라면 LAN 주소로, 밖에서 쓸 거라면 PC·폰 양쪽에 NetBird를 설치·로그인한 뒤 VPN 주소로 접속합니다.
- 기기 인증 요청 → PC 화면 왼쪽 메뉴 기기에서 승인하면 휴대폰에도 PC와 같은 오피스 화면이 표시됩니다. (휴대폰에는 오피스만 보이고, 기기 승인·로그·설정은 PC 전용입니다.)
- 알림을 받으려면 휴대폰 상단바의 🔔 알림 켜기를 누릅니다.
📱 알림을 받으려면 **인증서 등록 + 홈 화면에 추가(앱 설치)**가 필요합니다. 그림으로 따라 하는 자세한 과정은 **사용 가이드**를 보세요.
주요 기능
- 오피스 — Windows·WSL의 모든 Claude Code·Codex 세션이 오피스(파스텔 톤 방을 부드러운 벡터 그래픽으로, 라이트/다크 테마)의 캐릭터(후드티 입은 고양이·강아지)로 나타나, 하는 일에 따라 방을 옮겨 다닙니다: 📚 자료실(파일 읽기·검색·웹 조회 — 참조 카드에 파일 경로·URL·검색어 표시) · 🗂 사무실(생각 정리·할 일 목록·서브에이전트 위임) · 🔧 작업실(코드 수정·명령 실행) · 🔔 상담실(질문·권한 확인으로 당신을 기다리는 중) · ☕ 휴게실(턴 사이 휴식 — 조용히 쉬고 이름표는 마우스를 올리면 표시). 💭 생각 요약·💬 에이전트 설명 풍선과 프로젝트 이름·실행 위치(· Codex, · WSL) 이름표가 붙습니다. 방은 이름판을 끌어 배치를 바꾸고 오른쪽 아래 모서리를 끌어 방을 넓히며(브라우저별 저장), 🎨 버튼으로 바닥(단색·마루·타일, 색상별)을 고를 수 있고, 이름판에 마우스를 올리면 역할과 안에 있는 에이전트가 보입니다. 휠로 확대·축소, 드래그로 이동(휴대폰은 핀치·드래그). 서브에이전트·백그라운드 셸은 작은 캐릭터로 메인 에이전트와 하트 끈(가까우면 손잡기)으로 이어집니다. 프롬프트를 보낼 수 있는 세션만 표시되고(종료된 세션은 사라짐), 목록은 바뀐 부분만 갱신해 몇 초 안에 뜹니다.
- 채팅 패널 — 캐릭터·생각 풍선·이름표나 오른쪽 목록 카드를 클릭하면(휴대폰도 동일) 오른쪽에 대화 | 터미널 탭 패널이 열립니다 — 실시간 활동 피드(굵게·
코드 표시)·질문 카드(여러 질문·기타 직접 입력)·권한 허용/거부·프롬프트 입력. PC에서는 왼쪽 가장자리를 끌어 폭 조절. 질문·권한 요청은 오피스 토스트와 Windows 트레이 알림으로도 알리고, 알림을 클릭하면 그 세션 채팅이 열립니다.
- 새 에이전트 실행 — 오른쪽 목록 아래 ＋ 카드(휴대폰은 하단 바 ＋)에서 엔진(Claude Code/Codex)·실행 위치(Windows 또는 설치된 WSL 배포판)·작업 폴더(최근 작업 폴더 10개 목록에서 바로 선택)·첫 프롬프트(선택)를 고르면 AgentHub의 자식 프로세스(ConPTY)로 콘솔 창 없이 숨겨져 실행되고, 채팅 패널 터미널 탭에서 보고 입력합니다. AgentHub를 종료하면 함께 종료됩니다. 휴대폰(승인된 기기)에서도 가능. 해당 환경에 CLI(
claude/codex) 설치 필요.
- 한 화면 · 왼쪽 메뉴 — 오피스 · 기기(기기 승인 + 접속 중인 기기) · 로그 · 설정. 한 줄 상단바에 서버 상태·LAN/VPN 주소·QR·사용법·언어·☀️/🌙 테마. 기본은 라이트 테마이고, 고른 테마는 콘솔·오피스·채팅 패널이 함께 씁니다.
- 어디서나 접속 — NetBird 같은 P2P VPN으로 PC·폰을 직접 연결. 인증서가 VPN IP 대역(
100.64.0.0/10)을 자동 포함해 발급되고, 콘솔 상단에 LAN·VPN 주소가 각각 표시됩니다.
- 폰에서 원격 제어 — 질문 답변·위험 작업 허용/거부·명령 전송. (선택: 세션 터미널로 프롬프트·/슬래시 명령까지)
- 자리 비움을 아는 권한 승인 — 자리를 비운 사이(마지막 키·마우스 입력 후 1분)엔 권한 요청을 최대 약 10분 붙들어 폰에서 허용/거부하고, PC를 쓰는 중이면 PC 터미널에 바로 프롬프트를 띄웁니다. 대기 시간이 지난 요청도 권한 대기 카드로 남아 폰에서 답할 수 있습니다.
- 앱을 닫아도 알림 — 세션이 당신을 기다릴 때 푸시가 오고, AI 세션의 마지막 메시지가 본문에 표시됩니다.
- WSL 세션도 똑같이 — WSL(Ubuntu 등)에서 실행한 Claude·Codex CLI 세션도 자동 감지되고(최신 exec/apply_patch 형식의 Codex 세션도 도구 활동 표시), 알림·질문 답변·권한 승인·명령 전송이 Windows 세션과 동일하게 동작합니다.
- 기기 인증 — 승인된 기기만 접근. PC에서 요청을 승인·해제·삭제할 수 있습니다.
- 트레이 상주 · 자동 업데이트 — 창 없이 트레이에 조용히 있고(메뉴: 열기 · 업데이트 · 완전 종료), 새 버전은 자동으로 적용됩니다.
Claude Code 공식 원격 제어와 무엇이 다른가요?
Claude Code에는 세션을 원격에서 이어받는 공식 Remote Control 기능이 있습니다. 목표(자리를 비운 사이 폰에서 Claude를 제어)는 비슷하지만, Agent Hub는 연결 방식과 전제가 근본적으로 다릅니다.
| Claude Code Remote Control (공식) | Agent Hub |
|---|
| 연결 경로 | Anthropic 클라우드(API) 경유 | 클라우드 없이 내 기기끼리 직접(P2P) — 제어·모니터링 통신이 우리 클라우드를 거치지 않음 |
| 접근 범위 | 인터넷 어디서나 | NetBird 등 VPN으로 어디서나 (내 기기끼리 직접) · 같은 네트워크면 VPN 없이도 |
| 필요 조건 | Pro/Max/Team/Enterprise 구독 + 계정 로그인 | 구독 무관 — 로컬에 Claude Code만 있으면 됨 |
| 접근 통제 | 계정·조직 정책 / 신뢰 기기 | 내 PC에서 기기별 직접 승인 |
| 대상 세션 | 원격 제어로 켠 세션 | 로컬에서 돌고 있는 세션들을 자동 감지해 한눈에 |
| 클라이언트 | 네이티브 모바일 앱 · 웹 | PWA(앱으로 설치) — PC·휴대폰에서 같은 화면 |
💡 한마디로, 클라우드를 거치지 않고 내 기기끼리 직접, 내가 승인한 기기만 쓰고 싶을 때 Agent Hub가 맞습니다. NetBird 같은 VPN으로 유선·무선 상관없이 어디서나. (앱을 닫았을 때 오는 알림만 암호화되어 외부 푸시 서비스를 거칩니다.)
설정 · 업데이트
- PC 화면 왼쪽 메뉴 설정에서 서버 포트(기본
47600)와 표시 언어(한국어/English)를 바꿀 수 있습니다.
- 새 버전은 자동으로 내려받아 다음 실행 때 적용됩니다. (트레이 메뉴 업데이트 → 지금 업데이트 후 재시작으로 즉시 적용도 가능)
크레딧
- 오피스 화면은 MIT 라이선스 pixel-agents를 바탕으로 만들었습니다. 캐릭터·가구·타일은 Agent Hub용으로 새로 만든 오리지널 아트입니다 — 화면은
office/webview-ui/src/hub/vectorScene.ts가 벡터로 그리고, 배치·가구 목록은 office/art가 생성합니다.
문의
문제가 있거나 제안할 내용이 있으면 이슈로 남겨 주세요.
