9d860367cc
- Explains why honcho_deriver_autostart defaults to false (0 token burn) - Provides manual systemctl start/stop commands - Notes override procedure for permanent enable
119 lines
5.3 KiB
Markdown
119 lines
5.3 KiB
Markdown
# 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.
|