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

OptionWhat it doesWhat it needsBest for
Credential poolRotates between several keys on one providerTwo or more keys for the same providerOne key hitting its limit
fallback_providersMoves the main conversation to another provider:modelA provider and model per entryProvider outages, expired logins, retired models
auxiliary.<task>.fallback_chainGives one side task its own backup orderAt least a provider per entryVision or compression you can't lose
delegation.fallback_providersGives subagents their own chainSame shape as the main chainDelegation-heavy workflows
agent.auto_recovery_cyclesWaits and retries once retries and the chain are spentNothing; on by default (5 cycles)Short provider blips
model-fallback-heuristic (community)Rewrites the chain from public model catalogsA git clone into the plugins folderPeople rotating many free models
Manual /model switchYou change model by hand mid-chatAn already-configured providerOne-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

  1. Run hermes fallback add and pick a provider and model from the same menu as hermes model.
  2. Run hermes fallback list to confirm the order. First entry is tried first.
  3. Run hermes fallback check --live to 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

ErrorSwitch?When
429 rate limitYesAfter retries run out
500, 502, 503YesAfter retries run out
401, 403 authYesImmediately
404 not foundYesImmediately
Repeated empty or malformed repliesYesAfter repeats
A streamed refusal with an explanationNoShown 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.model and cron.model_provider to 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_providers if 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.

  • ready means the entry answered.
  • auth means the login or key is the problem.
  • model_mismatch means the provider served a different model from the one you named.
  • live_timeout or live_rate_limit means 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 check without --live proves config, not answers.
  • Expecting an environment variable. The chain lives only in config.yaml or the hermes fallback command.

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_chain if 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.