Quickstart

From a fresh account to an open session in one sitting. You need two machines: the target machine you want to reach (where the gateway runs) and the machine you are reaching it from. They can be the same machine while you try things out.

This walkthrough exposes a web app listening on port 3000 of the target machine, then opens it remotely — first in a browser, then with the CLI.

1. Sign up

Open https://console.burrowee.com and click Sign in with GitHub. That is the whole signup — there is no separate registration form.

2. Wait for approval

Burrowee is in preview, so access is granted manually. After signing in you land on a waiting-list page. Check back later — once your account is approved, the same address takes you straight to the dashboard. No re-login needed.

3. Create a gateway in the console

In the dashboard, go to Gateways → Add a gateway, then under Generate setup give the gateway a hostname (for example home) and click Generate setup.

The console shows a one-time setup blob and a PIN, plus the full command that combines them. Copy them — the PIN is shown once.

4. Install the gateway on the target machine

On the target machine, run:

curl -fsSL --proto '=https' --tlsv1.2 https://release.burrowee.com/gateway/install.sh | sh

The installer detects your OS and architecture, verifies the download's signature, and puts the binaries in the root-owned exec root /usr/local/burrowee/bin. macOS and Linux are supported, on arm64 and amd64.

That directory is not on your PATH, so the install ends with a Next steps block — the export PATH=… line for your shell and the file that makes it permanent. Run the first line now, in this terminal, so the commands below resolve (or type /usr/local/burrowee/bin/burrowee in full). Lost the block? It is reproduced in Put the exec root on PATH.

5. Bootstrap the gateway

Still on the target machine, run the command the console gave you:

burrowee gateway bootstrap <blob> <pin>

This decrypts the blob with the PIN, enrols the gateway with your account, and offers to install it as a managed system service (say yes — it then starts at boot, no login needed). The gateway's local console opens in your browser at http://127.0.0.1:16518.

TIP

The blob is safe to move over any channel — it is useless without the PIN. If the pair is rejected or lost, generate a fresh one from the console. To keep the secrets out of your shell history and process listings, you can pass them as files instead: burrowee gateway bootstrap --blob-file <path> --pin-file <path>.

6. Approve the gateway

A newly paired gateway starts awaiting approval — relays won't serve it until you say so. In console.burrowee.com → Gateways, open the new gateway and click Approve on the banner. It starts serving within about 30 seconds and then shows as online.

7. Add your first target

A target is a local service the gateway exposes. Targets come in two types: web (shown as http(s) — the gateway probes whether the service speaks plain HTTP or HTTPS) and raw (an opaque TCP byte pipe). In the gateway's local console (http://127.0.0.1:16518):

1. Open the Targets pane and click + Add target.
2. Name it app, point it at 127.0.0.1:3000 (or wherever your web app listens), and leave the type on web.
3. Click Add.

(The same thing from the terminal: burrowee gateway target add app 127.0.0.1:3000 --type web.)

8. Open it in a browser

In console.burrowee.com → Gateways, open your gateway, find the app target and mint a session. You get a share URL — open it and you are looking at the web app running on the target machine, end-to-end encrypted the whole way. Sessions have an expiry and can be extended or revoked from the same place.

That is the happy path done. The rest is the CLI route — for SSH and anything else that speaks TCP.

The CLI alternative

9. Install the CLI

On the machine you are connecting from:

curl -fsSL --proto '=https' --tlsv1.2 https://release.burrowee.com/cli/install.sh | sh

The CLI installs per-user, into ~/.local/bin. If that is not already on your PATH, the installer prints the line to add — run it before continuing.

10. Pair it with your gateway

Pairing blobs come from the gateway's local console, not from console.burrowee.com. On the gateway machine, open http://127.0.0.1:16518 → Clients → Pair a client → Generate pairing, and copy the blob + PIN it shows.

On the client machine, run:

burrowee bootstrap <blob> <pin>

(As with the gateway, --blob-file/--pin-file read the secrets from files instead of argv.)

It prints waiting for approval in the gateway console… and blocks. Back in the gateway's local console, a pending request appears under Clients — click Approve. The command unblocks and prints paired ✓. Pairing is one-time; the credentials persist under ~/.burrowee/cli/.

11. Connect

CLI connect reaches raw targets only — an opaque byte pipe; the web target from step 7 is web-path only (see Targets → raw). In the gateway's local console, add a raw twin: + Add target, name it app-tcp, point it at the same 127.0.0.1:3000, type raw (or burrowee gateway target add app-tcp 127.0.0.1:3000 --type raw). Then forward a local port to it:

burrowee connect --svc app-tcp --local 127.0.0.1:3000

Then browse to http://127.0.0.1:3000 on the client machine — you are talking to the app behind the gateway. Only --svc is required; the relay, gateway and keys all default from the pairing config.

For SSH, add a target named ssh pointing at 127.0.0.1:22 (type raw) in the gateway's local console, then:

burrowee ssh --svc ssh -l alice

This forwards an ephemeral port and drops you into ssh through the tunnel — pass the remote username with ssh's own -l flag.

Where next

• What is Burrowee — the components and the trust model.
• Run burrowee --help (or burrowee doctor) on either machine to explore the rest of the CLI.
• burrowee version prints the dispatcher's own version; burrowee <component> version (e.g. burrowee gateway version) prints that component's. burrowee cli version shows a fuller versions table — handy right after install or update to confirm everything landed.