Skip to content

Installation Debian Ubuntu

Jump to bottom
m4xx3d0ut edited this page May 12, 2026 · 1 revision

Installation: Debian and Ubuntu

This page documents a practical Debian or Ubuntu setup for WorkerBee source development and local app validation.

Packages

Install Python, build tools, and common diagnostics:

sudo apt-get update
sudo apt-get install -y \
  python3.11 python3.11-venv python3-pip \
  git curl jq openssl ca-certificates \
  build-essential

Install one runtime. Podman is a good default for local development:

sudo apt-get install -y podman

Docker is also supported if Docker is already your local standard.

Optional browser NSS trust support:

sudo apt-get install -y libnss3-tools

Optional advanced direct-containerd work:

sudo apt-get install -y containerd nerdctl

Package names vary by distribution release. If nerdctl is unavailable, use the upstream package for your release or stay on Podman/Docker mode.

Source Install

From the checkout:

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

Start MCP

workerbee mcp start
workerbee mcp status

The MCP server binds to loopback by default. Keep it loopback-only unless you are deliberately testing remote MCP transport with --allow-remote-mcp.

Trust the Local CA

WorkerBee uses Caddy internal TLS for local HTTPS ingress. It does not install that CA automatically. Use explicit commands:

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

On Debian and Ubuntu, --target system installs into /usr/local/share/ca-certificates/workerbee-caddy-local.crt and runs update-ca-certificates. --target nss installs into the user NSS database for browsers that use NSS.

LAN Ingress

For testing on another device on the same LAN:

workerbee mcp restart --ingress-exposure lan
workerbee mcp status

If you want DNS names without editing router DNS:

workerbee mcp restart --ingress-exposure lan --ingress-dns forwarding

If binding DNS port 53 fails, check whether another service owns it:

sudo ss -lntup | grep ':53'

Then either stop the conflicting local DNS service for the test window, bind WorkerBee DNS to a specific LAN IP, or choose a custom DNS port for clients that support it.

Clone this wiki locally