Relays
Direct first. Relay when we have to. Policy-enforcing always.
Beacons attempts direct peer-to-peer first with STUN-assisted hole punching. When NAT or firewall geometry forbids it, traffic drops to a relay — but the relay enforces fleet policy at the packet level.
STUN · signal · relay
The relay infrastructure is three components:
- beacons-stun — RFC 8489-compliant STUN server. Helps peers discover their public reflexive addresses.
- beacons-signal — Peer rendezvous and ICE candidate exchange.
- beacons-relay — Custom Rust TURN-equivalent. coturn fork was rejected because coturn cannot enforce Beacons policy at the packet level.
What the relay sees
The relay forwards encrypted WireGuard packets (or equivalent for other transports). It does not hold session keys. The relay can:
- Observe which peers are talking to which.
- Drop or rate-limit traffic by fleet policy.
- Refuse to forward cross-fleet traffic even if a peer guesses an overlay IP.
- Emit relay-side audit events for compliance.
It cannot decrypt payloads. Peer-to-peer end-to-end encryption is preserved.
Topology
Regional and federated.
Relays are deployed in each region a coordinator serves. A fleet can pin to a region, allow any region, or specify a preferred ordering. For self-hosted deployments, the relay is a single container or systemd service that joins your coordinator over mTLS.