f8cf139b10
Smoke-testing the first deploy uncovered three default-config issues
that no amount of Quadlet tuning would have caught:
1. DIALECTIC subsystem ignored DERIVER_MODEL_CONFIG__*. Honcho splits
dialectic into five reasoning levels (minimal/low/medium/high/max)
each with its own MODEL_CONFIG that defaults to OpenAI. Without
overrides, every /chat call fails with: ValidationException:
Missing API key for openai model config. Now setting all five
DIALECTIC_LEVELS__<level>__MODEL_CONFIG__* env vars to anthropic.
2. DERIVER batches representation tasks until a token threshold is
reached. For low-volume homelab use (one chatty operator), tasks
can sit unprocessed forever. Add DERIVER_FLUSH_ENABLED knob,
default true.
3. Embeddings default to OpenAI text-embedding-3-small. Anthropic
has no embedding API, so without an OpenAI key the embed step
fails the entire derivation. Default EMBED_MESSAGES=false until
a separate embedding provider is wired up (OpenAI for embeds-only
or a local BGE endpoint on astro-orbiter).
defaults/main.yml documents all three issues and the migration path
back to embeddings when ready.
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.