Edge relays

An edge relay is a relay you run yourself, with burrowee-edge. It does the same job as Burrowee's hosted relays — blind forwarding between your gateways and your clients, web-viewer ingress on :443, optional QUIC — but it runs on your own machine and carries only your own account's gateways.

Three properties define it:

• Self-hosted. You run the binary — on a VPS, a home server, a NAS, anything that runs macOS or Linux. You own the machine and the ports.
• Single-tenant and account-bound. The edge serves the gateways of the account that minted it, and nothing else. Its configuration arrives as a manifest signed by the console; it cannot widen its own scope.
• Hard-bound to the console. The console identity is compiled into the binary. There is no flag to point an edge at a different control plane — if a setup blob doesn't come from console.burrowee.com, the edge won't enroll with it.

When to use one

You don't need an edge relay to use Burrowee — the hosted relays cover the normal path. Run one when:

• You want traffic on your own domain and your own machine. A frontier edge sits on a public host (say edge.example.com), terminates TLS with certificates the console issues and pushes to it, and serves your custom domains end to end through infrastructure you control.
• You want fast hops inside your LAN. A LAN edge runs on your local network and serves clients there directly — a gateway and a CLI on the same network connect through it without ever leaving the building.

The two roles are the LAN and frontier modes; you pick when you mint the relay in the console.

How it fits together

The edge keeps a persistent outbound connection (the carrier) to the console. Everything flows through that: enrollment approval, the signed manifest that tells it what to serve, certificates for your custom domains, and the routes that map a hostname to a gateway. The console's Edge relays page is where you mint, approve, monitor, and remove edges — including, on a Team plan, minting or moving an edge under a team so it counts against the team's quota instead of your personal cap (see Edge relays).

Data through the edge stays end-to-end encrypted between the client and the gateway — the edge forwards bytes it cannot read, exactly like a hosted relay. A browser or scanner that hits the edge without a matching route or domain never sees an error either — it gets a generic placeholder page (see Custom domains → Unmatched hosts).

The burrowee-edge command

Install it with the one-line installer. It lays down three edge binaries — the lean serving daemon burrowee-edge (run, version), the setup CLI burrowee-edge-cli (everything else: bootstrap, migrate, nginx, mode, proxy-protocol, lan-listen, cert, doctor, service, status, config, push, bridge, uninstall), and the update agent burrowee-edge-updater (update, upgrade, reinstall). You don't need to remember which is which — burrowee edge <verb> routes to whichever binary owns that verb, and every level answers --help with its own page (burrowee edge <command> --help).

Command	What it does
bootstrap <blob> <pin>	Enroll this machine against the console, choose a serve mode (--mode frontier|lan), and offer to install the service. --blob-file/--pin-file read the secrets from files instead of argv. See Setup.
run	Serve in the foreground.
migrate [--from <dir>] [--force]	Adopt a pre-0.2.0 per-user edge tree into the system install (copies, never moves). Normally run for you by the install migrations — see Install edge.
mode <frontier|lan>	Switch serve mode after setup, reconciling the nginx front to match. See LAN & frontier modes.
doctor [--fix] [--yes] [--no-external]	Health checks: identity, fd limit, tls_listen, the public host front or the LAN front, console reachability, host cert. Exit 0 all green, 3 when any row is ✗. --fix remediates. See Operations.
status	The read-only alias of doctor — the same report, always exit 0.
service install|status|restart	Install, inspect, or restart the system-level service units for the edge and its updater. See Operations.
restart	Alias for service restart.
nginx install|uninstall|apply|reconcile	Stand up the public SNI front or the LAN front, tear one down, or reconcile whichever front the current mode needs. See nginx front.
proxy-protocol on|off|status	Whether the nginx front sends the PROXY header (default: derived from tls_listen). See nginx front.
lan-listen on|off|status	The loopback dial-in listener a co-located gateway dials directly. See LAN & frontier modes.
cert status|issue	Inspect or issue this edge's own Let's Encrypt certificate for a frontier host. See Custom domains.
config get|set	Read or write a key in the edge config file (buffer windows, listener addresses, …). See Operations.
push allow|stop|status	Opt in or out of console-initiated updates. See Operations.
bridge key|subscribe|approve|list|remove|raw-port	Chain this edge to another edge. See Edge-to-edge bridging.
uninstall [--purge]	Remove the service and back up (or --purge) config and state.
update	Stage the currently released edge version (takes effect on the next restart). Flags — --dry, --auto, --force, --version — live on updater update. See Operations.
reinstall	Reinstall the current version offline: every binary re-laid, config kept.
updater <command>	Forward any command to the co-located update agent. See Operations.
version	Print the version block (edge, cli, and updater).
docs	Print the full CLI reference as markdown.

In this guide

• Setup — mint, bootstrap, approve.
• LAN & frontier modes — the two serving topologies and how the edge picks one.
• nginx front — the nginx subcommand, the SNI front, the pinned LAN certificate.
• Custom domains — attach app.example.com to a target through your edge.
• Edge-to-edge bridging — chain edges together for multi-hop routing.
• Operations — doctor, status, service, push updates, logs, uninstall.