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 under ~/.burrowee/gateway/. 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) 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 (the default when run with no verb), and answers update/version/--help.
• burrowee-gateway-cli — every operator verb (bootstrap, status, doctor, target, relays, service, push, restart, uninstall, console, …).
• 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 (bare invocation), update, and version go to the daemon; every other verb routes to burrowee-gateway-cli. Calling the raw binaries directly works too, but only the daemon's own subset (run, update, 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 the gateway daemon in the foreground (the managed service runs this for you)
burrowee gateway bootstrap <blob> <pin>	First-time setup: persist relays + enroll, then set up + start the service and open the console
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 console	Open the local console in the browser
burrowee gateway target list|add|remove	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 status	Show service + live gateway status
burrowee gateway doctor [--fix] [--yes]	Diagnose identity/service/relay/console; --fix repairs the service
burrowee gateway service install|status	Manage the launchd/systemd unit
burrowee gateway restart	Restart the managed service
burrowee gateway uninstall [--purge]	Remove the service; 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] [--no-restart] [--version <stamp>]	Update to the latest (or a pinned) release
burrowee gateway version	Print the version

Flags on the daemon (serve) path: --home <dir> (default ~/.burrowee/gateway), --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.