Hermes Agent

Hermes Agent, from Nous Research, talks to custom endpoints in three formats: Chat Completions, Anthropic Messages and Responses. This guide uses Chat Completions with the base URL https://deference.si/v1.

Set up

1. Create a key in API keys.
2. Add the key to ~/.hermes/.env. Hermes reads secrets from this file, not from config.yaml.

DEFERENCE_API_KEY=sk-df-...

3. Add the provider and make it the default model in ~/.hermes/config.yaml.

providers:
  deference:
    api: https://deference.si/v1
    key_env: DEFERENCE_API_KEY
    transport: chat_completions
    models:
      "anthropic/claude-sonnet-5.5":
        context_length: 200000

model:
  default: anthropic/claude-sonnet-5.5
  provider: custom:deference

Run hermes config path and hermes config env-path to print where Hermes keeps these two files on your system.

To set it up by prompts instead, run hermes model and choose Custom endpoint. It asks for the base URL, the key and the model, and for the API format.

Verify

1. Run hermes doctor. It exits cleanly when nothing needs fixing.
2. Run hermes status. It shows the model and provider, and that credentials are present, without printing the key.
3. Start hermes and send a short message.
4. Open Activity. The request is the top row, with the model you chose.

Pick a model

• Hermes needs a context window of at least 64K tokens and refuses smaller ones at startup. List only models that meet it, and set context_length for each, because Hermes does not read it from GET /v1/models.
• Switch models in a session with /model custom:deference:anthropic/claude-sonnet-5.5. Add --global to keep the choice.
• transport can also be anthropic_messages or codex_responses. For anthropic_messages, the base URL is https://deference.si, without /v1. Set transport explicitly: Hermes otherwise guesses it from the URL.

Troubleshooting