A hermes agent fallback model is an entry in the ordered fallback_providers list in ~/.hermes/config.yaml, and Hermes walks that list on its own when the primary returns a 429, a 5xx, a 401 or 403, or a 404.
This page is the operator version: the exact keys, every trigger, what the swap does to your session, the separate auxiliary ladder, and the readiness check that landed in the v0.23.2 release.
Everything below comes from the official Fallback Providers page and the CLI reference.
If you'd like my team to sanity-check your provider plan first, get your Backlink Gameplan, or try Polar Rank free for 3 days.
Where Fallback Sits In The Resilience Stack
Hermes stacks three independent layers.
- Credential pools rotate keys on the same provider. They run first.
- Primary model fallback swaps the main loop to another provider:model pair.
- Auxiliary task fallback resolves side tasks such as vision and compression on their own.
Only when every key in a credential pool is spent does the cross-provider chain take over.
So if you run three OpenRouter keys and one Anthropic backup, the three keys get used up before Anthropic is touched.
The chain covers more surfaces than people expect: interactive CLI sessions, one-shot hermes -z runs, the messaging gateway for Telegram or Discord, and Desktop or TUI chats.
In the CLI it can also fire at startup, when the primary's credentials or quota fail before the first request is even sent.
Build The Chain From The CLI
The fastest route is the interactive manager:
hermes fallback add # same picker and credential prompts as hermes model
hermes fallback list # alias: ls (also the default with no subcommand)
hermes fallback remove # alias: rm
hermes fallback clear # wipe the chain
Each add appends to the end, so the order you add entries is the order Hermes tries them.
The picker validates the provider the same way hermes model does, which catches a typo in a model ID before it sits silently in your config.
The YAML, Key By Key
Prefer editing the file? This is the current shape:
fallback_providers:
- provider: openrouter
model: anthropic/claude-sonnet-4
- provider: custom
model: llama-3.1-70b
base_url: http://localhost:8000/v1
key_env: LOCAL_API_KEY
providerandmodelare both required. Drop either and the entry is ignored without an error.base_urlpoints an entry at a custom OpenAI-compatible endpoint.key_envnames the environment variable that holds that endpoint's key.api_modeoverrides the wire format. An entry naming aproviders.<name>block inherits that block's transport when it sets none.
There is no environment variable for the chain itself. The docs call that intentional, so a forgotten shell export can't rewrite your failover.
Migrating An Old fallback_model Block
Configs from earlier releases often carry fallback_model, a single provider/model dict.
Hermes still honours it, but fallback_providers takes priority when both exist.
The next time hermes fallback writes your config it migrates the legacy key for you, so the cleanest fix is simply to run hermes fallback list and then any write command.
🔥 Want a provider chain that's already wired and tested? Inside the AI Profit Boardroom you get step-by-step video trainings, the installable Agent OS, four coaching calls a week and 3,400+ members comparing their model setups. → Join the AI Profit Boardroom
Exactly Which Errors Flip The Switch
The trigger list splits into two groups.
After the normal retries are exhausted:
- HTTP 429 rate limits.
- HTTP 500, 502 and 503 server errors.
- Malformed or empty responses that repeat, including a router's connect-timeout text that arrives with zero completion tokens.
Immediately, because a retry can't fix them:
- HTTP 401 and 403 auth failures.
- HTTP 404 not found.
Account-policy refusals behave like the second group: the troubleshooting docs say Hermes sends the request once, skips retries and key rotation, and moves to your chain.
The v0.23.0 notes add one more: Gemini safety blocks now surface as a content-policy error and move on to the fallback model.
A streamed refusal, where the model declines with an explanation, is different. It's treated as a final answer and shown to you, not retried.
What The Swap Does To A Live Session
When a trigger fires, Hermes runs five steps in place:
- Resolves the backup's credentials, including named custom providers that use
key_cmd. - Builds a new API client.
- Swaps model, provider and client inside the running agent.
- Re-resolves reasoning effort from
agent.reasoning_overridesfor the new model, falling back toagent.reasoning_effort. - Resets the retry counter and continues.
History, tool calls and context survive. The cost is the prompt cache: the new route has no cached prefix, so the next request re-reads the full transcript, and the first request back on the primary does the same.
On a long session that flaps between providers, that re-read happens on every bounce.
The startup case gets the same treatment: the backup is sent its own configured effort, while an explicit hermes chat --reasoning level you passed is kept across the switch.
Turn Scope, Benching And min_switch_reset_seconds
Failover is per turn. Each new user message starts on the primary, a turn can fail over once at most, and a failing backup drops you into normal retries and then an error.
A rate-limited primary that names its reset time is benched until exactly then. One that says nothing gets an exponential backoff the docs describe as 60 seconds up to 4 hours.
If the primary reports a reset that's still in the future, Hermes skips the doomed retry and stays on the backup, so you avoid two pointless switches per turn.
To ride out short windows instead of switching:
fallback:
min_switch_reset_seconds: 120 # default 0 = always switch
With that set, a primary whose declared reset is under two minutes away is waited out, not swapped.
The CLI notice tells you where you stand, for example Primary retry eligible in ~60 s; recovery is not guaranteed.
Want to confirm which route answered a turn? Type /status, which shows the active model, provider and profile without making a model call.
The Auxiliary Ladder Is A Separate System
Side tasks resolve their own provider under auxiliary.<task>: vision, compression, mcp, approval, title_generation, review and triage_specifier.
On provider: auto, the order is the main provider and model, then the task's fallback_chain, then fallback_providers, then skip with a warning.
Pin a task to an explicit provider and only capacity errors climb the ladder: a 402, a 429 for exhausted daily quota, or a connection failure. A transient 429 carrying Retry-After respects your choice and doesn't move.
auxiliary:
compression:
provider: openrouter
fallback_chain:
- provider: openai
model: gpt-4o-mini
timeout: 240 # this candidate's own deadline (seconds)
A 401 on an explicit provider walks only the fallback_chain, never the main model. Point the spare at a different provider, because chain entries on the same provider label are skipped on auth errors.
When everything fails, the log shows all fallbacks exhausted at WARNING and the original error is raised.
Prove The Chain With hermes fallback check
This is the recovery check most guides skip.
hermes fallback check # static: resolve entries and credentials, no inference
hermes fallback check --live # one minimal request per entry, in parallel
hermes fallback check --live --json # machine-readable
hermes -p work fallback check --live # another profile
Each entry resolves exactly as the real switch would, and the chain is never walked, so a healthy first entry can't mask a dead second one.
The JSON reports a status per entry: ready, ready (static), config, auth, model_mismatch, live_response or a live_ reason such as live_timeout.
It exits 1 when any entry isn't ready. That makes it a clean gate for CI or a nightly cron job that pings you when a backup key quietly expires.
The live request uses the provider's request_timeout_seconds if set, otherwise 30 seconds.
Know the limits of each mode. A static pass on Bedrock or an external-process provider only proves the route resolves, so use --live there. Entries set to provider: auto or a moa preset never get a live request, because they aren't one fixed route.
Static mode still resolves credentials the way a session does, so an OAuth token close to expiry may be refreshed and saved while it runs.
Cron Jobs And Subagents: Pinned Versus Unpinned
Unpinned cron jobs inherit the chain, both when the primary's credentials fail before the run and when it errors mid-run.
A job that sets its own provider, model or base URL never falls back. Keep failover by leaving it unpinned and choosing its model through cron.model and cron.model_provider.
Our Hermes agent cron job guide covers the scheduling side.
Subagents use delegation.fallback_providers when it's set. Otherwise only unpinned children inherit the parent chain, and [] turns it off.
Local Primary, Hosted Backup
The providers page documents a local Ollama primary through the custom provider:
model:
default: qwen2.5-coder:32b
provider: custom
base_url: http://localhost:11434/v1
context_length: 64000
fallback_providers:
- provider: openrouter
model: anthropic/claude-sonnet-4
Hermes rejects agent use below 64,000 tokens of context, so set context_length rather than trusting Ollama's small default.
Two operator notes from GitHub. Issue #74280, still open, reports that entries written as provider: ollama never activate, so use custom plus base_url. And a prompt before switching to a paid backup isn't in core yet: PR #149020 (a fallback.confirm option) and PR #125301 (a free-first ladder) are both open.
The Community Heuristic Plugin
model-fallback-heuristic is a community plugin by tomkubik, version 0.2.0, listed in the Hermes Marketplace. It isn't a Nous Research plugin.
Its hooks rewrite fallback_providers at session start and after API errors, ranking candidates from public model catalogs and keeping any manual entries you wrote.
git clone https://github.com/tomkubik/hermes-fallback.git ~/.hermes/plugins/model-fallback-heuristic
hermes plugins validate ~/.hermes/plugins/model-fallback-heuristic
hermes fallback-heuristic status
Its auto_switch_primary_when_unavailable setting is off by default, so it doesn't touch your primary model unless you opt in.
Because it edits your config on every session start, diff config.yaml after the first run.
📞 Running agents for clients and need failover you can trust? Get your Backlink Gameplan and my team will walk through your providers, profiles and scheduled jobs with you, or try Polar Rank free for 3 days. Backlink Gameplan or try Polar Rank free for 3 days
Gotchas Worth Checking Today
- Same-provider backups. An outage that hits your primary usually hits a second model on that provider too.
- Half-written entries. A missing
modelline means the entry silently doesn't exist. - Pinned cron jobs. They fail instead of failing over.
- Chain edits mid-chat. They apply from the next turn, not the current one.
- Recovery after the chain.
agent.auto_recovery_cycles(default 5) waits and retries transient outages only after retries and the chain are spent.
Stuck on one of these? Bring your chain to a weekly coaching call in the AI Profit Boardroom.
My Verdict On The Hermes Agent Fallback Model Setup
One backup on a different provider, written with hermes fallback add, covers most operators.
Gate it with hermes fallback check --live in cron, give compression its own fallback_chain if your sessions run long, and leave cron jobs unpinned unless you want them to fail hard.
Treat the heuristic plugin as optional tooling for free-model setups, and want a review of the whole stack? Get your Backlink Gameplan, or try Polar Rank free for 3 days.
FAQ: Hermes Agent Fallback Model
Which key holds the fallback chain in Hermes?
The top-level fallback_providers list in ~/.hermes/config.yaml. The older singular fallback_model key still works but loses when both are set.
Does a 429 switch to the backup straight away?
No. Rate limits and 5xx errors switch only after the normal retries run out. Auth failures and 404s switch at once.
Why did my fallback entry never fire?
Usually it is missing a provider or a model line, so Hermes ignores it. Run hermes fallback check to see each entry's status.
Can a cron job use the fallback chain?
Yes, if it is unpinned. A job with its own provider, model or base URL fails instead of falling back.
How do I test the chain without starting a chat?
Run hermes fallback check --live. It sends one small request per entry and exits 1 if any entry is not ready.
Is model-fallback-heuristic made by Nous Research?
No. It is a community plugin by tomkubik in the Hermes Marketplace that rewrites fallback_providers for you.
📺 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 a team of 70+ SEO experts.
- I've grown a YouTube channel to 400,000+ subscribers.
- I wrote "Link Building Mastery".
- My Udemy courses have taught over 29,000 students.
→ Get my best AI training inside the AI Profit Boardroom
Write the chain, run the live check, schedule it, and for help with everything around it, the AI Profit Boardroom and a Backlink Gameplan are both open to you as you harden your hermes agent fallback model, or try Polar Rank free for 3 days.











