Skip to content

Getting Started

Jump to bottom
m4xx3d0ut edited this page May 12, 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/

If the browser does not trust the dashboard certificate, either continue with explicit browser override for local testing or 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