Self-Hosting

Relay is open source under the Apache-2.0 license. You can run the entire gateway yourself — there is no proprietary core and no lock-in.

The source lives at github.com/ramachandraa-ps/relay.

Requirements

A LiveKit deployment (self-hosted or LiveKit Cloud) plus its API key and secret. LiveKit carries the actual media.
A Postgres database for projects, API keys, and usage rollups.
The Relay container, which serves both the API and the portal.

Environment variables

Variable	Description
`DATABASE_URL`	Postgres connection string. Relay runs its migrations against this on start.
`LIVEKIT_URL`	WebSocket URL of your LiveKit deployment (`wss://…`). Returned to clients as `url` when you mint a token.
`LIVEKIT_API_KEY`	API key from your LiveKit deployment, used to sign access tokens.
`LIVEKIT_API_SECRET`	API secret paired with the key above. Also used to verify incoming webhook signatures.
`AUTH_SECRET`	Random secret used to sign Relay portal sessions. Generate a long random value.
`RELAY_API_URL`	Public base URL where this Relay instance is reachable.

Running Relay

Relay ships as a Docker image. On start the container runs prisma migrate deploy (idempotent) to apply any pending migrations, then boots the Next.js server.

deploy.sh

# 1. Run Postgres (or point at an existing instance)
docker run -d --name relay-db \
  -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=relay \
  -p 5432:5432 postgres:16

# 2. Run Relay (migrations run automatically on start)
docker run -d --name relay \
  -p 3000:3000 \
  -e DATABASE_URL="postgresql://postgres:secret@relay-db:5432/relay?schema=public" \
  -e LIVEKIT_URL="wss://your-livekit-host" \
  -e LIVEKIT_API_KEY="APIxxxxxxxx" \
  -e LIVEKIT_API_SECRET="your-livekit-secret" \
  -e AUTH_SECRET="$(openssl rand -base64 32)" \
  -e RELAY_API_URL="https://relay.example.com" \
  ghcr.io/ramachandraa-ps/relay

Connect LiveKit webhooks

Relay meters usage from LiveKit webhook events. Point your LiveKit webhook.urls at your Relay instance:

livekit.yaml

webhook:
  api_key: APIxxxxxxxx
  urls:
    - https://relay.example.com/api/webhooks/livekit

The webhook must use the same API key and secret you configured as LIVEKIT_API_KEY / LIVEKIT_API_SECRET, so Relay can verify the signature on each event. Without matching credentials, events are rejected and usage will not be recorded.