Installation NixOS

Installation: NixOS

The WorkerBee source tree includes a flake-based developer shell for NixOS and Nix-enabled Linux or macOS hosts.

Enter the Developer Shell

From the k1s-workerbee checkout:

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

The shell provides Python 3.11, uv, ruff, curl, jq, OpenSSL, Node.js, and Linux packages used by advanced direct-containerd workflows such as nerdctl and CNI plugins.

Rebuild WorkerBee and Restart MCP

When rebuilding WorkerBee from a sibling ../k1s checkout, stop the background daemon before reinstalling and refresh sudo before starting it again:

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

Stopping first prevents the old MCP process from serving stale in-process code. --force-reinstall refreshes the editable install against the rebuilt local wheelhouse, and sudo -v avoids direct-containerd sudo-helper startup stalls.

Container Runtime

For normal WorkerBee app validation, use Podman or Docker.

Podman on NixOS usually requires host-level service configuration. A typical NixOS system enables the runtime outside the project shell:

virtualisation.podman.enable = true;
virtualisation.podman.dockerCompat = true;

Docker is also supported if your user can access the Docker socket.

CA Trust on NixOS

NixOS system trust is declarative. WorkerBee does not mutate security.pki.certificates automatically. Export the CA and add it to your NixOS configuration when you want system trust:

workerbee ingress ca --output workerbee-ca.crt

Then add the certificate contents to:

security.pki.certificates = [
  ''
  -----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----
  ''
];

Rebuild with your normal NixOS process. For browser-only trust, Chrome and Chromium on Linux may read a user NSS database instead of NixOS system trust. workerbee trust install --target nss works only when certutil is available in the WorkerBee shell:

workerbee trust install --target nss

If workerbee trust status reports certutil: null, use nssTools and install the active WorkerBee CA into both common Chrome NSS locations:

export CA=/tmp/workerbee-containerd-verify/global/caddy-local-root.crt

nix shell nixpkgs#nssTools -c bash -lc '
set -euo pipefail
pw="$(mktemp)"
: > "$pw"
trap "rm -f \"$pw\"" EXIT

for db in "$HOME/.local/share/pki/nssdb" "$HOME/.pki/nssdb"; do
  mkdir -p "$db"
  certutil -N -d "sql:$db" --empty-password 2>/dev/null || true
  certutil -D -d "sql:$db" -n "WorkerBee Caddy Local Root" 2>/dev/null || true
  certutil -A -d "sql:$db" -f "$pw" -t "C,," \
    -n "WorkerBee Caddy Local Root" \
    -i "$CA"
  certutil -L -d "sql:$db" -n "WorkerBee Caddy Local Root"
done
'

--empty-password is suitable for a dev-only user NSS DB that stores only local development CA trust. It does not expose WorkerBee's private CA key. If an existing NSS DB prompts for a password or PIN, that prompt is for the existing user NSS DB, not WorkerBee. Either enter the existing NSS DB password or back up and recreate the user NSS DB if it only contains disposable dev certificates.

After changing NSS trust, fully quit Chrome or Chromium before retesting:

pkill -f 'chrome|chromium' || true

LAN DNS and Privileged Ports

WorkerBee LAN DNS defaults to port 53 because phones and tablets usually do not support custom DNS ports. Binding port 53 may require host configuration or a privileged launcher. For non-phone clients that support custom DNS ports, use:

workerbee mcp restart \
  --ingress-exposure lan \
  --ingress-dns forwarding \
  --ingress-dns-port 1053

Then configure the client to use the WorkerBee host IP and the selected port if the client supports it.

Direct Containerd Notes

Advanced k1s profile work can use direct containerd mode:

workerbee --runtime containerd containerd-privilege status
workerbee --runtime containerd profile list

Direct containerd is Linux-focused. It may require helper privilege setup and CNI access. See Advanced k1s Development.