Self-hosting notes

What the agent on your servers needs, and what it takes to run the Relay control plane yourself.

Two parts

Relay has a control plane (the API, a deploy worker and the dashboard) and anagent that runs on each server you own. Your apps always run on your servers. The control plane decides what should run, and the agent makes it happen.

Your servers

  • Any Linux machine, amd64 or arm64: a VPS, a dedicated box or a homelab.
  • The agent installs as a systemd service and drives Docker andCaddy on your behalf.
  • Ports 80 and 443 must be reachable so Caddy can serve your apps and obtain certificates.
  • No inbound management port. The agent connects out to the control plane over a WebSocket, so there is nothing to expose for Relay itself.

Enrolling a server

  1. In the dashboard, open Servers → Add server and create a token.
  2. Run the install command shown on the page on your server. The token is single-use and valid for 32 hours.
  3. The agent exchanges it for a persistent token stored on the server, then appears in the server list as soon as it checks in.

Running the control plane

You'll need:

  • A Postgres database and a Redis instance.
  • A small VM with Docker Compose for the API and worker, behind a reverse proxy that serves HTTPS. A personal setup runs comfortably on about 1 GiB of RAM with swap.
  • A GitHub OAuth app for dashboard sign-in, and a place to host the dashboard.

The main settings are environment variables:

VariablePurpose
DATABASE_URLPostgres connection string.
REDIS_URLRedis connection string for the deploy queue.
RELAY_MASTER_KEY64 hex characters that protect stored secrets. Generate with openssl rand -hex 32.
GITHUB_WEBHOOK_SECRETVerifies GitHub webhooks and signs requests between the dashboard, API and worker.
NEXTAUTH_SECRET, AUTH_GITHUB_ID, AUTH_GITHUB_SECRETDashboard sign-in.

Good to know

  • The first GitHub account to sign in becomes the organization owner. Everyone after that needs an invitation.
  • Back up RELAY_MASTER_KEY. Without it, stored environment variables can't be decrypted.
  • Agents connect to your API at wss://<your-api>/agent, so the API must be reachable from your servers.
  • Your images stay in your own registry, so rollbacks never depend on a rebuild.