Introduction

When running DeepSeek models locally, continuously monitoring the API balance is a necessary task. Manually checking the web interface or terminal is both inefficient and unintuitive. dsh-balance-local is designed for this scenario, integrating balance queries into the DSH UI and providing an intuitive display panel and badge while strictly following security principles to ensure the API key does not leave the Host process.

What Is It

This is a DeepSeek Harness (dsh) plugin developed by maintainer chenpengye. It is a Cordis bundle intended to provide balance query capabilities for dsh, including a settings-page panel and an input-box badge. The core value of this plugin is: API requests are completed on the Host side, and only masked balance data is returned to the browser.

Core Features

This plugin provides the following features:

  • Settings-page panel: Displays a “DeepSeek Balance” panel on the DSH settings page, including total balance, top-up balance, and gift balance. The panel provides a manual refresh button.
  • Input-box badge: Displays a balance-status badge below the conversation input box. Green indicates available balance, orange indicates no balance, and gray indicates loading or an error.
  • Automatic refresh: Automatically refreshes the balance every 60 seconds by default. The Host side caches responses for 30 seconds.
  • Security mechanisms: The API key is resolved only from the credential store of the Host process and is never sent to the browser. The routes provided by this plugin allow local loopback access only (default allowRemote: false). Error messages are categorized and sanitized, and upstream response bodies are not passed through.

Installation and Enablement

Because this plugin is not published to npm, it must be installed from source.

  1. Clone and build
    git clone https://github.com/chenpengye/dsh-balance-local.git
    cd dsh-balance-local
    pnpm install && pnpm build

After the build completes, `index.js` and `client.js` are generated in the `lib` directory.
  1. Install the dependency
    cd ~/.dsh/profiles/web
    pnpm add /absolute/path/to/dsh-balance-local -w
  1. Register the plugin
    Edit ~/.dsh/profiles/web/cordis.patch.yml and add the following entry:
    - insert:
        - id: dsh-balance-local
          name: dsh-balance-local
  1. Restart and refresh
    Restart dsh web (or trigger HMR hot reload), and perform a hard refresh in the browser (Cmd+Shift+R / Ctrl+Shift+R).

Typical Usage

No extra configuration is required. The API key reuses the DEEPSEEK_API_KEY saved in the dsh credential store (the same key saved in Settings → Model). After the plugin starts, it automatically reads this credential and queries the balance.

Use Cases and Notes

  • Runtime environment: The plugin runs with the permissions of the current dsh process. Ensure read/write permissions for the ~/.dsh/profiles/ directory.
  • Security configuration: By default, the plugin routes reject non-loopback requests. If you need to access the balance-query endpoint from other devices on the local area network, change the configuration item to allowRemote: true.
  • Response headers: The API response headers include no-store and nosniff. This is a standard security practice.
  • Updates: After modifying the source code, rerun pnpm build and restart dsh.

Conclusion

dsh-balance-local solves the cost-monitoring problem for developers by localizing balance queries and integrating them into the DSH UI. Its security design ensures the safety of the API key. For more details and source code, visit: GitHub Repository.