Relay and bootstrap node for the Alexandria P2P network: one Rust binary (libp2p 0.57) that helps nodes find each other and get through NAT.
| Function | How |
|---|---|
| NAT traversal | Circuit Relay v2, so mobile and firewalled nodes can accept inbound connections |
| Peer discovery | Private Kademlia DHT (/alexandria/kad/1.0); inbound records are mirrored to disk so they survive restarts |
| Handshake | Identify announces supported protocols and agent version |
| Username receipts | Countersigns first-seen username claims over /alexandria/username-reg/1.0 and serves GET /username/:name |
- Traffic is end-to-end encrypted. The relay can't read, change or censor it.
- It does not run GossipSub, AutoNAT or DCUtR, and holds no special authority except one: it is a trusted first-seen timestamp for username receipts. That trust is bounded. Claims collect receipts from every relay, and Cardano-anchored claims beat any receipt (see username-registry.md).
- Connection, per-IP, circuit and DHT-store limits are capped, and private addresses are kept out of the DHT routing table (limits).
- Operational endpoints need a bearer token and answer
404without it. - Any node can run a relay. The network does not depend on one instance.
With
--network-profilea relay joins the other relays' DHT; with--announceapp nodes discover it. Neither makes it a receipt issuer: that is the profile's issuer list.
cargo run -- --generate-key # print a new hex seed and its PeerId, then exit
cargo run -- --port 4001 # libp2p on TCP + QUIC 4001, HTTP on 9090
curl localhost:9090/health # from another shellTo run a relay of your own (systemd or Docker Compose, TLS, joining the
mesh, Prometheus, the doctor reachability check), follow
docs/self-hosting.md. Release binaries and the
ghcr.io/ifftu-dev/alexandria-relay image are published on every tag.
Every flag also reads the matching RELAY_* variable; --help lists them
all with their defaults. Limits (connections, circuits, DHT records, receipt
and lookup budgets) are in
docs/operations.md.
| Flag / variable | Default | Description |
|---|---|---|
--port / RELAY_PORT |
4001 |
TCP listen port (0 = ephemeral) |
--quic-port / RELAY_QUIC_PORT |
4001 |
QUIC (UDP) listen port |
--quic / RELAY_QUIC |
true |
Run QUIC alongside TCP. false binds no UDP port and advertises no QUIC address; set it where UDP does not reach the relay (Fly.io) |
--tcp-proxy-protocol / RELAY_TCP_PROXY_PROTOCOL |
off |
v2: every inbound TCP connection must open with a PROXY protocol v2 header, whose source address the per-IP limits, Identify and /peers use. Only behind a proxy that sends it to every connection; see client addresses |
--listen-ip4 / RELAY_LISTEN_IP4 |
0.0.0.0 |
IPv4 address the libp2p listeners bind |
--listen-ip6 / RELAY_LISTEN_IP6 |
:: |
IPv6 address the libp2p listeners also bind (best-effort), or off |
--metrics-port / RELAY_METRICS_PORT |
9090 |
HTTP health, metrics and lookup port |
--metrics-bind / RELAY_METRICS_BIND |
0.0.0.0 |
HTTP listen address; 127.0.0.1 keeps it behind a local reverse proxy |
--trusted-proxy-header / RELAY_TRUSTED_PROXY_HEADER |
unset | Read the HTTP client address from this header (Fly-Client-IP when given without a value). Only behind a proxy that overwrites it; see client addresses |
--public-host / RELAY_PUBLIC_HOST |
unset | Public hostname. Advertised (with its resolved IPs) in reservation responses; without it clients reject reservations |
--data-dir / RELAY_DATA_DIR |
./relay-data |
Receipts database and DHT record mirror |
--network-profile / RELAY_NETWORK_PROFILE |
unset | The app's network profile JSON. With it the relay dials the profile's other relays, redials them with backoff and runs Kademlia bootstrap every 5 minutes; without it, it joins no mesh |
--announce / RELAY_ANNOUNCE |
off | Publish this relay under the network's relay-discovery key so app nodes find it. Needs --network-profile. Advertises connectivity only; grants no receipt-issuer trust |
--generate-key |
— | Print a keypair seed and exit |
doctor (subcommand) |
— | Start with this configuration, dial every advertised address, report, exit non-zero if none answers |
probe (subcommand) |
— | Dial a running relay from another machine, check its PeerId and Identify, exit non-zero on failure (usage) |
RELAY_SEED (env only) |
random | 32-byte hex seed for a stable PeerId. Read, then cleared from the environment at startup |
RELAY_ADMIN_TOKEN (env only) |
unset | Bearer token for /peers, /metrics and /health/alerts; at least 16 characters, otherwise those endpoints stay off |
RUST_LOG (env only) |
info |
Log level |
Set RELAY_SEED and RELAY_PUBLIC_HOST in production. Generate an admin
token with openssl rand -base64 32; the monitoring observer needs the same
value.
TCP (Noise + Yamux, optionally reading a PROXY v2 header) and, unless
switched off, QUIC carry Circuit Relay v2, Kademlia and Identify, plus the
username-receipt request/response protocol. An Axum
router, served over HTTP/1.1 by hyper with header and request timeouts,
serves health, metrics and username lookups. The library's start
runs a whole relay from one configuration value; src/main.rs parses flags
and waits for a signal. Modules: config (flags and limits), swarm
(behaviour and event loop), http (routes), store (SQLite receipts and DHT
mirror), username_reg (receipt wire types and claim verification),
profile and mesh (network profile and mesh join), transport
(transport assembly), proxy (PROXY v2 parser and TCP wrapper),
quic_budget (QUIC pending-handshake budget), doctor and probe (the
reachability checks) and addr (address helpers). tests/ drives a relay
over loopback.
Relay PeerIds, hostnames and fallback IPs are owned by the app's network
profile:
src-tauri/resources/networks/preprod.json.
Two Fly.io apps run today: fly.toml (Singapore, sin) and fly-eu.toml
(Frankfurt, fra).
| Doc | Contents |
|---|---|
| docs/self-hosting.md | Running your own relay: systemd, Compose, TLS, mesh, doctor, probe, Prometheus, proxied hosts |
| docs/operations.md | Endpoints, metrics, alerting, limits, client addresses, deployment, rollback, staging rehearsal, adding a region |
| CONTRIBUTING.md | Local checks, CI and releases, commit messages |
| docs/audits/security-2026-08.md | Security audit (2026-08, remediated) |
MIT (Expat), except anything under an ee/ directory, which has its own
license. See LICENSE.md.