Skip to content

Operations Runbook

Jump to bottom
m4xx3d0ut edited this page May 13, 2026 · 3 revisions

Operations Runbook

Use this page when WorkerBee is already installed and you need to operate, inspect, restart, or clean up a local environment.

First Status Commands

workerbee doctor
workerbee mcp status
workerbee projects
workerbee ingress status
workerbee trust status

For machine-readable detail:

workerbee mcp status --json
workerbee ingress status --json

The MCP status output includes the global dashboard URL, dashboard CA download URL, CA export/trust commands, LAN CA download URL when applicable, DNS listen information when DNS is enabled, running state, and state root.

Restart MCP Cleanly

Use restart when changing ingress exposure, domain, bind address, CA port, DNS mode, DNS bind address, DNS port, DNS answer, or other daemon options:

workerbee mcp restart

After rebuilding WorkerBee packages or the local k1s runtime wheelhouse, stop the old daemon before reinstalling and refresh sudo before startup:

workerbee mcp stop
scripts/build_wheelhouse.sh --k1s-root ../k1s --out dist/workerbee-wheelhouse
uv pip install --python .venv -e '.[dev]' --find-links dist/workerbee-wheelhouse --force-reinstall
sudo -v && workerbee mcp start

Use this rebuild sequence instead of plain mcp restart when the installed code or runtime wheelhouse changed.

For LAN ingress:

workerbee mcp restart --ingress-exposure lan

For LAN ingress plus WorkerBee DNS:

workerbee mcp restart --ingress-exposure lan --ingress-dns forwarding

Project Controls

List all known projects:

workerbee projects

Persist start mode:

workerbee project mode start

Stop without purge:

workerbee stop

Reset project workloads and generated artifacts:

workerbee reset

The global dashboard can also start, stop, delete, or inspect projects. Row actions target only that row. Selected actions require checked projects. All actions intentionally ignore the current checkbox selection. Delete means stop, purge project runtime/state, unregister the project from the global dashboard, and resync Caddy imports.

Runtime Cleanup

Inspect stale resources:

workerbee cleanup

Execute cleanup:

workerbee cleanup --execute

Remove images too:

workerbee cleanup --execute --purge-images

Avoid deleting runtime resources manually unless the cleanup output identifies a gap. WorkerBee labels its resources for targeted cleanup.

CA and Trust Operations

Export the active Caddy CA:

workerbee ingress ca --output workerbee-ca.crt

Download the active Caddy CA from the global dashboard:

https://dashboard.workerbee.localhost:19443/workerbee-ca.crt
https://dashboard.workerbee.localhost:19443/workerbee-ca.sha256

The dashboard CA URL is available in loopback and LAN modes. The separate plain HTTP LAN CA URL is only published when LAN ingress is explicitly enabled, and is intended for other devices that cannot yet trust WorkerBee HTTPS.

Install host system trust:

workerbee trust install --target system

Install browser NSS trust:

workerbee trust install --target nss

Remove trust:

workerbee trust uninstall --target system
workerbee trust uninstall --target nss

WorkerBee does not install trust automatically. This keeps local HTTPS development explicit and reversible.

Logs and Diagnostics

Project app logs:

workerbee logs api --tail 100
workerbee logs frontend --tail 100

Bounded exec:

workerbee exec api -- sh -c 'id && pwd && env | sort'

Global status:

workerbee global-dashboard
workerbee ingress status --json

MCP Tooling Notes

Agents should prefer MCP tools for runtime behavior:

  • workerbee_v1_session_start
  • workerbee_v1_projects
  • workerbee_v1_project_status
  • workerbee_v1_ingress_status
  • workerbee_v1_ingress_probe
  • workerbee_v1_logs
  • workerbee_v1_exec
  • workerbee_v1_cleanup
  • workerbee_v1_trust_status

Use local shell commands for repo edits and ordinary unit tests. Use WorkerBee MCP for image builds, manifest staging, deploy, runtime probes, security review, and dashboard URLs.

Clone this wiki locally