LAN & frontier modes

An edge serves in one of two mutually exclusive modes. You pick one at mint time — the Mode dropdown on + Add edge relay (Frontier (public, TLS port 443) / LAN (local network, TLS port 8448), with an optional TLS-port override) — which the console delivers to the edge inside its signed configuration; the bootstrap prompt (see Setup) asks the same question locally. Either way you can switch later without re-minting:

burrowee edge mode frontier   # or: lan

This writes the mode to the edge's local config, reconciles the nginx front to match, and restarts the service. It's a local override that takes effect on the spot — and the console follows: the edge reports its serve mode, so the Edge relays page tracks a mode switched this way. The running edge itself remains authoritative for what it actually serves.

	Frontier	LAN
For	A public host serving your custom domains	Fast hops inside your local network
Listener	TLS on the loopback tls_listen port, certificates pushed by the console	Plain WebSocket on 127.0.0.1:9448, loopback only
nginx	Owns :443: an ssl_preread SNI front proxying the raw TLS bytes to tls_listen	Fronts the LAN port: :8448 TLS → 127.0.0.1:9448
TLS	Terminates inside the edge (SNI certs per domain) — nginx never touches a certificate	Terminates in nginx with a pinned self-signed cert
:443	Owned by nginx (an edge binding it directly — a root or setcap install — is the exception)	Never bound

Frontier mode

A frontier edge serves your attached custom domains on :443. Certificates are issued by the console and pushed to the edge over the carrier, and TLS always terminates inside the edge — but the socket facing the internet is normally not the edge's own: bootstrap (and burrowee edge nginx install) set up an nginx ssl_preread SNI front that owns :443 and proxies the raw TLS bytes to the edge's loopback tls_listen port, never touching a certificate (see nginx front). Binding :443 directly in the edge — a root or setcap install — works too, but it is the exception, not the default topology. Clients and browsers connect to edge.example.com:443 like any other TLS endpoint.

A frontier edge is inherently public-only: the two modes are mutually exclusive at the socket level, so it binds no LAN listener at all — regardless of what lan_listen says — and never self-reports LAN endpoints to the console. There is nothing LAN-related to disable on a frontier edge; lan_listen is a LAN-mode setting.

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 reconciles its nginx front itself at startup (best-effort — a user-mode service can't reload a root-owned nginx, so a failure prints the manual sudo burrowee edge doctor --fix hint 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 the relay row's [≡] menu → Pairing to get the blob a gateway needs to start dialing this edge.

How the mode is resolved on start

Each start of burrowee-edge run picks its serving mode in this order:

1. The local serve_mode config key — written by burrowee edge mode (above) or by the console-apply hook the next time the console pushes a mode change. Checking this first is what lets a local burrowee edge mode switch take effect on the next restart without waiting on the console.
2. The console-signed configuration — read when no local key is set yet.
3. Frontier fallback — see below.

A fresh edge: the fallback

Right after approval, an edge has no manifest yet and no local serve_mode — 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
serve_mode	—	unset	frontier or lan — the local mode override (above). Written by burrowee edge mode, or by the console when it pushes a mode/port change.
tls_listen	--tls-listen	:443	The frontier TLS listener. off disables it entirely (a LAN-only edge). The console can push a new value live — see Operations → keeping the front in sync.
lan_listen	--lan-listen	127.0.0.1:9448	The address the LAN plain-WS listener binds in LAN mode — loopback by default, with nginx fronting it. Ignored in frontier mode (no LAN listener exists there).
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 by hand: burrowee edge mode, bootstrap, and the nginx subcommand maintain the relevant keys for you. Read or write one directly with burrowee edge config get [key] / config set <key> <value> — useful for rebinding a port when the defaults clash with something else on the machine (see the port preflight) or for the buffer profile knobs.