Use Gonka Broker with Hermes Agent

Use a separate test path first

Do not replace a working Hermes provider on the first attempt. Add Gonka Broker as a custom endpoint, run bounded tests, and keep the existing provider available as a fallback. This is especially important for scheduled jobs and tool-heavy sessions.

Add a named provider without changing the default

Run hermes config env-path and store the key in that local environment file:

GONKA_BROKER_API_KEY=<your Gonka Broker key>

Keep the environment file private with mode 0600. Then run hermes config edit and add a named provider entry. Do not change model.provider, model.default or another working default:

custom_providers:
  - name: gonka_broker
    base_url: https://api.gonka.broker/v1
    key_env: GONKA_BROKER_API_KEY
    model: gonka-auto
    api_mode: chat_completions

If custom_providers already exists, add this item to the existing list rather than creating a duplicate YAML key. Run hermes config check after saving.

Run an explicit bounded smoke test

hermes chat \
  --provider custom:gonka_broker \
  --model gonka-auto \
  -t terminal \
  -Q \
  -q "Reply with exactly: Gonka route OK"

The explicit provider and model flags keep the existing default unchanged. Confirm that the reply is non-empty, then inspect the Gonka Broker dashboard for the corresponding usage record. Start with one short request rather than a full default-tool workload.

Expand the test in stages

1. One short non-streaming prompt
2. A longer answer with an explicit output limit
3. Streaming, if your Hermes workflow depends on it
4. One small tool-enabled session
5. The exact recurring task you plan to run

A model can answer a simple prompt successfully and still behave differently with a large system prompt, many tools or long context. Validate the real workload before assigning background automation.

Protect keys and spending

• Create a dedicated key for Hermes.
• Reference it with key_env; never put the key itself in config.yaml, public commands or chat.
• Set a small prepaid allowance and review usage after testing.
• Use bounded retries and finite request timeouts.
• Do not enable unattended cron jobs until manual tests pass.

Good first workloads

Short summaries, classification, drafting and bounded research preparation are practical starting points. Keep a fallback for tasks requiring a specific capability or highly predictable route behavior. OpenAI compatibility simplifies configuration, but it does not prove that every model and tool workload behaves identically.

Troubleshooting

Run hermes doctor if the provider is not available or configuration is incomplete. Authentication errors usually indicate an API key or endpoint problem; repeated temporary errors should trigger a fallback or operator review rather than an unlimited retry loop. See the Hermes provider documentation, the Gonka Broker API docs, and current pricing.

Next step: Create an account or read the integration docs.