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 Client pairings → New client pairing there, which mints two values:

• a blob — a self-contained, PIN-sealed payload carrying the gateway's public key, the relay URL, and a one-time bootstrap PSK. 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 keypair if you don't have one yet, dials the relay with the bootstrap PSK, 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 Client pairings, 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 per-client service PSK (sealed to your client key and signed by the gateway), bootstrap prints paired ✓, and persists:

~/.burrowee/cli/
  config.json   gateway ID, relay list (with any published LAN origins), default relay
  gw.pub        the gateway's Ed25519 public key (hex)
  psk.bin       your per-client service PSK (raw bytes, mode 0600)

The one-time bootstrap PSK from the blob is now spent; all future connections authenticate with the service PSK in psk.bin.

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.