Self-hosting the AgentRelay relay server

Deploy the AgentRelay relay for your team using Docker. Covers secret rotation, health verification, public exposure, and recommended hosting options.

The relay is the single shared service your whole team runs through — one deployment, done once by the team lead. It stores handoffs, enforces the block list, dispatches Slack notifications, and hosts everyone’s Agent Cards. You only need Docker; there is no Node, pnpm, or build step required on the host machine.

Rotate your secrets before exposing the relay publicly. The .env.example file ships with placeholder values that are safe for local testing but must not be used on a server accessible from the internet. Run the commands in Step 2 before you open any firewall or reverse-proxy rule.

Prerequisites

• Docker (any recent version with Compose v2 — docker compose, not docker-compose)
• openssl available on your PATH (ships with macOS and most Linux distributions)
• A domain or tunnel to expose the relay to teammates on other laptops

---

Setup

1. Clone the repo and copy the environment file

   git clone https://github.com/swayamg20/AgentRelay
   cd AgentRelay
   cp .env.example .env
   

   The .env file is read automatically by docker compose. All relay configuration — database credentials, secrets, public URL — lives here.

2. Rotate the secrets

   The example file ships with stable dev-only placeholders. Replace every secret with a freshly generated random value before exposing the relay outside localhost.

   Run these three commands exactly as shown. They overwrite the placeholder values in-place. RELAY_PEPPER hashes every API key — if you change it later, all existing API keys become invalid and every teammate must re-register.

   sed -i '' "s|^RELAY_PEPPER=.*|RELAY_PEPPER=$(openssl rand -hex 32)|" .env
   sed -i '' "s|^RELAY_ADMIN_TOKEN=.*|RELAY_ADMIN_TOKEN=$(openssl rand -hex 16)|" .env
   sed -i '' "s|^RELAY_ENCRYPTION_KEY=.*|RELAY_ENCRYPTION_KEY=$(openssl rand -hex 32)|" .env
   

   On Linux, drop the '' after -i:

   sed -i "s|^RELAY_PEPPER=.*|RELAY_PEPPER=$(openssl rand -hex 32)|" .env
   sed -i "s|^RELAY_ADMIN_TOKEN=.*|RELAY_ADMIN_TOKEN=$(openssl rand -hex 16)|" .env
   sed -i "s|^RELAY_ENCRYPTION_KEY=.*|RELAY_ENCRYPTION_KEY=$(openssl rand -hex 32)|" .env
   

   Stash the resulting RELAY_ADMIN_TOKEN value somewhere secure (see Share the admin token below) — your teammates need it to register.

3. Start the relay

   docker compose --profile selfhost up -d
   

   This brings up two containers:

   Container	Image	Port	Role
   agentrelay-postgres	postgres:16-alpine	5433 (host)	Persistent storage
   agentrelay-relay	Built from relay/Dockerfile	8080 (host)	Relay service

   The relay waits for Postgres to pass its health check, then runs Drizzle migrations on boot (idempotent — safe to re-run). Both containers restart unless-stopped, so they survive host reboots.

4. Verify the relay is healthy

   curl http://localhost:8080/healthz
   

   You should receive:

   {"status":"ok"}
   

   If the health check fails, check container logs:

   docker compose logs relay --tail 50
   

   Common causes: missing or empty secrets (the relay’s zod config validation rejects empty values with a descriptive error at startup), or Postgres not yet healthy.

---

Expose to the internet

Teammates on other laptops need to reach the relay over HTTPS. Point a reverse proxy at port 8080 on the host running Docker, then set RELAY_PUBLIC_URL in .env to the public URL and restart:

# Edit .env: set RELAY_PUBLIC_URL=https://relay.acme.dev
docker compose --profile selfhost up -d   # picks up the new env value

nginx

server {
    listen 443 ssl;
    server_name relay.acme.dev;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Caddy

relay.acme.dev {
    reverse_proxy localhost:8080
}

Caddy handles TLS automatically via Let’s Encrypt.

Cloudflare Tunnel

cloudflared tunnel --url http://localhost:8080

For a persistent tunnel, configure it via the Cloudflare dashboard and set the resulting *.trycloudflare.com (or custom) URL as RELAY_PUBLIC_URL.

---

Share the admin token

RELAY_ADMIN_TOKEN is what each teammate passes to agentrelay register to create their identity on the relay. Treat it like a password.

• Store it in 1Password, your team’s password manager, or another secrets vault.
• DM it to each teammate over a secure channel (not Slack public channels or email).
• Do not commit .env to version control.

---

Recommended hosting

For teams that prefer not to manage their own Linux box, any container-capable PaaS works. The relay is a single stateless container; Postgres can be the managed database your host offers.

Fly.io

256 MB shared-cpu VM + Fly Postgres. Approximately $5–10/month for a small team. Good free tier for testing.

Render

Web Service + managed Postgres. Approximately $7–15/month. Simple deploy from a Docker image.

Railway

Docker deploy + Railway Postgres. Approximately $5–12/month depending on usage. Good developer experience.

Self-hosted VPS

Any VPS (DigitalOcean, Hetzner, Linode) with Docker installed. Full control, lowest cost at scale.

For a small engineering team (under 50 developers, under 10k handoffs per day), the smallest paid tier on any of these platforms is sufficient. The relay’s resource ceiling in v0.1 is the notification dispatcher’s webhook throughput, not compute or memory.

---

What’s running

After a successful docker compose --profile selfhost up -d, two containers are active:

• agentrelay-postgres — Postgres 16 on host port 5433. Data is persisted in the postgres-data Docker volume. Credentials are set by POSTGRES_PASSWORD in .env.
• agentrelay-relay — The Hono relay service on host port 8080. Built from relay/Dockerfile (multi-stage: pnpm build in the builder stage, slim runtime image). Connects to Postgres over the internal Docker network.

Both containers have restart: unless-stopped, so they come back automatically after a host reboot or a Docker daemon restart.

---

Next step

Once the relay is running and reachable, share the relay URL and admin token with your teammates so they can complete developer onboarding.