Appearance
Config homes & files
Each component keeps all of its state under one fixed directory — its config home — at ~/.burrowee/<component>/. No runtime component reads BURROWEE_* environment variables (the installers do read a few, like BURROWEE_SKIP_PREFLIGHT — see Install); the only way to relocate a home is the component's --home flag (and the CLI's --config, whose parent directory becomes the home). Key material is written 0600 inside 0700 directories.
uninstall (without --purge) moves the home aside to a timestamped backup, <home>.bak.<timestamp>, instead of deleting it.
CLI — ~/.burrowee/cli/
Written by burrowee bootstrap <blob> <pin>.
| File | What it holds |
|---|---|
config.json | The gateway×relay matrix: gateways, relays (kind system|edge, origin, LAN origins, lan_only, pinned LAN-cert fingerprint, defaults), edges (the gateway↔relay membership pairs), bridges, defaults (global default gateway/relay), and an optional pinned transport mode. One client can be paired with several gateways, each reachable over several relays — see burrowee gateways/burrowee relays |
identity/client.key | The client's own identity key (0600) — generated on first use, shared across every gateway you pair with |
identity/device.key | The device's identity key — generated on first burrowee login, used to authorize the device with the console for gated downloads |
Both identity keys live under identity/; an older install that kept them flat in the home root is migrated into identity/ automatically on next use. Everything else a pairing needs lives inline in config.json — there are no sidecar files on a fresh pairing. connect / ssh / daemon default their flags from this config. relays pair, relays use, gateways use, and gateways resync edit config.json in place.
Older installs auto-migrate
A config.json from before the matrix model is migrated in place the first time it's loaded — older sidecar files are folded into the new shape and removed, only after a successful write. Nothing to do on your end; it happens transparently on the next connect, ssh, relays list, etc.
Daemon socket
| Path | Purpose |
|---|---|
~/.burrowee/cli/sockets/transport.sock | The transport daemon's IPC socket — stream consumers receive per-service-sealed streams over it, and every relays/gateways subcommand that mutates state or needs a live answer (use, rm, pair, resync, probe, ping, …) pokes it after editing config.json (the plain list forms read config.json directly and need no daemon). On a pathologically long home path it overflows to $XDG_RUNTIME_DIR/burrowee/transport.sock (OS temp dir when XDG_RUNTIME_DIR is unset). Override with --socket on daemon/relays/gateways. |
Service unit
Installed by burrowee service install; both units run <binary> daemon and restart on failure.
| Platform | Unit | Path |
|---|---|---|
| macOS (launchd agent) | org.burrowee.cli | ~/Library/LaunchAgents/org.burrowee.cli.plist |
| Linux (systemd user unit) | burrowee-cli.service | ~/.config/systemd/user/burrowee-cli.service |
Gateway — ~/.burrowee/gateway/
Created on first serve / bootstrap. The gateway's identity is self-generated — the private keys never leave this directory. The identity keys live under identity/; an older install that kept them in a flat keys/ directory is migrated into identity/ automatically on next start. Since the microkernel split, the home is shared by three binaries: burrowee-gateway (the daemon), burrowee-gateway-console (the local console, supervised as the daemon's child), and burrowee-gateway-updater (the push-update agent).
| File / dir | What it holds |
|---|---|
gateway.db | The gateway store: persisted relays, targets, sessions, pairings — everything the local console shows |
identity/relay_ed.key | The gateway's identity key toward relays (its fingerprint is the gateway's id everywhere) |
identity/cli_ed.key | The gateway's identity key toward paired clients |
identity/session.key | Key material for session tokens (generated on first serve) |
config | Optional KEY=VALUE overrides for the few operator-tunable defaults: console_port=<n> (the loopback console port, default 16518) and allow_push_update=false (opt out of console-driven remote push-updates; default true — see push allow|stop|status) |
logs/gateway.log, logs/gateway.err.log | stdout/stderr of the managed service (macOS launchd; on Linux, logs go to the journal — journalctl --user -u burrowee-gateway.service) |
Sockets
| Path | Purpose |
|---|---|
~/.burrowee/gateway/sockets/register.sock | Where burrowee-register registers a local TCP service with the running gateway. On a pathologically long home path it overflows to the fixed path /usr/local/var/burrowee/gateway/sockets/register.sock. |
~/.burrowee/gateway/sockets/console.sock | Where the separate burrowee-gateway-console process talks to the daemon for operations that need it live. |
Service unit
Installed by burrowee gateway service install (and automatically by bootstrap); the unit serves the daemon with --no-open. burrowee-gateway-updater gets its own unit installed alongside it (com.burrowee.gateway.updater / burrowee-gateway-updater.service) — there is no separate unit for the console, which runs as a supervised child of the daemon rather than its own service.
| Platform | Unit | Path |
|---|---|---|
| macOS (launchd agent) | com.burrowee.gateway | ~/Library/LaunchAgents/com.burrowee.gateway.plist |
| Linux (systemd user unit) | burrowee-gateway.service | ~/.config/systemd/user/burrowee-gateway.service |
Upgrading from an old install
Early gateway builds used the label org.burrowee.gateway. service install migrates automatically — it boots out and removes the stale agent before installing the current com.burrowee.gateway one.
Edge — ~/.burrowee/edge/
Written by burrowee edge bootstrap <blob> <pin> and by the running relay.
| File / dir | What it holds |
|---|---|
identity/relay_ed.key | The edge's identity key; its fingerprint is what you approve in the cloud console |
console.json | The enrolled console URL + public key (console_url, console_pub_hex), persisted by bootstrap; the compiled-in console identity is the fallback when absent |
config | Serve settings as KEY=VALUE lines: tls_listen (off = LAN-only), quic_addr, lan_listen, lan_advertise_port, lan_cert, lan_allow_ips, serve_mode (frontier|lan, written by edge mode), raw_port (the nginx-bypass isolated listener for edge-to-edge bridging, off by default — see Ports), allow_push_update (opt in to cloud-initiated push updates; default false), and the optional buffer profile buffer_stream/buffer_session/buffer_frame (byte counts, or k/m/g suffixes). Read by run; serve flags override per key (where a flag exists). # comments and blank lines are preserved. Read/write it with edge cli config get|set |
config.json | The latest console-signed relay config (owner tenant, authorized gateway fingerprints, served domains) — cached so status works offline; its signature is verified on every read |
lan-cert/cert.pem, lan-cert/key.pem | The long-lived self-signed LAN TLS cert nginx terminates on the LAN port; its SHA-256 fingerprint is pinned in client/gateway blobs. There is no rotate flag — to force a new one, delete this directory and re-run sudo burrowee edge nginx reconcile --mode lan (see Rotating the LAN certificate) |
bridge/bridge_ed.key | This edge's edge-to-edge bridge identity — separate from its relay identity above; generated automatically the first time the edge runs after upgrading, so every edge becomes bridge-capable with no setup step |
bridge/authorized_keys | The inbound bridge allowlist: peer edges' bridge public keys this edge accepts Links from (edge cli bridge approve) |
bridge/links.json | Operator-staged outbound bridge Links this edge subscribes to (edge cli bridge subscribe) |
nginx front
burrowee edge nginx writes server-only snippets and wires them in — it never rewrites your existing servers. The frontier and LAN fronts are two separate files, in different nginx include folders (see nginx front → File paths):
| Path | Purpose |
|---|---|
<nginx-conf-dir>/servers-stream/burrowee-edge-stream.conf | The frontier stream front (nginx install/reconcile --mode frontier, and the legacy apply's combined file): :443 ssl_preread SNI passthrough to the edge's loopback tls_listen |
<nginx-conf-dir>/servers/burrowee-edge-lan.conf (macOS) / <nginx-conf-dir>/conf.d/burrowee-edge-lan.conf (Linux) | The LAN front (reconcile --mode lan): an http-context listen 8448 ssl; server with the LAN cert, WebSocket-proxying to the edge's loopback lan_listen — lives in the stock http {} include folder, so it needs no extra hook |
<nginx-conf-dir>/nginx.conf | Gains one top-level line if missing (frontier only): stream { include servers-stream/*.conf; } |
Service unit
Installed by burrowee edge service install; both units run <binary> run and restart on failure.
| Platform | Unit | Path |
|---|---|---|
| macOS (launchd agent) | org.burrowee.edge | ~/Library/LaunchAgents/org.burrowee.edge.plist |
| Linux (systemd user unit) | burrowee-edge.service | ~/.config/systemd/user/burrowee-edge.service |