Skip to content

Advanced k1s Development

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

Advanced k1s Development

This page is for developers working on WorkerBee and k1s together.

Repository Layout

The common sibling layout is:

git/
  k1s/
  k1s-workerbee/
  k1s-workerbee.wiki/

WorkerBee prefers the installed k1s-workerbee-runtime package. For source development it can use a sibling k1s checkout:

export WORKERBEE_K1S_ROOT="$PWD/../k1s"
workerbee doctor

If the sibling checkout is on a development branch, keep the WorkerBee project name explicit or rely on the derived branch-scoped name so multiple branches can coexist.

Development Shell

From k1s-workerbee:

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

When rebuilding WorkerBee packages against a sibling k1s checkout and restarting the normal background MCP daemon, use:

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

This keeps the old MCP process from serving stale code, refreshes the editable install against the rebuilt runtime wheelhouse, and gives direct-containerd sudo-helper a current sudo credential before startup.

Without Nix:

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

Direct Containerd Profiles

List profiles:

workerbee --runtime containerd profile list

Start a profile against a sibling k1s checkout:

workerbee --runtime containerd profile start \
  --profile k1s-dev-min-sqlite \
  --k1s-root ../k1s \
  --timeout 180

Check profile state:

workerbee --runtime containerd profile status \
  --profile k1s-dev-min-sqlite \
  --k1s-root ../k1s

Stop and optionally purge:

workerbee --runtime containerd profile stop --k1s-root ../k1s
workerbee --runtime containerd profile stop --k1s-root ../k1s --purge

Profile Validation

Validate profile startup:

workerbee --runtime containerd validate \
  --scenario k1s-profile \
  --profile k1s-dev-min-sqlite \
  --k1s-root ../k1s

Validate a workload on the profile:

workerbee --runtime containerd validate \
  --scenario profile-workload \
  --profile k1s-dev-min-sqlite \
  --k1s-root ../k1s \
  --timeout 240

Through MCP, agents can use:

  • workerbee_v1_profile_list
  • workerbee_v1_profile_start
  • workerbee_v1_profile_status
  • workerbee_v1_profile_validate
  • workerbee_v1_profile_workload_status
  • workerbee_v1_profile_workload_validate

For the copy/paste validation ladder from a sibling k1s agent shell, including preflight, all-profile startup checks, realtime workload validation, evidence capture, and cleanup, use Direct Containerd k1s Profile Validation.

Ingress for Profiles

When the MCP daemon is running, profile dashboards and API shims are published under the project-scoped WorkerBee ingress. Example loopback hosts:

https://k1s.<project>.workerbee.localhost:19443/dashboard
https://k1s-api.<project>.workerbee.localhost:19443/healthz

In LAN mode, the same project hosts use the selected LAN base domain.

Branch and Worktree Pattern

For sibling development, keep each active branch in its own worktree and let WorkerBee derive a project name from repo, branch, and path:

git -C ../k1s worktree add ../k1s-dev dev
git -C . worktree add ../k1s-workerbee-dev dev
cd ../k1s-workerbee-dev
export WORKERBEE_K1S_ROOT="$PWD/../k1s-dev"
workerbee mcp restart

This avoids state collisions between branches. Use workerbee projects and the global dashboard to inspect which project belongs to which branch.

Use workerbee mcp restart for daemon option changes or editable source reloads. After rebuilding WorkerBee packages or the local k1s runtime wheelhouse, use the stop, wheelhouse build, force-reinstall, sudo-refresh, and start sequence from Development Shell.

Test Commands

Focused unit tests:

python -m pytest tests/test_daemon.py tests/test_mcp_daemon.py tests/test_mcp_server.py

Style:

ruff check .

Live runtime tests require a local runtime and should be run deliberately after checking host state and cleanup output.

Clone this wiki locally