aabb3d5009
The deriver script does "from src import crud" at the top, which only works when the cwd / sys.path[0] is /app. Running the script by file path (python /app/src/deriver/deriver.py) puts /app/src/deriver on sys.path instead, and the import fails with ModuleNotFoundError. Switch to python -m src.deriver.deriver and explicitly set WorkingDir=/app so module resolution is deterministic across Podman versions. Discovered during the first deploy of the honcho role on lincoln — honcho-api was healthy on :8000 but the deriver crash-looped 26 times in two minutes.
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.