Hermes custom endpoint

Hermes Agent and Hermes Desktop: how to get a custom OpenAI-compatible endpoint working before the UI sends you in circles.

The recurring Hermes custom-provider failures are usually not the model itself. They come from setup readiness, key_env detection, model discovery assumptions, or one config path resolving a provider while another path still thinks nothing is configured.

Use one tiny first request as the source of truth: if the same base URL, bearer token and model id work in a raw request, the next bug is in Hermes setup, routing, or provider normalization, not in the upstream model.

Need one hosted control endpoint before debugging Hermes?

Use this only when provider signup, payment, account region, or custom endpoint setup is blocking the first request. Pay $5, create an account, send the receipt, and get manually credited for a small live test.

Start $5 test Create account Send receipt

1. Prove the upstream endpoint first

Do not start with the Desktop onboarding screen. Start with one direct request that proves the endpoint, key and model id are real.

curl https://your-router.example/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [{"role": "user", "content": "hello"}]
  }'

2. Keep the first Hermes config as explicit as possible

Named custom providers are more reliable when the first test keeps every important field visible instead of relying on inference.

model:
  default: your-model-id
  model: your-model-id
  provider: custom:your-provider-name

custom_providers:
- name: your-provider-name
  base_url: https://your-router.example/v1
  key_env: YOUR_PROVIDER_API_KEY
  model: your-model-id
  api_mode: chat_completions

If the raw request works but Hermes Desktop still says no provider is configured, the bug is often in setup readiness or env-var detection, not in your API key.

3. Check these three Hermes-specific signals

  1. setup.status should say the provider is configured.
  2. setup.runtime_check should say the runtime is ready.
  3. resolve_runtime_provider() should resolve the same base URL, provider source and key presence you expect.

If those succeed while the Desktop onboarding screen still loops, you are looking at a readiness-path bug, not a missing credential.

4. Do not let /v1/models become a hidden choke point

Many valid OpenAI-compatible routers fail model discovery even though chat completions work:

The productive fallback is: save the provider, keep one manual model id, and treat model discovery as a convenience, not as proof that the provider is usable.

5. Watch for these repeated split-brain patterns

Signal What it usually means Best next check
Desktop onboarding says no provider configured Readiness code is not honoring custom key_env or named-provider resolution Compare UI readiness with setup.runtime_check
Provider saves, but a different router receives the traffic Catalog or provider-priority logic overrode the explicit custom route Inspect final runtime base URL
Model list is empty, but direct request works /v1/models is not a trustworthy gate for this provider Keep one manual model id and skip discovery
Only generic env vars are recognized Setup detection forgot your provider-specific key_env Check whether readiness scans custom provider env names

6. Debug in this order

  1. Raw chat completion works.
  2. Resolved Hermes runtime uses the exact base URL you expect.
  3. Resolved Hermes runtime sees the correct API key env var.
  4. Only after that, care about Desktop onboarding polish, model picker discovery, or background agent behavior.

7. If you only need one small hosted endpoint test

Some teams are not blocked by Hermes itself. They are blocked by payment rails, provider onboarding, or the time cost of getting one working endpoint before debugging the client. In that narrower case, it is useful to separate access friction from framework friction.

See the $5 starter flow Open Hermes DeepSeek guide See integration recipes

Reduce one variable at a time

Do not debug provider signup, billing, model discovery, framework routing and tool behavior all at once. First prove one endpoint can answer one request. Then expand.

Create account