Skip to content

Operations Runbook

Jump to bottom
m4xx3d0ut edited this page May 12, 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, 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, or DNS answer:

workerbee mcp restart

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. 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

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