Tutorial 28: Provider Configuration | Easy Understand Hermes Agent

This is part of the Hermes Agent official tutorial series. View all tutorials

Think of Hermes as a chef with two sets of tools: a main knife for chopping everything, and smaller specialty tools for peeling, coring, and garnishing. In Hermes, the main knife is your main model (the brain), and the specialty tools are auxiliary models (helpers for side-tasks like summarizing web pages or analyzing images). This tutorial shows you how to pick and configure both — without touching a single config file if you don’t want to.

What you’ll learn

How to set your main model (the one that thinks and talks)
How to assign auxiliary models for background jobs
How to switch models mid-conversation
How to use the dashboard, CLI, or config files (pick your style)

Step 1: Open the Models page

Log into the Hermes dashboard and click Models in the sidebar. You’ll see two sections:

Model Settings — the top panel where you assign models to slots.
Usage analytics — a ranked list of every model you’ve used, with token counts and costs.

The top card is where you’ll spend most of your time. The Main model row shows what new sessions will use. Click Change to open the picker.

Step 2: Pick your main model

The picker has two columns:

Left side: providers you’ve already connected (API key set, OAuth’d, or custom endpoint). If you don’t see a provider, go to Keys and add its credential first.
Right side: a curated list of recommended agentic models for that provider. Hermes filters out junk like TTS or image generators — you only see models that actually work well for agent tasks.

Type in the filter box to search by provider name, slug, or model ID. Click a model, hit Switch, and Hermes saves it to ~/.hermes/config.yaml under the model section.

Important: This change applies to new sessions only. Your current chat tab keeps running its original model. To hot-swap mid-conversation, use the /model slash command inside the chat.

Step 3: Understand the two model slots

Hermes uses two kinds of model slots:

Slot	What it does	Example
Main model	The brain — handles every user message, tool call, and streamed response	GPT-4o, Claude 3.5 Sonnet
Auxiliary models	Side-jobs — compression, vision, web summarization, approval scoring, MCP routing, session titles, skill search	A cheaper, faster model like GPT-4o-mini

Each auxiliary slot can be overridden independently. So you can use a big expensive model for thinking, but a tiny cheap one for summarizing web pages.

Step 4: Configure auxiliary models

On the same Model Settings panel, you’ll see rows for each auxiliary task. Click Change next to any of them to assign a different model. For example:

Vision → use a model with image understanding
Context compression → use a fast, cheap model (this runs often)
Session-title generation → any small model works

You don’t have to configure all of them — Hermes uses sensible defaults. But if you want to save money or speed things up, this is where you do it.

Step 5: The “empty string” gotcha (new installs)

On a fresh install, your config has model: "" — a placeholder meaning “not configured yet.” The first time you run hermes setup or hermes model, Hermes upgrades that to a proper mapping with provider, default, base_url, and api_mode.

If you ever see an empty string in config.yaml, just run:

hermes model

…or click Change in the dashboard. Hermes will write the correct format for you.

Step 6: Fastest path — Nous Portal

If you want 300+ models under one subscription, use Nous Portal:

hermes setup --portal

This logs you in and sets Nous as your provider in one command. Check what’s connected with:

hermes portal info

Portal subscribers also get 10% off token-billed providers — a nice bonus.

Step 7: Mid-session switches and warnings

When you switch models inside an active session (via the TUI picker, CLI, or /model on Telegram/Discord), Hermes checks whether your next message will need preflight context compression — that is, it estimates if your current conversation is too long for the new model’s window. If it is, Hermes will compress the context first so you don’t lose history.

Summary

You now know how to:

Set your main model from the dashboard
Assign auxiliary models for background tasks
Switch models mid-session with /model
Use Nous Portal for one-command setup
Handle the empty-string config on new installs

Next up: Tutorial 29 — Context Compression & Memory Management. We’ll dive into how Hermes keeps long conversations smart without blowing your token budget.