Hermes Agent
Hermes Agent fallback models: set a backup provider
Updated 22 November 2026
A Hermes Agent fallback model is a backup provider and model that Hermes can try when the main model cannot answer. If the backup answers, the conversation continues with its history intact. You manage it with hermes fallback or by editing config.yaml. This page covers both, what triggers the switch, where it applies, and how to test the chain before you need it.
Facts come from the Hermes Agent 0.23.3 documentation, read on 22 November 2026: Fallback Providers, CLI commands, Configuration, Credential Pools and Provider Routing.
Fallback, key pools and routing are different things
The docs describe three layers of resilience, and it helps to keep them apart because they sit at different levels.
- Credential pools rotate across several keys for the same provider. They are tried first. If every key in the pool is exhausted, Hermes can try a fallback if you configured one.
- Primary model fallback tries a configured backup provider and model pair when the main model cannot answer. This is what the rest of this page is about.
- Auxiliary task fallback is separate provider resolution for side tasks such as vision and compression.
Provider routing is something else again. It applies when OpenRouter is your provider, and its provider_routing section (with keys such as sort, only, ignore and order) controls which underlying providers OpenRouter uses for a request. The docs say Nous Portal decides routing centrally and ignores provider_routing. OpenRouter routing chooses who serves a request within OpenRouter. Hermes fallback can select another model or provider.
Credential pools and primary model fallback are optional. You can configure either on its own. Auxiliary tasks can also use the primary fallback chain. If you only want to understand which model Hermes is using in the first place, start with the pages for Claude, DeepSeek or ChatGPT, then come back.
Set a fallback with hermes fallback
If you run your own Hermes Agent v0.23.3 installation, run this command in its terminal. ReadyHermes does not document fallback-chain setup on hosted assistants.
hermes fallback addIt reuses the provider picker from hermes model: the same provider list, the same credential prompts and the same validation. All the subcommands are:
| Command | What it does |
|---|---|
hermes fallback list | Shows the current chain (alias ls; this is the default with no subcommand) |
hermes fallback add | Picks a provider and model with the same picker as hermes model and appends it to the chain |
hermes fallback remove | Lets you pick an entry to delete (alias rm) |
hermes fallback clear | Removes every fallback entry |
hermes fallback check | Verifies the chain without starting an agent session (see below) |
Changes are saved under the top-level fallback_providers: list in config.yaml. In an open CLI, Desktop or TUI chat, Hermes uses the updated chain starting with your next message. Use hermes -p <profile> fallback check to look at another profile’s chain; see Hermes Agent profiles for what a profile is.
The config.yaml keys
If you would rather edit the file, add a top-level fallback_providers list to ~/.hermes/config.yaml. Each entry needs both provider and model; the docs say an entry missing either is ignored. Entries are tried in order.
# ~/.hermes/config.yaml
model:
provider: anthropic
default: claude-sonnet-4-6
fallback_providers:
- provider: openrouter
model: anthropic/claude-sonnet-4For your own OpenAI-compatible server, use provider: custom and add base_url and, if it needs one, key_env, the name of the environment variable that holds the key (the key itself does not go in the file):
fallback_providers:
- provider: custom
model: llama-3.1-70b
base_url: http://localhost:8000/v1
key_env: LOCAL_API_KEYThe docs’ table of supported providers lists a value and the credential each needs, for example openrouter with OPENROUTER_API_KEY, anthropic with ANTHROPIC_API_KEY or Claude Code credentials, and deepseek with DEEPSEEK_API_KEY. The credential has to exist, or the entry cannot work when it is reached. A local model server is a possible fallback, with a catch: the llamacpp entry is skipped if the managed local server is not running, and Hermes never sends the local model name to another provider.
There is one optional setting for the moment of switching. When a rate-limit response names its reset time, the primary is benched until then. If you would rather wait than switch when the primary is about to reopen, set:
fallback:
min_switch_reset_seconds: 120The default is 0, meaning always switch. With a positive value, a rate-limited primary whose declared reset is sooner than that many seconds is not swapped; the retry backoff waits out the window instead.
Older key. fallback_providers is the current shape and supports several fallbacks in order. The singular fallback_model is the legacy single-fallback key. Hermes still honours it, hermes fallback writes the current key and migrates legacy config when it writes, and when both are set, fallback_providers takes priority. The docs also say there are no environment variables for the primary fallback chain: set it through config.yaml or hermes fallback.
Check the chain before you need it
hermes fallback check reports whether each entry would work if the switch reached it, and it does not start an agent session.
hermes fallback checkhermes fallback check --livehermes fallback check --live --json- Without flags it is a static check: it resolves each entry and its credentials and sends no inference request. The docs note it resolves credentials the way a session does, so an expiring OAuth token may be refreshed and saved.
- With
--liveHermes probes each statically ready, fixed-route entry directly, over that provider’s own API. SDK retries are off. If an Anthropic endpoint rejects streaming, the adapter resends the request once without streaming. The timeout uses the provider’srequest_timeout_secondssetting, or 30 seconds by default. For a streamed response, that limit applies to each read. An empty or malformed answer fails the check. Where the serving model can be verified, a different model fails withmodel_mismatch. A dated snapshot of the requested model counts as a match. Hermes skips this comparison when the reported name cannot verify the model, for example with router meta-models or local servers. - With
--jsonit prints a result per entry, includingstatus,latency_msanderror_class. Credentials are never printed and provider error text is redacted.
The command exits with status 1 when any entry is not ready, so a cron job or CI step can gate on it. Two limits worth knowing: entries with provider: auto or provider: moa are not one fixed route and are never sent a live request, and a static pass for Bedrock or an external-process provider only means the route resolves, so use --live to prove it.
When fallback triggers, and when it does not
The docs list the failures that make Hermes switch:
- Rate limits (HTTP 429) normally trigger fallback after retries are exhausted. On the free Nous tier without sign-in, an interactive session tries a configured fallback first if the cooldown exceeds 60 seconds.
- Server errors (HTTP 500, 502, 503), after exhausting retry attempts.
- Auth failures (HTTP 401, 403) can trigger fallback without the usual transient-error retries. For an expired OAuth token, Hermes first tries to refresh it. If refresh fails, an available pooled credential gets a turn before provider fallback.
- Not found (HTTP 404), immediately.
- Connection failures can also trigger fallback after transient-error retries are exhausted.
- Invalid responses, when the API returns malformed or empty responses repeatedly. A streamed refusal, where the model declines with an explanation, is a terminal result that is shown to you rather than retried.
On a switch, Hermes resolves the fallback’s credentials, builds a new client, swaps model, provider and client in place, re-resolves the reasoning effort for the new model, resets the retry counter and carries on. Conversation history, tool calls and context are preserved. During a user chat, Hermes shows a fallback notice before the backup answers, unless display.suppress_warning_notifications is on. The notice includes the provider’s shortened error with secrets masked and stays out of the model’s conversation history. A switch during chat setup is announced at the start of the turn. A background turn without a user message records the switch in the log.
These behaviours decide whether it does what you expect:
- It is per turn. Hermes normally tries the primary again on your next message. After a rate limit, it can stay on the backup during a cooldown. If the provider gives no reset time, the cooldown starts at 60 seconds and can grow to four hours. Within one turn, fallback activates at most once; if the fallback also fails, normal error handling takes over.
- It can stay on the fallback. When the primary reports a reset time that has not passed (the docs mention subscription windows such as Claude Pro/Max’s 5-hour blocks or Codex weekly limits), Hermes skips the doomed retry and stays on the fallback until the reset. Expiry makes the primary eligible for a later retry; it does not schedule one or guarantee recovery.
- Retries come first.
agent.api_max_retries(default3, so four attempts) sets how many times Hermes retries on transient errors before fallback engages. The docs suggest0if you want the first transient error to hand off at once. - Switching can increase the cost of the next request. A new provider and model has no cached prefix for your conversation, so the next request re-reads the whole history at full input price instead of the discounted cached rate. Switching back is another full re-read unless the primary’s cache has not expired.
- After everything is spent. If retries and fallbacks are exhausted during a temporary outage and you have received no answer text yet, Hermes can wait and try again.
agent.auto_recovery_cyclesdefaults to5. Set it to0to disable these extra attempts.
The CLI reference lists rate limits, overload and connection errors. The fallback guide also documents authentication failures, missing models and repeatedly invalid responses. If the primary is simply the wrong model for the job, that is a different fix: change the model rather than relying on fallback.
Where fallback works
| Context | What the docs say |
|---|---|
CLI sessions, including hermes -z one-shot | Supported: at startup when the primary’s credentials or quota fail, and mid-session |
| Messaging gateway (Telegram, Discord and so on) | Supported |
| Desktop app and TUI chats | Supported; a chain edited while a chat is open applies from the next turn |
| Subagent delegation | Uses delegation.fallback_providers when set; otherwise only unpinned children inherit the parent chain; an empty list disables it |
| Cron jobs | Unpinned jobs inherit the chain; a job with its own provider, model or base URL never falls back to it |
Auxiliary tasks on provider: auto | Per-task fallback first, then the main chain |
Two of these catch people out. A cron job is pinned if the job itself specifies a provider, model or base URL. If that route fails, the job can still try another credential for the same provider; once those are exhausted, it fails. To keep fallback for a job, leave it unpinned and choose its model with cron.model and cron.model_provider. Likewise a subagent you pinned to its own provider does not borrow the parent’s route; give it its own list under delegation: with fallback_providers, or [] to switch child fallback off. For the chat-app side, see Hermes Agent on Telegram.
Auxiliary tasks: a separate fallback
Side jobs such as vision, compression, MCP helpers, approval classification and title generation each have their own config block, auxiliary.vision, auxiliary.compression and so on. With provider: auto (the default), Hermes tries your main provider and model for that job first. When you have selected a main provider and its route is unavailable or hits a capacity error, Hermes tries the task’s auxiliary.<task>.fallback_chain, then the main fallback_providers chain or legacy fallback_model. If those routes cannot serve the task, Hermes skips it with a warning. Built-in provider discovery can run when no main provider is selected.
A task-specific chain is the most precise and wins when present. An example from the docs:
auxiliary:
vision:
provider: glm
model: glm-4v-flash
fallback_chain:
- provider: openrouter
model: google/gemini-3-flash-preview
- provider: nous
model: anthropic/claude-sonnet-4Two safeguards matter. For an auxiliary task set to provider: auto, if you have selected a main provider and its route is unavailable, Hermes skips the task with a warning when no fallback chain is configured; Hermes will not guess another provider you happen to be logged into, so that an expired session never bills another account unseen. In the vision example, Hermes tries glm first. On a payment error, exhausted quota or connection failure, it tries the listed backups in order, then the main agent model. A temporary HTTP 429 keeps the request on the chosen provider. For HTTP 401, Hermes tries only listed backups with a different provider label. If none succeeds, the task fails. If nothing is available for context compression, Hermes drops middle conversation turns without a summary instead of failing the session.
Fallback models on ReadyHermes
On ReadyHermes the model is set from the workspace in a browser, in the Model key tab: choose a provider, paste your own key, press Load models, then Check and switch. Use included AI switches back. That tab sets the assistant’s main model. Changing the model key automatically restarts your assistant, which takes about a minute.
There is no fallback-chain screen in the workspace, and we do not document editing fallback settings on a ReadyHermes assistant, so this page cannot tell you that any particular fallback is set up for you. Which hermes commands work inside an assistant is not something we document either, and assistants can run a Hermes release behind the newest one, so the 0.23.3 behaviour above may not match what your assistant runs. The instructions above describe self-hosted Hermes Agent v0.23.3. For setup instructions, see install Hermes Agent for that route.
ReadyHermes runs your Hermes Agent always on, connected to the chat apps you choose, from US$3.99 a month (Lite) or US$6.99 (Pro), with US$1 of AI included every month and a 1-hour free trial. See managed Hermes Agent hosting or self-hosting vs managed hosting to decide which fits.
Questions
How do I set a fallback model in Hermes Agent?
Run hermes fallback add, choose a provider and model in the picker, and Hermes appends your choice to the chain. You can instead add a top-level fallback_providers list to config.yaml, where each entry needs both provider and model.
What is the difference between fallback_providers and fallback_model?
fallback_providers is the current list, tried in order. fallback_model is the legacy single-fallback key, which Hermes still honours. hermes fallback writes fallback_providers and migrates legacy config when it writes, and when both are set, fallback_providers takes priority.
When does Hermes switch to the fallback model?
Usually after retries are exhausted for a rate limit (HTTP 429), server error (500, 502, 503) or connection failure. An interactive session on the free Nous tier without sign-in tries a configured fallback first if the cooldown exceeds 60 seconds. Hermes can also switch on auth failures (401, 403) after any applicable credential recovery, and immediately on not-found (404), and when the API repeatedly returns malformed or empty responses. The switch is per turn, and within one turn fallback activates at most once.
How do I check that my fallback chain works?
Run hermes fallback check for a static check of each entry and its credentials, or add --live to test each ready entry that points to a fixed route. It exits with status 1 when any entry is not ready, and --json prints a result per entry.
Is fallback the same as a credential pool?
No. A credential pool lets Hermes try another credential for the same provider. If the pool is exhausted, Hermes can try a configured fallback model. You can configure either feature on its own.