How to Configure Hermes Agent with OpenRouter

OpenRouter Is the Recommended Starting Point for Hermes

When you first set up Hermes Agent, you need to point it at an LLM provider. The official quickstart supports Nous Portal, OpenRouter, OpenAI, Anthropic, and any OpenAI-compatible endpoint. In practice, OpenRouter is the best choice for most users, especially on a first deployment.

The reason is simple: OpenRouter is a single API key that gives you access to hundreds of models from different providers. Instead of managing separate accounts with OpenAI, Anthropic, and Nous Portal, you get one billing interface, one API key, and a model switcher that does not require reconfiguring Hermes every time you want to try something different.

For a self-improving agent like Hermes, which is designed to get better over time, being able to swap models without infrastructure changes is useful. You can start with a cheaper model for everyday use and switch to a more capable one for complex tasks without touching your Hermes installation.

Getting Your OpenRouter API Key

The setup is quick:

1. Go to openrouter.ai and create an account.
2. Navigate to Settings → API Keys and generate a new key.
3. Copy the key, it starts with sk-or-.
4. Add credits to your account. OpenRouter supports pay-as-you-go billing, so you can start with a small amount.

The key you copy is what you will provide to Hermes (or to Hermify if you are using managed hosting) as OPENROUTER_API_KEY.

Configuring Hermes to Use OpenRouter

If you are running Hermes locally, the configuration happens in your config.yaml file. The relevant section looks like this:

provider: openrouter
model: anthropic/claude-3-5-sonnet
openrouter_api_key: sk-or-your-key-here

You can also use the interactive setup command:

hermes setup

This walks you through choosing a provider and model, and writes the configuration for you. If you want to change the model later without running the full setup again, you can use:

hermes model

This opens a model picker without resetting the rest of your configuration.

Choosing the Right Model on OpenRouter

OpenRouter exposes hundreds of models. The right choice depends on your use case and budget. Here are the practical options for Hermes:

Best general-purpose models on OpenRouter:

• anthropic/claude-3-5-sonnet, Strong reasoning, follows multi-step instructions well, good for complex workflows. This is the model most Hermes users start with.
• openai/gpt-4o, Fast, capable, good for code and structured tasks.
• meta-llama/llama-3.1-70b-instruct, Open-weights, lower cost per token, good for high-volume workflows.
• nousresearch/hermes-3-llama-3.1-405b, Nous's own Hermes-family model. Naturally fits the Hermes Agent system prompts, since both come from the same lab.
• google/gemini-2.0-flash, Fast and cheap, good for latency-sensitive applications.

Budget approach: Start with llama-3.1-70b-instruct for daily use. Switch to Claude or GPT-4o for tasks that require stronger reasoning or longer context windows.

The Nous model approach: nousresearch/hermes-3-llama-3.1-405b is worth testing specifically because the Hermes agent runtime was built around Nous models. The alignment between the agent's prompting style and the model's training tends to be tighter than with third-party models.

OpenRouter-Specific Configuration Tips

A few things that matter specifically for OpenRouter with Hermes:

Set a provider preference. OpenRouter routes requests to multiple infrastructure providers. If you are using Anthropic models, you can pin to Anthropic's own infrastructure by setting provider_order in your config. This reduces latency variance.

Configure fallback models. Hermes supports auxiliary providers in config.yaml. This means if your primary model is unavailable, Hermes can fall back to a secondary. With OpenRouter, you can specify multiple models as fallbacks under auxiliary_providers.

Watch your context window. Hermes uses persistent memory and context files, which means prompts can be long. Models with smaller context windows (under 32k tokens) can hit limits faster than expected. If you notice responses that seem to ignore recent context, the model may be truncating your memory file. Switch to a model with a larger context window, Claude and Gemini both offer 128k+.

Common Configuration Mistakes

Using the wrong base URL. Hermes expects an OpenAI-compatible endpoint. OpenRouter's base URL is https://openrouter.ai/api/v1. Some users accidentally use the OpenAI URL, which causes authentication failures with OpenRouter keys.

Forgetting the HTTP-Referer header. OpenRouter requires a HTTP-Referer header in API requests to identify your application. Hermes handles this automatically when you configure openrouter as the provider, but if you are using a custom endpoint setup, you need to add this header manually.

Quota exhaustion mid-session. OpenRouter blocks requests when your credits run low, which Hermes surfaces as an error in the terminal or messaging interface. Adding a small auto-reload threshold in OpenRouter settings prevents this from interrupting long workflows.

Picking a model that does not support tool calls. Hermes relies on tool use for many of its capabilities (file writes, web fetches, scheduled tasks). Some cheaper models on OpenRouter do not support tool calling. Check the model's capability flags on the OpenRouter model page before switching.

What Changes if You Use Managed Hosting

If you deploy Hermes through Hermify, the provider configuration works the same way, but you enter your OpenRouter API key through the onboarding dashboard instead of editing a config file. Hermify stores it encrypted and injects it into the runtime at startup.

You can also update your provider key or switch models from the Hermify dashboard without restarting the container manually. This is the main operational difference: instead of SSH access to edit config.yaml, you use the settings UI, trigger a restart, and the change takes effect in seconds.

The Starter plan is specifically designed around BYOK with OpenRouter, you bring the key, Hermify handles everything else. If you want to skip the OpenRouter account entirely, the Pro and Dedicated plans include model access so you do not need to set up a third-party provider at all.

A Practical Starting Configuration

If you want a solid default and do not want to spend time comparing models, this is the configuration that works well for most Hermes users on OpenRouter:

• Provider: OpenRouter
• Model: anthropic/claude-3-5-sonnet for primary use
• Fallback: meta-llama/llama-3.1-70b-instruct
• Context window: 200k tokens (Claude supports this)
• Initial credit load: $10–$20 (typically lasts several weeks of regular use)

From there, you can tune the model as you understand your own usage patterns better. Hermes is designed for long-running sessions, so the model you pick affects memory quality and tool reliability, not just response speed.

If you want to skip the configuration work and get to a working Hermes deployment faster, Hermify handles the provider wiring for you. You can also read more about the real cost difference between self-hosted and managed Hermes deployments before deciding.