Basic Use

Basic Use

This page covers the normal WorkerBee loop for a local project.

Health Check

Start with:

workerbee doctor
workerbee mcp status

If MCP is not running:

workerbee mcp start

Project Identity

WorkerBee scopes state by project. A project can be passed explicitly:

workerbee --project demo project status

When no project is supplied, WorkerBee derives one from the current working directory, git branch, and path hash. This allows multiple branches or sibling worktrees to run without fighting over state.

Project Modes

WorkerBee has three persisted project modes:

workerbee project mode lazy
workerbee project mode start
workerbee project mode stop

• lazy: default. Start the project stack only when an operation needs it.
• start: keep the project ready for future sessions.
• stop: refuse runtime operations until the mode changes.

Check mode and status:

workerbee project status
workerbee projects

Start and Stop

Project-local stack:

workerbee start
workerbee status
workerbee stop

Background MCP daemon and global ingress:

workerbee mcp start
workerbee mcp status
workerbee mcp restart
workerbee mcp stop

workerbee mcp stop stops the MCP daemon and global Caddy ingress. It does not purge every project state directory. Use project stop/reset or cleanup for that.

Manifest Workflow

Prepare a stage:

workerbee manifest prepare --name app --template frontend-api-store

Validate it:

workerbee manifest validate --stage app

Deploy locally:

workerbee manifest deploy-local --stage app

Deploy output includes app workload status. Ready workloads are reported separately from degraded workloads, orphaned workloads from a previous stage, and the case where the control plane is running but no app workload has been deployed yet.

If deploy reports orphaned workloads that are no longer declared by the current stage, rerun deploy with explicit pruning:

workerbee manifest deploy-local --stage app --prune

Export handoff artifacts:

workerbee bundle export --stage app --format k1s
workerbee bundle export --stage app --format k8s
workerbee bundle export --stage app --format helm

--stage may be the stage name under WorkerBee artifacts or an absolute stage directory returned by prepare.

Logs and Exec

workerbee logs api --tail 100
workerbee exec api -- sh -c 'id && env | sort'

workerbee logs falls back to matching exited containers by default when no running container has logs, which is useful for failed jobs. Use --no-include-exited when you only want running-container logs.

Use bounded exec for diagnostics. Do not use it as a hidden deployment step.

Ingress and CA

Default project URLs use local HTTPS:

https://app.<project>.workerbee.localhost:19443/
https://api.<project>.workerbee.localhost:19443/

Inspect ingress:

workerbee ingress status
workerbee ingress status --json

Export the CA:

workerbee ingress ca --output workerbee-ca.crt

Install trust only when you want the host to trust WorkerBee's local Caddy CA:

workerbee trust install --target system
workerbee trust install --target nss

Check trust metadata:

workerbee trust status

Security Review

Run advisory assessment against a staged app:

workerbee security assess --stage app

Review the latest deployed project and write an artifact:

workerbee security review-project --stage app

Security findings are advisory. They are designed to guide local development, not block every deploy/export.