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.

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.

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.