Preface

If you have been running the same LLM provider in DeepSeek Harness (DSH) for a long time, you have likely encountered this situation: the task runs halfway, the request returns QUOTA or 429, forcing the entire workflow to stop, requiring manual key swapping, process restart, and context restoration.

A common practice in the community is to write scripts to monitor logs and perform manual intervention. However, such solutions detach from Harness’s own request flow and cannot handle the task of “swapping keys and retrying immediately.” The dsh-llm-key-rotation plugin written by m1khal3v incorporates this step into Harness’s recovery chain: when a request fails, it automatically switches to the next key in the configured chain and retries immediately. No restart is needed, and context is not lost. Below is an introduction to its features, installation, and configuration.

What is this

dsh-llm-key-rotation is a plugin for DeepSeek Harness. Its positioning in the README is “Seamless API-key rotation for DeepSeek Harness” — providing seamless API-key rotation for LLM providers. The author is m1khal3v, current version 1.1.0, license MIT, and the README badge indicates compatibility with DeepSeek Harness v0.1.1-rc.1.

The scenarios it solves are specific: when a key for a provider triggers QUOTA, RATE_LIMIT, or AUTH errors, the plugin takes the next one from your pre-configured key chain and retries the request immediately after a hot swap. For Agents and users, this process is transparent — the current request is retried successfully with the new key, and subsequent requests continue to use the currently available key.

Core Features

According to the README, the plugin provides the following capabilities:

  1. Error-triggered Hot Swap: When a request returns QUOTA / RATE_LIMIT / AUTH, automatically switch to the next key in the configured chain and retry immediately, without restart, without losing context.

  2. Transparent to Agents and Users: Retry is imperceptible to requests; the workflow will not be interrupted due to quota issues.

  3. Native Web UI: View all keys available for the provider in Settings and toggle the rotation switch.

  4. Smart Anti-Spin: Built-in cooling mechanism to prevent infinite loops when all keys are exhausted.

  5. Smart Rotation Window (300 seconds): When failing consecutively, rotate keys forward sequentially; if no failure occurs for more than 5 minutes, the chain resets to the head to start over.

  6. Zero-core Patch: The plugin cleanly integrates into Harness’s recovery waterfall; installation and removal do not modify the core.

  7. Secure Key Storage: Keys are stored in Harness’s credential store.

  8. Terminal Real-time Logs without Key Leakage: Rotation events are output to the dsh terminal in real-time; logs only contain provider name, index, and error code, without recording key values.

Installation

The plugin is installed via web profile. Execute the following in your terminal:

dsh plugin --profile web add @m1khal3v/dsh-llm-key-rotation

Environmentally, the package.json engines require Node ^22.19 || >=24.

Configuration and Usage

After installation, go to Settings → Plugins → Key Rotation and configure as follows:

  1. Turn on the rotation switch for the target provider.
  2. Select trigger codes (default is QUOTA, AUTH).
  3. Click Add key and paste all keys to be rotated for that provider one by one, then click Save.

Keys are saved to Harness’s credential store and will not appear in plaintext configuration.

After configuration, rotation events are output to the dsh terminal in real-time. The log format is as follows:

[llm-key-rotation] rotated provider="opencode-go" chain[0]→"OPENCODE_GO_API_KEY" (QUOTA)

You can see the provider name, index position in the chain, the environment variable name switched to, and the trigger error code; the key value itself will not appear in the logs.

Collaboration with dsh-llm-retry and Rotation Behavior

If you use the dsh-llm-retry plugin simultaneously, the division of labor between the two plugins is:

  • QUOTA and AUTH: Handled by key-rotation immediately.
  • RATE_LIMIT: By default, handed to dsh-llm-retry for backoff retry.

If you want to swap keys immediately when encountering a 429 instead of backing off and waiting, you can remove RATE_LIMIT from the provider’s retryableCodes. Afterward, 429 will trigger the rotation directly.

The rotation itself follows the Smart Rotation Window mechanism: during consecutive failures, the plugin switches keys forward sequentially along the chain; once more than 5 minutes have passed without a failure, the chain resets and starts over next time. This window, combined with the cooling mechanism, ensures that when all keys are exhausted, it does not fall into a meaningless loop.

Applicable Scenarios and Considerations

The scenarios where this plugin is suitable are clear: you have multiple API keys for the same provider and want the workflow to automatically continue when a quota is exhausted or rate limits or authentication errors are encountered, rather than stopping for manual intervention. This is especially true for long-running Agent tasks; the higher the cost of interrupt and recovery, the more obvious the value of this plugin.

There are a few points to confirm before use:

  1. The plugin runs with the permissions of the current dsh process. It needs to read your keys and intervene in the request recovery process. It is recommended to check the source code (repository address at the end of the article) before installation to confirm the implementation meets expectations.

  2. Confirm the license. The project uses MIT, allowing free use and modification.

  3. The installation command uses the web profile, and the client platform is web. Confirm this matches your deployment method.

  4. If you participate in the development of the plugin itself, the repository provides a standard verification process:

pnpm install
pnpm run verify    # typecheck + test
pnpm run build

Conclusion

What dsh-llm-key-rotation does is not complicated, but it hits a real pain point: handling quota and rate limits in multi-key scenarios. It achieves hot switching by integrating into Harness’s recovery waterfall, without modifying core code. Combined with the Web UI and credential store, the cost of installation and configuration is very low.

  • Plugin Directory Page: https://www.skillhub.cn/plugins/m1khal3v/dsh-llm-key-rotation
  • GitHub Repository: https://github.com/m1khal3v/dsh-llm-key-rotation

Note: The plugin directory skillhub.cn is an independent community site and has no official affiliation with DeepSeek or High-Flyer.