Agent Hub 사용 가이드USER GUIDE
다운로드Download

PC → 휴대폰Phone · NetBird로 어디서나anywhere via NetBird

Agent Hub로 Claude Code·Codex를
휴대폰에서 제어하세요 Control Claude Code and Codex
from your phone

자리를 비워도, 휴대폰으로 Claude·Codex가 지금 뭘 하는지 보고 질문에 답하고, 위험한 작업을 승인하고, 명령까지 보냅니다. NetBird로 PC·폰을 직접(peer-to-peer) 연결해 유선·무선·어느 네트워크에 있든 어디서나. 모두 내가 PC에서 승인한 기기만, 클라우드를 거치지 않고 내 기기끼리 직접. Step away and still use your phone to see what Claude is doing and answer its questions, approve risky actions, and send commands. NetBird links your PC and phone directly (peer‑to‑peer), so you reach it from anywhere — wired or Wi‑Fi, on any network, only from devices you approved on your PC, device‑to‑device with no cloud relay.

최신 버전 받기Get the latest 설정 시작하기 ↓Start setup ↓
🌍
어디서나 · 클라우드 없이Anywhere · no cloud relay NetBird 같은 P2P VPN으로 PC·폰을 직접 연결 — 유선·무선·어느 네트워크든 상관없이. 보고·답하고·제어하는 통신은 우리 클라우드를 거치지 않고 내 기기끼리 직접 오갑니다. 앱을 닫았을 때 오는 알림만 암호화되어 외부 푸시 서비스를 거칩니다.Connect the PC and phone directly through a P2P VPN like NetBird — wired or Wi‑Fi, on any network. Monitoring & control traffic goes device‑to‑device with no cloud relay. Only closed‑app push alerts pass through an external, encrypted push service.
📱
자리 비워도 원격 제어Control while away 앱을 닫아도 알림이 오고, 폰에서 질문 답변·권한 승인·명령까지.Alerts arrive even with the app closed; answer, approve, and command from your phone.
🔐
내가 승인한 기기만Only devices you approve 어떤 기기가 접근·제어할지 PC에서 직접 승인·해제합니다.You decide which devices can connect and control — from the PC.
🖥️ PC

PC에 설치하고 열기Install and open on the PC

Agent Hub는 창 없이 트레이에 상주하는 백그라운드 앱입니다. 화면은 PC와 휴대폰에서 똑같이 쓰는 웹 앱(PWA)이라, PC에서는 브라우저(또는 앱으로 설치한 창)로 엽니다. 브라우저로 열면 앱으로 설치하라는 안내 창이 먼저 뜹니다. 서버가 꺼진 채 PC에서 앱을 열면 서버를 자동으로 켭니다(처음 한 번은 브라우저가 “AgentHub 열기”를 물어보니 “항상 허용”을 체크하세요). Agent Hub is a background tray app with no window of its own. Its screen is a web app (PWA) used the same way on PC and phone, so on the PC you open it in the browser (or as an installed app). Opened in a browser, it first offers to install itself as an app. Open the app on the PC while the server is off and it starts the server for you (the first time the browser asks to open AgentHub — tick “Always allow”).

  1. 최신 버전에서 AgentHub-win-Setup.exe를 받아 더블클릭으로 설치합니다(관리자 권한 필요 없음). Download AgentHub-win-Setup.exe from the latest release and double‑click to install (no admin rights needed).
  2. 시작 메뉴·바탕화면 바로가기로 실행하면 기본 브라우저에 화면이 열립니다. 이미 실행 중일 때 다시 실행해도 화면만 열립니다. Launch it from the Start menu or desktop shortcut and the screen opens in your default browser. Launching it again while it's running just opens the screen.
  3. Windows 로그인 때 자동 실행되면 화면을 띄우지 않고 트레이에만 조용히 상주합니다. When it starts automatically at Windows login, it stays quietly in the tray without opening the screen.
  4. 트레이 아이콘 메뉴: 열기(화면 열기) · 업데이트 · 완전 종료. 더블클릭·열기는 앱이 설치돼 있으면 앱 창으로 엽니다(이미 열린 창은 앞으로). 앱이 탭으로 열리면 크롬 chrome://apps에서 Agent Hub 우클릭 → 창으로 열기를 켜세요. Tray icon menu: 열기 / Open (open the screen) · 업데이트 / Update · 완전 종료 / Quit. Double-click or Open brings up the app window when the app is installed (an open one comes to the front). If it opens as a tab, right-click Agent Hub in Chrome's chrome://apps → Open as window.
  5. PC에서도 앱으로 설치: Edge·Chrome으로 https://127.0.0.1:<포트>/host를 연 상태에서(트레이 열기가 이 주소를 엽니다) 주소창의 설치 아이콘 → 설치. 이후엔 자기 창을 가진 앱처럼 열립니다. Install it as an app on the PC too: with https://127.0.0.1:<port>/host open in Edge/Chrome (the tray Open item opens this address), click the install icon in the address bar → Install. From then on it opens in its own app window.
✅ Agent Hub는 실행할 때 자체 루트 인증서(AgentHub Root CA)를 Windows 사용자 신뢰 저장소에 등록하므로, PC에서는 경고 없이 HTTPS로 열립니다. 처음 실행할 때 인증서 설치 창이 뜨면 예를 눌러 주세요. ✅ At startup Agent Hub registers its own root certificate (AgentHub Root CA) in the Windows user trust store, so HTTPS opens on the PC without warnings. If a certificate install dialog appears on first launch, click Yes.

PC 화면 둘러보기A tour of the PC screen

  1. 왼쪽 메뉴: 🏢 오피스 · 📱 기기 · 📜 로그 · ⚙️ 설정. 기기 메뉴 하나에서 기기 인증 요청 승인과 지금 접속 중인 기기를 함께 봅니다. 메뉴는 상단 바 왼쪽 ☰를 눌러 여닫습니다(기기 승인 대기가 있으면 ☰에 빨간 점). Left menu: 🏢 Office · 📱 Devices · 📜 Logs · ⚙️ Settings. The single Devices menu holds both device approval requests and the devices connected right now. Open and close the menu with ☰ at the left of the top bar (a red dot means a device is waiting for approval).
  2. 한 줄 상단바: 서버 상태 · LAN/VPN 주소 · ▣ QR · 사용법(이 가이드) · 언어 · ☀️/🌙 테마 One‑line top bar: server status · LAN/VPN addresses · ▣ QR · 사용법 / How to (this guide) · language · ☀️/🌙 theme
  3. 테마는 라이트가 기본이고 다크로 바꿀 수 있습니다. 고른 테마는 콘솔·오피스·채팅 패널에 함께 적용됩니다. Light is the default theme, with dark available. Your choice is shared by the console, office, and chat panel.
  4. 휴대폰에서는 오피스만 보입니다 — 기기 승인·로그·설정은 PC 전용입니다. Phones see only the office — device approval, logs, and settings are PC‑only.
STEP 01

NetBird로 어디서나 연결Connect from anywhere with NetBird

Agent Hub는 클라우드 서버가 없어 PC와 휴대폰이 서로 직접(peer-to-peer) 연결됩니다. NetBird 같은 오버레이 VPN을 PC와 휴대폰 양쪽에 깔아 같은 계정으로 로그인하면 두 기기가 하나의 가상 네트워크로 묶여, 유선이든 무선이든·집·회사·카페·LTE 등 어느 네트워크에 있든 그대로 접속됩니다. 통신은 여전히 내 기기끼리 직접(WireGuard 암호화) 오가고, 개인용은 무료입니다. (더 간단한 Tailscale도 대안으로 쓸 수 있어요 — 둘 중 하나만 고르면 됩니다.) Agent Hub has no cloud server, so the PC and phone connect directly (peer‑to‑peer). Install an overlay VPN like NetBird on both the PC and phone and sign in with the same account: the two join one virtual network and stay reachable on wired or Wi‑Fi, at home, office, cafe, or on mobile data — whatever network you're on. Traffic still flows device‑to‑device (WireGuard‑encrypted), and it's free for personal use. (The simpler Tailscale works as an alternative — pick just one.)

🐦NetBird추천recommended

무료 클라우드로 바로, 원하면 내 서버로도.Free cloud out of the box, or host it yourself.

  1. PC: netbird.io에서 Windows용을 설치하고 실행 → Connect 클릭 → 브라우저가 열리면 로그인 PC: install the Windows app from netbird.io, launch it, click Connect, and sign in when the browser opens
  2. 휴대폰: Play 스토어·App Store에서 NetBird 앱을 설치하고 같은 계정으로 로그인 (자체 호스팅이면 메뉴 ☰ → Change Server에서 관리서버 주소 입력) Phone: install the NetBird app and sign in with the same account (self‑hosted: set your management server under ☰ → Change Server)
  3. 두 기기가 같은 오버레이 네트워크에 연결되고 기기마다 고정 IP(100.x.x.x)를 받습니다. PC의 IP는 NetBird 대시보드나 앱에서 확인 Both devices connect to one overlay network and each gets a fixed IP (100.x.x.x). See the PC's IP in the NetBird dashboard or app
  4. 휴대폰 브라우저에서 https://<PC의 NetBird IP>:<포트> 접속 On the phone browser open https://<PC's NetBird IP>:<port>
🐾Tailscale가장 쉬움easiest

계정 로그인만으로 끝. 서버가 필요 없어요.Just sign in — no server to run.

  1. PC: tailscale.com/download에서 Windows용을 설치하고, Google·Microsoft·GitHub·Apple 계정 중 하나로 로그인 PC: install the Windows app from tailscale.com/download and sign in with a Google / Microsoft / GitHub / Apple account
  2. 휴대폰: Play 스토어·App Store에서 Tailscale 앱을 설치하고 같은 계정으로 로그인 Phone: install the Tailscale app from the Play Store / App Store and sign in with the same account
  3. 두 기기가 자동으로 같은 사설망(tailnet)에 묶입니다. PC의 Tailscale IP(100.x.x.x)는 트레이 아이콘 또는 tailscale ip로 확인 Both devices join one private network (tailnet). Find the PC's Tailscale IP (100.x.x.x) in the tray icon or via tailscale ip
  4. 휴대폰 브라우저에서 https://<PC의 Tailscale IP>:<포트> 접속. MagicDNS를 켜면 IP 대신 https://<PC이름>:<포트> 같은 이름으로도 접속 가능 On the phone browser open https://<PC's Tailscale IP>:<port>. With MagicDNS on you can also use a name like https://<pc-name>:<port>
💡 “네트워크를 옮기면 IP가 달라지잖아” — 맞습니다. 카페·LTE로 옮기면 일반 IP(192.168.x.x)는 매번 바뀝니다. 하지만 VPN IP(100.x.x.x)는 기기마다 고정이라, 어느 네트워크에 있든 그대로예요. 그래서 이 VPN 주소로 한 번 홈 화면에 앱 설치(또는 북마크)해 두면 집에서든 밖에서든 항상 같은 주소로 열립니다. (Tailscale은 IP 대신 MagicDNS 이름을 쓰면 더 편합니다.) 💡 “But the IP changes when I switch networks” — right, your ordinary IP (192.168.x.x) changes on every network. But the VPN IP (100.x.x.x) is fixed per device and stays the same wherever you are. So install this VPN address to the Home Screen (or bookmark it) once and it opens with the same address from home or away. (Tailscale's MagicDNS name is even handier than the IP.)
✅ Agent Hub 인증서는 이 VPN IP 대역(100.64.0.0/10)을 자동 포함해 발급되므로 경고 없이 접속됩니다. VPN을 나중에 깔았다면 Agent Hub를 한 번 재시작하면 VPN IP까지 넣어 인증서가 갱신돼요. 재시작하면 PC 콘솔 상단에 사설망(LAN) 주소와 VPN(NetBird 등) 주소가 각각 label과 함께 표시되니, 밖에서 쓸 VPN 주소를 그대로 복사해 STEP 02 인증서 등록 · STEP 03 앱 설치를 진행하면 됩니다. 포트는 PC 콘솔 설정에서 지정합니다. ✅ Agent Hub's certificate automatically covers this VPN IP range (100.64.0.0/10), so there's no warning. If you set the VPN up later, restart Agent Hub once to reissue the cert including the VPN IP. After the restart the PC console lists both the local‑network (LAN) address and the VPN (e.g. NetBird) address, each with a label — just copy the VPN address and do STEP 02 (install cert) & STEP 03 (install app) with it. Set the port in the PC console's Settings.
▣ 주소를 입력하기 싫다면 — PC 콘솔의 QR 찍기Don't want to type the address? Scan the QR on the PC console
PC 콘솔 상단 주소 옆의 ▣ QR 버튼을 누르면 접속하기와 인증서 받기 QR이 함께 나옵니다. 휴대폰 카메라로 찍으면 주소를 손으로 옮겨 적지 않아도 됩니다. LAN과 VPN 주소가 모두 있으면 위쪽 탭으로 골라 바꿀 수 있으니, 지금 휴대폰이 붙어 있는 쪽을 고르세요.

⚠️ 인증서 받기 QR은 아직 신뢰되지 않은 주소로 연결되므로 보안 경고가 먼저 뜹니다. 고급 → 계속(이동)을 눌러야 다운로드가 시작됩니다. 다운로드 후의 설치 과정은 아래 STEP 02와 같습니다 — QR은 주소 입력을 대신할 뿐, 설치까지 자동으로 해주지는 못합니다(휴대폰 OS가 인증서 설치는 반드시 사용자 확인을 받도록 막아 두었습니다). Click the ▣ QR button next to the address at the top of the PC console: it shows a QR to open the app and another to get the certificate. Scan with your phone camera instead of typing the address. If both LAN and VPN addresses exist, switch between them with the tabs — pick the one your phone is currently on.

⚠️ The certificate QR points at an address that isn't trusted yet, so a security warning appears first. Tap Advanced → Proceed to start the download. Installing it afterwards follows STEP 02 below — the QR only replaces typing the address; it cannot install the certificate for you, because phone operating systems require you to confirm that step yourself.
🏠 VPN 없이 — 같은 네트워크(집·회사)라면 바로 접속No VPN — connect directly on the same network
PC와 휴대폰이 같은 네트워크(같은 공유기·랜)에 있다면 VPN 없이도 바로 접속할 수 있습니다. PC 콘솔 상단의 주소(예: https://192.168.0.10:47600)를 휴대폰 브라우저 주소창에 입력 → 보안 경고가 뜨면 고급 → 계속(이동). ⚠️ 경고는 자체 서명 인증서라서 나오며, 아래 STEP 02에서 인증서를 등록하면 사라집니다. 단, 이 방식은 같은 네트워크에 있을 때만 동작하고 네트워크를 옮기면 IP가 바뀌므로, 어디서나 같은 주소로 쓰려면 위 NetBird를 권장합니다. If the PC and phone are on the same network (same router/LAN), you can connect without a VPN: type the address from the top of the PC console (e.g. https://192.168.0.10:47600) into the phone browser → if a warning appears, tap Advanced → Proceed. ⚠️ The warning is from the self‑signed cert; installing it in STEP 02 below removes it. This works only while on the same network and the IP changes when you switch networks, so use NetBird above for one address everywhere.
STEP 02알림 받기 필수 ①Required for alerts ①

인증서 등록 (조금 까다로워요)Install the certificate (the tricky part)

한 번만 등록하면 경고 없이 접속되고, 홈 화면에 앱으로 설치할 수 있습니다. 휴대폰 종류를 고르고 순서대로 따라오세요. Do this once — then no warnings, and you can install it as an app. Pick your phone type and follow along.

  1. 위 인증서 다운로드 → 다운로드 폴더에 AgentHub.crt 저장Tap Download certificate → saved to Downloads as AgentHub.crt
  2. 설정 검색에 기기에 저장된 인증서 설치 입력 → 실행Search Settings for Install stored certificate → open it
  3. CA 인증서 메뉴 선택 (VPN·앱 아님)Choose CA certificate (not VPN & app)
  4. 경고 화면에서 계속 설치Install anyway on the warning
  5. 다운로드한 AgentHub.crt 파일 선택 → 완료Pick the downloaded AgentHub.crt → done
⚠️ 다운로드한 파일을 그냥 탭하면 “신뢰할 수 있는 기관…” 오류가 납니다. 반드시 위 설정 경로로 설치하세요. (삼성 기준: 설정 검색 → 기기에 저장된 인증서 설치 → CA 인증서 → 계속 설치 → 파일 선택. 기종에 따라 “보안 → 기타 보안 설정”에 있을 수도 있어요.) ⚠️ Tapping the file directly shows a "trusted authority" error. You must install via Settings. (Samsung: search Settings for Install stored certificate → CA certificate → Install anyway → pick the file. On some models it lives under Security → More security settings.)
🔄 앱이 “인증서 확인 필요”라고 뜰 때If the app says "check the certificate"
인증서를 수동 삭제했거나 완전 제거 후 재설치한 경우에만 생깁니다(일반 재설치·업데이트에서는 인증서가 유지됨). 설치하는 인증서는 IP가 들어 있지 않은 AgentHub Root CA 하나뿐이라, Wi‑Fi·VPN이 바뀌거나 PC의 IP가 달라져도 다시 설치할 필요가 없습니다. 다시 받아야 한다면 PC 콘솔 상단의 ▣ QR → 인증서 받기를 찍는 것이 가장 빠릅니다(홈 화면에 설치한 앱에는 인증서 다운로드 버튼이 없습니다). 또는 앱에 표시된 주소를 휴대폰 브라우저(앱 아님)로 열어 인증서를 다시 받으세요 — 자체 서명이라 보안 경고가 뜨는데 고급 → 계속(이동)으로 진행하면 받을 수 있습니다. 접속과 같은 HTTPS 주소(/api/cert)라 LAN·VPN 어디서나 되고, 인증서 패널(🔒)의 인증서 다운로드도 같은 주소입니다.

PC의 인증서 저장소에서 지운 경우는 agent-hub.exe를 다시 실행하면 됩니다 — Windows가 “인증서를 설치하시겠습니까? 예/아니오”를 다시 물어보고, 예를 누르면 같은 인증서가 그대로 재등록됩니다(재발급이 아니므로 휴대폰의 기존 인증서·기기 승인은 그대로 유지). 아니오를 눌러도 앱은 정상 기동하며, 신뢰만 안 된 상태로 남습니다. Happens only if you manually deleted the cert or did a full uninstall + reinstall (ordinary reinstalls/updates keep it). The only certificate you install is the AgentHub Root CA, which contains no IP address — so you never need to reinstall it when Wi‑Fi, VPN, or the PC's IP changes. If you do need it again, the fastest way is the ▣ QR → Get the certificate on the PC console (the installed home‑screen app has no download button). Otherwise open the address shown in the app in your phone browser (not the app) to get the cert again — it is self-signed, so a security warning appears; continue via Advanced → Proceed and the download starts. It is served from the same HTTPS address you connect to (/api/cert), so it works over LAN and VPN alike, and the Download certificate action in the 🔒 panel uses the same address.

If you removed it from the PC's certificate store, just run agent-hub.exe again — Windows asks "Do you want to install this certificate? Yes/No" once more, and Yes re-registers the very same certificate (it is not reissued, so your phone's existing cert and device approvals stay valid). Choosing No still starts the app normally; it just stays untrusted.
STEP 03알림 받기 필수 ②Required for alerts ②

앱으로 설치 (홈 화면에 추가)Install as an app (Add to Home Screen)

홈 화면에 앱으로 추가하면 알림을 받을 수 있고, 전체화면으로 빠르게 열립니다. 휴대폰 종류를 고르세요. Adding it to the Home Screen enables notifications and opens full‑screen. Pick your phone type.

  1. 브라우저 메뉴 ⋮ → 홈 화면에 추가 (또는 앱 상단의 ⬇ 앱 설치 버튼)Browser menu ⋮ → Add to Home screen (or the ⬇ Install app button in the app)
  2. 이름 확인 → 추가Confirm the name → Add
  3. 홈 화면 아이콘으로 실행 — 앱처럼 열립니다Launch from the Home‑screen icon — opens like an app
⚠️ 앱 설치·홈 화면 추가가 안 보이면 STEP 02 인증서를 먼저 설치하고 새로고침하세요.⚠️ If the install / Add‑to‑Home option is missing, install the STEP 02 certificate first and refresh.
STEP 04

기기 인증받기Get your device approved

아무 휴대폰이나 몰래 보지 못하도록, 처음 접속하면 승인이 필요합니다. 폰에서 기기 이름을 넣고 요청하면 PC에서 승인합니다. So not just any phone can watch, the first visit needs approval. Enter a device name on the phone, then approve it on the PC.

  1. 폰: 기기 이름 입력 → 인증 요청 보내기Phone: enter a name → Request access
  2. PC 화면 왼쪽 메뉴 기기에서 요청 확인 → 승인PC screen, left menu Devices → Approve
  3. 폰이 자동으로 PC와 같은 오피스 화면으로 전환 (휴대폰엔 오피스만 보입니다)The phone switches to the same office screen as the PC automatically (phones see only the office)
STEP 05

오피스에서 에이전트 지켜보기Watch your agents in the office

PC에서 돌아가는 모든 Claude Code·Codex 세션(Windows·WSL)이 오피스의 캐릭터로 나타납니다(파스텔 톤 방을 부드러운 벡터 그래픽으로 그리며, 라이트/다크 테마를 따릅니다) — 후드티를 입은 고양이·강아지들이에요. 캐릭터는 지금 하는 일에 따라 방을 옮겨 다니고, 이름표에는 프로젝트 이름과 실행 위치(· Codex, · WSL)가 붙습니다. 프롬프트를 실제로 보낼 수 있는 세션만 나타나고, 종료·닫힌 세션은 사라집니다. 세션 목록은 바뀐 부분만 갱신해 큰 대화 기록을 다시 읽지 않으므로 오피스가 몇 초 안에 뜹니다. Every Claude Code / Codex session on your PC (Windows and WSL) appears as a character in the office (pastel rooms drawn as smooth vector graphics, following the light/dark theme) — cats and dogs in hoodies. Characters move between rooms as their work changes, and each label shows the project name and where it runs (· Codex, · WSL). Only sessions that can actually receive prompts are shown — exited/closed sessions disappear. The session list updates incrementally (large transcripts aren't re‑read), so the office appears within seconds.

방Room 이럴 때 이 방에 있어요When a character is here
📚 자료실Library 파일 읽기·코드/파일 검색·웹 조회/검색. 캐릭터 옆 참조 카드에 지금 보고 있는 파일 경로·URL·검색어가 그대로 표시됩니다.Reading files, searching code/files, web fetch/search. A reference card next to the character shows exactly which file path, URL, or search query it is looking at.
🗂 사무실Office 계획 — 도구 사이에 생각하거나 글을 쓰는 중(“생각 정리 중”), 할 일 목록 작성, 서브에이전트에게 일 맡기기.Planning — thinking or writing between tools (“생각 정리 중 / organizing thoughts”), todo lists, delegating to sub‑agents.
🔧 작업실Workshop 실제 작업 — 코드 수정, 명령 실행.Actual work — editing code, running commands.
🔔 상담실Consult room 당신을 기다리는 중 — 질문(AskUserQuestion / Codex request_user_input)이나 권한 확인. 요청이 오면 캐릭터가 바로 이곳으로 갑니다.Waiting for you — a question (AskUserQuestion / Codex request_user_input) or a permission prompt. The character goes here immediately.
☕ 휴게실Lounge 턴 사이 휴식. 쉬는 캐릭터는 휴게실 안에서 조용히 쉽니다(이름표는 마우스를 올리면 표시).Resting between turns. Resting characters stay quiet inside the lounge (label on hover).
  1. 생각 풍선 — 💭 생각 요약과 💬 에이전트가 직접 남긴 설명으로 각자 무엇을 생각·결정하는지 보여줍니다.Thought bubbles — 💭 a thinking summary and 💬 the agent's own explanation show what each agent is thinking and deciding.
  2. 캐릭터·생각 풍선·이름표, 또는 오른쪽 목록 카드를 클릭하면(휴대폰도 동일) 오른쪽에 채팅 패널이 열립니다 — 탭은 대화 | 터미널. 대화 탭에는 실시간 활동 피드(에이전트 글의 굵게·코드 표시), 질문 카드(여러 질문·기타 직접 입력), 권한 카드(허용/거부), 프롬프트 입력이 있고, 맨 아래를 보고 있으면 자동으로 따라 내려갑니다. PC에서는 패널 왼쪽 가장자리를 끌어 폭을 조절합니다.Click a character, its thought bubble or label, or a roster card on the right (phones too) to open the chat panel on the right — tabs 대화 (Chat) | 터미널 (Terminal). The chat tab has the live activity feed (agent text shows bold and code), question cards (multiple questions, Other — type your own), permission cards (Allow/Deny), and prompt input; it auto‑scrolls when you're at the bottom. On the PC, drag the panel's left edge to resize it.
  3. 🗺️ 지도 조작 — 마우스 휠로 부드럽게 확대·축소, 드래그로 이동. 휴대폰은 두 손가락으로 확대·축소, 드래그로 이동합니다.🗺️ Map controls — mouse wheel zooms (smoothly), drag to pan. On phones, pinch to zoom and drag to pan.
  4. 🏠 방 배치 — 방 이름판을 끌어 배치를 바꾸고, 오른쪽 아래 모서리를 끌어 방을 넓힐 수 있습니다(원래 크기보다 작게는 안 됨, 브라우저별로 저장). 방 이름판에 마우스를 올리면 그 방의 역할과 안에 누가 무엇을 하는지 보입니다.🏠 Room layout — drag a room by its name plate to rearrange and by its bottom-right corner to enlarge it (never below its designed size; saved per browser); hover a room's name plate to see its role and who's inside doing what.
  5. 🎨 바닥 꾸미기 — 확대·축소 버튼 아래 🎨를 누르면 방이 놓인 바닥을 단색·마루·타일 중에서, 색상별로 고를 수 있습니다(브라우저별로 저장).🎨 Floor — the 🎨 button under the zoom buttons picks the floor the rooms stand on: solid, wood or tile, each in several colours (saved per browser).
  6. 🧶 서브에이전트·백그라운드 셸은 작은 캐릭터로 따로 나타나 메인 에이전트와 하트 달린 끈으로 이어지고, 가까이 있으면 손을 잡습니다.🧶 Sub‑agents and background shells appear as their own small characters linked to their main agent by a string with a heart — or holding hands when close.
  7. 질문·권한 요청이 오면 오피스에 토스트가 뜨고 Windows 트레이 알림도 옵니다. 알림을 클릭하면 그 세션의 채팅이 열립니다.When a question or permission request arrives, a toast pops up in the office along with a Windows tray notification. Click it to open that session's chat.
  8. 최신 exec/apply_patch 도구 형식을 쓰는 Codex 세션도 도구 활동이 표시됩니다(이전엔 비어 보였음).Codex sessions using the newer exec/apply_patch tool format now show their tool activity (previously empty).
🎨 오피스 그림은 어디서 왔나요Where does the office art come from?
오피스 화면은 MIT 라이선스 오픈소스 pixel-agents를 바탕으로 만들었고, 캐릭터·가구·바닥 타일은 Agent Hub용으로 새로 그린 오리지널 아트입니다. The office is based on the MIT‑licensed open‑source pixel-agents project, with original Agent Hub art — the characters, furniture, and tiles are all new.
STEP 06

폰에서 원격 제어Control from your phone

폰에서 Claude·Codex를 원격으로 다룹니다 — 질문에 답하고, 위험한 작업을 허용/거부하고, 알림을 받습니다. Control Claude/Codex from your phone — answer questions, allow/deny risky actions, and get alerts.

  1. 🔔 알림 켜기 — 폰 상단바의 🔔 알림 켜기 버튼을 한 번 누르면(PC 훅 자동 설치) 앱을 닫아도 세션이 당신을 기다릴 때 푸시가 옵니다. 알림 본문에 AI 세션의 마지막 메시지가 담겨 완료인지 질문인지 바로 압니다. 알림은 작업이 끝났을 때·질문이 왔을 때·권한 승인이 필요할 때만 옵니다 — 진행 중에는 울리지 않고, 같은 내용도 반복해서 울리지 않습니다(메시지가 바뀔 때만 새로 알림). 작업이 끝난 뒤 다음 지시를 기다리는 세션은 알림 없이 캐릭터가 ☕ 휴게실에서 쉽니다.🔔 Enable alerts — tap the 🔔 알림 켜기 / Enable alerts button in the phone's top bar once (the PC hook installs itself). Even with the app closed, a push arrives when a session needs you, carrying the AI session's last message so you know at a glance if it's done or asking. Alerts fire only when a task finishes, a question arrives, or a permission needs approval — never mid‑progress, and never twice for the same message (you're re‑alerted only when it changes). A session that finished and is waiting for your next prompt just rests in the ☕ lounge — no extra alert.
  2. 💬 질문에 답하기 — Claude·Codex가 선택지 질문을 하면 질문·답변 카드가 떠, 옵션이나 직접 입력을 골라 답변 보내기. 실행 중인 그 세션에 바로 반영(새 터미널 불필요).💬 Answer questions — when Claude/Codex asks, a Q&A card pops up; pick an option or type your own and Send. Applied to the running session, no terminal needed.
  3. ⌨️ 자유 답변 입력 — 채팅 패널(세션 상세 화면) 하단 입력창은 여러 줄로 쓸 수 있습니다(Enter=줄바꿈, 전송은 전송 버튼으로만). 전송하면 질문 카드 없이도 PC에서 실행 중인 그 세션 콘솔에 그대로 입력되고, 전송하면 입력창과 전송 버튼이 잠기고 로딩이 표시되며 내 답변이 세션 상세에 다시 나타날 때(왕복 완료)까지 유지돼 중복 전송을 막습니다. 내가 보낸 답변은 오른쪽 말풍선으로 구분되어 표시됩니다. 입력창은 PC에서 CLI(cmd·PowerShell·WSL 등)로 실행했고 훅이 연결된 활성 Claude·Codex 세션에서 나타납니다. 그 외(Windows Terminal 실행·종료된 세션·콘솔 없는 데스크톱 앱)는 프롬프트를 보낼 수 없어 오피스에 나타나지 않습니다.⌨️ Free‑text reply — the input bar at the bottom of the chat panel (session detail screen) supports multiple lines (Enter=newline; send only via the Send button). Hitting Send types it straight into that session's console on the PC, even without a pending question card; the input bar and Send button then lock and show a loading state that stays until your reply reappears in the session detail (the full round‑trip) — preventing duplicate sends. Replies you send show up in a right‑aligned bubble so they're easy to spot. The input bar appears for active hooked Claude/Codex sessions started from a CLI (cmd, PowerShell, WSL, etc.) on the PC. Others (Windows Terminal, exited sessions, or desktop apps without a console) can't receive prompts and don't appear in the office.
  4. 🔐 권한 승인 — Claude·Codex가 승인을 요구하는 모든 작업(Bash·파일 편집·WebFetch·MCP 도구 등)에서 🔐 카드로 허용/거부합니다. 그 세션에 바로 적용됩니다. 앱이 닫혀 있어도 푸시가 오고, 알림을 눌러 앱을 켜면 대기 중인 권한 카드가 다시 표시됩니다.🔐 Approve permissions — every action Claude/Codex needs approval for (Bash, file edits, WebFetch, MCP tools…) shows a 🔐 card to Allow/Deny, applied to that session. A push arrives even with the app closed, and opening the app from the notification re‑shows the waiting permission card.
  5. 🔔 상담실 — 당신이 답해야 하는 세션(질문·권한)의 캐릭터는 곧장 상담실로 갑니다. 캐릭터를 탭하면 채팅 패널에서 바로 답할 수 있습니다.🔔 Consult room — a session that needs your reply (question or permission) sends its character straight to the consult room. Tap the character to answer in the chat panel.
⏱️ 질문 답변 창이 지나도 계속 답할 수 있어요You can still answer after the reply window passes
권한 요청은 PC를 쓰고 있는지에 따라 갈립니다. 자리를 비운 상태(마지막 키·마우스 입력 후 1분 경과)면 서버가 요청을 최대 약 10분 붙들어, 폰에서 누른 허용/거부가 그대로 그 세션에 적용됩니다(그동안 PC 터미널에는 프롬프트가 뜨지 않습니다). PC를 쓰는 중이면 폰 앱이 연결돼 있을 때만 약 2분까지 기다리고, 연결돼 있지 않으면 즉시 PC 터미널에 권한 프롬프트를 띄웁니다 — 자리에 있을 때 화면이 멈춘 것처럼 보이지 않게 하기 위함입니다.

Claude·Codex가 질문·권한을 기다리는 기본 약 10분(600초) 안에서는 답변이 그 세션에 즉시 반영됩니다. 이 창이 지나도 대기중 카드를 열면 같은 질문·답변 카드가 그대로 뜨고, 답변 보내기를 누르면 PC 세션 콘솔에 자동으로 입력됩니다 — 터미널을 직접 열 필요는 없습니다. 콘솔에 입력할 수 없는 상태면 실패 안내가 표시됩니다. 권한 승인도 창이 지나면 세션 상세에 권한 대기 카드가 남아, 허용 / 허용 + 다음부터 안 물음 / 거부를 누르면 PC 터미널의 권한 프롬프트에 콘솔로 직접 입력됩니다(콘솔 주입이 가능한 활성 Claude·Codex CLI 세션 한정; Windows Terminal·콘솔 없는 데스크톱 앱에서는 안내만 표시). Permission requests depend on whether you're at the PC. If you're away (no keyboard/mouse input for a minute), the server holds the request for up to ~10 minutes so the Allow/Deny you tap on the phone is applied to that session directly (no prompt appears in the PC terminal meanwhile). If you're actively using the PC, it waits up to ~2 minutes only when the phone app is connected, and otherwise shows the permission prompt in the PC terminal right away — so nothing looks frozen while you're sitting there.

Within the ~10 minutes (600s) Claude/Codex waits for questions/permissions, your answer is applied to the session immediately. After that window, opening the waiting card still shows the same Q&A card — tapping Send answer types it straight into the session's console on the PC, no need to open a terminal yourself. If it can't reach the console, a failure notice is shown. Permission requests, too, leave a pending‑permission card in the session detail after their window passes — tapping Allow / Allow + don't ask again / Deny types straight into the permission prompt in the PC terminal (for active Claude/Codex CLI sessions where console injection works; elsewhere, e.g. Windows Terminal or desktop apps without a console, only a note is shown).
⚠️ Clawd on Desk와 동시 실행 주의Running alongside Clawd on Desk
두 앱이 같은 질문 훅을 함께 가로채면 답변이 전달되지 않습니다. Agent Hub 실행 시 Clawd on Desk가 켜져 있으면 종료할지 묻는 창이 뜹니다 — [예]면 닫고 계속, [아니오]면 유지하되 모바일에서 답할 때 “Clawd on Desk가 실행 중이라 답변을 전달할 수 없습니다” 안내가 나옵니다. If both apps intercept the same question hook, answers won't be delivered. On startup Agent Hub asks whether to close Clawd on Desk — [Yes] closes it; [No] keeps it, but answering from mobile then shows “Clawd on Desk is running, can't deliver the answer.”
STEP 07

새 에이전트 실행Launch a new agent

오른쪽 목록 아래의 ＋ 카드(휴대폰은 하단 바의 ＋)로 PC에 새 Claude Code·Codex 세션을 띄웁니다. 휴대폰에서도(승인된 기기) 똑같이 쓸 수 있어요. Use the ＋ card under the right roster (on phones, the ＋ in the bottom bar) to start a new Claude Code or Codex session on the PC. It works from the phone too (approved devices).

  1. 엔진 선택: Claude Code / CodexPick the engine: Claude Code / Codex
  2. 실행 위치: Windows, 또는 WSL이 있으면 설치된 WSL 배포판Where to run: Windows, or an installed WSL distro if WSL is present
  3. 작업 폴더: 최근 작업 폴더 10개가 목록으로 보여 눌러서 고릅니다Working folder: pick from a list of your 10 most recent folders
  4. 첫 프롬프트(선택)First prompt (optional)
  5. 실행하면 셸이 AgentHub의 자식 프로세스(ConPTY)로 숨겨져 돌아가 콘솔 창이 뜨지 않고, 곧 오피스에 캐릭터가 나타납니다. 화면을 보거나 직접 입력하려면 채팅 패널의 터미널 탭을 쓰세요The shell runs hidden as a child process of AgentHub (ConPTY) — no console window — and its character shows up in the office shortly. To view it or type into it, use the chat panel's 터미널 (Terminal) tab
⚠️ 고른 환경(Windows 또는 해당 WSL 배포판)에 CLI(claude / codex)가 설치되어 있어야 합니다.⚠️ The CLI (claude / codex) must be installed in the chosen environment (Windows or that WSL distro).
ℹ️ AgentHub를 완전 종료하면 여기서 띄운 에이전트도 함께 종료됩니다.ℹ️ Quitting AgentHub ends the agents launched here.
🆚 차별점HOW IT DIFFERS

Claude Code 공식 원격 제어와 무엇이 다른가요?How is this different from Claude Code's official Remote Control?

Claude Code에는 세션을 원격에서 이어받는 공식 Remote Control 기능이 있습니다. 목표는 비슷하지만, Agent Hub는 연결 방식과 전제가 근본적으로 다릅니다. Claude Code has an official Remote Control feature for taking over a session remotely. The goal is similar, but Agent Hub differs fundamentally in how it connects and what it assumes.

Claude Code Remote Control (공식)Claude Code Remote Control (official) Agent Hub
연결 경로Connection path Anthropic 클라우드(API) 경유Via Anthropic cloud (API) 내 기기(로컬 서버)에 직접Direct to your local server — 제어·모니터링이 외부 클라우드를 안 거침— control & monitoring never pass a cloud
접근 범위Reach 인터넷 어디서나Anywhere over the internet NetBird 등 VPN으로 어디서나Anywhere via a VPN like NetBird (내 기기끼리 직접)(device‑to‑device)
필요 조건Requirements Pro/Max/Team/Enterprise 구독 + 계정 로그인Pro/Max/Team/Enterprise plan + account login 구독 무관No plan needed — 로컬에 Claude Code만 있으면 됨— just local Claude Code
접근 통제Access control 계정·조직 정책 / 신뢰 기기Account/org policy, trusted devices 내 PC에서 기기별 직접 승인You approve each device on your PC
대상 세션Sessions 원격 제어로 켠 세션A session you start in remote‑control mode 로컬에서 돌고 있는 세션들을 자동 감지Auto‑detects sessions already running locally
클라이언트Clients 네이티브 모바일 앱 · 웹Native mobile app · web PWA(앱으로 설치)PWA (installable app) — PC·휴대폰에서 같은 화면— the same screen on PC and phone
💡 한마디로, 클라우드를 거치지 않고 내 기기끼리 직접, 내가 승인한 기기만 쓰고 싶을 때 Agent Hub가 맞습니다. NetBird 같은 VPN으로 유선·무선 상관없이 어디서나. (앱을 닫았을 때 오는 알림만 암호화되어 외부 푸시 서비스를 거칩니다.) 💡 In short: pick Agent Hub when you want no cloud relay — device‑to‑device, only devices you approved. Anywhere via a VPN like NetBird, on wired or Wi‑Fi. (Only closed‑app push alerts pass through an external, encrypted push service.)
📌 제한 사항 · 알아두기LIMITS & NOTES

쓰기 전에 알아두면 좋아요Good to know before you start

📶 알림엔 인터넷이 필요해요Alerts need internet
앱을 닫아도 오는 푸시는 폰·PC 모두 인터넷이 필요합니다(브라우저 푸시 서비스 경유). 질문 상세는 종단간 암호화되어 알림에 바로 표시됩니다. iOS는 홈 화면에 추가한 PWA + iOS 16.4 이상에서만 동작합니다. Push while the app is closed needs internet on both phone and PC (via the browser's push service). The question detail is end‑to‑end encrypted and shown right in the notification. On iOS it works only for a Home‑Screen PWA on iOS 16.4+.
✈️ PC에 연결할 수 없을 때When the PC can't be reached
PC가 꺼져 있거나 다른 네트워크라서 Agent Hub에 닿지 않으면, 앱은 ‘연결 확인 중’ → ‘연결할 수 없음’ 화면을 보여 주고 인증서 재설치 링크를 함께 표시합니다(예전처럼 마지막 세션 목록을 보여 주지는 않습니다). Agent Hub에 다시 닿으면 자동으로 오피스로 넘어갑니다. If the PC is off or you're on another network and Agent Hub can't be reached, the app shows a “Checking connection” → “Can't connect” screen with a certificate re‑install link (the last session list is no longer shown). Once Agent Hub is reachable again it moves on to the office automatically.
🌍 다른 네트워크에서 접속 (VPN)Connect from another network (VPN)
Agent Hub는 클라우드 서버가 없어 PC와 휴대폰이 직접 연결됩니다. NetBird 같은 VPN을 쓰면 유선·무선·어느 네트워크에서든 접속할 수 있어요. 설치·설정 단계, 모바일 접속, IP가 바뀌는 문제까지 위 STEP 01 ‘NetBird로 어디서나 연결’에 정리해 두었습니다. Agent Hub has no cloud server, so the PC and phone connect directly. A VPN like NetBird lets you connect on wired or Wi‑Fi, on any network. Full setup, mobile access, and the changing‑IP question are covered in STEP 01 ‘Connect from anywhere with NetBird’ above.
🔒 P2P라서 안전한가요? (relay·암호화)Is P2P actually secure? (relay & encryption)
NetBird는 가능하면 PC·폰을 직접(peer-to-peer) 연결합니다. 다만 양쪽 네트워크 환경(예: 대칭형 NAT·엄격한 방화벽)에 따라 직접 연결이 안 되면 NetBird의 relay 서버로 자동 폴백해 트래픽이 중계될 수 있어요. 그래도 안전한 이유는 중계 여부가 아니라 암호화에 있습니다. 모든 트래픽은 WireGuard로 종단간 암호화되어, relay를 거치더라도 relay는 암호문만 전달할 뿐 내용을 볼 수 없습니다. 관리 서버도 연결 조율만 하고 실제 데이터는 지나가지 않습니다. 결국 실제 보안 경계는 각 기기와 그 안의 키이므로, 승인한 기기의 관리가 핵심입니다. NetBird connects your PC and phone directly (peer‑to‑peer) whenever it can. But depending on both networks (e.g. symmetric NAT or a strict firewall), if a direct link can't be made it falls back to NetBird's relay server and traffic is relayed. It's still safe because security comes from encryption, not from avoiding relays: all traffic is end‑to‑end encrypted with WireGuard, so even via a relay the relay only forwards ciphertext and can't read it. The management server only coordinates the connection — your data never passes through it. The real security boundary is each device and the keys on it, so managing your approved devices is what matters.
🚀 Windows 시작 시 자동 실행 (기본 켜짐)Launch on Windows startup (on by default)
PC에 로그인하면 Agent Hub가 자동으로 실행되어 화면을 띄우지 않고 트레이에만 조용히 상주합니다. PC 화면 설정 › 일반의 ‘Windows 시작 시 자동 실행’ 체크로 언제든 끄고 켤 수 있어요. 관리자 권한은 필요 없으며(현재 사용자 로그인 항목에만 등록), 설치본에서만 적용됩니다. Agent Hub launches automatically when you log in to the PC and stays quietly in the tray without opening the screen. Toggle it anytime with ‘Launch on Windows startup’ under Settings › General on the PC screen. No admin rights needed (registered only for the current user), and it applies to the installed build only.
🔄 재설치·업데이트해도 인증서·승인은 유지Reinstall/update keeps cert & approvals
인증서와 기기 승인은 LocalAppData에 보관되어 재설치·업데이트에도 유지됩니다(재승인 불필요). 설치되는 인증서는 IP가 들어 있지 않은 AgentHub Root CA 하나로 고정이라, 네트워크가 바뀌어 접속 IP가 달라져도 PC·휴대폰 모두 재설치가 필요 없습니다(접속 IP가 담긴 서버 인증서는 이 CA가 서명해 조용히 갱신됩니다). 홈 화면에 설치한 앱에서는 이미 인증서가 깔려 있으므로 헤더의 인증서 다운로드 버튼이 숨겨집니다. 완전 삭제 후 재설치하거나 인증서를 수동 삭제해 연결이 끊긴 경우, 연결 화면에 뜨는 ‘새 인증서 설치’ 링크(또는 앱에 표시된 주소)를 휴대폰 브라우저로 열어 다시 받으세요. 접속과 같은 HTTPS 주소(/api/cert)에서 내려받으므로 LAN·VPN 어디서나 되고, 자체 서명이라 뜨는 보안 경고는 고급 → 계속으로 넘기면 됩니다. The certificate and device approvals live in LocalAppData, so they survive reinstalls and updates (no re‑approval). The one certificate you install is the fixed AgentHub Root CA, which holds no IP address — so neither the PC nor the phone needs a reinstall when the network and connection IP change (the server certificate carrying those IPs is signed by this CA and renews silently). In the installed home‑screen app the cert is already trusted, so the header download button is hidden. Only after a full uninstall + reinstall or if you manually deleted the cert and lost the connection, re‑download via the “Install new certificate” link shown on the connection screen (or the address shown in the app) in your phone browser. It comes from the same HTTPS address you connect to (/api/cert), so it works over LAN and VPN alike; clear the self-signed warning with Advanced → Proceed.
🧱 첫 연결이 안 되면 방화벽First connection fails? Firewall
휴대폰에서 첫 접속이 안 되면 PC의 Windows 방화벽에서 해당 포트의 수신(인바운드) 허용이 필요할 수 있습니다. If the first connection from a phone fails, you may need to allow inbound connections for that port in the PC's Windows Firewall.
🔔 캐릭터가 상담실에 가는 건 언제인가요When does a character go to the consult room?
사용자가 실제로 답해야 할 때(질문 또는 권한 확인)만 상담실로 갑니다. 서브에이전트에게 일을 맡긴 동안은 사무실, 턴 사이에 쉬는 동안은 휴게실에 있습니다. Only when you must respond (a question or a permission prompt). While delegating to a sub‑agent it stays in the office room, and between turns it rests in the lounge.
🐧 WSL에서 실행한 세션도 보여요WSL sessions show up too
WSL(Ubuntu 등) 안에서 실행한 Claude·Codex CLI 세션도 오피스에 캐릭터로 나오고 이름표의 · WSL로 구분됩니다. 알림·질문 답변·권한 승인은 물론 세션 상세 하단의 자유 답변 입력까지 Windows 세션과 똑같이 동작합니다(실행 중인 배포판의 Claude·Codex 설정에 훅이 자동 설치되며, 배포판을 나중에 켜도 1분 안에 자동으로 설치됩니다). WSL 세션도 결국 PC의 콘솔 창에서 wsl.exe로 실행되므로, 그 콘솔에 입력을 넣으면 WSL 안의 Claude·Codex 프로세스에 그대로 전달됩니다 — 한글도 그대로 들어가고, 터미널을 여러 개 띄워도 각 세션에 정확히 들어갑니다. 단, Windows 세션과 마찬가지로 cmd·PowerShell 같은 콘솔 창에서 실행한 경우에만 입력할 수 있고, Windows Terminal에서 실행했다면 입력창 대신 안내가 표시됩니다. Claude·Codex를 종료하면 그 세션은 입력 대상에서 자동으로 빠지고 오피스에서 사라집니다 — 터미널 창이 열려 있어도 입력이 셸 프롬프트로 새어 들어가지 않습니다. Claude/Codex CLI sessions started inside WSL (Ubuntu, etc.) appear in the office too, marked · WSL on their label. Alerts, question answers, permission approvals — and the free‑text reply bar — all work exactly like Windows sessions (hooks install themselves into Claude/Codex settings in running distros, and into a distro you start later within a minute). A WSL session still runs through wsl.exe in a console window on the PC, so text typed into that console reaches the Claude/Codex process inside WSL as‑is — non‑ASCII text included — and it lands in the right session even with several terminals open. As with Windows sessions, input works only when it was started from a console window such as cmd or PowerShell; if you started it from Windows Terminal, a short note is shown instead of the input bar. When you quit Claude/Codex, that session drops out of the input targets automatically and disappears from the office — so nothing leaks into the shell prompt even if the terminal window is still open.
🌗 라이트/다크 테마 전환Light / dark theme
상단바의 ☀️ / 🌙 버튼으로 라이트·다크 테마를 전환할 수 있습니다(기본은 라이트). 선택한 테마는 기기에 저장되어 다음에 열 때도 유지되고, 콘솔·오피스·채팅 패널에 함께 적용됩니다. Use the ☀️ / 🌙 button in the top bar to switch between light and dark themes (light by default). Your choice is saved on the device, kept the next time you open the app, and shared by the console, office, and chat panel.
📲 앱 설치는 브라우저 메뉴에서Install the app from the browser menu
앱 안의 설치 안내 배너는 없어졌고, 앱 설치는 브라우저에서 합니다. Android(Chrome·삼성 인터넷): 메뉴 → ‘앱 설치’ 또는 ‘홈 화면에 추가’. iPhone(Safari): 공유 → ‘홈 화면에 추가’. PC(Edge·Chrome): 주소창의 설치 아이콘. 설치 메뉴가 안 보이면 STEP 02 인증서를 먼저 설치하고 새로고침하세요. There is no in‑app install banner anymore — install from the browser. Android (Chrome / Samsung Internet): menu → “Install app” or “Add to Home screen”. iPhone (Safari): Share → “Add to Home Screen”. PC (Edge / Chrome): the install icon in the address bar. If the install option is missing, install the STEP 02 certificate first and refresh.