여러 머신 토큰 동기화

무엇을 서버에 두지 않는가

동기화 서버는 작은 서버 하나(tools/synserver)입니다. 제작자가 돌리는 공식 서버를 그대로 써도 되고, 같은 코드를 자기 기계에 올려도 됩니다 — 둘은 같은 프로그램입니다. 남의 서비스에 토큰 기록을 맡기지 않으려고 파일 하나짜리로 만들었고, 의존성은 암호 라이브러리 하나뿐입니다. 무엇보다 서버가 알 수 있는 것을 설계로 줄였습니다.

• 계정 이름을 저장하지 않습니다. 이메일 대신 각 머신만 아는 열쇠로 만든 가명으로 계정을 구분합니다 — 서버는 “계정 A 와 B 는 다르다”만 알고 누구인지는 모릅니다.
• 기록을 읽지 못합니다. 토큰 수치·모델명은 보내기 전에 각 머신에서 잠그고, 서버에는 암호문만 올라갑니다. 열쇠는 서버에 없습니다.
• 사람 이름이 들어갈 칸이 없습니다. 로그인은 아이디도 비밀번호도 없이 패스키 하나로 합니다.

공식 서버로 바로 시작하기

서버를 직접 올리지 않아도 됩니다. 제작자가 같은 코드로 돌리는 공식 서버가 있고, pytmux 에 기본 주소로 이미 들어 있습니다 — 설정 파일을 만질 일도, 주소를 칠 일도 없습니다.

1. 브라우저로 위 주소를 열고 새 패스키 만들기 — 아이디도 이메일도 묻지 않습니다. 한 번 뜨는 복구 코드를 지금 보관하세요(아래 “첫 설정” 참고).
2. 코드 새로 만들기 를 눌러 나온 명령 한 줄을 복사합니다.
3. 합치고 싶은 머신의 pytmux 에서 : 프롬프트에 붙여넣습니다. 머신마다 2~3 을 반복하면 끝입니다.

기본값을 들고만 있는 머신은 트래픽이 0 입니다. 등록하기 전에는 네트워크 요청이 한 번도 나가지 않고, claude-token-sync off 로 끄면 도입 전과 완전히 같습니다. 즉 이 기능은 등록해야 켜집니다.

운영자가 볼 수 있는 것도 정직하게 적어 둡니다. 위에 쓴 대로 기록 내용과 계정 이름은 공식 서버에서도 볼 수 없지만, vault 별 활동 시각·양·건수 같은 메타데이터는 서버에 남습니다. 그것조차 남기고 싶지 않다면 자기호스팅이 답입니다.

지금은 가입이 열려 있습니다(아무나 vault 를 만들 수 있음). 다만 자원 사정에 따라 예고 없이 닫힐 수 있습니다 — 그때는 이미 등록한 머신은 계속 동작하고, 새 가입만 막힙니다.

직접 서버 올리기 (선택)

메타데이터도 남기고 싶지 않거나 가용성을 스스로 책임지고 싶다면 직접 올리면 됩니다. 집 서버·개인 VPS 어디든 됩니다. TLS 는 앞단 리버스 프록시(Caddy·Cloudflare 터널 등)가 맡고, 서버는 루프백에만 붙입니다 — 패스키는 HTTPS 에서만 동작합니다.

도메인은 신중히 고르세요. 패스키는 이 도메인에 묶여, 나중에 바꾸면 등록된 패스키가 전부 무효가 됩니다. 그리고 a.b.example.org 처럼 점이 하나 더 깊은 이름은 기본 인증서가 덮지 못해 HTTPS 가 안 될 수 있습니다 — sync.example.org 같은 2단계 이름이 안전합니다.

첫 설정 — 패스키와 복구 코드

1. 브라우저로 서버 주소를 열고 새 패스키 만들기. 아이디 입력 없이 vault(내 공간)가 생깁니다.
2. 화면에 복구 코드가 한 번 뜹니다 — 지금 보관하세요. 서버는 해시만 갖고 있어 다시 보여줄 수 없습니다.
3. 가능하면 패스키를 하나 더 만들어 두세요(로그인 상태에서 같은 버튼). 패스키가 하나뿐이면 그것을 잃는 순간 잠깁니다.

머신 붙이기 — 명령 한 줄

브라우저에서 코드 새로 만들기 를 누르면 실행할 명령 전체가 복사 버튼과 함께 나옵니다. 그 머신의 pytmux 에서 : 프롬프트에 붙여넣으면 끝입니다.

암호화 열쇠도 그 코드에 실려 함께 넘어갑니다 — 머신끼리 열쇠를 손으로 옮길 필요가 없습니다. 코드는 1회용·10분이고, 쓰이는 즉시 브라우저 화면이 스스로 갱신돼 등록된 머신이 나타납니다. 서버 주소는 공식 서버가 기본값으로 들어 있어 따로 설정하지 않아도 되고, 등록 전에는 네트워크 요청이 한 번도 나가지 않습니다.

UI 없는 머신(헤드리스·CI)에서는 셸로도 됩니다.

붙은 머신은 웹 화면의 등록된 머신 목록에 이름과 마지막 동기화 시각 (방금 전 · 3시간 전 — 마우스를 올리면 정확한 시각)으로 남고, 오른쪽 폐기 로 언제든 끊을 수 있습니다. 오래 조용한 머신은 그쪽에서 동기화가 멈춰 있다는 뜻이니 그 머신에서 claude-token-sync status 를 보세요.

자기 서버를 쓰려면

기본 주소(공식 서버) 대신 자기 서버를 쓰려면 둘 중 하나면 됩니다 — 코드를 고칠 필요는 없습니다.

끄려면 claude-token-sync off. 꺼 두면 동작·성능·프라이버시가 도입 전과 완전히 같습니다.

서버에 쌓인 기록에 보존 기간을 걸 수도 있습니다 — 서버를 띄울 때 PYTMUX_SYNC_RETAIN_DAYS=90 처럼 주면 그보다 오래된 것을 알아서 정리합니다. 기본은 무기한이고, 원본은 각 머신의 로컬 기록이라 서버에서 지워도 사용량 회계는 그대로입니다.

결과 읽는 법

claude-token-sync now 는 세 숫자를 돌려줍니다.

• pushed — 이번에 올린 내 기록 수
• merged — 다른 머신에서 받아 합친 수
• rejected — 받았지만 버린 수. 0 이 아니면 열쇠가 다릅니다 — 머신마다 다른 열쇠로 올리고 있다는 뜻이라, 열쇠를 맞추고 claude-token-sync resync 로 전량 다시 올려야 합니다.

계정이 여러 개면 계정별로 갈려서 합쳐집니다. 같은 계정은 머신을 넘어 하나로, 다른 계정은 끝까지 따로입니다. 특정 계정만 내보내려면 token_sync_accounts 에 그 계정만 적으면 됩니다(회사 계정을 개인 서버로 올리지 않기).

잠겼을 때 · 열쇠를 바꿀 때

패스키를 잃었다면 로그인 화면의 복구 코드로 로그인 을 쓰세요. 첫 설정 때 받은 1회용 코드를 넣으면 그 자리에서 새 패스키를 붙일 수 있고, 새 복구 코드가 다시 발급됩니다. 이 코드로 얻는 것은 접근 권한뿐이라, 코드가 새도 기록은 읽히지 않습니다.

열쇠 자체를 바꾸려면(기기 분실 등) 순서가 있습니다. 서버에 쌓인 기록은 새 열쇠로 읽을 수 없게 되지만, 각 머신의 로컬 기록이 원본이라 다시 올리면 복구됩니다.

1. 웹 화면에서 모든 기기 폐기
2. 각 머신에서 db/ 의 sync_vault.key · sync_device.key · sync_device.id 삭제 (토큰 기록 claude-tokens.db 는 그대로)
3. 웹에서 로그아웃 → 로그인 하면 새 열쇠 생성
4. 머신마다 코드를 새로 만들어 재등록하고 claude-token-sync resync

지금 동기화되는 것

현재는 한도 스냅샷(5시간·주간 퍼센트와 리셋 시각)이 오갑니다. 이 값들은 원래 계정 단위라 계산이 틀렸던 게 아니라 그 머신이 최근에 관측하지 못했을 뿐이었고, 그래서 이것만 맞춰도 체감 문제의 절반이 사라집니다. 요청별 토큰 회계 (usage_xc) 동기화는 다음 단계입니다.