Custom Endpoint Routing

How a request flows from Settings UI → config.yaml → Hermes Agent → your OpenAI-compatible endpoint

PHASE 1 — Configure Settings /settings/providers route ProvidersScreen Provider = Custom, Base URL, key_env navigate Save POST /api/hermes-proxy/config on submit PHASE 2 — Persist ~/.hermes/config.yaml provider: manifest • type: openai • base_url ~/.hermes/.env CUSTOM_API_KEY=your-key-here writes PHASE 3 — Agent starts Hermes Agent reads config.yaml + .env on startup Provider Router selects "manifest" / openai type Resolve base_url + key_env → CUSTOM_API_KEY reads PHASE 4 — Chat turn POST /v1/chat/completions Authorization: Bearer CUSTOM_API_KEY SSE stream back token deltas → Hermes Agent → UI Your Endpoint any OpenAI-compat base_url/v1/ self-hosted model internal gateway small provider local inference on chat turn chunks Restart required Agent reads config.yaml and .env only at startup — restart after any config change Model discovery (on chat page load) Model picker chat composer /api/models Switch UI API route Hermes Agent queries each provider base_url/v1/models your endpoint model list Failure modes • /v1/models 404 → free-text model entry • API key wrong → 401 on chat send • base_url unreachable → "Provider not found" Legend Switch UI Storage (~/.hermes/) Hermes Agent Chat turn External endpoint

What gets written

  • • ~/.hermes/config.yaml — provider: manifest, type: openai, base_url, key_env
  • • ~/.hermes/.env — CUSTOM_API_KEY=your-key
  • • Provider name must be manifest, not custom
  • • Agent restart required to pick up changes

What the agent does

  • • Reads config.yaml + .env at startup
  • • Provider router selects "manifest"/openai slot
  • • Resolves base_url and reads key from key_env
  • • Attaches key as Authorization: Bearer header

Endpoint requirements

  • • Must implement OpenAI Chat Completions API shape
  • • GET /v1/models → model list (optional; fallback = free-text)
  • • POST /v1/chat/completions → SSE token stream
  • • Keyless: set CUSTOM_API_KEY=none in .env

Hermes Switch UI • custom endpoint routing • Settings → config.yaml → manifest provider → your endpoint