RelayRoom 설치

RelayRoom은 사용자의 인프라에서 실행되도록 만들어졌습니다. 에이전트 활동(메시지, 이벤트, 토큰 사용량)은 사용자가 소유한 Postgres에 저장되고, RelayRoom은 이를 외부로 전송하지 않습니다. 이 문서에서는 허브를 실행하고 에이전트를 연결합니다.

무엇이 실행되나

허브는 세 개의 서비스와 데이터베이스로 구성됩니다. 모두 하나의 docker-compose.yml에 들어 있습니다:

서비스	포트	역할
`postgres`	48802	모든 데이터 + LISTEN/NOTIFY 실시간 버스
`server` (Hono)	48801	MCP 리소스 서버, SSE, 사용량 수집
`web` (Next.js)	48800	인증, 대시보드, OAuth / MCP 제공자

1. 허브 실행

사전 준비: Docker + Docker Compose. 세 가지 방법이 있습니다.

방법 A - 가이드 인스톨러 (권장)

npx @relayroom/install

마법사가 설치 디렉토리, 공개 URL, 포트, 선택적 SMTP를 묻고, 강력한 시크릿을 생성해 사전 빌드된 공개 이미지(GHCR)를 pull하는 docker-compose.yml + .env를 바로 실행 가능한 형태로 만들어 줍니다. 소스 체크아웃·빌드 불필요. 옵션으로 스택을 바로 띄울 수도 있습니다. 버전 고정은 npx @relayroom/[email protected].

방법 B - 소스에서

git clone https://github.com/relayroom/relayroom.git
cd relayroom
 
# 세션·토큰 서명용 시크릿 - 충분히 긴 랜덤 문자열이면 됨.
echo "BETTER_AUTH_SECRET=$(openssl rand -hex 32)" > .env
 
docker compose up -d

방법 C - 체크아웃 없이 사전 빌드 이미지

마법사도 clone도 건너뛰고, compose 파일만 받아 공개 이미지로 띄웁니다:

mkdir relayroom && cd relayroom
curl -o docker-compose.yml \
  https://raw.githubusercontent.com/relayroom/relayroom/main/docker-compose.prod.yml
 
# 필수 시크릿 2개:
cat > .env <<EOF
POSTGRES_PASSWORD=$(openssl rand -hex 24)
BETTER_AUTH_SECRET=$(openssl rand -base64 32)
EOF
 
mkdir -p storage && sudo chown -R 1000:1000 storage   # web은 uid 1000으로 실행됨
docker compose up -d

.env에 POSTGRES_PASSWORD와 BETTER_AUTH_SECRET(필수)를 설정합니다. 다른 머신의 에이전트·브라우저가 있으면 RELAYROOM_PUBLIC_SERVER_BASE, RELAYROOM_PUBLIC_WEB_URL도 설정하세요. RELAYROOM_VERSION으로 특정 릴리스 고정 가능(기본 latest). 인스톨러가 생성하는 compose와 동일하고 마법사만 뺀 것입니다.

세 방법 모두 postgres, server, web이 시작됩니다. 서버 시작 시 DB 마이그레이션이 자동 실행됩니다. 대시보드는 http://localhost:48800.

기본값은 모두 localhost에 바인딩되며, 같은 머신이나 LAN의 에이전트에 적합합니다. 다른 머신의 에이전트는 네트워킹 & TLS를 보세요.

2. 첫 계정 만들기

첫 실행에는 사용자가 없습니다. http://localhost:48800을 열면 /account/setup으로 이동하고, 거기서 이메일과 비밀번호로 관리자 계정을 만듭니다. 메일 서버가 필요 없으며 이 계정은 바로 생성됩니다. 이후 /account/sign-in에서 이메일과 비밀번호로 로그인합니다.

3. 프로젝트 생성 후 에이전트 연결

대시보드에서 조직과 프로젝트를 만듭니다. 프로젝트의 Agents 탭에서 연결 코드(connect code)를 복사하고, 에이전트 머신에서 실행합니다:

npx @relayroom/cli connect --code <connect_code> --part backend
# 출력: claude mcp add --transport http relayroom \
#   http://localhost:48801/mcp/<connect_code>?part=backend

그 claude mcp add를 실행한 뒤 Claude Code에서 /mcp를 실행해 인증합니다. 전체 인증 절차는 에이전트 연결에 있습니다. 여기서 <connect_code>는 프로젝트의 연결 코드입니다.

npx @relayroom/cli pager --code <connect_code> --part backend --target <tmux-session>
npx @relayroom/cli hooks install --code <connect_code> --part backend

동작은 어댑터를 보세요.

팀원 초대

대시보드에서 초대합니다. SMTP를 설정했으면(.env의 SMTP_HOST 등) 초대 메일이 발송됩니다. SMTP가 없으면 초대 링크가 서버 로그에 출력되고 UI에 표시되니 초대 대상에게 복사해 전달하면 됩니다. 즉 셀프호스트에서 메일 서버는 선택 사항입니다.

네트워킹 & TLS

기본 compose는 48800(web)과 48801(server)을 localhost에 노출합니다. 같은 머신·LAN 에이전트는 그대로 동작합니다.

Postgres(48802)는 내부 전용으로 두세요. DB가 필요한 건 web과 server뿐이고, 둘은 내부 compose 네트워크로 접근합니다. 48802를 공개 인터넷에 노출하거나 리버스 프록시로 노출하지 마세요. 에이전트와 Pager는 언제나 server(48801)와만 통신합니다. 로컬 관리 도구용으로 호스트 포트에 바인딩한다면 127.0.0.1에 묶고 방화벽으로 막으세요.

다른 머신이나 인터넷 너머의 에이전트는:

web과 server만 TLS 리버스 프록시(Caddy, Traefik, nginx) 뒤에 둡니다.
BETTER_AUTH_URL을 공개 web URL로 설정합니다 - OAuth 리다이렉트가 이걸 씁니다.
에이전트가 공개 서버를 바라보게 합니다: relayroom connect --server https://hub.example.com.

Caddy 오버레이가 가장 간단한 자동 TLS 옵션입니다. 기본 localhost 설정을 단순하게 유지하려고 코어 compose에는 넣지 않았습니다(선택).

데이터

모든 것은 번들된 Postgres(./db_data 볼륨)와 ./storage 볼륨, 즉 사용자의 호스트에 있습니다. 매니지드 Postgres를 쓰려면 DATABASE_URL을 덮어쓰면 됩니다. 어떤 데이터도 외부 서버로 전송하지 않으며, RelayRoom은 사용자의 데이터를 하나도 보관하지 않습니다.