Headmaster by GCAP Labs

A fallback provider is a backup model. If your main model fails, for example because of a rate limit or an outage, Headmaster switches to the next one in your list and carries on, without losing the conversation.

This is for people who use their own provider keys. See Models and providers.

What happens when the main model fails

Headmaster switches to the first fallback when the main model returns:

Rate limits, after retries run out.
Server errors, after retries run out.
Sign-in or permission errors and not found, straight away, because retrying cannot help.
Empty or broken replies, when they repeat.

The switch keeps your history, tool results and context. The agent continues from where it stopped, on the backup model.

Fallback applies per turn. Your next message starts on the main model again. Within one turn it switches at most once, so two failing models cannot bounce back and forth. If the main provider says when its limit resets, Headmaster stays on the fallback until then instead of retrying a model that will refuse.

A fallback model has no cached copy of your conversation, so the first request after a switch can cost more than usual.

Set up a chain

headmaster fallback

This opens the same provider and model picker as headmaster model, including key prompts and checks. Manage the list with:

Command	What it does
`headmaster fallback list`	Show the chain. This is the default. Alias: `ls`.
`headmaster fallback add`	Pick a provider and model and add it to the end.
`headmaster fallback remove`	Pick an entry to delete. Alias: `rm`.
`headmaster fallback clear`	Remove every entry.

Entries are tried in order. A chain you change while a chat is open applies from its next turn.

Edit the config yourself

The chain is the fallback_providers list in your config file. Run headmaster config path to find the file.

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4
  - provider: custom
    model: my-local-model
    base_url: http://localhost:8000/v1
    key_env: MY_LOCAL_KEY

Every entry needs both provider and model. An entry missing either is ignored. For a custom endpoint, add base_url, and key_env to name the setting that holds its key.

To skip the switch when the main model will be back soon:

fallback:
  min_switch_reset_seconds: 120

With this set, a rate-limited main model whose limit resets sooner than that many seconds is waited out instead of replaced. The default 0 always switches.

There is no environment setting for the chain. Use the command or the config file.

Where fallback works

Where	Fallback
Terminal chats, including one-shot runs	Yes
Desktop app chats	Yes
Messaging apps	Yes
Sub-agents	Yes. They use `delegation.fallback_providers` if set, otherwise they inherit the chain.
Scheduled tasks	Yes. A task pinned to its own model never falls back.
Side tasks (reading images, shortening long chats, naming chats)	Yes, through their own chains, then your main one.

Side tasks

Headmaster uses small helper models for side jobs such as vision, summarizing a long conversation, and titles. When a helper is set to auto, it tries your main model first, then its own fallback_chain, then your fallback_providers, and otherwise skips the job with a warning. It never quietly picks another provider you happen to be signed in to.

Tips