Service & restart

The gateway is meant to run continuously, as a system service running as root — a launchd daemon on macOS, a systemd system unit on Linux. Its state lives under two machine-owned roots:

Root	Path	Holds
Config root	/usr/local/etc/burrowee/gateway	config, identity/ (the gateway's keys), fingerprints.json, console.token
Data root	/usr/local/var/burrowee/gateway	gateway.db, sockets/, logs/

Every relevant verb takes --config-dir/--data-dir to override them (--home remains as a deprecated alias setting both). An interactive bootstrap offers to set the service up for you; this page covers managing it afterwards. Steps that touch system paths elevate via sudo, prompting when needed.

Upgrading from 0.1.x?

Pre-0.2.0 gateways kept everything in a per-user ~/.burrowee/gateway/ and ran as a per-user service. That tree is now a one-way migration source: burrowee gateway migrate --from <dir> (or --migrate-from on bootstrap/run/relays pair) adopts its identity, config, and database into the system roots and then retires it. Migration adopts only from the running user's home; the installer runs it for you on update.

Install the service

burrowee gateway service install

writes both system units, loads them, and starts them:

• macOS — launchd daemon plists in /Library/LaunchDaemons: com.burrowee.gateway.plist and com.burrowee.gateway.updater.plist. The gateway starts at boot, and launchd restarts it if it crashes.
• Linux — systemd system units in /etc/systemd/system: burrowee-gateway.service and burrowee-gateway-updater.service, enabled and started. The units restart on failure and start at boot.

On other platforms service install is unsupported — run burrowee-gateway under your own supervisor instead. The units run the daemon as burrowee-gateway --no-open with explicit --config-dir/--data-dir, so it never pops a browser on its own. If a legacy per-user unit owned by another user is still present, service install refuses to fight it — take it over deliberately with service install --force-service-override.

Already running?

If a service starts while another gateway instance already owns the console port, the new one notices the healthy instance and exits cleanly rather than fighting over the port — so you won't get respawn loops from a double start.

The second unit is the updater (burrowee-gateway-updater) — a separate small agent that dials the daemon's socket and applies updates the console pushes; you don't run it directly, but its lifecycle verbs live under burrowee gateway updater … (see Updates).

Configuration

The gateway reads one optional file, /usr/local/etc/burrowee/gateway/config (key=value per line, # comments; missing file or key falls back to the default):

Key	Default	Meaning
console_port	16518	The loopback port the local console listens on. The host is always 127.0.0.1 — this only changes the port.
allow_push_update	true	Whether the cloud console may push an update to this gateway. Set false to opt this gateway out of console-initiated updates; the console's push button then shows as disabled for it. This never affects the local console's own Update button (see below) — local authority always applies.

Edit the file directly, or use burrowee gateway push allow|stop|status to flip allow_push_update without hand-editing:

burrowee gateway push status   # cloud push-updates: ALLOWED (allow_push_update=true)
burrowee gateway push stop     # opt out — takes effect immediately, no restart needed
burrowee gateway push allow    # opt back in

Check on it

Two complementary verbs share one diagnosis of identity, service, relay, and console:

burrowee gateway status

is strictly read-only — it queries both the service units and the live daemon and prints an aligned summary (service state, daemon up/down, fingerprint, version, carrier connection, target/session counts, uptime, the console URL, and each configured relay with its connection state), but it never remediates anything. A daemon that's down is a reported row, not an error exit. This is the first command to reach for when something seems off.

burrowee gateway doctor [--fix] [--yes]

is the same diagnostic plus repairs: --fix remediates the checks that have one (like a service that isn't running), --yes assumes yes to the prompts. Because the gateway's roots are machine-owned, some inputs aren't readable without root — rather than guessing, both verbs report "cannot determine" for those rows, and doctor on a terminal offers to re-run the check as root.

There's also the raw supervisor view — what launchd/systemd itself says about both units, per platform:

burrowee gateway service status

Restart

burrowee gateway restart

restarts the managed system service. If no managed service is installed it says so and points you at burrowee gateway service install. Targets, sessions, and pairings all persist across restarts.

Updates

The whole update lifecycle lives under one verb tree:

burrowee gateway updater update [--auto] [--dry] [--force] [--version <stamp>]

installs the gateway component at console-current, or a pinned version. --dry resolves and prints the version gap without installing; --auto assumes yes and restarts the freshly-placed binary into service; --force installs even when already current; --version <stamp> pins to (or rolls back to) an exact catalog stamp instead of console-current. Two top-level shorthands save typing: burrowee gateway update ≡ updater update (same flags), and burrowee gateway reinstall ≡ updater reinstall — a re-run of the installer pinned to the running version: repair, not upgrade.

The rest of the tree manages the updater agent itself: updater upgrade replaces the updater binary, updater restart restarts its daemon, and updater status / updater doctor inspect its health (doctor --fix installs and starts the updater daemon if push updates are enabled but it isn't running); updater version prints its version block. The local console's Services tab has the same pair of buttons — Update gateway/console and Update updater (see Local console → Services).

Whether the cloud console is allowed to push an update to this gateway is controlled by allow_push_update — flip it with burrowee gateway push allow|stop|status, see Configuration above.

Logs

• macOS — the launchd unit writes to files under the data root:

  sudo tail -f /usr/local/var/burrowee/gateway/logs/gateway.log /usr/local/var/burrowee/gateway/logs/gateway.err.log

• Linux — the unit logs to the system journal:

  journalctl -u burrowee-gateway.service -f

Every gateway binary timestamps its stderr lines, so logs from the daemon, console, and updater can be ordered against each other.

Uninstall

burrowee gateway uninstall

removes both service units and backs up the gateway's state: the state root is renamed to a timestamped .bak. sibling, and the command prints how to restore it (mv it back, then burrowee gateway service install). A restore brings the gateway back exactly as it was.

burrowee gateway uninstall --purge

deletes the gateway's state and all previous backups outright instead of backing them up. There is no way back except a fresh enrollment with a new setup blob (burrowee gateway bootstrap <blob> <pin>).

--purge is irreversible

After a purge there is no backup to restore from: every session token, share link, and client pairing this gateway issued is permanently dead. Use the default (backup) mode unless you're certain you're done with this gateway.