Burrowee Docs

Appearance

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 tick Local LAN relay, 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.
  • Local LAN relay — tick it if this relay should serve clients on its local network directly. This is what decides the relay's serving mode: ticked means LAN mode, unticked means frontier mode.

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 carries the console's address and public key in its header, and the PIN authenticates them: a tampered 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:

sh
burrowee edge bootstrap <blob> <pin>

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

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

  2. Decodes the blob with the PIN, recovering the console address, the console's public key, and the one-time enroll secret. 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.

  5. Stands up the nginx front, best-effort: it installs nginx if missing (asking first when you're at a terminal), applies the stream config, and starts nginx. Enrollment has already succeeded at this point, so a failure here — nginx not installable, a port conflict, missing root — only prints a warning with the exact manual command to run later (see nginx front). It never fails the bootstrap.

  6. Offers to install the service: Set up and start the burrowee-edge service now? [y/N]. Say yes and the edge runs as a managed launchd/systemd service that survives 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:

sh
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 ​