The Hermes subagent model is the AI model your Hermes Agent child agents run on when the main agent hands work out with the delegate_task tool.
By default it is simply the same model as your main agent, with the same provider and the same keys.
You change it with one setting, delegation.model, and you can set that in three places: the config file, the hermes model picker or the Desktop app.
This page is the operator walkthrough for all three routes, plus the extra settings that decide how a pinned subagent behaves when something goes wrong.
Hermes Agent is the free, open-source agent from Nous Research, and everything below comes from Nous's own documentation, not from guesswork.
The Hermes Subagent Model Setup At A Glance
Here is the whole job on one screen, so you can see which route fits you before you read the detail.
| Step | What you do | Where it lives |
|---|---|---|
| 1 | Check what your subagents run on today, which is your main model unless something is pinned. | delegation: block in ~/.hermes/config.yaml |
| 2 | Pin one subagent model in the config file. | delegation.model plus optional delegation.provider |
| 3 | Or pin it with the interactive picker instead of editing YAML. | hermes model → Configure auxiliary models → delegation |
| 4 | Or pin it in the Desktop app for one profile. | Settings → Model → Subagents |
| 5 | Point subagents at a direct endpoint, such as a local model, if you need privacy. | delegation.base_url plus delegation.model |
| 6 | Give pinned subagents their own fallback chain. | delegation.fallback_providers |
| 7 | Start a fresh session and watch which model the children actually use. | The live subagent dock or /agents |
The rest of this walkthrough takes each step in order.
What The Hermes Subagent Model Actually Controls
When your main agent calls delegate_task, Hermes spawns child agents that each get a fresh conversation, their own terminal session and the parent's enabled tools.
The subagent model is the brain inside each of those children.
It doesn't touch your main chat, which keeps running on whatever you set with hermes model as your default.
The docs make the default plain: if you don't set a delegation model, subagents use the same model as the parent.
They also inherit the parent's API key, provider configuration and credential pool, which means key rotation on rate limits still works for children.
That default is safe, but it isn't free.
Nous's delegation page says a parallel batch of subagents typically burns the large majority of a run's total tokens.
So if your main agent sits on a top frontier model, every child summarising a web page sits on that frontier model too.
That is the main reason operators pin a separate Hermes subagent model.
If you're new to how subagents work in general, my sibling post on Hermes Agent subagents covers delegate_task itself.
🔥 Want my exact Hermes Subagent Model setup, step by step? Inside the AI Profit Boardroom you get step-by-step video trainings, my installable Agent OS and four coaching calls a week with 3,400+ members building real automations. → Join the AI Profit Boardroom
Step 1: Check What Your Subagents Run On Now
Open ~/.hermes/config.yaml and find the delegation: block.
If model and provider are empty or commented out, your subagents inherit the main model.
The configuration reference describes the precedence in one line: delegation.base_url first, then delegation.provider, then the parent's provider.
For the model, delegation.model wins, and an empty value falls back to the parent's model.
If you prefer to look rather than read YAML, the hermes model picker shows the delegation entry as "auto / inherit main agent" when nothing is pinned.
Write down what you find, because it tells you whether a change you make later actually took effect.
Step 2: Pin One Subagent Model In config.yaml
This is the cleanest route for anyone comfortable with a text editor.
The official docs give this exact pattern, which they call frontier planner, inexpensive workers.
# ~/.hermes/config.yaml
model:
default: "your-frontier-model" # parent (planner) stays on the frontier model
delegation:
model: "your-inexpensive-model" # all delegate_task children run on this
provider: "openrouter" # optional: route children to a different provider
Swap the placeholder names for real model ids from a provider you already have credentials for.
The reasoning behind the pattern is simple and it comes straight from the docs.
Splitting a problem into well-specified subtasks takes frontier-level judgment.
Doing a subtask that already has a clear goal, full context and an output format usually doesn't.
If you set model without provider, Hermes changes only the model name and keeps the parent's credentials.
The configuration reference says that is useful for switching models inside the same provider, such as OpenRouter.
If you set provider too, Hermes resolves that provider's full credential bundle, including the base URL, key and API mode.
Step 3: Pin It With The hermes model Picker
If you'd rather not touch YAML, run the picker.
hermes model
Choose Configure auxiliary models, and you'll see a list of side tasks such as vision, compression and approval, with delegation at the bottom.
The configuration reference says the delegation entry is special, because it writes to the top-level delegation.provider and delegation.model keys rather than auxiliary.*.
That is because subagents are full child agents, not side calls to a model.
Pick a provider, pick a model, and the picker finishes with a reasoning-effort step.
The docs say that effort is stored as delegation.reasoning_effort, and there is a Provider default row if you'd rather leave the level to the provider.
Choosing auto puts you back on inherit, which means the parent's provider, model and credentials.
Step 4: Pin It In The Desktop App
Desktop users get the same settings on one page.
Open Settings → Model → Subagents to choose the provider and model for delegated agents.
The same page also adjusts the subagent turn limit, concurrency, timeout and reasoning effort.
Pick the profile you want to change under Applies to, because the catalogue and saved changes belong to that profile.
Your choices stay a local draft until you click Apply, and cancelling or leaving the page throws the draft away.
The docs list three routes on that page, and they map cleanly to the YAML keys.
| Desktop option | What it does | YAML equivalent |
|---|---|---|
| Inherit from main agent | Subagents use the parent's model and credentials. | delegation.model and delegation.provider left empty |
| Custom model (use parent credentials) | It overrides only the model and keeps the parent's keys. | delegation.model set, provider empty |
| A provider plus a model | It routes children to a different provider with that provider's credentials. | delegation.provider and delegation.model set |
| Direct endpoint override | It shows an existing direct endpoint you set up earlier. | delegation.base_url plus delegation.model |
The docs add that a change only affects subagents launched after you click Apply.
It never changes your main model or a child that is already running.
🔥 Want my Hermes setups done with you, step by step? Inside the AI Profit Boardroom, I've got a full Hermes Agent course plus the Agent OS, with video walkthroughs on profiles, models and subagents. You'll be learning alongside 3,400+ members with four coaching calls every week. → Get access here
Step 5: Send Subagents To A Local Model Or Direct Endpoint
Sometimes the right Hermes subagent model is one that never leaves your machine.
For that, the docs give a direct custom endpoint pattern.
delegation:
model: "qwen2.5-coder"
base_url: "http://localhost:1234/v1"
api_key: "local-key"
The direct endpoint takes precedence over delegation.provider.
If you leave out api_key, the configuration reference says Hermes falls back to OPENAI_API_KEY only.
When base_url points at an Anthropic-compatible endpoint, such as a path ending in /anthropic, Hermes auto-detects the anthropic_messages wire format.
For endpoints the heuristic can't classify, you set delegation.api_mode to chat_completions, codex_responses or anthropic_messages.
Keep in mind that a key written in config.yaml sits there in plain text, so a named provider is tidier when you have one.
Step 6: Give Pinned Subagents Their Own Fallback Chain
This step catches people out, so read it twice.
The configuration reference says an explicitly pinned child, by provider, endpoint or model, only uses a fallback chain when you declare one.
Without that list, a pinned child fails loudly instead of borrowing the parent agent's route.
An unpinned child is different, because it still inherits the parent's fallback chain.
You declare the chain with delegation.fallback_providers, which uses the same entry shape as the top-level fallback list.
Setting fallback_providers: [] under delegation: switches child fallback off completely.
If a child does fail, the docs say it is never silent.
The CLI prints a one-line reason, gateway chats get a notice, and the parent receives status: "failed" with the error text so it can retry or re-route.
Step 7: Start A New Session And Check The Result
I start a fresh chat after any change, so the test isn't mixed up with work that began on the old settings.
Give your agent a job that naturally splits into parts, such as researching three competitors at once.
In the classic CLI, Ctrl+T or F6 opens the live roster of subagents, and the TUI has the /agents overlay with per-branch cost and token rollups.
In Desktop, a Subagents frame appears above the composer while workers are live.
My second video below shows those live controls in action, including steering a worker without killing the run.
The Catch: One Pin Covers Every Subagent
The delegation page is honest about the limit.
With the default strategy, delegate_task has no per-task model parameter, so every child in a batch runs on the same delegation model.
That is fine when your subagents all do similar work, like summarising pages or checking links.
It hurts when one task in the batch is a hard debugging job that needs a stronger brain.
The docs give you three ways around it.
- Leave
delegation.modelunset for that session, so children inherit your strong main model. - Use a delegation strategy plugin, such as the official advanced-delegation plugin with its model routes and profile routes.
- Hand the task to the kanban board, which supports a per-task model override with
hermes kanban set-model.
The plugin route is big enough to deserve its own page, so I wrote one on Hermes advanced delegation.
Other Settings That Shape How A Subagent Model Behaves
A few more delegation keys change how the model inside each child behaves.
delegation.request_overridessends extra request settings on every subagent call, such as OpenRouter routing hints likesort: throughput.delegation.max_iterationscaps how many tool-calling turns each child can take, and the docs give 250 as the default.delegation.compression_threshold_tokensadds an optional cap on when a child compacts its context, and it stays off by default.auxiliary.reviewpins a separate model for the/reviewreviewer subagent, which otherwise runs on your main model.
None of these are required, so add them only when you hit the problem they solve.
Which Model Should Your Subagents Run On?
I won't quote prices here, because they change too often, so check your provider's current pricing.
This is how I'd think about the choice for each kind of subagent job.
| Subagent job | What matters most | A sensible pick |
|---|---|---|
| Web research and summaries | Speed and low cost | A fast, inexpensive model |
| Coding and refactors | Tool use and code quality | A strong coding model |
| Hard debugging and design | Reasoning quality | Your best model with high reasoning effort |
| Private or client data | Data staying on your hardware | A local model through base_url |
For actual model names, my best Hermes Agent model guide ranks the options I've looked at.
If your subagents run shell commands on real files, read my Hermes Agent sandbox walkthrough first, because the model choice doesn't make a bad command any safer.
Common Problems And Fixes
My subagents still use the main model.
Check that you saved the change to the profile you're actually running, because every Hermes profile has its own config.yaml.
A subagent fails with a model-not-found error.
The model id doesn't exist on that provider, so pick it from the hermes model catalogue instead of typing it.
A pinned subagent stops when its provider is down.
That is the designed behaviour, so add delegation.fallback_providers if you want a backup.
The local endpoint gets the wrong wire format.
Set delegation.api_mode explicitly for that endpoint.
If you'd like a second pair of eyes on how agents fit your SEO business, you can book a free SEO strategy session with my team.
🔥 Want help picking the right subagent models for your business? The AI Profit Boardroom has Hermes Agent training, the Agent OS and four weekly coaching calls where you can ask me which models to give your workers. → Join the AI Profit Boardroom
Related Reading
- Hermes Agent subagents explains what a subagent is and how
delegate_taskworks. - Hermes advanced delegation covers model routes and profile routes for a different model per task.
- The best Hermes Agent model ranks the brains worth plugging in.
- Hermes Agent v0.22 covers the release line the newest delegation features build on.
Also On Our Network
- 🌐 How a business can cut agent costs with the right Hermes subagent model
- 🌐 Every Hermes subagent model option, scored with a verdict
- 🌐 The Hermes subagent model quick start for an Agent OS
- 🌐 Which subagent models score best on GoldieBench
- 🌐 My Hermes agent swarm setup on the AI Profit Boardroom blog
FAQ: Hermes Subagent Model
What model do Hermes subagents use by default?
They use the same model as the parent agent.
They also inherit the parent's API key, provider configuration and credential pool.
How do I change the Hermes subagent model?
Set delegation.model, and optionally delegation.provider or delegation.base_url, in ~/.hermes/config.yaml.
You can also use hermes model → Configure auxiliary models → delegation, or Settings → Model → Subagents in Desktop.
Can each Hermes subagent use a different model?
Not with the default strategy, because one pin covers every child in a batch.
The advanced-delegation plugin's routes or the kanban board's per-task model override give you a different model per task.
Can a Hermes subagent run on a local model?
Yes, because delegation.base_url plus delegation.model sends children to any OpenAI-compatible endpoint, including one on your own machine.
What happens if a pinned subagent model fails?
A pinned child only falls back when you declare delegation.fallback_providers.
Without that list it fails loudly, and the parent sees status: "failed" with the error.
If you run an agency and want help mapping agents to your client work, you can book a free strategy session and we'll talk it through.
📺 Video notes + links to the tools 👉
🎥 Learn how I make these videos 👉
🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉
About Julian
I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.
I help business owners scale with AI agents, automation and SEO.
- I've built a 7-figure SEO and link-building agency, Goldie Agency, with 70+ people in Bangkok.
- I've grown a YouTube channel to 400,000+ subscribers.
- I wrote the book "Link Building Mastery", which covers nine link building strategies.
- I run GoldieBench, where I score AI models on real one-shot builds.
→ Get my best AI training inside the AI Profit Boardroom
Check what you inherit, pin one cheaper model, add a fallback chain, and you'll have a Hermes subagent model that does the volume work without burning your budget.
