# Honcho role

Deploys [Honcho](https://honcho.dev) — 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):**

```bash
# 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):

```yaml
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:

```yaml
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.