Configuration

Relay is configured entirely via environment variables. No config files needed.

Environment Variables

All configuration is handled through environment variables. The table below lists every option with its default value.

Variable	Default	Description
RELAY_HOST	`0.0.0.0`	IP address to bind to
RELAY_PORT	`6001`	Port to listen on
RELAY_APP_ID	`relay-app`	Application identifier
RELAY_APP_KEY	`relay-key`	Public app key (shared with clients)
RELAY_APP_SECRET	—	Secret key for signing auth tokens (keep private!)
RELAY_MAX_CONNECTIONS	`10000`	Maximum concurrent WebSocket connections
RELAY_MAX_CHANNEL_NAME_LENGTH	`200`	Maximum channel name length in characters
RELAY_MAX_EVENT_PAYLOAD_KB	`100`	Maximum event payload size in KB
RELAY_PING_INTERVAL	`120`	Seconds between server pings
RELAY_PING_TIMEOUT	`30`	Seconds to wait for pong before disconnecting
RELAY_DASHBOARD_ENABLED	`true`	Enable the built-in web dashboard
RELAY_DASHBOARD_PATH	`/dashboard`	URL path for the dashboard
RELAY_DEBUG	`false`	Enable verbose debug logging

Using a .env File

Relay automatically loads a .env file from the working directory if one exists.

env

# .env
RELAY_APP_KEY=my-app-key
RELAY_APP_SECRET=my-super-secret-key
RELAY_PORT=6001
RELAY_DEBUG=true
RELAY_DASHBOARD_ENABLED=true

Multi-App Support (apps.json)

For multi-tenant deployments, create an apps.json file to register multiple applications on a single server instance.

json

[
  {
    "id": "app-1",
    "key": "key-1",
    "secret": "secret-1",
    "max_connections": 1000
  },
  {
    "id": "app-2",
    "key": "key-2",
    "secret": "secret-2",
    "max_connections": 5000
  }
]

When apps.json is present, the RELAY_APP_* environment variables are ignored. Each app gets its own isolated namespace of channels and connections.

apps.json Fields

Field	Required	Description
id	Yes	Unique app identifier (used in API paths)
key	Yes	Public key (clients connect with this)
secret	Yes	Secret for HMAC signing
max_connections	No	Per-app connection limit

Warning: In production, always change the default app secret. The default value relay-secret-change-me is not secure.

Docker Deployment

Basic

bash

docker run -d -p 6001:6001 \
  -e RELAY_APP_KEY=my-key \
  -e RELAY_APP_SECRET=my-secret \
  relayhq/relay:latest

With .env file

bash

docker run -d -p 6001:6001 \
  --env-file .env \
  relayhq/relay:latest

With apps.json

bash

docker run -d -p 6001:6001 \
  -v $(pwd)/apps.json:/relay/apps.json \
  relayhq/relay:latest

Docker Compose

yaml

version: '3.8'
services:
  relay:
    image: relayhq/relay:latest
    ports:
      - "6001:6001"
    environment:
      RELAY_APP_KEY: my-key
      RELAY_APP_SECRET: my-secret
      RELAY_DEBUG: "false"
    restart: unless-stopped

Production Checklist

Before deploying Relay to production, make sure you have addressed the following:

Change the default app secret to a strong, random value
Use TLS termination via a reverse proxy (nginx, Caddy, Cloudflare)
Set RELAY_DEBUG=false to disable verbose logging
Consider disabling the dashboard or restricting access: RELAY_DASHBOARD_ENABLED=false
Set RELAY_MAX_CONNECTIONS based on your server resources