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
Loopback dial-in	127.0.0.1:9448 — bound in both modes, clamped to loopback; a co-located gateway dials it directly (see below)	Same — in LAN mode it is also the listener nginx fronts
Web protocols	Served (viewer ingress, custom domains)	Locked out entirely — raw forwarding only, but server-first protocols (e.g. VNC) work through the TLS front

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 still public-only toward the network: it never self-reports LAN endpoints to the console, and LAN clients don't discover it. But it does keep one local face: the loopback dial-in listener on 127.0.0.1:9448 is bound in both modes (clamped to loopback, so it is never reachable off-machine) — that is what lets a gateway running on the same host dial the edge directly instead of looping out through the nginx front. See the loopback dial-in listener below.

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 is an L4 stream front: it listens on :8448, terminates TLS with a locally generated 10-year self-signed certificate, and passes the byte stream through to the loopback listener — which is why server-first protocols like VNC work through a LAN edge. The edge never binds :443 in LAN mode, and web protocols (viewer ingress, custom domains) are locked out entirely: a LAN edge raw-forwards only.

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 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.

The loopback dial-in listener

Whichever mode the edge serves, it binds a plain-WS dial-in listener on loopback — 127.0.0.1:9448 by default, and clamped to loopback addresses only. A gateway co-located on the same machine dials it directly, skipping the nginx front. It is managed with its own verb:

burrowee edge lan-listen status          # the configured address and whether it is in effect
burrowee edge lan-listen on [<addr>]     # enable it (default: the current address, else 127.0.0.1:9448) — loopback-only, restarts
burrowee edge lan-listen off             # disable it and restart

lan-listen off is refused in LAN mode — there the listener is the socket nginx fronts, so turning it off would mean serving nothing. And on a frontier edge, don't turn it off while a gateway runs on the same host: that forces the co-located gateway out through the nginx front like a remote client. off is the deliberate choice only for an edge with no co-located gateway.

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 the config file in the edge config root (/usr/local/etc/burrowee/edge/config on a system install; 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 loopback dial-in listener (both modes, above); in LAN mode it is also the socket nginx fronts. off disables it. Managed by burrowee edge lan-listen.
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.
proxy_protocol	—	derived	Whether the fronted listener expects the PROXY header — on when tls_listen is loopback (nginx-fronted), off when public. Managed by burrowee edge proxy-protocol on|off|status (see nginx front).
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, lan-listen, proxy-protocol, 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.