Hosted Andon: 어디서나 보는 보드

Andon은 로컬 우선이며 영원히 무료로 셀프 호스팅할 수 있습니다 — 이것이 기본값으로 유지되며 아무것도 공유하지 않습니다. 이 가이드는 선택적이고 옵트인 방식의 호스팅 모드를 다룹니다: 암호문만 라우팅하는 콘텐츠 블라인드(에이전트의 콘텐츠를 읽지 못함) 릴레이를 통해, 어디서나 보드를 보고 휴대폰 알림을 받습니다.

다른 사람들과 공유할 릴레이를 배포하려면? **deploy-relay.md**를 참고하세요.

무엇인가 (1분 요약)

모든 상태 이벤트는 컴퓨터를 떠나기 전에 여러분의 컴퓨터에서 종단 간 암호화됩니다.
릴레이는 그 암호문을 저장하고 전달할 뿐 키는 절대 갖지 않습니다 — 대략적인 라우팅 정보만 봅니다(어느 보드인지, 해시된 세션 ID, working/waiting/done/error/idle, 타이밍).
셀프 호스팅과 동일한 보드를 엽니다; 링크의 #fragment에 담긴 키로 여러분의 브라우저에서 복호화됩니다(서버로는 절대 전송되지 않음). 서비스 워커도 같은 방식으로 휴대폰 푸시를 복호화합니다.
로컬 andon serve가 필요 없습니다 — 훅의 일반 전송 경로가 봉인된 사본도 함께 전달합니다.

사용하는 방법은 두 가지입니다:

	릴레이 운영자	사용할 수 있는 사람
A. 직접 운영하는 릴레이	여러분(직접 관리하는 장비의 `andon relay`)	여러분만
B. 공유 릴레이	운영자, 하나의 공개 HTTPS URL에서	여러 사람 — 각자 같은 URL 아래에서 격리된 자신만의 보드를 가짐

둘 다 같은 코드입니다; B는 A를 공개적으로 노출한 것일 뿐입니다. 멀티테넌트를 참고하세요.

빠른 시작

# 1) Run a relay (yours), or skip this and use a shared relay URL someone gives you
andon relay                            # listens on :8788 (see deploy-relay.md for HTTPS/public use)

# 2) Opt in — generates a key that NEVER leaves your machine, prints your board link
andon hosted setup http://127.0.0.1:8788
#   → prints:  http://127.0.0.1:8788/b/<board-id>#k=<key>

# 3) Open that link in a browser. Done — your agents now show up there.

andon hosted setup은 먼저 릴레이가 무엇을 볼 수 있고 볼 수 없는지 정확히 보여준 다음 [y/N]을 묻습니다(기본값 No). 켜진 뒤에는 모든 Claude Code / Codex 상태도 (봉인된 채로) 릴레이로 전달됩니다.

보드 링크를 비밀번호처럼 다루세요 — #k=… 부분이 바로 여러분의 복호화 키입니다. 채팅에 스크린샷으로 올리지 말고 비밀번호 관리자에 저장하세요. (또는 복사-붙여넣기 없이 페어링하려면 터미널에 표시된 QR을 스캔하세요.)

보드 열기

같은 컴퓨터에서: http://127.0.0.1:<port>/b/<board-id>#k=<key>를 엽니다. localhost / 127.0.0.1은 보안 컨텍스트이므로 일반 HTTP에서도 브라우저 내 복호화가 작동합니다.
휴대폰 / 다른 기기에서: 릴레이는 HTTPS로 접속할 수 있어야 합니다(브라우저는 복호화 + 푸시에 보안 컨텍스트를 요구합니다). 간단한 두 가지 방법:
- Tailscale (이미 사용 중): tailscale serve --bg <relay-port> → https://<machine>.<tailnet>.ts.net 주소를 제공합니다. 휴대폰에서 https://…ts.net/b/<board-id>#k=<key>를 엽니다.
- 실제 도메인 + 인증서 (공유 릴레이용) — deploy-relay.md를 참고하세요.

휴대폰 알림 (PWA)

휴대폰에서 HTTPS로 보드 링크를 엽니다.
iPhone: 공유 → 홈 화면에 추가(iOS는 설치된 PWA에서만 Web Push를 허용합니다), 그런 다음 홈 화면에서 엽니다. Android/Chrome: 일반 탭에서 작동합니다; “홈 화면에 추가”는 선택 사항입니다.
알림 켜기를 탭 → 알림을 허용합니다. 에이전트가 처음으로 여러분을 필요로 하거나 막힐 때 진동이 옵니다 — 보드를 닫고 휴대폰을 잠근 상태에서도요. 알림 텍스트는 여러분의 휴대폰에서 복호화됩니다; 릴레이는 절대 보지 못합니다.

관리하기

andon hosted status                    # is hosted on? which relay + board id
andon hosted pair                      # re-print your board link — add a device, or recover a lost link
andon hosted off                       # stop forwarding — your agents go back to local-only
andon verify  <relay-url>              # check the relay serves the exact open-source code (see below)

자유롭게 오갈 수 있습니다; off는 로컬 설정(~/.andon/hosted.json)을 삭제할 뿐입니다.

릴레이가 볼 수 있는 것 / 볼 수 없는 것


❌ 읽을 수 없음	프롬프트, 코드, 프로젝트 이름, 제목, 메시지, 레버리지 집계
• 볼 수 있음	활동 중이라는 사실과 대략의 시점(이벤트별 타이밍), 세션 수, IP, 암호문 크기 구간
• 할 수 있음	이벤트를 지연/보류하거나, 실제 과거의 푸시 알림 중 하나를 다시 표시할 수 있습니다(이미 해결된 세션에 대한 오래된 “여러분을 필요로 함”) — 하지만 새 콘텐츠를 만들어 낼 수 없고, 읽을 수도 없습니다

셀프 호스팅은 아무것도 공유하지 않으며 기본값으로 유지됩니다. 호스팅은 편의성과 메타데이터 사이의 트레이드오프이며, 이를 솔직하게 밝힙니다.

”신뢰만이 아니라 검증 가능” (투명성)

웹 보드의 코드는 릴레이가 제공하기 때문에, “침해당해도 읽을 수 없다”는 완벽한 보장은 설치된 앱에만 적용됩니다. 웹 보드의 경우 솔직한 주장은 **“여러분에게 은밀하게 백도어를 심을 수는 없다”**는 것입니다:

andon verify https://relay.example.com

이 명령은 릴레이가 실제로 제공하는 보드 + 서비스 워커를 가져와 해시한 다음, 여러분 자신의 오픈 소스 사본의 바이트와 비교합니다. 일치하면 릴레이가 감사받은 코드를 그대로 제공하고 있다는 뜻입니다 — 숨겨진 키 탈취가 없습니다. 같은 버전에서 불일치가 지속되면 수정된 코드를 제공하고 있다는 뜻이니, 그 릴레이에 키를 맡기지 마세요. 릴레이는 또한 GET /version에서 자신의 해시를 공개합니다.

멀티테넌트 — 하나의 URL, 여러 보드

릴레이는 설계상 멀티테넌트입니다: 하나의 프로세스가 여러 보드를 제공하며, 진입점은 사용자별 서브도메인이 아니라 하나의 URL입니다.

            https://relay.example.com        (one URL = the shared entry)
            ├── /b/<A's board-id>#k=<A's key>     only A's key decrypts it
            ├── /b/<B's board-id>#k=<B's key>     only B's key decrypts it
            └── /b/<C's board-id>#k=<C's key>     only C's key decrypts it
            the relay holds only ciphertext for all of them

모두가 andon hosted setup https://relay.example.com을 실행하며, 각자 그 하나의 URL 아래에서 256비트의 추측 불가능한 보드 ID를 받습니다. 격리는 두 계층으로 이루어지며 테스트를 거쳤습니다:

누구도 남의 것을 읽지 못함: 보드별 키 K, 릴레이는 암호문만 저장합니다(콘텐츠 블라인드).
누구도 남의 것에 쓰지 못함: 보드 ID는 읽기 권한입니다; 쓰기에는 해당 보드 자체의 인제스트 토큰이 필요합니다(B의 보드에 A의 토큰 → 401).

업그레이드 (이미 설치된 PWA)

자동 — 앱 스토어 불필요, 재페어링 불필요.

보드 HTML은 no-store로 제공되며 어디에도 캐시되지 않으므로, 실행할 때마다 최신 버전을 불러옵니다.
서비스 워커는 자동으로 업데이트됩니다(브라우저가 재실행/탐색/약 24시간마다 /sw.js를 다시 확인하며, skipWaiting()을 호출해 새 버전이 즉시 적용됩니다).
여러분의 키 K는 (서버가 아니라) 브라우저의 기기 내 IndexedDB에 저장되며 업데이트 후에도 유지됩니다 → 페어링이 그대로 유지됩니다. 최신 버전을 받으려면 PWA를 다시 실행하기만 하면 됩니다.

(새 기기는 여전히 한 번 페어링해야 합니다 — 그 기기의 IndexedDB에는 아직 K가 없습니다.)

문제 해결

보드 링크(#k=…)를 잃어버렸나요? 그것은 릴레이에 없습니다 — 릴레이는 여러분의 키를 가진 적이 없습니다. 그 링크는 andon hosted setup을 실행한 컴퓨터에 있습니다: 그곳에서 andon hosted pair를 실행해 전체 링크를 다시 출력하세요(또는 ~/.andon/hosted.json을 읽어 relayUrl + /b/ + boardId + #k= + key를 이어 붙이세요). 한 번도 페어링하지 않은 기기는 릴레이에서 링크를 복구할 수 없습니다 — 그 컴퓨터로 돌아가 링크를 가져온 뒤, 새 기기에서 한 번 여세요.
“다시 페어링 — 이 기기에서 보드 링크를 다시 열어 주세요.” 이 기기에는 키가 없습니다(새 기기, 저장소 비움, 또는 #k가 제거된 홈 화면 실행). 전체 보드 링크(#k=… 포함)를 한 번 다시 여세요; 그러면 키가 다시 캐시됩니다.
보드는 로드되는데 전부 비어 있거나 / 복호화되지 않습니다. #k=… 부분 없이 링크를 열었을 가능성이 큽니다(일부 도구는 #에서 잘라냅니다). 링크 전체를 다시 복사하세요.
오래된 카드가 사라지지 않습니다. 카드는 에이전트가 done/gone을 보내거나 6시간 TTL이 지나면 사라집니다. 완료된 세션은 보통 스스로 정리됩니다; 죽었거나 테스트용 세션은 TTL이 지날 때까지 남아 있습니다.
휴대폰 푸시가 오지 않습니다. 푸시에는 HTTPS가 필요합니다(따라서 127.0.0.1로 연 보드는 푸시하지 않습니다); iPhone에서는 보드를 먼저 홈 화면에 추가해야 합니다; 그리고 알림 켜기를 탭하고 알림을 허용해야 합니다.
전부 중지: andon hosted off(전달 중지), 그리고 직접 릴레이를 운영했다면 lsof -ti tcp:<port> | xargs kill.