Relays

A paired client can reach its gateway through more than one relay: the system relay you got at bootstrap, plus any edge relays added later with burrowee relays pair. Your gateway identity (its ID, public key, and your PSK) is the same across all of them — only the path differs. The end-to-end encryption also doesn't change: whichever relay carries your traffic only ever sees sealed bytes.

Listing relays

burrowee relays list

relays list reads config.json directly (no daemon needed) and prints a fixed-width table with columns # * ID HOST URL FINGERPRINT LAN (the * marks the active relay):

# * ID                HOST              URL                          FINGERPRINT  LAN
1 * 1a2b3c4d5e6f7a8b  edge.example.com  wss://edge.example.com/ws    sha256:…     wss://192.168.1.20:9443

Relay IDs are just stable names: the relay seeded at bootstrap is named after your gateway's fingerprint, while relays added via relays pair use their origin (wss://host:port) as the ID.

relays list works with no daemon running, since it reads config.json. The 5-second IPC timeout applies to use/priority/pair/probe, not list.

Switching the default

burrowee relays use <id|host>

The argument accepts a relay id, host, or IP. The default relay is the one connect and ssh dial when you don't pass --relay. relays use does two things: it persists default_relay in config.json, then tells the running daemon to switch live. If the daemon is down, the preference is still saved — you'll see saved default=… to config; daemon not updated and the daemon picks it up next time it starts.

Setting failover priority

burrowee relays priority <id|host> [<id|host> …]

Sets the failover order: the relays you list, in the order you give them, become the preference order the CLI tries when dialing.

Probing connectivity

burrowee relays probe [--json]

Reports the per-relay connection state. It needs a running daemon. Pass --json for machine-readable output.

All relays subcommands accept --socket <path> and --config <path> if you've moved the daemon socket or the config file.

LAN origins and the pinned certificate

An edge relay running on your own network can publish LAN origins — direct local addresses like wss://192.168.1.20:9443 — alongside its internet-facing URL. When a relay entry carries LAN origins, the CLI dials LAN-first: each origin gets a short (~2 s) attempt before falling back to the stored URL. At home that means your traffic never leaves the network; elsewhere the LAN attempts fail fast and the normal path takes over.

A LAN address can't be verified by a public certificate authority — there's no hostname to vouch for. So each LAN-capable relay entry also carries the relay's certificate fingerprint (a SHA-256 hash of its LAN TLS certificate, stored as lan_cert_fp in config.json). When dialing a LAN origin, the CLI accepts the connection only if the certificate it is shown hashes to exactly that fingerprint — in plain words: the config remembers which certificate this relay is supposed to present, and refuses imposters. No fingerprint, no LAN dial; those entries just use the regular URL.

LAN-only relays

Some edge relays are LAN-only ("lan_only": true in the relay entry): they have no internet-facing listener at all, and their stored ws URL serves purely as a stable identity — it is never dialed. The CLI reaches a LAN-only relay exclusively through its LAN origins, which means it simply isn't usable when you're away from that network. That's the point: a LAN-only relay keeps your traffic strictly local.

LAN origins, fingerprints, and the lan_only flag all arrive in pairing and relay-add blobs; the CLI doesn't receive live pushes. If a relay's published endpoints change, run burrowee relays pair with a freshly minted blob (it updates the existing entry in place) — or re-bootstrap.