Relay Server

Public relay#

A production relay runs at relay.subway.dev:

All agents connect to this relay by default.

Health check#

curl https://relay.subway.dev/v1/health

Returns {"status":"ok"} when healthy.

What the relay does#

1. Listens on port 9000 for QUIC/WebTransport connections
2. Registers names — agents register human-readable names on connect
3. Resolves names — maps name → PeerId for callers
4. Relays traffic — provides circuit relay for NAT traversal
5. Gossipsub mesh — participates in pub/sub topic mesh
6. HTTP bridge — REST endpoints on port 9001 via bridge.relay
7. WebSocket bridge — full-duplex agent sessions on port 9002

Running your own#

subway relay --port 9000

The relay generates identity keys on first start and stores them at .subway/relay-keys. These persist across restarts.

With logging

RUST_LOG=info subway relay --port 9000

Docker

FROM rust:bookworm AS builder
# ... build subway binary
 
FROM debian:bookworm-slim
COPY --from=builder /target/release/subway /usr/local/bin/
ENTRYPOINT ["subway", "relay", "--port", "9000"]

Relay configuration#