Model Sources Architecture

Where the model picker dropdown gets its list — config → agent → providers → UI

Source — config.yaml ~/.hermes/config.yaml providers block model.default field Agent startup Hermes Agent reads config on start port 8642 reads Provider router — queries /v1/models Provider Router GET /v1/models per provider aggregates results Configured providers Anthropic api.anthropic.com/v1/models OpenRouter openrouter.ai/api/v1/models Ollama (local) 127.0.0.1:11434/v1/models Custom endpoint base_url/v1/models Z.AI / GLM api.z.ai/v1/models Kimi / MiniMax platform provider endpoints Fallback: reads config.yaml directly when gateway unreachable Switch UI API /api/models TanStack Start API route aggregated + deduplicated model list UI — Chat composer Model picker dropdown in composer user selects model models list Failure modes No provider configured config.yaml has no providers block Result: empty picker Fix: Settings → Model & Provider → add provider API key wrong / missing CUSTOM_API_KEY not in .env or wrong value Result: provider entry fails / 401 Fix: re-enter key in Settings → restart agent Custom endpoint /v1/models 404 endpoint doesn't implement models list Result: free-text model entry field shown Fix: type model ID manually in composer Capability probe failed probe ran before agent was ready Result: stale "no models" cache Fix: Settings → Agent → Reconnect → reload Default model config.yaml model.default is placed first in picker — if that model ID no longer exists at the provider, requests may fail; update config.yaml or re-select in Settings Legend Storage Hermes Agent Switch UI External providers Failure mode

Config is the source of truth

  • • Providers block in config.yaml drives everything
  • • Agent reads it at startup — restart required after changes
  • • model.default sets the picker's first selection
  • • Fallback: /api/models reads config directly if agent is down

How models are discovered

  • • Provider router queries GET /v1/models per provider
  • • Results aggregated and deduplicated
  • • Ollama auto-discovered at 127.0.0.1:11434
  • • Custom endpoint: must expose /v1/models or use free-text entry

When picker is empty

  • • No providers configured → add one in Settings
  • • API key missing or wrong → re-enter, restart agent
  • • Capability probe failed → Reconnect in Settings → Agent
  • • Custom endpoint /v1/models 404 → type model ID manually

Hermes Switch UI • model sources architecture • config.yaml → agent → /v1/models → /api/models → picker