Daemon & service

connect and ssh work fine on their own, but each invocation dials a relay and completes the handshake from scratch. The daemon removes that cost: it is a long-running process that holds a warm carrier pool to each configured relay — with idle standbys for isolated services, automatic re-bridging on carrier death or network change (see Connect & SSH), and liveness keepalive — so sessions that go through it start instantly, and the relays/gateways commands have something to talk to. The daemon is unix-only (macOS and Linux).

Running it in the foreground

burrowee daemon

It loads ~/.burrowee/cli/config.json, opens a carrier per relay, and serves requests over a local unix socket, printing a status line like:

burrowee daemon: socket=/home/you/.burrowee/cli/sockets/transport.sock gateways=1 relays=2 edges=2

It runs until interrupted (Ctrl-C). Two flags if you need them:

Flag	Meaning
--config <path>	config.json path (default ~/.burrowee/cli/config.json)
--socket <path>	transport IPC socket path (see below)

Foreground mode is fine for trying things out or running under your own supervisor (tmux, a custom systemd unit). For day-to-day use, install the managed service instead.

The managed service

burrowee service install

On macOS this writes a launchd agent to ~/Library/LaunchAgents/org.burrowee.cli.plist and loads it (RunAtLoad + KeepAlive, so it starts at login and is restarted if it dies). On Linux it writes a systemd user unit to ~/.config/systemd/user/burrowee-cli.service and runs systemctl --user enable --now on it. Either way the unit simply runs <your binary> daemon.

install always (re)writes the unit pointing at the binary you ran it with — so after upgrading the CLI (see Updates), run burrowee service install followed by burrowee restart to pick up the new binary.

Check on it:

burrowee service status

This shells out to launchctl list org.burrowee.cli or systemctl --user status burrowee-cli.service and prints a friendly not loaded / not active line when the unit isn't running.

Restart it:

burrowee restart

(launchctl kickstart -k on macOS, systemctl --user restart on Linux.) If the restart fails, the error message includes the exact manual command to run yourself.

burrowee status

burrowee status

A one-stop health summary: the managed service state, then (by querying the running daemon over its socket) whether the daemon itself is up, your default gateway and its relay count, a per-relay liveness line, and finally the versions block — the installed CLI version, whether the running daemon matches it, and the dispatcher version if you invoked it via burrowee. It exits non-zero when the daemon can't be reached, so it's a good one-liner for a script or a health check.

burrowee doctor

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

Read-only diagnostics, in order: whether you're paired, whether the default relay is reachable (a plain TCP dial, 3s budget), whether the daemon is running (a probe of the transport socket), and the same versions block status prints. Each line is prefixed ok/fail. Pass --fix to apply the thin remediations doctor knows about — today that's restarting a down daemon (via the managed service) after a confirmation prompt; an unpaired client just gets pointed back at burrowee bootstrap. --yes skips the confirmation prompt (for scripting). --config <path> overrides the config.json location, same as elsewhere.

The socket

The daemon listens on a unix socket at ~/.burrowee/cli/sockets/transport.sock. On a pathologically long home path it falls back to $XDG_RUNTIME_DIR/burrowee/transport.sock (the OS temp directory when XDG_RUNTIME_DIR is unset). relays use/rm/gateway default/pair/probe/ping and the equivalent gateways mutators talk to the daemon over this socket (relays list and gateways list read config.json directly and need no daemon); if you moved it with --socket, pass the same --socket to those commands. uninstall removes the socket as part of cleanup.