Appearance
Gateway
The gateway is the Burrowee component you run on the machine you want to reach. It sits next to your services — the dev server on port 3000, the SSH daemon, the database — dials out to a relay over WSS, and stays connected. Nothing ever connects inbound to your machine; when a request arrives through the relay, the gateway decrypts it, talks to the local service, and encrypts the reply.
Three things make the gateway the centre of gravity in Burrowee:
- It is the sole verifier. Every session token, every share link, every paired CLI client is checked by the gateway itself, against keys generated on your machine that never left it. Relays forward ciphertext they cannot read, and the cloud console signs credentials but is not on the data path.
- It owns its targets and sessions locally. The list of what is exposed (targets) and who may reach it (sessions, paired clients) lives in the gateway's own store on the machine — under the system config and data roots,
/usr/local/etc/burrowee/gatewayand/usr/local/var/burrowee/gateway(see Service & restart). The cloud console only mirrors that state and remote-controls it through the relay — if the console is unreachable, your gateway keeps serving. - It carries its own management UI. A local web console on
http://127.0.0.1:16518(loopback only, gated by a bearer token) is always available on the gateway machine itself.
If you haven't installed the gateway yet, start with the install guide, then come back here for pairing.
Under the hood: four binaries, one dispatcher word
burrowee gateway is a single dispatcher word, but the install bundle carries four gateway-specific binaries (plus the burrowee dispatcher itself and burrowee-register — six in all):
burrowee-gateway— the daemon. It only serves (run/serve, or a bare flags-only invocation — the form the service units use), and answersversion/--help.burrowee-gateway-cli— every operator verb (bootstrap,migrate,status,doctor,target,relays,service,push,updater,restart,uninstall,console,fingerprint, …).burrowee-gateway-console— the local console web server, run as a child process of the daemon.burrowee-gateway-updater— a standalone agent that applies updates the console pushes; it runs as its own managed-service unit alongside the daemon (see Service & restart).
You never pick between these yourself — burrowee gateway <verb> always resolves to the right one: run, serve, and version go to the daemon; every other verb routes to burrowee-gateway-cli (update goes through the cli to the updater). Calling the raw binaries directly works too, but only the daemon's own subset (run/serve, version) is implemented on burrowee-gateway itself — everything else needs burrowee-gateway-cli (or, easier, just go through the dispatcher).
Commands at a glance
| Command | What it does |
|---|---|
burrowee gateway run | Run the gateway daemon in the foreground (the managed service runs this for you; serve is a synonym) |
burrowee gateway bootstrap <blob> <pin> | First-time setup: persist relays + enroll, then set up + start the service and open the console (--blob-file/--pin-file read the secrets from files instead of argv) |
burrowee gateway migrate --from <dir> | One-way adopt a pre-0.2.0 per-user tree (~/.burrowee/gateway) into the system roots, then retire it |
burrowee gateway relays list | List this gateway's configured relays |
burrowee gateway relays local <id|host:port> on|off | Mark a relay as on the same host, so the gateway dials it over loopback first |
burrowee gateway relays pair <blob> <pin> | Pair a console-minted relay into an already-enrolled gateway |
burrowee gateway relays resync [<ws_url>] | Re-check relay addresses with the console |
burrowee gateway console open | Check the local console is up and open it in the browser |
burrowee gateway console password | Set or change the console password that gates remote console access (see Local console) |
burrowee gateway console-url | Print the signed-in console URL without opening a browser |
burrowee gateway console-rotate-token | Rotate the console bearer token, signing out every session |
burrowee gateway target list|add|remove|address|mode | Manage targets — what the gateway exposes |
burrowee gateway target console enable|disable | Expose (or stop exposing) the local console itself through a relay, token-gated |
burrowee gateway register info [--json] | Print the resolved register socket, whether it dials, and the declared targets |
burrowee gateway fingerprint … | The opt-in uTLS browser disguise on the relay dial (path/list/validate/enable/disable) |
burrowee gateway status | Read-only diagnosis of identity, service, relay, and console — never remediates |
burrowee gateway doctor [--fix] [--yes] | The same diagnosis plus repairs; offers to re-check as root when it can't read something |
burrowee gateway service install|status | Manage the system launchd/systemd units |
burrowee gateway restart | Restart the managed service |
burrowee gateway uninstall [--purge] | Remove the units; back up (or --purge) config + state |
burrowee gateway push allow|stop|status | Allow or stop console-initiated push-updates for this gateway (see Service & restart) |
burrowee gateway update [--dry] [--auto] [--force] [--version <stamp>] | Update to the latest (or a pinned) release — shorthand for updater update |
burrowee gateway updater … | The full update lifecycle: update/upgrade/reinstall/restart/status/doctor/version |
burrowee gateway version | Print the version |
burrowee gateway docs | Print the whole command surface as markdown |
Every level of the tree answers -h/--help with its own page (there is no help verb), and burrowee gateway docs prints the entire reference. Flags on the daemon (run/serve) path: --config-dir <dir> and --data-dir <dir> (defaults /usr/local/etc/burrowee/gateway and /usr/local/var/burrowee/gateway; --home is a deprecated alias), --console off, --no-open.
Register a service directly (bypassing target add) with burrowee register --name <svc> --target <host:port> — see Targets.
In this section
- Pairing — claim a gateway into your account with a setup blob and PIN.
- Targets — define what the gateway exposes, and how the two handler types work.
- Local console — a full tour of the gateway's built-in web UI.
- Sessions — full and page-share sessions: mint, extend, revoke, share.
- Service & restart — running the gateway as a managed service, config, updates, logs, uninstall.