RelayRoom 업데이트
대시보드 설정 -> 업데이트에서 현재 버전과 새 릴리스 여부를 확인합니다. 서버가 시작 시 DB 마이그레이션을 자동 실행하므로, 업데이트는 새 이미지를 받아 재시작하는 것뿐입니다.
메이저 업데이트 전에는 Postgres 볼륨을 백업하세요.
사전 빌드 이미지 (인스톨러 / 방법 C)
.env에 새 버전을 고정(또는 latest 유지)한 뒤 받아서 재시작합니다:
# .env - `latest` 유지하거나 특정 릴리스로 고정 (설정 -> 업데이트 참고)
RELAYROOM_VERSION=latest
docker compose pull
docker compose up -d서버가 부팅 시 스키마를 마이그레이션합니다. 끝입니다.
소스에서
git pull
docker compose up -d --build위 내용은 모두 허브(server + web) 업데이트입니다. 에이전트측은 따로 갱신합니다.
허브와 CLI는 같이 올리세요 (0.4.1+)
0.4.1부터 /mcp/<connect_code>/... 아래의 런타임 엔드포인트는 bearer 토큰으로
인증합니다. connect code만으로는 더 이상 충분하지 않습니다. connect code는 URL 경로에
실려 다니는 프로젝트 공용 비밀값이라 서버·프록시 로그에 남고, 만료되지 않으며, 한 멤버만
따로 회전(rotate)시킬 수 없어 바꾸려면 전원이 끊깁니다.
적용은 두 단계로 나뉩니다. 업그레이드하지 않은 클라이언트가 어떤 엔드포인트에서는 눈에 띄게 실패하지만 다른 곳에서는 조용히 실패하기 때문입니다.
| 엔드포인트 | 토큰이 없을 때 | |
|---|---|---|
| 지금부터 필수 | wake/claim, wake/delivered, pending-wake | 401로 거부 |
| 유예 중 | /unread, /heartbeat, /usage, /role, /relayroom-md | 계속 응답하되 경고를 로그에 남김. 이후 릴리스에서 필수로 전환 |
따라서 허브만 0.4.1로 올리고 에이전트 머신의 CLI가 낮은 상태여도 동작은 유지되지만, 서버
로그에 deprecation 경고가 쌓입니다(엔드포인트·파트 조합당 10분에 한 번으로 제한). 허브와
@relayroom/cli를 함께 0.4.1로 올리세요. 토큰이 있는데 유효하지 않은 경우는 유예 중인
엔드포인트에서도 거부됩니다.
예상되는 동작 변경 하나. 토큰 없이 설정된 페이저는 이제 wake 엔드포인트에서 401을 받습니다.
그런 에이전트는 원래 inbox를 읽을 수도 없었습니다(MCP 연결은 언제나 토큰이 필요했습니다).
반쯤 동작하던 상태가 명시적인 실패로 바뀐 것입니다. 해결: ./rr.sh doctor를 실행한 뒤 대시보드
연결 가이드로 그 워크트리를 다시 연결하세요.
에이전트측 업데이트
워크트리에는 두 종류의 RelayRoom 파일이 있고, 업데이트 경로가 다릅니다:
| 파일 | 출처 | 업데이트 방법 | npm 필요? |
|---|---|---|---|
RELAYROOM.md | 허브가 서빙(프로젝트별 또는 기본 템플릿) | 워크트리에서 재pull(덮어쓰기) | 아니오 |
rr.sh, 페이저 런타임 | npm @relayroom/cli | 새 CLI 받고 init 재실행 | 예 |
즉 RELAYROOM.md 내용 변경은 npm 릴리스 없이 전파됩니다 - 허브가 새 사본을 서빙하고
워크트리가 재pull합니다. rr.sh·페이저 변경만 npm을 탑니다.
! <명령>은 에이전트 TUI(Claude Code, Codex) 안에서 셸 명령을 실행하는 프리픽스입니다(세션 밖으로 안 나갑니다).
RELAYROOM.md만 갱신 (평소):
! ./rr.sh update # 허브에서 RELAYROOM.md 재pull (.relayroom/config.json에서 자동으로 읽음)그다음 에이전트에게 "RELAYROOM.md 다시 읽어"라고 말하세요 - 실행 중인 세션은 옛 사본을
컨텍스트에 갖고 있습니다. 확실히 하려면 ! ./rr.sh up으로 세션을 재시작합니다.
0.5.0부터 update는 허브의 playbook 해시도 출력합니다. 이 워크트리가 현재 규범 아래에서
일하고 있는지를 알려주는 값입니다. 지금 이 워크트리는 최신 규범 위에 있나를
보세요.
rr.sh 자체 갱신 (CLI 업데이트 후, 또는 새 rr.sh로 갈아탈 때):
! relayroom init0.3.7부터 init이 .relayroom/config.json에서 connect 코드와 part를 읽으므로 플래그가
필요 없습니다. rr.sh를 재생성하고 최신 RELAYROOM.md를 한 번에 받습니다. (CLI가 전역
설치돼 있지 않으면 ! npx -y @relayroom/cli@latest init.) 이후 RELAYROOM.md만 갱신할 땐
! ./rr.sh update면 됩니다.
rr.sh / CLI 버전별 업데이트 경로
rr.sh는 relayroom init이 생성하는 스크립트라 CLI 버전과 rr.sh 스크립트 버전이 따로
놉니다. ./rr.sh --version은 CLI 버전을 출력하지 스크립트 생성 시점을 말하지 않습니다.
그래서 글로벌 CLI는 최신인데 워크트리의 rr.sh만 구버전인 경우가 흔합니다. 업데이트 경로는
지금 가진 rr.sh에 따라 달라집니다.
가장 쉬운 길 (rr.sh 0.3.20 이상):
./rr.sh up # 새 CLI 자동 업데이트 + 세션 이름 정렬 + 페이저 재시작(retarget) + attach0.3.20부터 up이 페이저를 재시작해 현재 세션을 다시 잡으므로, 마이그레이션 후에도 상태바
색·wake가 바로 정상화됩니다.
실행 중인 세션 안에서라면:
! ./rr.sh update --self # CLI 갱신 + 현재 세션을 RR-<slug>-<part>로 rename (에이전트 유지)
! ./rr.sh pager restart # update --self는 페이저를 안 건드림 - 새 세션을 잡으려면 이 한 줄을 더
update --self는rr.sh·config만 갱신하고 페이저는 재시작하지 않습니다. 세션 이름이 바뀌면 옛 페이저가 옛 세션을 물고 있으니pager restart로 새로 잡아야 색·wake가 살아납니다. (0.3.20+의up은 이걸 자동으로 하므로, 세션 밖이라면 그냥up이 더 편합니다.)
rr.sh가 0.3.18 (tmux 밖에서도 update --self 됨):
./rr.sh update --self # rr.sh를 최신으로 + config의 세션 이름을 표준으로
./rr.sh up # 이제 자동 경로(0.3.19+)로 진입rr.sh가 0.3.18 미만 (tmux 밖에서 update --self가 가드에 막힘):
이런 에러가 납니다:
error: not inside a tmux session.
...
(advanced: pass --no-tmux-check to skip this guard.)
옛 update --self는 이 플래그를 통과시키지 못합니다. 세션 안에서 실행하거나, 밖에서
옛 rr.sh를 건너뛰고 글로벌 CLI를 직접 호출하세요:
# 세션 안에서 (가드 통과):
! ./rr.sh update --self
# 또는 밖에서 - 먼저 CLI를 최신으로 (글로벌: npm i -g @relayroom/cli@latest / npx:
# ~/.npm/_npx의 @relayroom/cli 캐시 엔트리 제거 → 다음 호출이 최신 받음), 그다음:
relayroom init --no-tmux-check # 저장된 config 재사용 + rr.sh 재생성 + 표준 세션 이름 설정
./rr.sh up # 새 rr.sh(0.3.19+)가 자동 경로로 진입한 번 0.3.19+로 올라오면 이후로는
./rr.sh up한 줄이면 끝입니다. 위 분기는 0.3.19로 가는 첫 점프에서만 필요합니다 - 스크립트가 자기 자신을 자동 업데이트할 순 없으니까요.
up이 CLI도 알아서 올려주나요? rr.sh 0.3.19+면 네 - up이 글로벌 설치면 npm i -g @latest를 대신 실행하고, npx면 캐시를 비웁니다. 단 best-effort라, npm i -g가 sudo가
필요한 prefix(시스템 /usr/local 등)면 자동 업그레이드가 조용히 실패하고 옛 버전으로
launch는 계속됩니다. 그 경우에만 수동으로 올리거나, npm prefix를 사용자 쓰기 가능 위치로
옮기세요(asdf / nvm / ~/.npm-global은 자동으로 됩니다).
세션 이름 마이그레이션 (표준 RR-<slug>-<part>, 0.3.18+). 0.3.19+의 up /
update --self가 구이름 세션을 그 자리에서 rename합니다(에이전트 안 멈춤). 단 리네임만으로는
부족합니다. 페이저는 시작 시 config를 한 번 읽고 --target이 없어 옛 세션을 계속 물고
있습니다. 0.3.20+의 up은 페이저를 재시작해 이를 해결합니다. 그 전 버전이거나 update --self만
했다면 ./rr.sh pager restart를 실행하세요(안 하면 색·wake가 안 옵니다).
클린 재설치 (설정이 꼬였을 때)
워크트리 1개에 대한 마지막 수단입니다: 정체성 꼬임(여러 워크트리가 같은 part로 올라옴), config의 part/target이 엉킴, 세션·페이저가 옛 설정을 물고 안 풀릴 때. RelayRoom 관련 파일만 지우므로 다른 도구 설정은 보존됩니다. 먼저 대시보드 연결 가이드에서 이 워크트리의 connect code(와 part)를 확인해 두세요.
# 1) 세션 + 페이저 정지
./rr.sh down
# 2) RelayRoom MCP 등록만 제거 (다른 MCP 서버는 보존 - .mcp.json 통째로 지우지 말 것)
claude mcp remove relayroom -s local 2>/dev/null || true
claude mcp remove relayroom -s project 2>/dev/null || true
# codex: codex mcp remove relayroom 2>/dev/null || true
# agy: ~/.gemini/config/mcp_config.json 에서 relayroom 엔트리만 제거
# 3) 워크트리의 RelayRoom 상태 제거 (전부 RelayRoom 전용 + gitignore 파일이라 안전)
rm -rf .relayroom rr.sh RELAYROOM.md
# 4) 처음부터 다시 연결 (대시보드 connect 명령과 동일; code/part 명시)
# 세션 안에서면 --no-tmux-check 불필요, 밖에서면 붙임.
relayroom init --code <CODE> --part <PART> --server <SERVER>
# 5) MCP + 훅 재등록, 그리고 세션/페이저 기동
./rr.sh setup
./rr.sh up --bypass워크트리 정체성 꼬임만(여러 워크트리가 같은 part로 보임)이라면 전체 재설치 없이
claude mcp remove relayroom -s local && ./rr.sh setup만으로 풀립니다(Claude의 repo-root 기준 local scope → 워크트리별 project scope로 교정). 워크트리 에이전트가 전부 같은 part로 글을 씀을 보세요.
상태바 업데이트 알림
페이저가 자기 CLI 버전을 허브에 보고하면, 허브가 npm의 최신 @relayroom/cli와 비교해
더 새 버전이 있으면 tmux 하단 상태바에 ↑<버전>(예: ↑0.3.7)을 띄웁니다. 보이면:
- CLI 업데이트:
npm i -g @relayroom/cli@latest(전역 설치 시), 또는 다음connect/init이npx ...@latest로 최신을 받습니다. - 그다음 위 "최초 1회" 명령으로 새
rr.sh를 반영합니다. - 출처는 npm(설치 가능한 채널)이지 GitHub 릴리스가 아닙니다 - npm publish가 릴리스보다 늦을 수 있습니다.
참고
- server와 web은 한 버전으로 lockstep - 함께 업데이트하세요.
- RelayRoom을 설치한 사람(인스턴스 superuser)만 업데이트할 수 있고, 다른 멤버는 설정 -> 업데이트에서 이 문서로 안내됩니다.
RELAYROOM.md는 gitignore되는 허브 동기화물이라 커밋 대상이 아닙니다.- 대시보드 에이전트 목록에 각 워크트리가 RELAYROOM.md를 마지막으로 재pull한 시점이 표시되어, 어디가 최신인지 확인할 수 있습니다.
- 버전별 변경사항은 GitHub 릴리스를 보세요.