homelab/ansible/roles/honcho/README.md

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

1. Installs Podman + ensures the rootful Quadlet drop-in dir exists.
2. Creates a user-defined Podman network (honcho-net).
3. Creates a named volume for Postgres data (honcho_postgres_data).
4. Deploys a pgvector-enabled Postgres 16 container and waits for it to be ready.
5. Deploys the Honcho API container (honcho-api) — FastAPI on :8000.
6. Deploys the Honcho deriver worker container (honcho-deriver) — stopped and disabled by default (see below).
7. Verifies the API answers on /docs.

Deriver service (disabled by default)

The honcho-deriver service is created but not started by default (honcho_deriver_autostart: false). This prevents autonomous token burn.

Why disabled:
The deriver runs background reasoning loops that consume LLM tokens continuously, independent of the Hermes client-side contextCadence and dialecticCadence settings. Even with both cadences set to zero in ~/.hermes/honcho.json, the deriver polls Postgres every second and fires Claude API calls autonomously.

In production, this discovered behavior cost $10 USD overnight before the service was stopped.

Manual start (if needed for testing):

# On lincoln.local.mk-labs.cloud as jarvis or with sudo:
sudo systemctl start honcho-deriver.service

# Check status:
sudo systemctl status honcho-deriver.service

# Stop again:
sudo systemctl stop honcho-deriver.service

To enable permanently:
Override honcho_deriver_autostart: true in group_vars or inventory, then re-run the playbook.

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.