Introduction¶

A common requirement when running agents with DSH is having multiple API Keys for the same endpoint address: switching to a backup key when the primary one is rate-limited, or rotating them based on quotas. The native approach is to modify the credentials references in the configuration or environment variables, which only takes effect after saving and restarting DSH. Switching once is not costly, but repeatedly restarting during troubleshooting disrupts ongoing requests.

Below is an introduction to dsh-api-key-switch, a Web plugin maintained by my-0228. It adds a new page in the settings panel, stores multiple Keys locally in the credential database, and allows switching by clicking “Use” in the list. The change takes effect on the next model request without requiring a DSH restart. The plugin belongs to the admin-security category, has no runtime dependencies, and no build steps.

What is this¶

One-sentence definition: A DSH Web plugin that saves multiple API Keys in the settings panel and switches the currently active one.

• Maintainer: my-0228 (author in package.json is mayue, email: 1771826962@qq.com)
• License: MIT
• Version: 1.0.0
• Requirements: DSH 0.2.x (Web), Node.js >= 20
• Path: dsh-api-key-switch (package name and plugin id are the same)

It does not modify DSH’s own model configuration interface; it simply adds a page in the left navigation of the settings, reusing DSH’s existing client slot contract (settings.section) and Connection RPC envelope. The native “Settings -> Models” page remains fully usable, and both sides read from the same underlying credential facts.

Core Features¶

1. Adds a new page “API Key Switch” in the left navigation of the settings panel.
2. Saves multiple API Keys (Name + Key) locally; click “Use” in the list to switch.
3. Writes the selected Key into the credentials referenced by the current LLM route (default DEEPSEEK_API_KEY); the credential database is parsed per request, so the change takes effect on the next model request.
4. The list only displays masked keys (e.g., sk-a…599c); plaintext only exists at the moment of input and does not return to the browser.

The “Currently Active” column can display either the Key name within the plugin or “External Settings”. The latter indicates that the credential was written elsewhere (e.g., the official “Models” page), and you can manage it by clicking “Add to list”.

Installation & Enablement¶

The installation command comes from the README; install via profile and enter the web platform:

dsh plugin --profile web add github:my-0228/dsh-api-key-switch

This command creates dependencies in the profile and appends this package to dsh.profile.bundles (this package declares dsh.bundle.patch). Refresh the DSH page after completion; if the new page does not appear in the settings panel, restart DSH once.

You can also install from a local directory during development for immediate testing:

dsh plugin --profile web add /path/to/dsh-api-key-switch

In development mode, both halves are pure source code: the Host half is a standard ESM Cordis plugin lib/index.js, and the Browser half is a hand-written window.__ModuleLoader__.load({id, factory}) wrapping CJS lib/client.js; no build steps are required.

Typical Usage¶

First, prepare a credential reference in the profile. The plugin defaults to writing DEEPSEEK_API_KEY; as long as your LLM route references this name, you can use it directly. You can also override ref via the profile overlay (see the next section).

1. Open Settings, and select “API Key Switch” in the left navigation.
2. Fill in “Name” and “API Key”, check “Enable immediately after saving”, and save.
3. In the future, click “Use” in the list to switch; the row currently in effect is marked with “In Use”.

Three rules to know in advance:

• The same Key can only be saved once. Otherwise, a duplicate entry will appear that is displayed as not effective but cannot be deleted.
• Deleting the row that is “In Use” will be rejected.
• When changing the Key in the “In Use” row, the new Key will automatically take over effectiveness, leaving no state where the “old Key is still in use”.

Configuration Items¶

There is a Host line in the Cordis patch for this package:

- insert:
    - id: dsh-api-key-switch
      name: dsh-api-key-switch
      config:
        ref: DEEPSEEK_API_KEY   # Credential reference to switch; changing to other apiKeyEnv also works

• ref: Credential reference name in POSIX identifier form, default is DEEPSEEK_API_KEY.
• RPC route /api/dsh-api-key-switch is hardcoded on the same convention in both browser and host halves; to change it, you must change constants in both lib/index.js and lib/client.js.
• When changing ref, please modify it via the profile overlay (targeted override by id in cordis.patch.yml), do not modify this package’s patch directly: the patch performs a full replacement of config, not a merge.

Storage & Security Boundaries¶

Saved Keys are placed in the record area of the DSH credential database $DSH_HOME/.credentials.yaml, with the shape as follows:

records:
  dsh-api-key-switch/<id>:
    kind: grant
    payload:
      label: Primary
      apiKey: sk-…
      createdAt: 2026-11-03T02:41:59.797Z

There are several common pitfalls, all documented in the README:

• id is of the form k-<uuid> and must start with a lowercase letter. The credential database requires each segment of the record key to match [a-z][a-z0-9-]*; otherwise, the entire credential file parsing will fail on the next startup, affecting all LLM routes.
• “Currently Active” is not stored separately; it is equal to the value of refs[ref]. Manually editing the credential file will not cause inconsistencies between the two sides.
• Switching uses the credential service’s set(): atomic write plus cross-process lock.
• Validation: Name 1–64 characters, control characters prohibited; Key 8–512 visible ASCII characters, whitespace prohibited; maximum 50 keys; Key duplicates are not allowed; deleting an active Key is rejected.
• When the credential database is read-only (describe().writable === false), all write operations on this page are disabled and the reason is explained.
• On Windows, the protection of the credential file depends on the directory ACL, consistent with DSH’s own credential database.
• The plugin does not go online, does not perform Key validity validation, and does not write Keys to logs or locations outside the frontend.

Uninstallation & Cleanup¶

dsh plugin --profile web remove dsh-api-key-switch

Uninstalling does not delete saved Key records. Key records remain in the records of .credentials.yaml, and refs retains the result of the last switch. For cleanup, only delete the entry; do not manually write or modify record contents: simply delete the entire section starting with dsh-api-key-switch/ under records. Writing the wrong shape (e.g., missing kind: grant/payload) will cause parsing failure on the next startup.

If invalid record keys already exist in .credentials.yaml (symptoms are credential errors for all model requests after DSH starts, or invalid document appearing in logs), use the accompanying script to rename them in one click. The default only fixes this plugin’s scope and defaults to a dry-run:

node scripts/repair-credentials.mjs            # Dry run, only prints
node scripts/repair-credentials.mjs --apply    # Actual fix (backs up .credentials.yaml.bak-<timestamp> before writing)

The script only fixes the spelling of the record key (adding the k- prefix), leaving payload, refs, comments, and other scopes intact; restart DSH or wait for it to reload the credential database after fixing.

Applicable Scenarios & Notes¶

Suitable for: Developers who have multiple keys for the same source for one LLM route, need to manually rotate based on rate limits, quotas, or costs, and do not want to restart DSH for every switch. If your requirement is to switch baseURL or switch models, this plugin is not applicable.

Please note the following:

• The plugin runs with the permissions of the current DSH process, with write capabilities equivalent to DSH’s credential database access permissions. You should check the source code and license (MIT) before installing to confirm that the credential reference names it accesses match your configuration.
• The plugin does not perform Key validity validation and does not go online. When a Key is invalid, DSH will report the error natively.
• No exported Config (schemastery); ref validation is written manually in apply, and the plugin inspector cannot see the form.
• The browser half relies on DSH 0.2.x’s client slot contract and Connection RPC envelope; after upgrading DSH to a major version, you need to review based on the new contract.
• Ecosystem background: DSH’s philosophy is “everything is a plugin”; the directory site is an independent community site with no official affiliation with DeepSeek / Synthesia.

Summary¶

dsh-api-key-switch solves the rotation problem of having multiple keys for the same interface: panel management, local storage, request-based effectiveness, and no restart required. It does only this one thing, with very clear boundaries. Directory page and source code are as follows:

• Directory page: https://www.skillhub.cn/plugins/my-0228/dsh-api-key-switch
• GitHub: https://github.com/my-0228/dsh-api-key-switch