Appearance
Commands
Complete command reference for the four binaries: the burrowee dispatcher, burrowee-cli, burrowee-gateway, and burrowee-edge. Everything below is current as of the shipping builds; run any binary with --help to see the same surface from the binary itself.
burrowee — the dispatcher
The bare burrowee command is a zero-logic dispatcher: a reserved first word maps to a component binary, which is exec'd in place (a true process replacement — the component's exit code is your exit code). Anything that isn't a reserved word falls through to burrowee-cli untouched, which is why burrowee connect --svc 22 and burrowee cli connect --svc 22 are the same command.
burrowee <component> [args] run a component
burrowee <anything-else> [args] runs burrowee-cli <anything-else> …| Component word | Dispatches to | Role |
|---|---|---|
cli | burrowee-cli | client tunnels (connect, ssh, daemon, relays, relays pair) |
gateway | burrowee-gateway | the home gateway daemon + local console |
relay | burrowee-relay | the system relay server |
edge | burrowee-edge | self-hosted edge relay |
console | burrowee-console | the cloud control plane server |
register | burrowee-register | register a local service with the gateway |
The dispatcher handles two things itself: --help / -h / help (prints the component table) and --version (prints the dispatcher's own version). Everything else is forwarded. Target binaries are looked up on PATH, then in /usr/local/bin, /opt/homebrew/bin, and ~/.local/bin — so a service host with a thin PATH still resolves them.
Exit codes:
| Code | Meaning |
|---|---|
| (component's own) | The dispatched component ran; its exit code passes through unchanged |
0 | A dispatcher intrinsic (--help, --version) was handled |
126 | The target binary was found but could not be exec'd |
127 | The target component is not installed on this machine (the error lists what is installed) |
burrowee-cli
The client and local-forwarder bridge: it listens on a local TCP port, opens a carrier to the relay, completes the per-service end-to-end encryption with the gateway, and pipes your local connection through.
| Command | What it does |
|---|---|
bootstrap <blob> <pin> | First-time setup: pair with a gateway. Writes ~/.burrowee/cli/ — see Pairing and Bootstrap |
relays pair <blob> <pin> | Pair a console-minted relay into an already-enrolled client. |
connect --svc <s> [flags] | Forward a local TCP port through the relay to a service |
ssh --svc <s> [ssh args…] | Connect on an ephemeral local port, then exec the system ssh against it |
daemon [flags] | Run the long-running transport daemon (unix only) |
relays <list|use|priority|pair|probe> | List configured relays, switch the default (use), set priority, pair a console-minted relay, or probe relays |
doctor [--fix] [--yes] | Run read-only health checks (--fix: thin remediations) |
service <install|status> | Install or inspect the managed daemon service (launchd / systemd user unit) |
restart | Restart the managed daemon service |
uninstall [--purge] | Back up state + clear the socket (--purge deletes all) |
status | Summarize the service, daemon, and version state. |
update [--dry] [--force] | Update to the latest release (--dry report only; --force reinstall even if current). |
version | Print the version |
connect / ssh flags
connect and ssh share one flag set. Only --svc is always required — every other connection flag defaults from the config written by bootstrap; a flag given explicitly overrides its config value individually, and when all four identity flags (--relay, --gw, --gw-pub, --psk) are passed, the config file is not read at all.
| Flag | Default | Meaning |
|---|---|---|
--svc <name> | (required) | Service name, e.g. "22" |
--local <addr> | 127.0.0.1:0 | Local listen address (ssh always forces an ephemeral loopback port) |
--relay <url> | from config | Relay WebSocket URL (ws://… or wss://…) |
--relay-quic <addr> | from config | Relay QUIC address (host:port); empty disables QUIC |
--gw <id> | from config | Gateway id |
--gw-pub <file> | from config | Path to the gateway ed25519 public key (hex file) |
--psk <file> | from config | Path to the pairing PSK file |
--config <path> | ~/.burrowee/cli/config.json | Config path |
With ssh, everything after the flags is passed to the system ssh verbatim:
sh
burrowee ssh --svc 22 -l alice -i ~/.ssh/id_ed25519Other flags
| Command | Flag | Default | Meaning |
|---|---|---|---|
bootstrap | --label <s> | host-derived | A label for this client (shown to the gateway operator) |
bootstrap | --home <dir> | ~/.burrowee/cli | Component dir to write config under |
daemon | --config <path> | ~/.burrowee/cli/config.json | Config path |
daemon | --socket <path> | ~/.burrowee/cli/sockets/transport.sock | Transport IPC socket path (overflow fallback: $XDG_RUNTIME_DIR/burrowee/transport.sock, OS temp dir when XDG_RUNTIME_DIR is unset) |
relays | --socket <path> | as above | Transport IPC socket path |
relays | --config <path> | ~/.burrowee/cli/config.json | Config path |
doctor | --config <path> | ~/.burrowee/cli/config.json | Config path |
doctor | --fix | off | Apply thin remediations (bootstrap guidance; restart a down daemon) |
doctor | --yes | off | Assume yes for any --fix prompt |
uninstall | --purge | off | Delete the cli home and all prior backups (default: back up) |
uninstall | --home <dir> | ~/.burrowee/cli | CLI state dir to uninstall |
uninstall | --config <path> | — | Config path; its parent dir is used as the home (overrides --home) |
relays use works even when the daemon is down
relays use <id> writes the new default to config.json first, then attempts IPC; if the daemon is down it prints a warning and exits 0 — the preference is still persisted. Only relays probe needs a running daemon; relays list reads config.json directly. relays use/priority/pair write config then best-effort poke the daemon (they exit 0 even if it is down).
Exit codes: 0 success, 1 runtime failure, 2 usage error (unknown command, missing arguments).
burrowee-gateway
The home gateway (NAT tunnel endpoint): it self-generates its identity, dials every configured relay, and dispatches opaque streams by service name. Running it with no command serves the daemon.
| Command | What it does |
|---|---|
| (none) | Serve the gateway daemon |
bootstrap <blob> <pin> | First-time setup: persist relays + enroll, then set up + start the service and open the console |
relays pair <blob> <pin> | Pair a console-minted relay into an already-enrolled gateway. |
console | Open the local console in the browser |
status | Show service + live gateway status |
doctor [--fix] [--yes] | Diagnose identity/service/relay/console; --fix the service |
service install|status | Manage the launchd/systemd unit |
uninstall [--purge] | Remove the service; back up (or --purge) config+state |
restart | Restart the managed service |
update [--dry] [--force] | Update to the latest release (--dry checks only; --force re-installs when already current). |
version | Print the version |
Flags
| Command | Flag | Default | Meaning |
|---|---|---|---|
| (serve) | --home <dir> | ~/.burrowee/gateway | Component dir |
| (serve) | --console on|off | on | Local console at 127.0.0.1:16518 |
| (serve) | --no-open | off | Do not open the local console in a browser (the installed service unit always runs with --no-open) |
bootstrap | --home <dir> | ~/.burrowee/gateway | Component dir |
doctor | --fix | off | Remediate fixable checks (service not running) |
doctor | --yes | off | Assume yes to all remediation prompts |
uninstall | --purge | off | Delete config+state instead of backing it up |
update | --dry | off | Check for a newer version + changelog without installing |
update | --force | off | Re-install even when already on the latest version |
Exit codes: 0 success, 1 runtime failure, 2 usage error.
burrowee-edge
The self-hosted edge relay, hard-bound to the Burrowee console (the console identity is compiled in — there is no override).
| Command | What it does |
|---|---|
bootstrap <blob> <pin> | Enroll this edge against the console, then set up the nginx LAN front automatically (best-effort) |
run | Serve the relay (foreground) |
doctor [--fix] [--yes] | Check console reachability + config; --fix remediates an unhealthy nginx LAN front |
status | Show enrollment + serve settings (owner tenant, authorized gateways, served domains, config age) |
service install|status | Manage the launchd/systemd unit |
restart | Restart the installed edge service |
nginx [flags] | Generate + apply the nginx front (--print to preview, --rotate-lan-cert to mint a new LAN cert) |
uninstall [--purge] | Remove the service + back up config/state (--purge deletes instead) |
version | Print the version |
Serve settings
run resolves each setting as: serve flag > ~/.burrowee/edge/config (KEY=VALUE file) > built-in default. No environment variables are consulted.
| Flag | Config key | Default | Meaning |
|---|---|---|---|
--home <dir> | — | ~/.burrowee/edge | Component dir |
--tls-listen <addr> | tls_listen | :443 | TLS listen address, or off for a LAN-only edge |
--quic-addr <addr> | quic_addr | off | QUIC listen address |
--lan-listen <addr> | lan_listen | 127.0.0.1:9448 | LAN plain-WS listen address (loopback-only — nginx fronts it on 8448) |
--lan-advertise-port <p> | lan_advertise_port | the lan-listen port | LAN port to advertise in self-reports |
| — | lan_cert | — | LAN cert directory |
| — | lan_allow_ips | — | LAN client IP allowlist |
Other flags
| Command | Flag | Default | Meaning |
|---|---|---|---|
nginx | --home <dir> | ~/.burrowee/edge | Component dir |
nginx | --listen-tls <port> | 443 | External TLS port nginx listens on |
nginx | --listen-lan <port> | 8448 | External LAN TLS port nginx listens on (proxies to the edge lan_listen address) |
nginx | --conf-dir <dir> | auto-detected | nginx conf dir for apply |
nginx | --print | off | Preview the config to stdout; perform no writes or cert generation |
nginx | --rotate-lan-cert | off | Force-regenerate the LAN cert before applying (operator act — re-paste cli blobs after) |
doctor | --fix | off | Remediate an unhealthy nginx LAN front (install → apply → start) |
doctor | --yes | off | Assume yes for all remediation prompts (unattended) |
uninstall | --purge | off | Delete the edge config/state instead of backing it up |
uninstall | --home <dir> | ~/.burrowee/edge | Component dir |
uninstall | --conf-dir <dir> | auto-detected | nginx conf dir (so the snippet is removed too) |
Exit codes: 0 success, 1 runtime failure, 2 usage error (no command, unknown command).