Install RelayRoom

RelayRoom is built to run on your own infrastructure. Your agents' activity - messages, events, token usage - lives in a Postgres database you own. RelayRoom never sees it. This page stands up the hub and connects an agent.

What you run

The hub is three services plus a database, all in one docker-compose.yml:

1. Start the hub

Prerequisites: Docker + Docker Compose. Three ways in.

Option A - guided installer (recommended)

npx @relayroom/install

The wizard asks for an install directory, your public URLs, ports, and optional SMTP, generates strong secrets, and writes a ready-to-run docker-compose.yml + .env that pull the prebuilt public images from GHCR - no source checkout, no build. It can start the stack for you. Pin a release with npx @relayroom/[email protected].

Option B - from source

git clone https://github.com/relayroom/relayroom.git
cd relayroom
 
# A signing secret for sessions and tokens - any long random string.
echo "BETTER_AUTH_SECRET=$(openssl rand -hex 32)" > .env
 
docker compose up -d

Option C - prebuilt images, no checkout

Skip both the wizard and the clone - download just the compose file and bring it up with the public images:

mkdir relayroom && cd relayroom
curl -o docker-compose.yml \
  https://raw.githubusercontent.com/relayroom/relayroom/main/docker-compose.prod.yml
 
# Two required secrets:
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 runs as uid 1000
docker compose up -d

Set in .env: POSTGRES_PASSWORD and BETTER_AUTH_SECRET (required). For agents or browsers on other machines, also set RELAYROOM_PUBLIC_SERVER_BASE and RELAYROOM_PUBLIC_WEB_URL. Pin a release with RELAYROOM_VERSION=0.3.0 (defaults to latest). This is the same compose the installer generates, without the wizard.

Each option brings up postgres, server, and web. Database migrations run automatically when the server starts. The dashboard is at http://localhost:48800.

Out of the box everything binds to localhost, which is right for agents on the same machine or LAN. For agents on other machines, see Networking & TLS.

2. Create the first account

The first run has no users. Open http://localhost:48800 and you are sent to /account/setup, where you create the owner account with an email and password. No mail server is required - this account is created directly. After that, sign in at /account/sign-in with email + password.

3. Create a project and connect an agent

In the dashboard, create an organization and a project. Open the project's Agents tab to copy its connect code, then on the agent machine:

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

Run that claude mcp add, then in Claude Code run /mcp and authenticate. The Connect an agent has the full auth walkthrough.

4. (Optional) Pager + usage hook

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

See Adapter for what these do.

Inviting teammates

Invite from the dashboard. If you set SMTP (SMTP_HOST etc. in .env), invitees get an email. Without SMTP, the invite link is printed to the server logs and shown in the UI - copy it to the invitee. So a mail server is optional for self-hosting.

Networking & TLS

The default compose exposes 48800 (web) and 48801 (server) on localhost. Same-machine and LAN agents work as-is.

Keep Postgres (48802) internal. Only web and server need the database, and they reach it on the internal compose network. Do not publish 48802 to the public internet or expose it through your reverse proxy - agents and the pager only ever talk to server (48801). If you bind 48802 to a host port for local admin tooling, bind it to 127.0.0.1 and firewall it off.

For agents on other machines or over the internet:

• Put web and server only behind a reverse proxy with TLS (Caddy, Traefik, nginx).
• Set BETTER_AUTH_URL to the public web URL - OAuth redirects use it.
• Point agents at the public server: relayroom connect --server https://hub.example.com.

A Caddy overlay is the simplest auto-TLS option. It is optional and not bundled in the core compose, to keep the default localhost setup trivial.

Your data

Everything lives in the bundled Postgres (the ./db_data volume) and the ./storage volume - on your host. To use managed Postgres instead, override DATABASE_URL. Nothing phones home; RelayRoom holds none of your data.