A Hermes Agent fallback model is a backup provider and model pair that Hermes switches to on its own when your main model fails, so the conversation carries on instead of dying on a rate limit, an outage or an expired login.
📺 Watch: NEW Hermes Marketplace is INSANE! 🤯
🔥 Get the Agent OS as a free bonus: AI Profit Boardroom members get the full Agent OS zip, prompt libraries, daily tutorials and weekly live coaching calls. → Get inside
This guide sets one up from scratch with the official Fallback Providers docs: the command, the config, what makes it fire, the separate fallback for side tasks, and how to prove the chain works before you need it.
Julian Goldie walks members through agent setups like this one inside the AI Profit Boardroom, with step-by-step trainings and weekly coaching calls. If you want a second pair of eyes on your model plan first, book a free AI strategy session.
What a fallback actually does in Hermes
Hermes has three separate layers that keep a session alive when a provider has a bad day.
- Credential pools rotate between several API keys on the same provider. They are tried first.
- Primary model fallback moves the main conversation to a different provider and model.
- Auxiliary task fallback covers side jobs such as vision, compression and approval checks.
Step 1: Add a backup with the hermes fallback command
Open a terminal and run hermes fallback add. It uses the same provider picker as hermes model, with the same credential prompts and checks, so you pick a provider, sign in or paste a key, then choose the model.
Run it again to add a second backup. Entries are tried in the order you add them.
The other subcommands keep the list tidy: hermes fallback list shows the chain, hermes fallback remove deletes one entry and hermes fallback clear empties it.
Everything you pick is saved to a top-level list called fallback_providers in ~/.hermes/config.yaml.
Step 2: Or write the chain into config.yaml by hand
If you prefer editing the file, add the fallback_providers list yourself. Each entry is a small block with a provider line and a model line. The docs example uses provider openrouter with model anthropic/claude-sonnet-4.
Two rules matter. Every entry needs both a provider and a model, and an entry missing either one is silently ignored. And there is no environment variable for this chain at all: the docs say that is deliberate, so a stale shell export can't override it.
Older configs may still have fallback_model, the singular legacy key that holds just one backup. Hermes still reads it, but fallback_providers wins when both exist, and the hermes fallback command migrates the old key the next time it writes.
📺 Watch: Run Hermes Agent FREE With This NEW Model🤯
What makes Hermes switch to the backup
The switch is automatic. The docs list these triggers:
- Rate limits (HTTP 429), after the normal retries run out.
- Server errors (HTTP 500, 502 and 503), also after retries.
- Auth failures (HTTP 401 and 403), straight away, because retrying won't help.
- Not found (HTTP 404), straight away.
- Malformed or empty replies that keep coming back.
When it fires, Hermes loads the backup's credentials, builds a new client, swaps the model in place and carries on from the same point. Your history, tool calls and context stay intact.
Each switch does clear the prompt cache, because the new model has never seen your conversation, so a session that keeps bouncing between providers re-reads its full history every time.
The fallback lasts one turn, not the whole session
This is the part people get wrong. Fallback is scoped to a single turn. Your next message starts on the primary again, and within one turn the backup is used at most once.
There is one smart exception. When the primary reports a reset time that hasn't passed yet, such as a subscription window, Hermes stays on the backup until that time instead of trying a request it knows will fail.
If you would rather wait out a short limit than switch at all, set fallback.min_switch_reset_seconds. The default of 0 means always switch.
📺 Watch: Run Hermes Agent FREE With This NEW Model 🤯
Auxiliary task fallback for vision, compression and more
Hermes runs side tasks on their own lightweight models. Each one has a key under auxiliary in config.yaml: vision, compression, mcp, approval, title_generation, review and triage_specifier.
On the default provider setting of auto, a side task tries your main provider and model first, then its own fallback_chain if you wrote one, then your main fallback_providers list, and finally skips the task with a warning.
If you pin a side task to a named provider, the rules change. Capacity errors, meaning a payment error, a daily quota running out or a failed connection, walk your fallback_chain and then the main agent model. A short 429 with a Retry-After header does not, because Hermes treats that as a request limit, not a capacity problem.
Want help deciding which side tasks deserve their own backup? Bring your config to a free AI strategy session.
How to test a Hermes Agent fallback model before an outage
The newest tool here is hermes fallback check, listed in the v0.23.2 release notes from 16 November 2026. It tells you whether each entry would work if the switch ever reached it, without starting a session.
- hermes fallback check resolves every entry and its credentials with no model request.
- hermes fallback check --live also sends one tiny request to each entry, in parallel, on that entry's own provider.
- Add --json for output a script can read.
Each entry is checked on its own, so a good backup can't hide a broken one.
The command exits with status 1 when any entry isn't ready, which means a scheduled job can run it and alert you when a backup key expires. Use hermes -p with a profile name to check a different profile.
| Status | What it means | What to do |
|---|---|---|
| ready | The live request was answered | Nothing |
| ready (static) | Config and credentials resolve, no request sent | Run again with --live to prove it |
| config | The entry itself is wrong | Check provider, model and base URL |
| auth | Credentials are missing or rejected | Log in again or replace the key |
| model_mismatch | The provider answered with a different model | Fix the model name |
| live_timeout, live_rate_limit, live_auth | The live request failed for that reason | Fix that cause, then re-run |
A local-first, cloud-backup pattern
A common setup runs a model on your own machine as the primary and keeps a hosted model as the backup for when the local server is off or overloaded.
The providers docs show the local half: in the model section, set provider to custom, base_url to your server's address, such as http://localhost:11434/v1 for Ollama, and the model name. Hermes needs at least 64,000 tokens of context for agent work with tools, so raise the context length to match.
Then add a hosted entry, such as openrouter, to fallback_providers. The docs also show the reverse, with a cloud primary and a local custom endpoint as the backup.
Two limits are worth knowing. Hermes has no built-in rule today that asks before moving to a paid backup: a confirm option and a free-first ladder are still open pull requests on GitHub. And an open issue reports that fallback entries written as provider ollama never activate, so use provider custom with a base_url as the docs examples do.
Picking the local model is its own job. Our best local model for Hermes Agent page covers that.
Cron jobs, subagents and the community plugin
Cron jobs inherit your chain only when they are unpinned. A job with its own provider or model never falls back, so keep fallback by choosing its model with cron.model and cron.model_provider instead.
Subagents use delegation.fallback_providers when you set it. Otherwise only unpinned children inherit the parent chain, and an empty list switches it off.
If you want backups chosen for you, the model-fallback-heuristic plugin in the Hermes Marketplace ranks models from public catalogs and rewrites fallback_providers at session start and after API errors. It is a community plugin by tomkubik, version 0.2.0, not a Nous Research plugin. By default it never replaces your primary model.
My verdict on fallback models in Hermes
Add one backup on a different provider from your primary, run the live check, and put that check in a weekly cron job. That covers almost every setup.
Add a second entry only if your primary and first backup share a weak point, and give compression a fallback_chain if long sessions matter to you.
Julian covers model routing with members inside the AI Profit Boardroom. His Agent OS guide shows how profiles, models and jobs fit together, and Goldie Bench compares the models you might pick as a backup. For a plan built around your own work, book a free AI strategy session.
FAQ
Where does Hermes store the fallback chain?
In the top-level fallback_providers list in ~/.hermes/config.yaml. The hermes fallback command writes there too.
Does Hermes go back to my main model after a fallback?
Yes. Every new message starts on the primary again, unless the primary reported a reset time that hasn't passed yet.
Will a fallback lose my conversation?
No. The model is swapped in place, and history, tool calls and context carry over.
Can I set the fallback with an environment variable?
No. The docs say the chain lives only in config.yaml or the hermes fallback command, on purpose.
What is the difference between fallback_providers and fallback_chain?
fallback_providers protects the main conversation. fallback_chain sits under one auxiliary task, such as vision or compression, and protects only that task.
Is model-fallback-heuristic part of Hermes?
No. It is a community plugin by tomkubik listed in the Marketplace. Core Hermes fallback needs no plugin.
Add one backup, run the live check, schedule it, and your Hermes Agent fallback model will be ready long before your main provider has its next bad day.











