Field notes · AI agents, Hermes & Claude Code By Julian Goldie

Hermes Agent Fallback Model: The Exact Config, Every Trigger And A Live Check For Your Chain (2026)

The keys, the triggers, what the swap does mid-session and the one command that proves your backups work before an outage does.

Get The AI Profit Stack Join AIPB →
  • 01 1,000+ done-for-you AI agent workflows
  • 02 5 live coaching calls / week with me
  • 03 7-day refund, cancel anytime
  • 04 3,400+ AI operators inside

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
  • provider and model are both required. Drop either and the entry is ignored without an error.
  • base_url points an entry at a custom OpenAI-compatible endpoint.
  • key_env names the environment variable that holds that endpoint's key.
  • api_mode overrides the wire format. An entry naming a providers.<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:

  1. Resolves the backup's credentials, including named custom providers that use key_cmd.
  2. Builds a new API client.
  3. Swaps model, provider and client inside the running agent.
  4. Re-resolves reasoning effort from agent.reasoning_overrides for the new model, falling back to agent.reasoning_effort.
  5. 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 model line 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.

§ Member reviews

What members say about the AI Profit Boardroom

Read the member reviews on Skool →
Ahmad Bukhari: Julian doesn't gatekeep. That's why I'd recommend this group. He's extremely active here, sharing what's working right now and jumping in to help anyone who's stuck. If he can give it away, he does. He keeps the vibe positive and pushes everyone to help each other. His challenges reward members for getting people unstuck, so the whole room shares knowledge, not just him. Want a generous, positive place to learn AI and actually use it? This is it. Thanks Julian!
Ahmad Bukhari
Julian doesn't gatekeep. That's why I'd recommend this group. He's extremely active here, sharing what's working right now and jumping in to help anyone who's stuck. If he can give it away, he does. He keeps the vibe positive and pushes everyone to help each other. His challenges reward members for getting people unstuck, so the whole room shares knowledge, not just him. Want a generous, positive place to learn AI and actually use it? This is it. Thanks Julian!

Still a paying member after 1 month

Jay Parsons: There are so many helpful members in this amazing community ready to help out with suggestions and solutions whenever someone asks a question. I am amazed at the progress I have made in learning AI. I came here to learn how to use AI better and apply what I learned to my business. I am learning so much more than I even dreamed of. I have built an Agentic OS and use it every day, and I have no background in coding. There are an incredible amount of useful tutorials on everything AI.
Jay Parsons
There are so many helpful members in this amazing community ready to help out with suggestions and solutions whenever someone asks a question. I am amazed at the progress I have made in learning AI. I came here to learn how to use AI better and apply what I learned to my business. I am learning so much more than I even dreamed of. I have built an Agentic OS and use it every day, and I have no background in coding. There are an incredible amount of useful tutorials on everything AI.

Still a paying member after 11 months

Brian O'Connor: At 47, with 30 years in sales and finance, embracing AI was exciting but overwhelming. While building a business to help others adopt AI, I found myself chasing tools and fearing I was falling behind. Julian and the AI Profit Boardroom helped me refocus through practical, personalized advice and a supportive community. I now feel more confident adapting to change while staying focused on my goals. Thank you, Julian, for bringing this community together!
Brian O'Connor
At 47, with 30 years in sales and finance, embracing AI was exciting but overwhelming. While building a business to help others adopt AI, I found myself chasing tools and fearing I was falling behind. Julian and the AI Profit Boardroom helped me refocus through practical, personalized advice and a supportive community. I now feel more confident adapting to change while staying focused on my goals. Thank you, Julian, for bringing this community together!

Still a paying member after 2 months

Neil Martin: This is a truly amazing community, thanks in no small part to Julian's prodigious output and tireless efforts to provide value to his subscribers. Nothing is too much trouble for him. If you ask a question it gets answered in short order usually with a custom video. I have been in quite a few groups and this level of service is unparalleled. If you are serious about getting an AI education, you need to be in this group!
Neil Martin
This is a truly amazing community, thanks in no small part to Julian's prodigious output and tireless efforts to provide value to his subscribers. Nothing is too much trouble for him. If you ask a question it gets answered in short order usually with a custom video. I have been in quite a few groups and this level of service is unparalleled. If you are serious about getting an AI education, you need to be in this group!

Still a paying member after 7 months

Crystal Hill: AIPB has inspired me to go beyond learning AI as individual tools, skills, and prompts, and start thinking in terms of larger systems. What I really appreciate is how responsive Julian is and how quickly the material evolves with the technology. You’re being exposed to the right tools and ideas as they emerge. AIPB has given me the confidence to learn, experiment, build, and think much bigger about what’s really possible with AI.
Crystal Hill
AIPB has inspired me to go beyond learning AI as individual tools, skills, and prompts, and start thinking in terms of larger systems. What I really appreciate is how responsive Julian is and how quickly the material evolves with the technology. You’re being exposed to the right tools and ideas as they emerge. AIPB has given me the confidence to learn, experiment, build, and think much bigger about what’s really possible with AI.

Still a paying member after 5 months

Maurice Morrison: AI Profit Board Room has been a game-changer. The insights are practical, timely, and focused on turning AI into real business results—not just theory or hype. The community is supportive, the guidance is clear, and I leave every session with ideas I can actually apply. If you’re serious about using AI to grow smarter and move faster, this is absolutely worth joining.
Maurice Morrison
AI Profit Board Room has been a game-changer. The insights are practical, timely, and focused on turning AI into real business results—not just theory or hype. The community is supportive, the guidance is clear, and I leave every session with ideas I can actually apply. If you’re serious about using AI to grow smarter and move faster, this is absolutely worth joining.

Still a paying member after 2 months

Jeremy Murdock: I have truly enjoyed my experience here. The group of folks on the calls is quite diverse and I find it comforting to know that I am not the only one going through the changes that are happening at a faster and faster pace. I have chosen to embrace the change and go full force into integrating AI and what I have learned form the group and Julian. I am also impressed and appreciative that he actually takes the time to help with challenges I have along the way and get involved personally!
Jeremy Murdock
I have truly enjoyed my experience here. The group of folks on the calls is quite diverse and I find it comforting to know that I am not the only one going through the changes that are happening at a faster and faster pace. I have chosen to embrace the change and go full force into integrating AI and what I have learned form the group and Julian. I am also impressed and appreciative that he actually takes the time to help with challenges I have along the way and get involved personally!

Still a paying member after 10 months

Michael Lovitch: I have been a part of a million ai groups in Skool for years now. They are all okay and have helped, but usually they get out of date and don't offer real service to help you through especially at the beginning. This group is different, Julian actually answers questions which is crazy! And although ai marketing moves at the speed of light, they stay current and actually help you keep up… Highly recommended!
Michael Lovitch
I have been a part of a million ai groups in Skool for years now. They are all okay and have helped, but usually they get out of date and don't offer real service to help you through especially at the beginning. This group is different, Julian actually answers questions which is crazy! And although ai marketing moves at the speed of light, they stay current and actually help you keep up… Highly recommended!

Still a paying member after 3 months

Hoebing Lo: I don't know of any other community that is as active and sharing. Julian is a star and he answers so many questions in lightning speed. If you want a great place to start with AI here it is. No question too simple. No workflow too complicated. The community is about action and results not education so if you are looking to win at AI then come for the ride of a lifetime!
Hoebing Lo
I don't know of any other community that is as active and sharing. Julian is a star and he answers so many questions in lightning speed. If you want a great place to start with AI here it is. No question too simple. No workflow too complicated. The community is about action and results not education so if you are looking to win at AI then come for the ride of a lifetime!

Still a paying member after 5 months

Darren Wagstaff: Very responsive... great personal support (not an ai chat bot). Very clear straight forward trainings in easy to understand actionable language. I'm in numerous Skool groups but this one has the most human and real community by far. No question gets ignored. You never fell like just another number. It's great to see so many members getting great results with Ai.
Darren Wagstaff
Very responsive... great personal support (not an ai chat bot). Very clear straight forward trainings in easy to understand actionable language. I'm in numerous Skool groups but this one has the most human and real community by far. No question gets ignored. You never fell like just another number. It's great to see so many members getting great results with Ai.

Still a paying member after 2 months

Rod Martin: Julian is brilliant, and more prolific than I can keep up with (which is a great thing). His AgentOS is remarkable, and he is THE go-to guy for what you can really do (and not do) with the ever-increasing deluge of new AI upgrades and tools. HIGHLY recommend.
Rod Martin
Julian is brilliant, and more prolific than I can keep up with (which is a great thing). His AgentOS is remarkable, and he is THE go-to guy for what you can really do (and not do) with the ever-increasing deluge of new AI upgrades and tools. HIGHLY recommend.

Still a paying member after 5 months

Yosuke Sato: The best Skool course you get for AI! I have attended a few Skool courses before, but AI Profit Boardroom is the most active community and has great support from the management team, including Julian! You can get the most up-to-date information and practical implementations in this community. I highly recommend this!
Yosuke Sato
The best Skool course you get for AI! I have attended a few Skool courses before, but AI Profit Boardroom is the most active community and has great support from the management team, including Julian! You can get the most up-to-date information and practical implementations in this community. I highly recommend this!

Still a paying member after 19 months

⚑ Next step

Ready to run AI agents that actually do the work?

Join 3,400+ operators inside the AI Profit Boardroom. Get 1,000+ plug-and-play AI agent workflows, 5 coaching calls a week, and a community that holds you accountable.

Join The AI Agent Community →

7-day no-questions refund · Cancel anytime

Found this useful? Get more of this site in your Google.

One tap adds us as a preferred source — Google then shows you our posts more often in Search, Top Stories, and AI Overviews.

← Back to all posts