# Signoff + WorkerBee local setup Set up the Signoff + WorkerBee local agent harness on this computer. Your goal is a safe local pairing: Signoff owns the user-facing specification, real-product QA evidence, and verdicts. WorkerBee owns the project-scoped local infrastructure loop for containers, services, manifests, logs, ingress, probes, security review, cleanup, and export. WorkerBee health is supporting evidence, never a Signoff verdict. ## Safety and scope - Detect the operating system, shell, CPU architecture, installed coding harnesses, and existing configuration before changing anything. - Support macOS, Linux, and Windows through WSL2. On Windows, install and run WorkerBee inside WSL2 and use Docker Desktop with WSL integration unless the user already has a working compatible runtime. - Keep WorkerBee MCP bound to loopback at http://127.0.0.1:8765/mcp. Do not expose it to a LAN or the public internet. - Preserve existing MCP servers, agent instructions, secrets, and unrelated configuration. - Never print, invent, or commit the Signoff API key. Ask the user for a key from Signoff Settings only when no usable key is already available. - Prefer current official documentation and the latest stable WorkerBee release. Do not replace a working container runtime merely to standardize the machine. ## 1. Prepare the local runtime 1. Confirm Python 3.11 or newer. 2. Confirm a supported runtime is actually running with `docker version` or `podman info`. 3. On macOS, prefer Docker Desktop for the general runbook. A working Colima-based Docker context is also acceptable. 4. On WSL2, confirm the distro can execute the Docker CLI and reach the Docker daemon before continuing. 5. On Linux, prefer rootless Podman or a correctly configured Docker daemon. ## 2. Install and start WorkerBee Use the official release installer from https://github.com/the-cm-collective/k1s-workerbee: ```sh curl -fsSL https://github.com/the-cm-collective/k1s-workerbee/releases/latest/download/install-workerbee.sh | sh export PATH="$HOME/.local/bin:$PATH" workerbee doctor workerbee mcp start workerbee mcp status ``` On macOS, pass `PYTHON=python3.11` to the installer when the default Python is older. If policy forbids piping a download to a shell, download the release installer and wheelhouse, inspect them, and use the documented offline install path instead. Verify that the MCP endpoint answers on http://127.0.0.1:8765/mcp and that the dashboard health check succeeds at `https://dashboard.workerbee.localhost:19443/healthz`. Install the local CA only when browser or HTTPS ingress testing requires it, using `workerbee trust install --target system`. ## 3. Register both MCP servers globally Register WorkerBee as a remote Streamable HTTP MCP server named `workerbee` with URL http://127.0.0.1:8765/mcp. Preserve any working authorized Signoff integration, especially a private-local endpoint and its generated credentials. Confirm `deployment_mode` with `whoami`. For a new hosted integration only, register Streamable HTTP MCP named `signoff` with URL `https://sign-off.cloud/mcp` and header `X-Api-Key: `. Use each harness's global configuration and preserve its existing servers: - Codex: use `codex mcp add workerbee --url http://127.0.0.1:8765/mcp`. Configure Signoff with the same endpoint and header shown in Signoff Settings. - Kimi Code: use `kimi mcp add --transport http workerbee http://127.0.0.1:8765/mcp` when that command exists. For older Kimi Code releases, merge a `workerbee` URL entry into the existing global `mcp.json` under `~/.kimi-code`. Newer Kimi installations normally use `~/.kimi/mcp.json`. Detect the active home instead of creating both. - OpenCode: use its native remote-MCP configuration for WorkerBee and the selected Signoff endpoint. Preserve an existing private-local configuration. Its global configuration normally lives at `~/.config/opencode/opencode.json`. - Other harnesses: use their native global remote-MCP configuration. Use a local proxy only when the harness cannot connect to Streamable HTTP directly. Restrict credential-bearing files to the current user. Prefer the harness's environment or secret-file substitution when supported. ## 4. Add the project instruction bridge Run `workerbee agent instructions` and add its current short trigger to the project's existing agent instruction file without replacing project-specific guidance. Also preserve this division of responsibility: ```markdown For new or changed user-facing behavior, bug fixes, releases, or QA requests, call Signoff whoami first and follow its live contract. Signoff defines the expected human-observable behavior and records evidence-backed verdicts. When the task needs a runnable local environment, containers, services, manifests, ingress, runtime logs, infrastructure diagnostics, security review, or deployment artifacts, call WorkerBee workerbee_v1_session_start with the repository's absolute path and the task goal. Use the returned project identity for later WorkerBee calls. Use WorkerBee to create and observe the local environment. Use the real browser, app, device, or public feature to perform Signoff checks. WorkerBee health, deployment success, logs, and probes are supporting evidence, not Signoff verdicts. Never approve a Signoff check until its user-facing behavior has actually been exercised. Exercise a meaningful vertical slice early, then repeat implementation, runtime observation, behavioral verification, and repair. Read fresh runtime identity before relying on earlier evidence after redeployment. Public API or CLI behavior is checked at that real public surface, not relabeled as browser verification. Before approving a check, compare its actual actions and assertions with the complete source criterion, including relevant boundaries, failures, permissions, and state transitions. A source/check binding establishes traceability, not relevance or execution. An unrelated health or CRUD check cannot prove a different requirement by changing its title or ID. WorkerBee owns project-scoped runtime facts; readiness, logs, probes, and deployment receipts support diagnosis but do not certify application behavior. Execute the matching public behavior against the current identified build and retain reproducible steps, observed results, actor attribution, and redacted evidence. Use actual process or runner results when available; never manufacture a passing terminal summary or substitute printed text for an execution result. Recheck affected behavior after a deployment, implementation, fixture, or assertion changes; old evidence remains history, not fresh proof. Model review may help assess relevance when an authorized harness provides it, but is fallible and cannot replace execution or an independent acceptance result. Use the installed WorkerBee tool schema and retain its returned project identity. Signoff guidance does not change WorkerBee's API, authorize installations, or imply that an optional harness helper exists in every client. When no human reviewer is available, this workspace keeps the agent on track: Signoff QA continues as a self-protecting eval harness with the same contract, pinned fixtures, and truthful agent provenance, and WorkerBee diagnostics remain supporting evidence that never earns a verdict. ``` ## 5. Make startup durable Confirm the container runtime starts after login or reboot. Then configure WorkerBee MCP to start after that runtime is ready, using the operating system's ordinary user-level service mechanism. - macOS: use the runtime's login setting and a user LaunchAgent for `workerbee mcp start` or a small health-aware wrapper. - Linux with systemd: use a user service with restart-on-failure and an ordering or retry strategy for Docker or Podman readiness. - WSL2: when systemd is enabled, use the same user-service pattern. Otherwise use Windows Task Scheduler to invoke the WSL distro and start WorkerBee after Docker Desktop is available. Do not create a tight restart loop. After configuring startup, test one stop/start cycle. Explain that coding clients snapshot available MCP tools at startup and may need a full restart if they opened while WorkerBee was unavailable. ## 6. Run the cheap lights-on test 1. Start a fresh session in every configured harness. 2. Confirm it can see Signoff `whoami` and WorkerBee `workerbee_v1_session_start`. 3. Call Signoff `whoami` and follow the returned live contract. 4. Call WorkerBee `workerbee_v1_session_start` with one real repository path and a lights-on goal. 5. Confirm the returned WorkerBee project is scoped to that repository and the global dashboard is healthy. 6. Do not deploy a sample workload unless the user asks. This test proves discovery, authentication, project scoping, and local runtime health without spending a large model or infrastructure budget. Finish with a redacted report listing the files changed, MCP status in each harness, startup behavior, verification results, and any manual step still required. ## Source and ownership WorkerBee is maintained at https://github.com/the-cm-collective/k1s-workerbee and distributed under the Apache License 2.0. Signoff provides this handoff as a convenience for people who want local infrastructure execution paired with evidence-backed product QA.