--- # ============================================================================ # honcho role defaults # ============================================================================ # Deploys Honcho (https://honcho.dev — plastic-labs/honcho) as a rootful # Podman + Quadlet service on a single VM. Three containers: # # honcho-postgres pgvector-enabled PostgreSQL backing store # honcho-api FastAPI server on :8000 (theory-of-mind read/write) # honcho-deriver background worker that consumes the queue and calls # out to the configured LLM provider for derivations # # All three share a user-defined podman network. State persists to named # volumes. Traefik on lightning-lane terminates TLS and routes the # `hall-of-presidents.local.mk-labs.cloud` host to honcho-api:8000. # # LLM provider for the first deployment is Anthropic Claude. Switching # providers is a single env-var change (see DERIVER_MODEL_CONFIG__TRANSPORT # / SUMMARY_MODEL_CONFIG__TRANSPORT and the LLM_*_API_KEY variables). # ============================================================================ # --------------------------------------------------------------------------- # Image pinning # --------------------------------------------------------------------------- # Honcho does not yet publish a Docker Hub image we trust; we use the # GitHub Container Registry build. Pin to a digest-stable tag. honcho_image: "ghcr.io/plastic-labs/honcho:latest" # pgvector/pgvector image follows the upstream postgres version channel. honcho_postgres_image: "docker.io/pgvector/pgvector:pg16" # --------------------------------------------------------------------------- # Container & network identifiers # --------------------------------------------------------------------------- honcho_container_name: honcho-api honcho_deriver_container_name: honcho-deriver honcho_postgres_container_name: honcho-postgres honcho_network_name: honcho-net # Named podman volumes honcho_postgres_volume: honcho_postgres_data # --------------------------------------------------------------------------- # Networking # --------------------------------------------------------------------------- # Honcho's FastAPI default port is 8000. Bind to 0.0.0.0 so Traefik on # lightning-lane can reach it; auth is enabled (JWT) so the open port is # not an open door. honcho_listen_address: "0.0.0.0" honcho_listen_port: 8000 # Public-facing URL used for absolute links / OIDC callbacks. # Leave EMPTY to make Honcho host-agnostic — FastAPI emits relative URLs. # Set to a fully-qualified URL only if a specific feature requires it. honcho_web_url: "" # --------------------------------------------------------------------------- # PostgreSQL configuration # --------------------------------------------------------------------------- honcho_db_user: honcho honcho_db_name: honcho # honcho_db_password sourced from vault below # pgvector-enabled Postgres uses the same env vars as the stock image honcho_postgres_initdb_args: "--encoding=UTF8 --locale=C" # --------------------------------------------------------------------------- # LLM provider configuration # --------------------------------------------------------------------------- # Supported transports: openai, anthropic, gemini. We start with anthropic # and can flip to a local OpenAI-compatible endpoint later by changing # these knobs plus the API-key env-var name. # # Honcho has THREE distinct LLM subsystems, each with its own settings # class and env-var prefix: # # DERIVER — generates observations from messages (background worker) # SUMMARY — periodic session summaries # DIALECTIC— answers theory-of-mind queries (the `peers/{peer}/chat` API) # # Honcho's dialectic subsystem uses PER-LEVEL config (minimal/low/medium/ # high/max) under DIALECTIC_LEVELS____MODEL_CONFIG__*. Defaults # point at OpenAI, so any honcho.dev install without an OpenAI key will # fail dialectic queries with "Missing API key for openai model config". # We override all five levels to Anthropic below in the API template. honcho_llm_transport: "anthropic" honcho_deriver_model: "claude-sonnet-4-5" honcho_summary_model: "claude-sonnet-4-5" honcho_dialectic_model: "claude-sonnet-4-5" # Deriver tuning. Honcho batches representation tasks until the per-batch # token threshold is reached. For homelab use with one chatty operator, # that means short bursts of conversation can sit unprocessed forever. # DERIVER_FLUSH_ENABLED=true bypasses the batching threshold so each # message is processed promptly. # # honcho_deriver_enabled controls whether the deriver Quadlet is created. # honcho_deriver_autostart controls whether the service starts on boot. # Set autostart=false to create the service but leave it disabled — useful # after discovering the deriver burns tokens autonomously despite client-side # cadence=0 settings. honcho_deriver_enabled: true honcho_deriver_autostart: false honcho_deriver_workers: 1 honcho_deriver_polling_seconds: "1.0" honcho_deriver_flush_enabled: true # --------------------------------------------------------------------------- # Embeddings # --------------------------------------------------------------------------- # Anthropic does not provide an embedding API. Honcho defaults to # OpenAI text-embedding-3-small, which fails without an OpenAI key. # Three options going forward: # 1. Set EMBED_MESSAGES=false — disables semantic search/vector recall # but theory-of-mind derivation still works. Default for now. # 2. Provide an OpenAI API key purely for embeddings (cheap; embeddings # are ~$0.02 per million tokens). Set honcho_embed_messages=true and # add vault_honcho_openai_api_key. # 3. Stand up a local BGE/nomic embedding endpoint (e.g. on astro-orbiter # once GPU is ready) and point Honcho at it via # EMBEDDING_MODEL_CONFIG__OVERRIDES__BASE_URL. honcho_embed_messages: true # Embedding provider (transport must be openai-compatible). The default # OpenAI endpoint requires honcho_openai_api_key. To swap to a local # OpenAI-compatible embedder (e.g. Ollama), set honcho_embedding_base_url # to the upstream /v1 URL and the API key can be any non-empty string. honcho_embedding_transport: "openai" honcho_embedding_model: "text-embedding-3-small" honcho_embedding_base_url: "" # --------------------------------------------------------------------------- # Auth # --------------------------------------------------------------------------- # AUTH_USE_AUTH=true means clients must present a JWT signed with # AUTH_JWT_SECRET. The secret lives in vault. honcho_auth_enabled: true # --------------------------------------------------------------------------- # Vault inputs (defined in group_vars/all/vault, encrypted with ansible-vault) # --------------------------------------------------------------------------- # vault_honcho_database_password - postgres role password # vault_honcho_jwt_secret - 32+ byte random string for JWT signing # vault_honcho_anthropic_api_key - Anthropic API key for Claude calls # vault_honcho_openai_api_key - OpenAI API key, embeddings-only honcho_db_password: "{{ vault_honcho_database_password }}" honcho_jwt_secret: "{{ vault_honcho_jwt_secret }}" honcho_anthropic_api_key: "{{ vault_honcho_anthropic_api_key }}" honcho_openai_api_key: "{{ vault_honcho_openai_api_key }}" # --------------------------------------------------------------------------- # Health check # --------------------------------------------------------------------------- honcho_health_check_retries: 30 honcho_health_check_delay: 2 # --------------------------------------------------------------------------- # Quadlet location (rootful) # --------------------------------------------------------------------------- honcho_quadlet_dir: /etc/containers/systemd