Operations

The day-2 surface: checking health, reading state, managing the service, and removing an edge cleanly.

Doctor

burrowee edge doctor

Runs the health checks, one line each, in order:

Check	Healthy looks like	When it fails
identity	present	missing — run burrowee edge bootstrap <blob> <pin>; the machine has never been bootstrapped (or was purged).
console reachable	the console's relay endpoint	The edge can't reach the console over WebSocket. An auth-level rejection still counts as reachable — only a transport failure (DNS, firewall, outbound blocked) fails this line.
nginx installed	the nginx binary path	nginx isn't on PATH.
nginx running	running	No nginx master process.
LAN front config	applied	The stream snippet is missing — run sudo burrowee edge nginx.
LAN front reachable	:8448 → 127.0.0.1:9448 reachable	A TCP probe of the advertised LAN port was refused.

When the nginx front is unhealthy, doctor --fix remediates in dependency order — install nginx, apply the config, start the service — asking before each step. Add --yes to run it unattended:

burrowee edge doctor --fix --yes

After fixing, it re-probes and prints the settled state.

Status

burrowee edge status

Three possible shapes, depending on how far setup has gone:

• not enrolled — run burrowee edge bootstrap <blob> <pin>; no identity on this machine.
• enrolled; no config received yet (run burrowee-edge run while approved + connected, then re-check) — bootstrapped, but the signed manifest hasn't arrived over the carrier.
• The full readout. Before printing it, status verifies the cached config's signature against the console's key — a stale or tampered file is an error, never silently served:

owner tenant:   42
max gateways:   10
custom domains: [app.example.com]
served domains: [app.example.com]
gateways (fp):  3 authorized
config age:     2m10s

Field	Meaning
owner tenant	The account this edge is bound to.
max gateways	How many gateways the manifest allows on this edge.
custom domains / served domains	The domains attached to and served through this edge.
gateways (fp)	How many gateway fingerprints are authorized to use it.
config age	How long ago the console issued the current manifest. A fresh sync resets it — an ever-growing age suggests the carrier is down.

Service

burrowee edge service install     # install + start the managed service
burrowee edge service status      # is it loaded/active?
burrowee edge restart             # restart it

service install writes a launchd agent on macOS (~/Library/LaunchAgents/org.burrowee.edge.plist) or a systemd user unit on Linux (~/.config/systemd/user/burrowee-edge.service), and starts it. The service runs burrowee-edge run, restarts on failure, and survives reboots.

restart kicks the service (launchctl kickstart -k / systemctl --user restart) and then prints the nginx-front status lines, read-only — it never touches nginx itself. If the front is down it points you at doctor --fix.

On a platform without launchd or systemd, both commands say so; run burrowee edge run under your own supervisor instead.

Update

burrowee edge update          # install the latest release, then restart the service
burrowee edge update --dry    # report the version gap + changelog only
burrowee edge update --force  # re-install even when already current

update always prints the version gap and changelog first. Without --dry it installs the latest release (skipped when already current unless --force) and restarts the managed service; a restart failure is non-fatal since the new binary is already in place.

Logs

• Linux: the service is a systemd user unit, so:

  journalctl --user -u burrowee-edge.service -f

• macOS: the launchd agent doesn't write a log file. For live logs, stop the service and run in the foreground:

  burrowee edge run

The foreground run logs the carrier connection, the serving mode decision, and every listener — it is the primary debugging surface on any platform.

Uninstall

burrowee edge uninstall            # remove the service, BACK UP config + state
burrowee edge uninstall --purge    # remove the service, DELETE everything

The default is non-destructive: it stops and removes the launchd/systemd service, then moves the nginx stream snippet and the whole ~/.burrowee/edge/ directory aside with a timestamped .bak.<timestamp> suffix, and reloads nginx so it stops serving the front. Nothing is lost:

uninstalled burrowee-edge (config + state backed up, not deleted):
  nginx snippet → /etc/nginx/servers-stream/burrowee-edge-stream.conf.bak.20260612-101500
  edge state    → /home/user/.burrowee/edge.bak.20260612-101500
restore:   mv <backup> back to its original path
reinstall: burrowee-edge service install && burrowee-edge nginx

Restoring really is just the mv — the identity, console config, and certificates all live in the backed-up directory.

--purge deletes instead: the snippet, the edge home, and any .bak.* backups from earlier uninstalls. Use it when decommissioning a machine for good. The identity is unrecoverable afterwards — re-enrolling means minting a fresh blob in the console.

Both forms accept --home and --conf-dir if the edge lives in non-default locations. The nginx reload is best-effort (it may need sudo); a failure prints the manual sudo nginx -s reload and never blocks the removal. Removing the relay from your account is a separate, console-side act: Edge Relays → Remove (then Delete to drop the row entirely).