> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fau.run/developer/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a relay

> Deploy the blind rendezvous — DNS, TLS constraints, register flow, and health checks.

**Purpose:** operate a conforming **relay** so nodes can register and agents can resolve
users.

**Audience:** operators / developers deploying `relay/` (Fly or VPS).

## What a relay is

A Go service that:

1. Maps `HMAC(email) → node` (no long-term plaintext email after confirm)
2. Accepts each node's outbound WebSocket tunnel
3. Peeks TLS **SNI** on :443 and forwards **ciphertext** to that tunnel

It must **not** terminate TLS for `*.relay.<domain>` node hostnames.

Deep dive: [Relay](https://docs.fau.run/developer/protocol/relay.md). Frames: [Wire specification](https://docs.fau.run/developer/protocol/spec.md) § Tunnel.

## Critical constraint

DNS for `relay.<domain>` and `*.relay.<domain>` must be **DNS-only** (no TLS-terminating
CDN / Cloudflare orange cloud). Otherwise SNI routing breaks and the threat model
collapses.

## Path A — Public FAU relay

Use `https://relay.fau.run` (already deployed). Nodes:

```bash theme={null}
fedagent relay register --url https://relay.fau.run
```

Agents hard-code or configure that resolve URL. You do not need to run a relay to build
an agent or a personal node against the public instance.

## Path B — Your own domain

### Prerequisites

* Domain you control
* VPS or Fly app with a stable IPv4
* Port **443/tcp** open to the relay process
* Optional: registrar DNS API for ACME (e.g. Porkbun on Fly)

### DNS

| Type | Name | Value |
| - | - | - |
| A | `relay.example.com` | relay IP |
| A | `*.relay.example.com` | relay IP |

### Configure and run

Follow `relay/deploy/README.md` (Docker/VPS) or `relay/deploy/fly.md` (Fly).

Typical flow:

```bash theme={null}
cd relay
cp deploy/relay.example.yaml deploy/relay.yaml
./deploy/gen-secrets.sh   # paste secrets into relay.yaml
# set domain, public_ip, TLS, SMTP
docker compose up -d --build
```

### Verify

```bash theme={null}
curl -sS https://relay.example.com/v1/health
# expect status ok and nodes_connected
curl -sS https://relay.example.com/v1/transparency
```

Then register a node against `https://relay.example.com` and confirm
`/.well-known/fau-node` on its hostname.

**Before inviting strangers:** configure SMTP so registration codes are emailed (otherwise
codes only appear in relay logs).

## Failure modes

| Symptom | Likely cause |
| - | - |
| Resolve OK, TLS wrong cert | CDN terminating `*.relay` |
| Register never emails | SMTP unset — check logs |
| Tunnel flaps | Heartbeat / NAT; duplicate node\_id |
| ACME stuck | DNS API credentials / TXT propagation |

## 3 AM checklist

1. `/v1/health`
2. DNS grey-cloud / not proxied
3. `nodes_connected` vs expected
4. Node-side `relay status`
5. AUTH\_FAIL / rate\_limited in logs

## Next

* Point nodes at your relay: [Run a node](https://docs.fau.run/developer/developers/run-node.md)
* Agent resolve URL must match **your** relay if you are not on `relay.fau.run`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.