Connect Hermes Agent to 9Router

Hermes Agent can connect to 9Router through its Custom endpoint provider setup. You need a running 9Router instance, a local router API key if authentication is enabled, and a model identifier exposed by that instance. Configure the provider with hermes model outside an active chat session.

These steps are checked against the linked configuration documentation. They are not a claim that a paid model call or a complete autonomous task was run for this guide.

Prepare the router before opening Hermes

Start 9Router and connect one provider. Verify the model list from the same machine where Hermes will run:

curl -i http://localhost:20128/v1/models \
  -H "Authorization: Bearer $NINEROUTER_API_KEY"

Set NINEROUTER_API_KEY in your shell to your router-issued key before using the example. Do not substitute an upstream provider secret unless your router’s documentation specifically requires it. Choose one exact model identifier returned by this request. A combo is better added after the first explicit model works.

If the request is refused, the problem is below Hermes: check the process, address, port, and network. An HTTP 401 means something answered but did not accept the authentication. An empty catalog calls for checking the provider and model configuration.

Configure the custom endpoint

Run this in your terminal after leaving the current Hermes conversation:

hermes model

Choose Custom endpoint, enter http://localhost:20128/v1 as the base URL, supply the local router key, and select or enter the verified model ID. For the OpenAI-compatible route described here, choose Chat Completions when the wizard asks for the API mode or transport. Do not select Responses or Anthropic Messages unless you have deliberately configured and verified that different protocol. Follow the remaining wizard prompts rather than overwriting your whole configuration file.

Hermes stores configuration beneath ~/.hermes/; its documentation distinguishes config.yaml settings from .env secrets and OAuth credentials. Back up your existing settings before changing providers. Never commit these private files to a repository or paste them into a public issue.

After configuration, start a fresh Hermes session. Use a short prompt first. Then try a harmless tool task in a disposable directory, such as listing a few test files. Confirm that the model returns a usable tool call and that the tool result reaches the next model turn.

Why does /model not add my new provider?

/model inside a session switches already-configured providers and models. hermes model in the terminal performs setup, including adding credentials and custom endpoints. This distinction is documented in Hermes provider setup.

If the new route is missing, leave the session, run the setup command, and start a new session. Also check which profile or configuration directory the running process uses. A setting written for one environment does not necessarily affect another terminal, container, or service.

When Hermes runs in a container

localhost inside a container refers to that container. It does not automatically refer to the host running 9Router. Use an address reachable from the agent’s environment, with the appropriate Docker network or host access configuration.

Test the model-list request inside that environment before modifying Hermes again. Keep the route protected if it is reachable beyond your own computer. Do not publish an unauthenticated dashboard just to solve a local networking problem.

Check tools and auxiliary requests

Some agent features make additional model or service calls. Review Hermes’ auxiliary-model settings if text chat succeeds but vision, summarization, or another capability fails. The main model selection does not establish that every auxiliary feature uses the same provider or supports the same inputs.

Watch the router’s request log during a small test. If no request arrives, inspect Hermes’ selected provider and endpoint. If a request arrives and fails, preserve the error code, selected model, and minimal redacted payload. For an HTTP 400, reduce optional parameters before testing tools or reasoning again.

Add fallback only after the baseline works

Save the working endpoint and explicit model. Configure a compatible combo in 9Router, select it in Hermes, and repeat the same small task. Verify the actual route after a failure rather than assuming the backup was used. If the new setup breaks, return to the previous explicit model and compare the requests. The fallback guide covers that check in more detail.