b647f6afee
src/deriver/deriver.py is a helpers module with no __main__ guard — running it directly loads it and exits cleanly in ~3s with no logs, which is what we were seeing. The actual queue-processor entry point is src/deriver/__main__.py (asyncio.run(run_deriver())), invoked via "python -m src.deriver". Discovered during honcho first-deploy on lincoln: deriver container crash-looped (in the sense that systemd restarted it constantly) but the underlying process was actually exiting 0 on completion of the empty helpers module.
Honcho role
Deploys Honcho — Plastic Labs' memory + theory-of-mind
layer for stateful agents — on a single mk-labs VM (lincoln) using
rootful Podman + Quadlet.
Topology
┌──────────────────────────────┐
│ lightning-lane (Traefik) │
│ hall-of-presidents.l... │
└─────────────┬────────────────┘
│
│ HTTP :8000
▼
┌──────────────────────────────── lincoln ───────────────────────────────┐
│ │
│ ┌───────────────┐ ┌───────────────┐ ┌──────────────────────┐ │
│ │ honcho-api │ │ honcho-deriver│ │ honcho-postgres │ │
│ │ (FastAPI:8000)│◄──►│ (worker loop) │◄──►│ pgvector/pgvector:pg16│ │
│ └──────┬────────┘ └──────┬────────┘ └──────────────────────┘ │
│ │ │ │
│ └────────┬───────────┘ │
│ ▼ │
│ Anthropic Claude API (outbound, east-west to Internet) │
│ │
└────────────────────────────────────────────────────────────────────────┘
What this role does
- Installs Podman + ensures the rootful Quadlet drop-in dir exists.
- Creates a user-defined Podman network (
honcho-net). - Creates a named volume for Postgres data (
honcho_postgres_data). - Deploys a pgvector-enabled Postgres 16 container and waits for it to be ready.
- Deploys the Honcho API container (
honcho-api) — FastAPI on :8000. - Deploys the Honcho deriver worker container (
honcho-deriver). - Verifies the API answers on
/docs.
Required vault entries
Add to group_vars/all/vault (ansible-vault encrypted):
vault_honcho_database_password: "<strong random>"
vault_honcho_jwt_secret: "<32+ byte random>"
vault_honcho_anthropic_api_key: "sk-ant-..."
LLM provider switching
This role starts with Anthropic Claude. To swap to a local
OpenAI-compatible endpoint later (e.g. astro-orbiter once we have the
GPU running llama.cpp/Ollama in OpenAI-compatible mode), override these
in group_vars/honcho_server or via a playbook variable:
honcho_llm_transport: "openai"
honcho_deriver_model: "qwen3:8b"
honcho_summary_model: "qwen3:8b"
honcho_dialectic_model: "qwen3:8b"
# and add LLM_OPENAI_API_KEY (or set the base URL override in the template)
Traefik route
The Traefik file-provider YAML for hall-of-presidents.local.mk-labs.cloud
lives at boilerplates/traefik/dynamic/honcho.yml. It points at
http://lincoln.local.mk-labs.cloud:8000.
Known Quadlet pitfall (carried from the semaphore role)
Quadlet regenerates the systemd unit on .container file change but does
NOT restart the running container. This role explicitly handles that by
gating a state: restarted task on the template's changed status —
the same pattern documented in homelab-application-deployment's
quadlet-patterns reference.
Honcho version pinning
The honcho_image default is ghcr.io/plastic-labs/honcho:latest.
Move to a digest-pinned tag once we've validated the deployment works
against a known-good build.