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 everything the gateway needs to enroll
• 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:

burrowee gateway bootstrap <blob> <pin>

Prefer not to put secrets on a command line? --blob-file <path> and --pin-file <path> read the blob and PIN from files instead of argv.

What bootstrap does, in order:

1. Generates (or loads) the gateway's identity keys under the system config root, /usr/local/etc/burrowee/gateway (--config-dir/--data-dir override the roots; --home is a deprecated alias). If an unmigrated pre-0.2.0 tree exists at ~/.burrowee/gateway, bootstrap refuses to silently mint a fresh identity: pass --migrate-from <dir> to adopt it, or --accept-new-identity to deliberately start fresh.

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

3. Enrolls with the console — binds this machine to the pending gateway you created in step 1, so the console can recognise it 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 system launchd/systemd units (elevating via sudo, so it may prompt for your password), 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 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.

3. Approve the gateway

A newly paired gateway starts awaiting approval: it is enrolled and online, but the relays only serve its traffic once you approve it. Open the gateway's detail page in the cloud console — an Approve banner sits at the top — and approve it; serving starts within about 30 seconds. This is a one-time step per pairing (re-pairing resets it, see below).

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.

Re-pair an enrolled gateway. The gateway detail page's Pairing modal has two tabs — pair and Re-pair. Re-pair mints fresh bootstrap material for a gateway that is already enrolled; run burrowee gateway bootstrap <blob> <pin> with it and the gateway re-enrolls without dropping out of service. A re-pair resets the approval step, so approve the gateway again afterwards.

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:

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 (and takes the same --blob-file/--pin-file flags as bootstrap). Pasting the blob into the local console's Relays → Pair a relay box does the same thing. On a shared or team edge relay, any team member can mint the gateway-add blob — not just the relay's owner.

List what a gateway currently has with burrowee gateway relays list, and re-check the relay addresses against the console with burrowee gateway relays resync — useful after a relay's address changes.

Same-host edge relays. If you're running a self-hosted edge relay on the same machine as the gateway, mark it so the gateway dials it over loopback instead of the public network:

burrowee gateway relays local <id|host:port> on|off

<id|host:port> matches the relay by its WS URL, host:port, or any of its LAN origins (system relays never match — this only applies to edge relays). The change takes effect on the relay's next reconnect. The local console's Relays tab has the same toggle per edge relay.

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.

A different thing: pairing a CLI client

Everything above claims the gateway itself into your account. Letting a CLI client (a laptop running burrowee cli) reach this gateway is a separate, unrelated flow — and it is entirely local: the gateway's own local console mints the client's one-time blob + PIN (the Clients tab's Pair a client), and you approve the incoming request there too. The bootstrap secret never leaves the gateway machine, and the cloud console cannot mint one on your behalf — its Pair this gateway action just opens a guide pointing you at the local console (see the cloud console guide). Full walkthrough: Local console → Clients.