Rotates configured LLM API keys after quota, rate-limit, or authentication failures.
Install
# from npm (prebuilt)
dsh plugin --profile web add @m1khal3v/dsh-llm-key-rotation
# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)
dsh plugin --profile web add github:m1khal3v/dsh-llm-key-rotation
Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).
README
⚡️ Highlights
- 🔄 Invisible to Agent & User: Request fails with quota/rate limit → plugin hot-swaps the key → request retries and succeeds seamlessly.
- 🎛 Native Web & Desktop UI: List every key a provider can use and toggle rotation right inside Settings → Plugins.
- 🧠 Smart Anti-Spin: Cooldown discipline prevents infinite loops if all your keys are exhausted.
- 🧼 Zero Core Patches: Plugs cleanly into the Harness recovery waterfall — safe to install, safe to remove.
🛠 How It Works
┌─────────────────┐ 429 / QUOTA / AUTH ┌──────────────────────┐
│ Model Request │ ───────────────────────────────────► │ llm-key-rotation │
└─────────────────┘ └──────────┬───────────┘
▲ │
│ { kind: 'retry' } │ 1. Pick next key
│ (Adapter re-resolves key) │ 2. Hot-swap env ref
└──────────────────────────────────────────────────────────┘
- You keep working with your currently-active key as usual.
- If a request fails (
QUOTA,RATE_LIMIT, orAUTH), the plugin loads the next key from your configured chain. - The turn retries with the new key, and future requests continue with the working key.
🚀 Quick Start
1. Install the plugin
Desktop app — open the Plugins page and install @m1khal3v/dsh-llm-key-rotation. The desktop client is a web client, so the same browser-half card renders there.
CLI / local install — add the plugin to your web profile:
dsh plugin --profile web add @m1khal3v/dsh-llm-key-rotation
2. Configure via the Plugins UI
Navigate to Settings → Plugins → Key Rotation tab:
- Toggle on rotation for your target provider.
- Select your trigger codes (default:
QUOTA,AUTH). - Click Add key, paste all the keys you want that provider to rotate through, and hit Save.
(Keys are safely saved to the Harness credential store).
3. Desktop
Install through the desktop Plugins page, then open Settings → Plugins → Key Rotation. Keys are stored in the desktop profile's credential store. Rotation runs host-side on the same credential seam as the web build, so a rotated key reaches the next request without restarting the app or the session.
⚙️ Behavior & Good to Know
- Smart Rotation Window (300s): During consecutive failures, the plugin walks forward through your configured keys. If no failures occur for >5 minutes, the chain resets to start from the top again.
- Interplay with
dsh-llm-retry:QUOTAandAUTHrotate immediately.RATE_LIMITis handled bydsh-llm-retryfirst (with backoff). To rotate instantly on 429 errors instead, simply removeRATE_LIMITfrom your provider'sretryableCodes.
- Live Terminal Logs: Watch rotation events in real time right in your
dshterminal:
(Secret values are never logged — only provider names, indices, and error codes).[llm-key-rotation] rotated provider="opencode-go" chain[0]→"OPENCODE_GO_API_KEY" (QUOTA)
🧑💻 Development
pnpm install
pnpm run verify # typecheck + test
pnpm run build
📄 License
Links
More in this category
bowenliang123/dsh-context★ 5364
DSH context insight panel: Context dashboard + /context command + Context browser — one-stop context lifecycle management with categorized composition, content details, evolution trends, compaction/injection events, and stats.
Han-1413141/dsh-cost-meter★ 737
Per-session and daily API cost, budget with usage %, official balance, history dashboard, and one-click official price sync with peak/off-peak pricing.
wssfk12138/dsh-damage-pulse★ 290
Tracks DeepSeek token usage, per-call and session costs, and account balance with cache-aware charge animations in the DSH Web UI.
zh667/TokenLedger★ 205
Sidebar usage panel that attributes tokens to the relay site that served each request, read from your existing provider config: today/month/all-time totals, per-site and per-model breakdowns, a year activity heatmap, and New API / Sub2API / DeepSeek balances.
Ychris12138/dsh-usage-stats★ 192
Multi-provider usage dashboard with provider/model token breakdowns, calendar drill-downs, account balances, and OpenCode Go / Z.ai subscription quota tracking.
PolinniZhong/dsh-personal-center★ 115
Personal center for DeepSeek Harness: cross-session usage statistics with per-provider and per-model breakdown (auto-discovers configured models), per-model cost estimation, global custom instructions, a data-driven desktop pet with bitmap & vector skins, and a conversation status overview, all local and offline.
Community comments
Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.