문서블로그
ENKO

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-wake401로 거부
유예 중/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 init

0.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) + attach

0.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가 릴리스보다 늦을 수 있습니다.

0.8.0에서 달라지는 것

herdr를 두 번째 멀티플렉서로 쓸 수 있습니다. 요청하지 않으면 아무것도 달라지지 않습니다. .relayroom/config.json에 multiplexer 필드가 없는 워크트리는 예전과 똑같이 tmux 워크트리입니다. 멀티플렉서 고르기를 보세요.

쓰려면 순서가 중요합니다. 새로 설치할 때와 같은 순서이고(에이전트 CLI 설치), 워크트리가 이미 있으므로 init 자리에 update --self가 들어갑니다.

  1. 허브(server + web) 업그레이드. 마이그레이션 0024가 포함됩니다.
  2. npm i -g @relayroom/cli
  3. 각 워크트리에서 ./rr.sh update --self
  4. 각 워크트리에서 ./rr.sh up --use-herdr

사람들이 건너뛰는 것이 3번이고, 건너뛰면 가장 나쁜 방식으로 실패합니다.

구버전 rr.sh는 --use-herdr를 거부하지 않고 무시합니다

rr.sh는 각 워크트리에 기록되는 파일이고 스스로 갱신되지 않습니다. 0.7.0 이하에서 생성된 사본은 --use-herdr를 거부하지 않고 그냥 버린 뒤 tmux 세션을 띄웁니다. 명령은 성공하고, 아무 경고도 없고, 워크트리는 여전히 tmux입니다. 출시 당일 실제로 한 사용자가 여기 걸렸습니다.

이미 디스크에 있는 사본을 소급해서 고칠 방법은 없습니다. 0.8.0부터는 up이나 launch에 모르는 옵션을 주면 플래그와 해결책을 함께 알려주는 에러가 납니다.

rr: unknown option for 'up': --use-herdr
    up accepts: --bypass --new --restart --use-herdr --use-tmux --channel --no-channel
    If you expected that flag to exist, this rr.sh may predate it:
      npm i -g @relayroom/cli && ./rr.sh update --self

이미 구버전 rr.sh에서 실행했다면, 터미널이 아니라 설정에 무슨 일이 있었는지 물어보세요.

grep multiplexer .relayroom/config.json

multiplexer 필드가 없으면 전환은 일어나지 않은 것입니다.

0.7.0에서 달라지는 것

마이그레이션 0023이 지식 행을 삭제합니다. 먼저 DB를 백업하세요. 되돌리는 마이그레이션이 없고 사본도 남기지 않습니다.

자동 스레드 추출기가 사라졌고(지식 검토하기 참고), 마이그레이션이 그것이 만든 것을 지웁니다. 라벨로 판단하지 않습니다. 후보 행마다 추출기가 같은 스레드에서 무엇을 썼을지 재구성해서 바이트 단위로 일치하는 것만 지웁니다.

결과어떤 행인가
삭제재구성이 정확히 일치하는 행. 제목이 스레드 제목이고 본문이 마지막 에이전트 메시지를 2000자로 자른 것.
재분류제목이 스레드 제목이 아닌 행. 에이전트가 쓴 것이므로 남기고 레슨으로 표시합니다.
그대로 둠귀속할 수 없는 것 전부. 스레드가 사라졌거나, 레닥션 때문에 본문이 원래 메시지와 더 이상 일치하지 않는 경우.

승격됐거나 trusted로 표시된 행은 삭제되지 않습니다. 사람이 그것을 읽고 승인했고, 그건 마이그레이션이 내릴 수 있는 것보다 나중이고 더 구체적인 판단이기 때문입니다.

삭제된 행의 추출 워터마크도 함께 지워집니다. 그래야 그 스레드들이 지워진 것을 대신할 레슨을 받을 수 있습니다.

행이 남습니다. 실패가 아닙니다

여기가 가장 오해하기 쉬운 지점입니다. 마이그레이션을 돌린 뒤에도 항목이 남아 있는 것은 동작하지 않았다는 뜻이 아닙니다.

우리 허브에서 실제로 돌린 결과입니다. 대상 847행:

결과개수
삭제833
레슨으로 재분류2
그대로 남음12

digital-docent 프로젝트 하나는 322행에서 5행이 됐습니다.

이건 우리 허브의 숫자이지 당신이 볼 값을 예측한 것이 아닙니다. 개수도 비율도 데이터에 전적으로 달려 있습니다.

그 12행이 남은 이유: 레닥션 규칙을 설정한 프로젝트에서 나옵니다. 마이그레이션은 추출기 출력을 재구성해 바이트 단위로 대조해서 식별하는데, 레닥션으로 본문에서 일부 구간이 지워진 행은 그것이 만들어진 원 메시지와 더 이상 일치하지 않습니다. 그래서 대조에 걸리지 않고 그대로 남습니다.

이건 설계이지 빠진 부분이 아닙니다. 에이전트의 레슨을 지우는 것은 되돌릴 수 없지만, 남은 쓰레기는 화면에 보이고 손으로 지울 수 있습니다. 확신을 갖고 귀속할 수 없는 행을 만나면 마이그레이션은 그것을 남깁니다.

업그레이드 후에는 지식 목록이 비어 있는 것이 정상 상태입니다. 이제 자동으로 수집되는 것이 없습니다. 에이전트가 레슨과 함께 스레드를 닫거나, learn을 부르거나, 사람이 제안을 승인할 때 항목이 생깁니다.

0.6.1은 건너뛰세요

0.6.1은 아예 시작되지 않았습니다. CLI가 첫 인자를 읽기도 전에 import 시점에 죽어서 에이전트를 하나도 띄울 수 없었습니다. 0.6.2가 그 수정입니다. 0.6.0을 쓰고 있다면 그대로 지나가세요.

0.6.1에는 wake 전달 방식 변경도 실렸고 그 변경은 유효합니다. 기본이 페이저이고 Claude Code 채널은 옵트인입니다. 어댑터를 보세요.

0.6.0에서 달라지는 것

DB 마이그레이션은 없습니다. 드롭인 업그레이드입니다. 아무것도 설정하지 않아도 바로 보이는 동작 변화가 셋 있습니다.

  • 에이전트가 스레드를 닫으면서 레슨을 붙일 수 있고, 이것이 기본으로 켜져 있습니다. 끄려면 프로젝트의 knowledge_config를 직접 고쳐야 합니다. close를 보세요.
  • 일회성 재증류. learn이 인용만 하던 스레드는 그동안 조용히 추출에서 빠져 있었는데 이제 아닙니다. 그래서 한 번씩 증류됩니다. 반복되지 않고, 이미 추출된 스레드는 영향받지 않습니다. 몇 개인지는 에이전트들이 learn에 스레드 참조를 얼마나 자주 넘겼는지에 달려 있습니다.
  • 추출은 closed에서만 일어납니다. 예전에는 answered에서도 돌았으므로, answered로 남겨둔 스레드는 이제 증류되지 않습니다.

참고

  • server와 web은 한 버전으로 lockstep - 함께 업데이트하세요.
  • RelayRoom을 설치한 사람(인스턴스 superuser)만 업데이트할 수 있고, 다른 멤버는 설정 -> 업데이트에서 이 문서로 안내됩니다.
  • RELAYROOM.md는 gitignore되는 허브 동기화물이라 커밋 대상이 아닙니다.
  • 대시보드 에이전트 목록에 각 워크트리가 RELAYROOM.md를 마지막으로 재pull한 시점이 표시되어, 어디가 최신인지 확인할 수 있습니다.
  • 버전별 변경사항은 GitHub 릴리스를 보세요.