Bootstrap

Bootstrap is the one-time pairing step that links your machine to a gateway. After it succeeds, connect and ssh work with no extra flags — everything they need is persisted under ~/.burrowee/cli/.

1. Get a blob and PIN from the gateway

The pairing material comes from the gateway's local console — the loopback web console running on the gateway host (not the cloud console). The gateway operator opens the Clients tab there and clicks Generate pairing (in the Pair a client panel), which mints two values:

• a blob — a self-contained, PIN-sealed payload. It is useless without the PIN, so it's safe to send over chat or email;
• a short PIN that unseals it.

If you run the gateway yourself, mint the pair on the gateway machine and carry both values over to the machine you're pairing.

2. Run bootstrap

burrowee bootstrap <blob> <pin>

Two optional flags:

Flag	Meaning
--label <name>	A label for this client, shown to the gateway operator in their console next to the pending request. Defaults to your hostname — set it to something the operator will recognize, e.g. --label "alice-laptop".
--home <dir>	Write config under <dir> instead of ~/.burrowee/cli (useful for testing or keeping multiple pairings side by side).

The command decrypts the blob with the PIN (a wrong PIN fails immediately with decrypt blob (wrong PIN?)), generates your client identity if you don't have one yet, dials the relay, and sends the pairing request. Then it blocks:

waiting for approval in the gateway console…

3. Approve on the gateway

While bootstrap is waiting, your request appears in the gateway's local console under Clients → Pending, labelled with your --label. The gateway operator clicks Approve — you have about 6 minutes before the request times out. If it expires or is denied, bootstrap exits with an error; just mint a fresh blob + PIN and run it again.

On approval, the gateway sends back your durable client credentials, bootstrap prints paired ✓, and persists:

~/.burrowee/cli/
  config.json   the gateway×relay matrix: this gateway, its system relay (with any
                published LAN origins), and the default edge
  client.key    your client's own identity key (mode 0600) — generated once,
                shared across every gateway you pair with

The blob's one-time bootstrap secret is now spent; all future connections authenticate with the durable credentials stored in config.json.

Pairing with more than one gateway

Bootstrap is additive: running it again with a blob from a different gateway adds that gateway (and its relay) alongside any you already have, rather than replacing your config. Your existing pairings are untouched, and the very first bootstrap you ever ran is the one that sets your global default gateway and relay. See Relays for switching between gateways and relays.

Adding more relays later

Bootstrap seeds your config with the gateway's system relay. If the gateway later becomes reachable through additional relays — for example a self-hosted edge relay — you don't re-pair. The console mints a smaller relay-add blob + PIN, and you run:

burrowee relays pair <blob> <pin>

This upserts the new relay entries into config.json (re-adding the same relay is harmless — the entry is just updated) and prints one relay paired: … line per relay. Relay-add blobs carry an expiry; a stale one fails with relay-add blob expired — mint a fresh one in the console. And the two blob kinds are mutually exclusive: feeding a full bootstrap blob to relays pair (or vice versa) is rejected with a hint pointing you at the right command.

See Relays for listing relays and switching the default.