Service & restart

The gateway is meant to run continuously, as a user-level managed service — launchd on macOS, a systemd user unit on Linux. An interactive bootstrap offers to set this up for you; this page covers managing it afterwards.

Install the service

burrowee gateway service install

• macOS — writes a launchd agent plist to ~/Library/LaunchAgents/com.burrowee.gateway.plist (label com.burrowee.gateway) and loads it into your user session. The gateway starts at login, and launchd restarts it if it crashes.
• Linux — writes a systemd user unit to ~/.config/systemd/user/burrowee-gateway.service and runs systemctl --user enable --now burrowee-gateway.service. The unit restarts on failure and starts at login.

On other platforms service install is unsupported — run burrowee-gateway under your own supervisor instead. The service runs the daemon with --no-open, so it never pops a browser on its own.

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.

Installing the service also installs a second, independent unit for the updater (burrowee-gateway-updater, launchd label com.burrowee.gateway.updater / systemd unit burrowee-gateway-updater.service). It's a separate small agent that dials the daemon's socket and applies updates the console pushes; you don't run it directly.

Configuration

The gateway reads one optional file, ~/.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 views:

burrowee gateway status

queries both the service unit 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. It exits non-zero if the daemon is unreachable. This is the first command to reach for when something seems off.

burrowee gateway service status

shows just the raw supervisor view — launchctl list com.burrowee.gateway on macOS, systemctl --user status burrowee-gateway.service on Linux.

For a deeper diagnosis (identity, service, relay reachability, console), there's burrowee gateway doctor, with --fix to repair a broken service unit.

Restart

burrowee gateway restart

restarts the managed service (launchctl kickstart -k / systemctl --user restart under the hood). 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

burrowee gateway update [--dry] [--auto] [--force] [--no-restart] [--version <stamp>] [--console <url>]

Fetches and applies the latest release from the console's catalog (default https://console.burrowee.com, override with --console). --dry only checks whether an update is available; --auto skips the confirmation prompt; --force re-applies even when already current; --no-restart installs the new binary without restarting the service; --version <stamp> pins to (or rolls back to) a specific release instead of "latest". The update is idempotent — it only restarts the service when the installed version actually changes.

The updater agent updates itself the same way (burrowee-gateway-updater update) — invoked for you when the console pushes an updater update; the local console's Services tab has an Update updater button alongside Update gateway/console (see Local console → Services). To inspect the updater agent's own health, burrowee gateway updater status and burrowee gateway updater doctor pass straight through to it (doctor --fix starts the agent if it's down) — the same output the standalone burrowee-gateway-updater status/doctor prints. burrowee gateway status and burrowee gateway doctor both print a versions block comparing the installed binary against the currently-running daemon, flagging drift (e.g. after a binary swap that hasn't restarted yet) with a hint to run burrowee gateway restart.

Whether the console is allowed to trigger an update on this gateway at all is controlled by allow_push_update — see Configuration above.

Logs

• macOS — the launchd unit writes to files under the gateway home:

  tail -f ~/.burrowee/gateway/logs/gateway.log ~/.burrowee/gateway/logs/gateway.err.log

• Linux — the unit logs to the user journal:

  journalctl --user -u burrowee-gateway.service -f

Uninstall

burrowee gateway uninstall

removes the service unit and backs up the gateway home: ~/.burrowee/gateway is renamed to ~/.burrowee/gateway.bak.<timestamp>, and the command prints how to restore it (mv it back, then burrowee gateway service install). Your gateway identity, relays, targets, and sessions are all in that backup, so a restore brings the gateway back exactly as it was.

burrowee gateway uninstall --purge

deletes the gateway home and all previous backups outright. This destroys the gateway's identity keys — 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, every session token, share link, and client pairing this gateway ever issued is permanently dead — they were all bound to the keys you just deleted. Use the default (backup) mode unless you're certain you're done with this gateway.