Setup

Pairing an edge to your account takes three steps: mint it in the console, bootstrap it on the machine, approve it back in the console. Install the binary first — see Install edge.

1. Mint the edge in the console

In console.burrowee.com, open Edge relays → + Add edge relay.

• Hostname — the base hostname the relay will answer on. For a public VPS, the name you'll point DNS at, say relay.example.com. If you pick the LAN mode, this becomes the LAN hostname instead — a .local mDNS name or a LAN IP, and a custom domain stays optional.
• Name (optional) — a display name; defaults to the hostname.
• Mode — Frontier (public, TLS port 443) or LAN (local network, TLS port 8448). This is what decides the relay's serving mode; the optional TLS port field overrides the mode's default port.
• Owner (Team plan) — mint the edge for yourself (Personal, the default) or under one of your teams where you're an owner or manager. A team-owned edge counts against that team's quota instead of your personal edge-relay cap — see Edge relays for the console-side detail.

Click Create. The console shows a one-time setup blob and PIN, plus the full command that combines them. Copy them — they are shown once, and the PIN expires.

TIP

The blob is safe to move over any channel — it is useless without the PIN. The blob is useless without the PIN — a tampered or mismatched blob fails to decrypt rather than enrolling somewhere else.

2. Bootstrap on the machine

On the machine that will run the edge, paste the command the console gave you:

burrowee edge cli bootstrap <blob> <pin>

An optional --mode <frontier|lan> skips the interactive prompt in step 5 below — useful for a scripted install.

Bootstrap does the whole first-time setup in one shot:

1. Generates the edge's identity under ~/.burrowee/edge/identity/. The private key never leaves the machine.

2. Decodes the blob with the PIN. An expired blob is rejected — mint a fresh one.

3. Enrolls against the console and prints the edge's fingerprint:

   enrolled. fingerprint: <fingerprint>
   awaiting approval — approve it in console.burrowee.com → Edge relays (Ctrl-C to stop waiting).

   Note the fingerprint — it is how you recognise this edge in the console.

4. Persists the console identity to ~/.burrowee/edge/console.json, so every later run needs no flags and no environment variables. It also seeds the high-throughput buffer defaults into ~/.burrowee/edge/config if they aren't already there — see Operations → Buffer profile.

5. Prompts for a serve mode — serve mode [frontier|lan] (default frontier): — unless --mode was passed. This is the same choice as the console's Mode dropdown, just made locally too; see LAN & frontier modes for what each does:

   • frontier — asks whether to set up the public host front now: say yes and give it a host FQDN (default: this machine's hostname) and a Cloudflare DNS API token, and it issues this edge's own Let's Encrypt certificate via DNS-01 and installs the SNI nginx front for that FQDN. Decline (or run non-interactively) and nothing is installed yet — set it up later with burrowee edge cert then burrowee edge nginx install.
   • lan — writes serve_mode=lan and reconciles the LAN nginx front on :8448. No certificate, no DNS token needed.

6. Offers to install the service: Set up and start the burrowee-edge service now? [y/N]. Say yes and the edge — plus its updater agent — run as managed launchd/systemd services that survive reboots. Say no (or run non-interactively, where the prompt is skipped) and it prints the manual alternative: burrowee-edge run for the foreground, or burrowee edge service install later.

3. Approve in the console

Back in Edge relays, the new edge appears as pending, with its fingerprint. Confirm the fingerprint matches what bootstrap printed, then click Approve. The terminal session from step 2 unblocks:

approved ✓ — edge relay <fingerprint> is active.

4. Verify

Poll the edge until its configuration has arrived:

burrowee edge status

Right after approval it may say enrolled; no config received yet — the signed manifest arrives over the carrier shortly after the edge connects (make sure it is running). Once it lands, status prints the owner tenant, the served domains, and the authorized gateways — see Operations for the full field list. A final burrowee edge doctor confirms the console link and the nginx front are healthy.

Re-pairing

To start over from scratch: burrowee edge uninstall (or --purge), delete or re-mint the relay in the console, and run the three steps again. The console-side pending row binds to the first fingerprint that enrolls with its blob, so a wiped identity always needs a freshly minted blob.

Where next

• A frontier edge serving your own domain: Custom domains.
• A LAN edge: gateways pick it up via the row's [≡] menu → Pairing on the Edge relays page — see LAN & frontier modes.