Choosing a hermes agent fallback model setup comes down to one question: which failure are you protecting against, a single tired API key, a whole provider going dark, or a side task like vision quietly dropping out?
Hermes has a different tool for each, and picking the wrong one leaves the real gap open.
This page lays the options side by side, then sets up the one most people need, using the official Fallback Providers documentation.
If you'd like help matching the options to your own workload, get your Backlink Gameplan with my team, or try Polar Rank free for 3 days.
Every Fallback Option In Hermes, Compared
| Option | What it does | What it needs | Best for |
|---|---|---|---|
| Credential pool | Rotates between several keys on one provider | Two or more keys for the same provider | One key hitting its limit |
fallback_providers | Moves the main conversation to another provider:model | A provider and model per entry | Provider outages, expired logins, retired models |
auxiliary.<task>.fallback_chain | Gives one side task its own backup order | At least a provider per entry | Vision or compression you can't lose |
delegation.fallback_providers | Gives subagents their own chain | Same shape as the main chain | Delegation-heavy workflows |
agent.auto_recovery_cycles | Waits and retries once retries and the chain are spent | Nothing; on by default (5 cycles) | Short provider blips |
| model-fallback-heuristic (community) | Rewrites the chain from public model catalogs | A git clone into the plugins folder | People rotating many free models |
Manual /model switch | You change model by hand mid-chat | An already-configured provider | One-off fixes while you watch |
The order matters too: pool keys are tried before the cross-provider chain, per the credential pools docs, and the recovery cycles only start after the chain has nothing left.
Which Failure Are You Actually Protecting Against?
Match the option to the problem.
- "My key keeps hitting its limit." A credential pool fixes that without changing model.
- "My provider was down for an hour." Only a cross-provider chain helps.
- "My login expired overnight." A chain switches on a 401 or 403 straight away.
- "Image reading stopped working." That's an auxiliary task; give vision its own
fallback_chain. - "My subagents died mid-job." Check whether they were pinned to a provider.
Most single-machine users need the second row of the table and nothing else on day one.
If you can't tell which failure hit you, look at the error text from the failed request: a rate limit, a rejected login and a missing model each point to a different row.
Setting Up The Main Chain In Three Moves
- Run
hermes fallback addand pick a provider and model from the same menu ashermes model. - Run
hermes fallback listto confirm the order. First entry is tried first. - Run
hermes fallback check --liveto prove each entry answers.
The result lands in ~/.hermes/config.yaml:
fallback_providers:
- provider: anthropic
model: claude-sonnet-4
- provider: openrouter
model: anthropic/claude-sonnet-4
Every entry needs both lines. One without a model is skipped, and nothing warns you.
🔥 Want to see how other people structure their provider chains? 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 sharing what works for them. → Join the AI Profit Boardroom
What Triggers The Switch, And What Doesn't
| Error | Switch? | When |
|---|---|---|
| 429 rate limit | Yes | After retries run out |
| 500, 502, 503 | Yes | After retries run out |
| 401, 403 auth | Yes | Immediately |
| 404 not found | Yes | Immediately |
| Repeated empty or malformed replies | Yes | After repeats |
| A streamed refusal with an explanation | No | Shown to you as the answer |
If a 429 names a reset time, the primary is benched until exactly then. You can also tell Hermes to wait out short resets with fallback.min_switch_reset_seconds, which is 0 by default.
What A Switch Costs You In Practice
Before you add a backup, know what you're trading.
What you keep: the conversation history, the tool calls already made and the working context. Hermes swaps the model in place and carries on from the same step.
What changes: the reasoning effort is looked up again for the backup model, so a backup you've set to a lower effort will think less hard on that turn.
What you lose: the prompt cache. The backup has never seen the conversation, so its first request reads all of it again, and the first request back on the primary does the same.
That last point is the real cost of a flapping provider. A session that bounces back and forth many times re-reads its history each time.
So the better your primary's uptime, the less a backup ever costs you, and the more a reliable backup is worth on the rare bad day.
Turn-Scoped Failover: The Detail That Changes Your Choice
A fallback in Hermes covers one turn. The next message starts on the primary again, and each turn fails over once at most.
That shapes the decision. If your primary is flaky but usually fine, turn scope is ideal: you get the primary back as soon as it recovers.
If your primary is down for hours and reports a reset time, Hermes is smart about it and stays on the backup until that time, rather than retrying every turn.
One doc conflict to know about: the configuration page still says activation is "one-shot per session", while the dedicated fallback page describes the per-turn behaviour in detail. The fallback page is the fuller source, so plan around per-turn.
Auxiliary Fallback: Leave It On Auto Or Pin It?
Side tasks live under auxiliary: vision, compression, mcp, approval, title_generation, review and triage_specifier.
Leave a task on auto and it tries your main model, then its own chain if set, then your main fallback_providers, then skips with a warning. Zero config, and usually enough.
Pin a task to a provider and it only climbs the ladder on capacity errors: payment errors, exhausted daily quota or a failed connection. A short 429 with Retry-After stays put.
Pin when a task needs a specific model, such as a vision model you trust. Leave it on auto when any decent model will do.
Compression is the forgiving one: with no model available it trims middle turns without a summary rather than ending the session.
Cron Jobs And Subagents: The Pinning Trade-Off
The same pin-or-not choice shows up for scheduled jobs and subagents.
- Unpinned cron jobs inherit the chain. Pick their model with
cron.modelandcron.model_providerto keep that. - Pinned cron jobs, with their own provider or model, never fall back. They fail hard, which some people want for predictable spend.
- Subagents use
delegation.fallback_providersif you set it; otherwise only unpinned children inherit the parent chain.
The cron docs and our Hermes agent cron job walkthrough cover scheduling itself.
Local-First Or Cloud-First?
Both directions are supported.
Cloud primary, local backup: the fallback docs show a custom entry pointing at http://localhost:8000/v1. Good when the cloud model is your daily driver and your own machine is the emergency spare.
Local primary, cloud backup: the providers docs show a local Ollama model as the main custom provider, and you add a hosted entry to the chain. Good when you want most work kept on your own hardware.
Two things tip the decision. Agent work in Hermes requires a context window of 64,000 tokens or more, which rules out small local setups. And there's no built-in prompt before moving to a paid backup: PR #149020 proposes one, and it's still open.
Is The Community Plugin Worth Adding?
model-fallback-heuristic is a community plugin from tomkubik at version 0.2.0. Nous Research didn't make it.
What it does well: it ranks live models from public catalogs, refreshes your chain at session start and after errors, and keeps any entries you wrote by hand. By default it leaves your primary alone.
What to weigh: it rewrites your config file on its own, and it adds a moving part you need to review.
It suits people who rely on free models across several providers, where hand-written model IDs go stale quickly. For a stable paid primary with one trusted backup, the core chain is simpler.
📞 Weighing these options for a team or client setup? Get your Backlink Gameplan and my team will help you pick the right mix of pools, chains and pins, or try Polar Rank free for 3 days. Backlink Gameplan or try Polar Rank free for 3 days
Reading The Check Results Before You Commit
The hermes fallback check command, listed in the v0.23.2 release notes, is the fairest way to compare candidate backups before you rely on them.
Run it plain first to confirm each entry resolves, then with --live to send each one a single short request on its own provider.
readymeans the entry answered.authmeans the login or key is the problem.model_mismatchmeans the provider served a different model from the one you named.live_timeoutorlive_rate_limitmeans the backup itself is struggling, which is a poor sign for an emergency spare.
Because the command exits 1 when any entry isn't ready, you can schedule it and get told when a candidate stops qualifying. Run hermes -p with a profile name to test another profile's chain.
Common Mistakes When Choosing A Backup
- Backing up a provider with itself. A second model on the same provider shares its outages.
- Using a pool where you needed a chain. Extra keys don't help when the whole provider is down.
- Pinning everything. Pinned cron jobs and subagents skip the chain.
- Trusting a static check alone.
hermes fallback checkwithout--liveproves config, not answers. - Expecting an environment variable. The chain lives only in
config.yamlor thehermes fallbackcommand.
Who Each Setup Suits
- Solo user, one machine: one cross-provider entry plus a weekly live check.
- Team on a messaging gateway: the same chain, plus a vision
fallback_chainif staff send images. - Heavy delegation: add
delegation.fallback_providers; see the delegation docs. - Free-model tinkerer: consider the community plugin, and review what it writes.
Members of the AI Profit Boardroom can bring their setup to a weekly coaching call for a second opinion.
My Verdict On Picking A Hermes Fallback Setup
For most people the right answer is the plain cross-provider chain: one entry from a different provider, tested with --live.
Add a credential pool only if key limits are your real problem, pin side tasks only when they need a specific model, and treat the heuristic plugin as an extra for free-model setups.
Want a second opinion before you commit? Get your Backlink Gameplan, or try Polar Rank free for 3 days.
FAQ: Hermes Agent Fallback Model
Should I use a credential pool or a fallback chain?
A pool rotates keys on one provider, so it helps with key limits. A chain moves to another provider, so it helps with outages. Many setups use both.
Which fallback option do most Hermes users need?
The main fallback_providers chain with one entry from a different provider, checked with hermes fallback check --live.
Do side tasks like vision need their own backup?
Not usually. On auto they already fall through to your main chain. Give one a fallback_chain only if it needs a specific model.
Why would I pin a cron job if it loses fallback?
Pinning keeps a job on one known model, which some people prefer for predictable spend. The trade-off is that the job fails instead of switching.
Is the heuristic fallback plugin better than the built-in chain?
It solves a different problem: stale model IDs across many free providers. For a stable setup the built-in chain is simpler.
Can Hermes ask me before it moves to a paid backup?
Not yet. A fallback.confirm option has been proposed in an open pull request, but it is not part of core Hermes today.
📺 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
Match the tool to the failure, test it live, and then talk the choice over in the AI Profit Boardroom or in your Backlink Gameplan before you lock in your hermes agent fallback model, or try Polar Rank free for 3 days.











