Appearance
Config homes & files
Each component keeps all of its state under one fixed directory — its config home — at ~/.burrowee/<component>/. There are no BURROWEE_* environment variables anywhere; 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 binding: gw_id, the relays list (each entry: id, ws URL, optional lan origins, lan_only, lan_cert_fp), default_relay, optional relay_quic, and the paths to the two key files below (gw_pubkey_path, psk_path) |
gw.pub | The paired gateway's ed25519 public key, hex-encoded |
psk.bin | The pairing pre-shared key, raw bytes |
connect / ssh / daemon default their --relay, --gw, --gw-pub, --psk, and --relay-quic values from this config. relays pair and relays use edit config.json in place.
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 relays use/priority/pair/probe poke it (relays list reads config.json directly). 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. |
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.
| File / dir | What it holds |
|---|---|
gateway.db | The gateway store: persisted relays, targets, sessions, pairings — everything the local console shows |
keys/relay_ed.key | The gateway's ed25519 identity toward relays (its public-key fingerprint is the gateway's id everywhere) |
keys/cli_ed.key | The gateway's ed25519 identity toward paired clients |
keys/session_hmac.key | HMAC key for session tokens (generated on first serve) |
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) |
Register socket
| 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. |
Service unit
Installed by burrowee gateway service install (and automatically by bootstrap); the unit serves the daemon with --no-open.
| 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 ed25519 identity; 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. Read by run; serve flags override per key. # comments and blank lines are preserved |
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. Rotate with burrowee edge nginx --rotate-lan-cert |
nginx front
burrowee edge nginx writes a server-only snippet and wires it in — it never rewrites your existing servers:
| Path | Purpose |
|---|---|
<nginx-conf-dir>/servers-stream/burrowee-edge-stream.conf | The generated stream front: external TLS (:443) passthrough and/or the LAN TLS listener (:8448 → the edge's loopback lan_listen) |
<nginx-conf-dir>/nginx.conf | Gains one top-level line if missing: 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 |