Burrowee Docs

Appearance

Pairing ​

Pairing claims a freshly installed gateway into your Burrowee account. The whole flow is one value pasted across: the cloud console mints a setup blob sealed under a short PIN, and you feed both to the gateway. The gateway's identity keys are generated on the machine itself — the console never sees a private key.

1. Mint the setup in the cloud console ​

Open https://console.burrowee.com and go to Gateways → Generate setup. Give the gateway a hostname — it labels the gateway and must be unique within your account (something like home or office-box).

The console assigns a relay set and returns three copyable values:

  • the full command — burrowee gateway bootstrap <blob> <pin>, ready to paste into a terminal
  • the setup blob — a self-contained, PIN-sealed payload carrying the relay URL(s), the console's public key, and the enroll credential
  • the PIN — shown once; it's the key that opens the blob

The blob plus PIN is everything the gateway needs: no environment variables, no key files to copy around.

2. Bootstrap the gateway ​

On the gateway machine, run the command the console gave you:

sh
burrowee gateway bootstrap <blob> <pin>

What bootstrap does, in order:

  1. Generates (or loads) the gateway's identity — Ed25519 keys under ~/.burrowee/gateway/ (--home <dir> overrides the location).

  2. Decrypts the blob under the PIN and persists the relay(s) into the gateway's local store.

  3. Enrolls with the console — binds the gateway's public key to the pending gateway row you created in step 1, so the console can recognise this machine from now on.

  4. Offers to set up the managed service. On a terminal you'll see:

    Set up and start the burrowee-gateway service now? [Y/n]

    The default is yes — press Enter and bootstrap installs the launchd/systemd unit, starts the gateway, and opens the local console in your browser at http://127.0.0.1:16518. Answer n and it prints where the relays were saved plus the manual hint: run 'burrowee gateway service install' to start the gateway as a managed service.

    When bootstrap runs non-interactively (piped input, no TTY), it still installs and starts the service but never opens a browser.

Once the service is up, the gateway appears as online under Gateways in the cloud console within a few seconds.

Prefer the browser?

You can skip the terminal for the blob entirely: with the gateway already running, paste the blob and PIN into the local console's Relays tab instead. Same effect, no restart needed.

Re-pairing and adding relays ​

Regenerate a setup. A blob + PIN pair is one-time. If you lose the PIN or the blob expires, mint a fresh one in the cloud console — Gateways → Generate setup (or Generate another) — and run burrowee gateway bootstrap again. Re-running bootstrap on an already-paired gateway reuses the existing identity; it does not create a second gateway.

Add a relay to an enrolled gateway. When the console assigns you an additional relay (for example a self-hosted edge relay), it mints a relay-add blob. Ingest it with:

sh
burrowee gateway relays pair <blob> <pin>

relays pair persists the relay and kicks the running service so it picks the new relay up; it skips the first-setup service prompt. Pasting the blob into the local console's Relays → Add an edge relay box does the same thing.

Start over from scratch. To wipe a gateway's identity and state completely, run burrowee gateway uninstall --purge (see Service & restart), then bootstrap with a fresh blob. The console will treat it as a new enrollment.