4d7766d1b1
Deploys Honcho (plastic-labs/honcho) as a rootful Podman + Quadlet service on the lincoln VM (10.1.71.132). Three containers on a user-defined network: - honcho-postgres pgvector/pgvector:pg16 - honcho-api FastAPI on :8000 - honcho-deriver background worker for theory-of-mind derivations LLM provider: Anthropic Claude (claude-sonnet-4-5). Switching providers is two env-var changes — see README. Traefik route hall-of-presidents.local.mk-labs.cloud -> lincoln:8000 added under boilerplates/traefik/dynamic/. JARVIS itself talks to Honcho directly at lincoln:8000 (east-west); the Traefik alias exists only for browser access to the Swagger /docs UI. Requires three new vault entries before first run: - vault_honcho_database_password - vault_honcho_jwt_secret - vault_honcho_anthropic_api_key
86 lines
4.3 KiB
Markdown
86 lines
4.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`).
|
|
7. Verifies the API answers on `/docs`.
|
|
|
|
## 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.
|