Skip to content

Getting Started

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

Getting Started

This page gets a new developer from a clean checkout to a running WorkerBee MCP daemon and a usable project stack.

Prerequisites

WorkerBee needs:

  • Python 3.11 or newer.
  • Git.
  • A local container runtime: Podman or Docker for normal use.
  • curl, openssl, and jq for diagnostics and runbook commands.
  • Optional: certutil for browser NSS trust stores.
  • Optional Linux-only advanced path: containerd, nerdctl, and CNI plugins.

WorkerBee can use an installed k1s-workerbee-runtime package. For source development it can also use a sibling ../k1s checkout. See Advanced k1s Development for that path.

Source Checkout Setup

From the k1s-workerbee repo:

python3.11 -m venv .venv
. .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"
workerbee doctor

On Nix systems, prefer the repo flake:

nix develop
python -m pip install -e ".[dev]"
workerbee doctor

Start WorkerBee MCP

Start the background MCP daemon:

workerbee mcp start
workerbee mcp status

The default MCP endpoint is:

http://127.0.0.1:8765/mcp

The default global dashboard is:

https://dashboard.workerbee.localhost:19443/

The dashboard exposes the active WorkerBee Caddy CA under the same host:

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

If the browser does not trust the dashboard certificate, either continue with an explicit browser override for local testing, download the CA from the dashboard, or export and install the local CA explicitly:

workerbee ingress ca --output workerbee-ca.crt
workerbee trust install --target system
workerbee trust install --target nss

Add Agent Instructions

Install the WorkerBee instructions block into a repo AGENTS.md:

workerbee agent install --target AGENTS.md --append --allow-create

Agents should start sessions with the WorkerBee MCP tool and use the returned project name for all later WorkerBee calls.

First Project Flow

Run these from a project repo:

workerbee project status
workerbee project mode start
workerbee manifest prepare --name app --template frontend-api-store
workerbee manifest validate --stage app
workerbee manifest deploy-local --stage app
workerbee projects

Project hosts are scoped under the project name. In default loopback mode they look like:

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

Use HTTPS probes through WorkerBee when possible because WorkerBee already knows the local CA and expected ingress shape:

workerbee security assess --stage <stage-dir>

Agents can use workerbee_v1_ingress_probe for detailed method, body, header, and response checks.

Stop and Cleanup

Stop MCP and its global ingress:

workerbee mcp stop

Stop a project stack:

workerbee stop

Inspect stale runtime resources before removing them:

workerbee cleanup
workerbee cleanup --execute

Clone this wiki locally