Skip to content

Advanced k1s Development

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

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

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.

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