LAN & frontier modes

An edge serves in one of two mutually exclusive modes. You choose at mint time — the Local LAN relay checkbox on Add edge relay — and the choice reaches the edge inside the console-signed manifest as its lan_mode flag. The edge never decides its own mode; it serves what the console signed.

	Frontier (checkbox off)	LAN (checkbox on)
For	A public host serving your custom domains	Fast hops inside your local network
Listener	TLS on :443, certificates pushed by the console	Plain WebSocket on 127.0.0.1:9448, loopback only
nginx	Not used	Fronts the LAN port: :8448 TLS → 127.0.0.1:9448
TLS	Terminates inside the edge (SNI certs per domain)	Terminates in nginx with a pinned self-signed cert
:443	Owned by the edge	Never bound

Frontier mode

The edge binds the TLS listener on :443 and serves your attached custom domains directly. Certificates are issued by the console and pushed to the edge over the carrier — there is nothing to install on the machine, and no nginx. Clients and browsers connect to edge.example.com:443 like any other TLS endpoint.

LAN mode

The edge binds a plain WebSocket listener on loopback (127.0.0.1:9448 by default) and lets nginx own the externally visible port. The nginx front listens on :8448, terminates TLS with a locally generated 10-year self-signed certificate, and proxies to the loopback listener. The edge never binds :443 in LAN mode.

Self-signed is not a compromise here: clients don't trust the cert through a CA — they pin its SHA-256 fingerprint. The edge reports the fingerprint to the console with its LAN endpoints, and gateways receive it automatically; CLI clients get it inside the relay blob they paste. A connection only succeeds against the exact certificate the edge minted.

A LAN edge starts the nginx front itself on run (best-effort — a user-mode service can't reload a root-owned nginx, so a failure prints the manual sudo burrowee edge nginx command and the run continues).

On the console's Edge Relays page a LAN edge carries a LAN badge, lists the LAN endpoints it self-reported, and offers Update endpoints when new addresses appear — publishing pushes them to your gateways. Use Add to gateway on the relay row to get the blob a gateway needs to start dialing this edge.

A fresh edge: the fallback

Right after approval, an edge has no manifest yet — the signed config arrives over the carrier shortly after run connects. Until it does, the mode is unknown: run polls for the manifest for about 20 seconds, then falls back to frontier (the :443 listener) if none arrived. The log says which happened:

edge: no manifest applied yet — polling for console-signed config
edge: manifest applied after 1 tick(s) — serving lan mode

or, on a timeout:

edge: no manifest within the poll window — falling back to frontier (:443)

Once the manifest lands it is cached on disk, so every later start resolves the mode instantly. If a LAN edge ever logs the frontier fallback, check that it can reach the console (burrowee edge doctor) and restart it once the carrier is up.

Serve settings

Listener addresses come from ~/.burrowee/edge/config (KEY=VALUE lines), overridable per-run by flags. Precedence: flag > config file > built-in default. No environment variables are read.

Key	Flag on run	Default	Meaning
tls_listen	--tls-listen	:443	The frontier TLS listener. off disables it (a LAN-only edge).
lan_listen	--lan-listen	127.0.0.1:9448	The LAN plain-WS listener. Loopback by default — nginx fronts it.
lan_advertise_port	--lan-advertise-port	the listener port	The external port the edge advertises in its self-reports — the nginx front port, since that is what peers actually dial. The nginx subcommand sets this for you.
lan_cert	—	unset	Where the LAN certificate lives. The nginx subcommand sets this for you.
lan_allow_ips	—	unset	Comma-separated allowlist of client IPs for the LAN listener; unset means no restriction.
quic_addr	--quic-addr	off	An optional QUIC (UDP) listener. Not fronted by nginx.

You normally never edit this file: bootstrap and the nginx subcommand maintain it. The exception is rebinding ports when the defaults clash with something else on the machine — see the port preflight.