Skip to content
BSWEN
Blog

Hermes Agent Model Configuration: DeepSeek, Ollama, Claude & OpenRouter

- Last update:
Cowrie
Cowrie
Dev @ Bswen

A digital artwork depicting the synergy between the human brain and artificial intelligence

Quick Answer

  • hermes setup — interactive first-time configuration: pick a provider, enter your API key, and you’re done.
  • hermes model — terminal provider/auth/model setup.
  • /model — switch among already-configured models inside an active Hermes chat.
  • ~/.hermes/config.yaml — non-secret settings, including the persistent model configuration.
  • ~/.hermes/.env — where API keys and secrets live (never in config.yaml).

The full flow in three commands:

Terminal
hermes setup              # guided first-time setup (provider + API key)
hermes model              # provider/auth/model setup
cat ~/.hermes/config.yaml # see the persistent model config

The Problem: Too Many LLM Providers, Confusing Configuration

Hermes Agent supports many LLM backends—DeepSeek, Ollama, Claude, OpenRouter, and more. Each provider has different setup requirements, different API key locations, and different model name formats.

I made several mistakes:

  1. Put the API key in the wrong file
  2. Used incorrect model name prefixes
  3. Forgot to start Ollama before configuring it

These mistakes cost me hours of debugging. Let me save you that time.

How Model Configuration Is Stored

Hermes Agent separates two concerns:

  • Model and provider settings (non-secret) live in ~/.hermes/config.yaml.
  • API keys and secrets live in ~/.hermes/.env — a plain file that should never be committed to Git.
~/.hermes/config.yaml
model:
  provider: anthropic
  default: claude-sonnet-4-6
~/.hermes/.env
ANTHROPIC_API_KEY=sk-ant-your-key-here

You can open the config file with hermes config edit or edit ~/.hermes/config.yaml directly. In the YAML, the model is a nested block: provider selects the backend and default is the model name on that provider. hermes config set model <provider>/<model> is a convenient CLI shortcut that writes to this structure, but the provider/model string is not the underlying single source of truth.

Provider Configuration

The setup differs by authentication flow: API-key providers (DeepSeek, Claude, OpenRouter) need a key in ~/.hermes/.env; OAuth providers authenticate interactively through hermes model; local/custom endpoints (Ollama) need no key at all. After configuring, verify with hermes chat.

DeepSeek

Terminal
hermes config set model deepseek/deepseek-chat
~/.hermes/.env
DEEPSEEK_API_KEY=sk-your-key-here

Model IDs change over time, so treat deepseek-chat as an example and verify the current model IDs in the provider catalog (for example, the DeepSeek Platform) before configuring. DeepSeek is popular for its low cost, but the setup is identical to any other API-key provider.

Ollama (Local)

Terminal
ollama serve   # start the Ollama server FIRST
hermes model   # then pick Custom endpoint → http://localhost:11434/v1

Ollama runs models locally: zero API fees, full privacy, and offline support. Configure it by starting ollama serve, then running hermes model and choosing Custom endpoint with http://localhost:11434/v1. No API key is needed for local models.

Claude

Terminal
hermes config set model anthropic/claude-sonnet-4-6
~/.hermes/.env
ANTHROPIC_API_KEY=sk-ant-your-key-here

OpenRouter

Terminal
hermes config set model openrouter/anthropic/claude-sonnet-4-6
~/.hermes/.env
OPENROUTER_API_KEY=sk-or-your-key-here

OpenRouter fronts many providers behind one API key, so you can switch models without changing keys — just update the model name.

How to Change the Model in Hermes Agent

This is the flow I use most. There are a few ways to change the model.

1. Terminal setup

Terminal
hermes model

hermes model is the terminal provider/auth/model setup: it walks you through choosing a provider, entering your API key (or a custom endpoint such as Ollama’s), and selecting the model. Your choice is saved to ~/.hermes/config.yaml.

2. /model inside a chat

Inside an active Hermes chat, /model switches among already-configured models without leaving the session. It’s the quickest way to hop between models once everything is set up.

3. Direct command

Terminal
hermes config set model openrouter/anthropic/claude-sonnet-4-6

hermes config set model <provider>/<model> is a convenient CLI shortcut where supported — it writes the same provider/default block into ~/.hermes/config.yaml. For local models, use hermes model and pick Custom endpoint → http://localhost:11434/v1 instead.

Check the current model

Terminal
hermes config
cat ~/.hermes/config.yaml

When you change providers, make sure the matching API key exists in ~/.hermes/.env (see below).

API Key Configuration

API keys go in ~/.hermes/.env — not in config.yaml. I learned this the hard way when I almost committed my key to Git. Hermes writes secret values to ~/.hermes/.env automatically when you run hermes setup or hermes config set <ENV_VAR> <value>:

Terminal
hermes config set OPENROUTER_API_KEY sk-or-your-key-here

Or edit the file directly:

Terminal
mkdir -p ~/.hermes
echo 'DEEPSEEK_API_KEY=sk-your-key-here' >> ~/.hermes/.env

Each provider needs its own key:

ProviderEnv var
DeepSeekDEEPSEEK_API_KEY
ClaudeANTHROPIC_API_KEY
OpenRouterOPENROUTER_API_KEY
Ollamanone (local models only)

Auxiliary Models (Optional)

Hermes also uses separate models for side tasks like vision/image analysis and web content extraction. The defaults work fine for most people, so you usually don’t need to touch this. If you do want to customize, hermes model → Configure auxiliary models is easier than manually editing YAML. In config.yaml, each auxiliary task uses its own provider and model (note: auxiliary tasks use model, not default):

~/.hermes/config.yaml
auxiliary:
  vision:
    provider: openrouter
    model: google/gemini-2.5-flash

Delegation is configured separately with the top-level delegation.provider / delegation.model, not under auxiliary.

Setting a cheap model for side tasks keeps them from burning through your premium provider budget.

Troubleshooting

Unknown model or provider

If Hermes reports an unknown provider, check the model name for typos and make sure the provider prefix is present:

Terminal
hermes config set model deepseek/deepseek-chat   # correct
hermes config set model deepseek-chat            # missing provider prefix

Missing API key

If you see a missing API key error, the key for that provider isn’t in ~/.hermes/.env. Add it — hermes config set <ENV_VAR> <value> writes it to ~/.hermes/.env automatically — and restart Hermes:

Terminal
hermes config set DEEPSEEK_API_KEY sk-your-key-here

Ollama connection refused

A connection refused error almost always means the Ollama server isn’t running:

Terminal
ollama serve

Keep ollama serve running in its own terminal, then retry. If the model isn’t downloaded yet, fetch it first:

Terminal
ollama pull llama3.3

Also make sure Hermes is pointed at Ollama’s custom endpoint (hermes model → Custom endpoint → http://localhost:11434/v1).

Ollama context window too small

Hermes Agent requires models with at least a 64K context window. A local model may run successfully in Ollama but still be rejected by Hermes if its configured context is too small. Check the model’s configured context size on the Ollama side before using it with Hermes.

Invalid model name

The model name must exist on the provider you picked. Model IDs change over time, so verify the current ones against the provider’s catalog — for example deepseek/deepseek-chat and anthropic/claude-sonnet-4-6 are valid, while a made-up name will fail. On OpenRouter, keep the vendor prefix: openrouter/anthropic/claude-sonnet-4-6, not openrouter/claude-sonnet-4-6.

Verifying Your Configuration

After any change, verify:

Terminal
# Show current config
hermes config


# Check environment variables
cat ~/.hermes/.env


# Test the connection
hermes chat "Hello, are you working?"

Summary

Configuring Hermes Agent with different LLM providers is straightforward once you know where things live. Non-secret model/provider settings go in ~/.hermes/config.yaml (set them with hermes model or hermes config set model provider/model), API keys and secrets go in ~/.hermes/.env, hermes setup handles first-time configuration, and /model switches models inside an active chat. Use this checklist:

  • Model config → ~/.hermes/config.yaml (via hermes model or hermes config set model <provider>/<model>)
  • API keys → ~/.hermes/.env (via hermes setup, hermes config set <ENV_VAR> ..., or direct edit)
  • Change model → hermes model, or /model inside a chat, or hermes config set model ...
  • Ollama → start ollama serve, then hermes model → Custom endpoint → http://localhost:11434/v1

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: