feat(honcho): add role + day1 playbook + traefik route for lincoln
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
This commit is contained in:
85
ansible/roles/honcho/README.md
Normal file
85
ansible/roles/honcho/README.md
Normal file
@@ -0,0 +1,85 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user