All plugins

hermes-kame-api-rotation

Smart API key rotation: the healthiest key for every call, each 429 / RESOURCE_EXHAUSTED / quota refusal sized from its own evidence. Install with its companion hermes-kame-provider, which hands Hermes this plugin's rotating client through ProviderProfile.create_client (and create_messages_client where Hermes offers it); no core override. When Hermes has a fallback list, a reply whose model is busy, resting or slow moves down a ladder: the model the reply started on, then the main model (model.default), then the rest of the list; a model of the same provider answers inside the plugin on the same keys and endpoint, a model of another provider is handed to Hermes' own fallback (which walks the list), and a late reply can be raced by the next model of the same provider; nothing moves once part of the reply is on screen, and never_fall_back_to_another_model turns every switch off (the plugin reads the model and fallback_providers from config.yaml, read-only; no new network destination). Disclosure — /kame-keys add|import|split, and on start a key variable holding several comma-joined keys, write one auth.json pool row per key through Hermes' pool API after an owner-only plaintext backup (last 5 kept; switch: resolver_disabled); settings changed from /kame or the Desktop panel are saved as KAME_* lines in Hermes' .env; key-redacted, size-capped owner-only local logs (current file plus one previous), a status file, a small lifetime-counters file (replies answered and saved, requests sent per model in 24 hours, the provider's stated daily limit; no key, prompt or text) and a small model-health file (the time and the success or failure of each model's last judged outcomes, at most 7 days; no key, prompt or text) per profile; the Desktop panel reads that file and queues its settings requests through its own dashboard/plugin_api.py route (GET /state, POST /control, this plugin's plugin-data folder only); after Hermes' own fallback answered a reply, the Desktop page sets that conversation's model back to the model the reply started on with config.set --session (never --global; config.yaml is not written); while every key is resting and no fallback model can take over, chats (CLI, Desktop, messaging gateway) keep waiting with no total limit (each key's rest capped by max_hold_seconds) and cron runs give up after 300 s with the provider's refusal unless max_total_wait_seconds is set. Optional speech: where Hermes offers register_tts_provider, the plugin registers a text-to-speech provider named kame-gemini, unused until the owner sets tts.provider: kame-gemini; it sends each sentence to Gemini's own endpoint on the owner's Gemini keys, rotated like the chat's, rests a refused key as long as Google said and waits at most once, under 2 s, for a key about to come back. Optional listening: where Hermes offers register_transcription_provider, the plugin registers a speech-to-text provider named kame-gemini, unused until the owner sets stt.provider: kame-gemini; it sends the recording to Gemini's own endpoint on the same keys, rotated the same way. Extra billed requests (chat replies only, plain API keys only - a credential Hermes records as a subscription is never raced; hedge_mode off turns them all off): a late reply, or one whose model has just answered busy (a 5xx on a key: the next model of the list is then asked beside the retry at once), may also be sent to up to two more keys of the same model (about 10% of replies, 30% in "Faster", bursts of 3), to up to two next models of your fallback list on the same provider, keys and endpoint, and to one more model of the list when it stays silent; a best model that is busy, or remembered as failing (its latest judged outcome failed, with at least two failures in its last ten within seven days; the reply then starts on the next model of your list, and KAME_NO_REMEMBERED_TROUBLE=1 turns this off), may be asked again beside a reply every 20 s - less often the longer it keeps failing, at most every 5 min - and that ask is heard to its first word or 30 s; a model of the list left out for its record is a candidate again 10 min after its latest failure (doubling, at most 2 h); when keys keep coming back out of quota the next attempt asks 4, then 8, then up to 16 keys at once (probe_burst_max_legs); and a reply that showed a thought and then went quiet with nothing shown past its learned limit (8-20 s, at most 90 s; thought_quiet_s sets it, 0 turns it off) may be asked once more on another key of its model (the same key when it has only one) and once on the next model of your list (another key of the same model when no other model may be asked), its thoughts still shown live, the first to show text or a tool call being the answer; if those stay silent too, the reply is handed to the next entry of your list; and an answer that has begun and then sends nothing for answer_quiet_s (45 s; 0 turns it off; never while a tool the provider runs on its side is in flight) is continued with one more request. Titles and other background jobs are limited to a few requests and are stopped with a timeout so Hermes moves them down your own list; a title on a model remembered as failing, or busy, goes once to the first healthy model of your list on the same provider.

Kame6964Modelsv1.9.0.1Updated 2 days ago

About

Smart API key rotation: the healthiest key for every call, each 429 / RESOURCE_EXHAUSTED / quota refusal sized from its own evidence. Install with its companion hermes-kame-provider, which hands Hermes this plugin's rotating client through ProviderProfile.create_client (and create_messages_client where Hermes offers it); no core override. When Hermes has a fallback list, a reply whose model is busy, resting or slow moves down a ladder: the model the reply started on, then the main model (model.default), then the rest of the list; a model of the same provider answers inside the plugin on the same keys and endpoint, a model of another provider is handed to Hermes' own fallback (which walks the list), and a late reply can be raced by the next model of the same provider; nothing moves once part of the reply is on screen, and never_fall_back_to_another_model turns every switch off (the plugin reads the model and fallback_providers from config.yaml, read-only; no new network destination). Disclosure — /kame-keys add|import|split, and on start a key variable holding several comma-joined keys, write one auth.json pool row per key through Hermes' pool API after an owner-only plaintext backup (last 5 kept; switch: resolver_disabled); settings changed from /kame or the Desktop panel are saved as KAME_* lines in Hermes' .env; key-redacted, size-capped owner-only local logs (current file plus one previous), a status file, a small lifetime-counters file (replies answered and saved, requests sent per model in 24 hours, the provider's stated daily limit; no key, prompt or text) and a small model-health file (the time and the success or failure of each model's last judged outcomes, at most 7 days; no key, prompt or text) per profile; the Desktop panel reads that file and queues its settings requests through its own dashboard/plugin_api.py route (GET /state, POST /control, this plugin's plugin-data folder only); after Hermes' own fallback answered a reply, the Desktop page sets that conversation's model back to the model the reply started on with config.set --session (never --global; config.yaml is not written); while every key is resting and no fallback model can take over, chats (CLI, Desktop, messaging gateway) keep waiting with no total limit (each key's rest capped by max_hold_seconds) and cron runs give up after 300 s with the provider's refusal unless max_total_wait_seconds is set. Optional speech: where Hermes offers register_tts_provider, the plugin registers a text-to-speech provider named kame-gemini, unused until the owner sets tts.provider: kame-gemini; it sends each sentence to Gemini's own endpoint on the owner's Gemini keys, rotated like the chat's, rests a refused key as long as Google said and waits at most once, under 2 s, for a key about to come back. Optional listening: where Hermes offers register_transcription_provider, the plugin registers a speech-to-text provider named kame-gemini, unused until the owner sets stt.provider: kame-gemini; it sends the recording to Gemini's own endpoint on the same keys, rotated the same way. Extra billed requests (chat replies only, plain API keys only - a credential Hermes records as a subscription is never raced; hedge_mode off turns them all off): a late reply, or one whose model has just answered busy (a 5xx on a key: the next model of the list is then asked beside the retry at once), may also be sent to up to two more keys of the same model (about 10% of replies, 30% in "Faster", bursts of 3), to up to two next models of your fallback list on the same provider, keys and endpoint, and to one more model of the list when it stays silent; a best model that is busy, or remembered as failing (its latest judged outcome failed, with at least two failures in its last ten within seven days; the reply then starts on the next model of your list, and KAME_NO_REMEMBERED_TROUBLE=1 turns this off), may be asked again beside a reply every 20 s - less often the longer it keeps failing, at most every 5 min - and that ask is heard to its first word or 30 s; a model of the list left out for its record is a candidate again 10 min after its latest failure (doubling, at most 2 h); when keys keep coming back out of quota the next attempt asks 4, then 8, then up to 16 keys at once (probe_burst_max_legs); and a reply that showed a thought and then went quiet with nothing shown past its learned limit (8-20 s, at most 90 s; thought_quiet_s sets it, 0 turns it off) may be asked once more on another key of its model (the same key when it has only one) and once on the next model of your list (another key of the same model when no other model may be asked), its thoughts still shown live, the first to show text or a tool call being the answer; if those stay silent too, the reply is handed to the next entry of your list; and an answer that has begun and then sends nothing for answer_quiet_s (45 s; 0 turns it off; never while a tool the provider runs on its side is in flight) is continued with one more request. Titles and other background jobs are limited to a few requests and are stopped with a timeout so Hermes moves them down your own list; a title on a model remembered as failing, or busy, goes once to the first healthy model of your list on the same provider.

KAME — API Key Rotation for Hermes

Paste several API keys. KAME picks the healthiest one for every call, reads every refusal, and keeps recoverable rate limits from prematurely ending your turn.

Smart API key rotation, 429 / RESOURCE_EXHAUSTED recovery and rate-limit failover for Hermes — Gemini, OpenAI, OpenRouter, Anthropic, or any provider. No third-party package, no telemetry, no key ever printed.

Full documentation and screenshots: https://github.com/Kame696/kame-api-rotation-for-hermes

In 30 seconds

  • One field, many keys. Put key1,key2,key3 in the provider field you already use.
  • The healthiest key, every call — fewest requests in the last 60 seconds, least recently used on a tie.
  • It reads the error instead of guessing. Throttle, daily quota, outage and dead key each get their own wait — the provider's own number whenever it states one.
  • A prompt no key can answer goes straight back. A provider's safety refusal is not a tired key: Hermes gets it at once, and no key is rested for it.
  • No key sits out longer than an hour, and KAME never silently switches you to another model.
  • When every key is resting, it waits for the first one back and tells you how long. For cron or an unattended gateway, max_total_wait_seconds (off by default) bounds that wait. Past the bound, the provider's refusal goes to Hermes.

Install

hermes plugins install Kame696/kame-api-rotation-for-hermes/hermes-kame-api-rotation
hermes plugins install Kame696/kame-api-rotation-for-hermes/hermes-kame-provider
hermes plugins enable hermes-kame-api-rotation

Both are needed: hermes-kame-api-rotation is the carousel, the commands and
the panel; hermes-kame-provider (a model-provider plugin) is how Hermes asks
it for a client. Either one alone changes nothing — Hermes builds its own client.

Restart Hermes once. This also mounts the panel's backend route. The Desktop panel ships in desktop/plugin.js. Turn it on in Desktop Settings → Plugins, and you will find KAME's settings there too. Then paste your keys, comma separated, into one provider field:

GOOGLE_API_KEY=AIzaSy...aaa,AIzaSy...bbb,AIzaSy...ccc

How KAME reads every error

The provider saysKAME does
429 with a stated wait (retryDelay, Retry-After, a reset header)rests that key exactly that long, up to the 1-hour ceiling
Gemini 429 RESOURCE_EXHAUSTED with no number1s, then 2, 4, 8, 16, 32, 64s on each repeat; back to 1s when it answers
Any other throttle with no numbera short flat rest, 20–30s
A daily quotaa 5-minute re-probe while other keys answer; 1 hour once the whole pool has been silent 20 minutes
An account-wide limitthat credential rests on every model of the provider, up to the ceiling
Out of credit1 hour
5xx / overloaded1 second, never escalates
Timeout / dropped connectionnext key; no rest
"This key is invalid / revoked"out of rotation until you replace it
403 for one model onlythat key skips that model only
A safety refusal of the prompt (every wording Hermes itself lists)handed to Hermes at once; no key is rested
Anthropic's "extra usage is required for long context"handed to Hermes at once, so it can shorten the request
An answer cut mid-streamcontinued on another key, joined into one reply
Anything it cannot sizeleft to Hermes' own classifier

Commands

  • /kame — pool health, counters, what is resting and the build fingerprint
  • /kame doctor — is it rotating correctly, and what only a person can fix
  • /kame get · /kame set <key> <value> · /kame reset <key> — settings, live
  • /kame-quota — the quota picture per key and per model
  • /kame-keys — add and inspect keys in bulk. add and import write to ~/.hermes/auth.json, after saving a plaintext backup auth.json.kame-<timestamp>.bak beside it (last 5 kept)

Voice (Hermes)

KAME registers a speech provider named kame-gemini. It speaks with your Gemini keys, rotated
like the chat's: a comma list in GOOGLE_API_KEY is read as the keys it holds, every sentence
goes to the healthiest key, and a refused key rests as long as Google said while the same
sentence goes to the next one. Speech never waits for a rested key: when every key is resting it
fails at once and says when the first is back. One sentence has a 60 s budget, and a second
connection failure in it ends it at once. With KAME's rotation switched off, this speech stops
too and says so: Hermes does not move to another speech provider by itself, so pick another
tts.provider if you want speech while rotation is off.

To use it, set this in the profile's config.yaml (your choice; nothing switches it on for you):

tts:
  provider: kame-gemini
  voice: Kore                          # optional, any Gemini prebuilt voice
  model: gemini-2.5-flash-preview-tts  # optional, else Hermes' own default for Gemini speech

Hermes' live voice mode is OpenAI only, so it cannot use these keys. Agent Zero's voice runs
locally and needs no key, so there is nothing to rotate there.

How it plugs into Hermes

No runtime overrides. Hermes asks a provider profile for its model client
(ProviderProfile.create_client, the documented way to bring a transport), and
KAME's companion package hermes-kame-provider answers with a client that
rotates the keys. No Hermes module, class or dict is rebound. The Desktop panel
uses only @hermes/plugin-sdk, through its own backend route
(dashboard/plugin_api.py). hermes plugins validate passes both packages.
Full notes: CHANGELOG.

Two Hermes seams that are not merged yet. KAME uses each one as soon as
your Hermes has it:

  • notify_turn_status
    (#133474):
    the
    live status line ("next key in 2m 10s") on the spinner. Without it, the line
    appears only above the Desktop composer.
  • create_messages_client
    (#133461):

    per-call key rotation on the Anthropic Messages wire. Without it, KAME sizes
    each refusal there but does not pick the key.

Both seams arrive with those Hermes pull requests. Until then, the author's
repository also has an optional hermes-kame-bridge package that adds them
early. It patches Hermes core at runtime, is not supported by Hermes,
and is not part of this catalog entry.

MIT licence. Issues: https://github.com/Kame696/kame-api-rotation-for-hermes/issues

README from the reviewed commit 0d7cdce; it updates when the author re-pins.

More by Kame696

2 plugins by Kame696 in the catalog.

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section