Introduction

When managing multiple OpenCode Go subscriptions, manually monitoring the balance of each API key, handling usage overruns or gateway errors, and addressing related issues significantly increases operational overhead. The DSH plugin ecosystem advocates “everything is a plugin,” and dsh-llm-api-pool is a tool designed for this scenario. It aggregates multiple OpenCode Go subscriptions into a single pool, queries usage in real time through the official endpoint, and routes requests based on remaining balance to enable hot failover.

Plugin Overview

dsh-llm-api-pool is an API pool plugin designed for DeepSeek Harness (DSH). It is maintained by user bainianlaoyao and follows the MIT license. The plugin addresses fragmented management of multiple API keys and opaque balance states. By collecting multiple {baseUrl, apiKey} entries into a pool, it maintains official usage data locally and automatically forwards model requests according to the “largest remaining balance first” principle; if a key encounters a 429 or 5xx error, it is automatically cooled down and the next key is used.

Core Features

The plugin mainly provides the following capabilities:

  1. Multi-API key pool: It uses {baseUrl, apiKey} as the primary key for each entry. Repeatedly adding the same key updates the configuration in place, while a different key is added as a new subscription. You can manage any number of OpenCode Go subscriptions simultaneously without following a specific naming convention.
  2. Official balance/usage query: The plugin calls the native OpenCode Go gateway endpoint GET https://opencode.ai/zen/go/v1/usage. This allows real-time retrieval of official usage percentages and exact reset times for the rolling (5h), weekly, and monthly quotas without an Org Token. The USD values are converted reference values (percentage × quota), not official raw amounts.
  3. Balance-driven hot failover: Routing decisions prioritize cached official usage pressure data (remotePressure, usageRemote, cache TTL is 5 minutes). Before a model request is sent, if the official usage data has expired, the system refreshes balances non-blockingly and selects the subscription with the largest remaining balance. If the request fails (429, 5xx, or timeout), that key is cooled down for 60 seconds, and the next key in the list is attempted automatically.
  4. Settings page UI: In DSH settings, open the “LLM API Pool” page to add, delete, enable, or disable entries, and probe the model list. Each card independently displays the official quota (progress bar + converted USD + reset time) and the current routing preview.

Installation and Enabling

Install it through the official DSH CLI. The installation process automatically handles dependencies and mounts the Host half and Client half.

dsh plugin --profile web add dsh-llm-api-pool

After installation, the plugin automatically registers the related routes and Provider.

Usage

After installing and starting the plugin, you can use it in the following ways:

  1. Manage via the settings page:

    • Open Settings → LLM API Pool.
    • Click + Add API. Select OpenCode Go as the preset, and the system automatically fills in https://opencode.ai/zen/go/v1 and the default quota information (5h $12 / week $30 / month $60). Paste your OPENCODE_API_KEY and add it; the system then automatically probes the model list.
    • On the card, click “Refresh quota / query balance”, and the system calls the official endpoint and displays [Official] $x.xx / $cap (p%) · Reset HH:MM:SS.
    • Add a second subscription (using a different key), and you will see a second card. Each independently manages its balance. Subsequent model requests are automatically routed to the subscription with the largest remaining balance, with automatic failover on failure.

  2. Use CLI tools:
    The plugin provides a rich set of command-line tools for scripted operations:

    • llm_pool_list / llm_pool_add / llm_pool_remove / llm_pool_update
    • llm_pool_probe / llm_pool_usage / llm_pool_limits / llm_pool_route / llm_pool_chat / llm_pool_balance

Operating Modes

The plugin provides two integration modes to accommodate different use cases:

  1. Use as a native DSH Provider (zero configuration):
    After it is loaded, the plugin automatically registers a model Provider named LLM API Pool (Balance Hot Failover) with DSH.

    • Model selector: The model list is the union of models probed across all entries in the pool. Selecting any model uses the pool routing, and balance hot failover takes over automatically.
    • Parameter support: The model selector automatically shows the reasoning effort option (low/medium/high/max). After selection, it is passed through to the opencode go gateway (reasoning_effort).
    • Model settings: On the model settings page, this Provider appears ready; there is no need to manually fill in baseUrl or apiKey (both come from the pool).
    • Empty pool handling: When the pool is empty, the Provider’s model list is empty; it appears automatically after the first key is added.

  2. Use as an OpenAI-compatible Provider:
    The pool itself exposes OpenAI-compatible API endpoints and reuses the DSH Web service port (default 127.0.0.1:3080).

    • Model list: GET http://127.0.0.1:3080/llm-pool/v1/models returns all models in the pool.
    • Chat endpoint: POST http://127.0.0.1:3080/llm-pool/v1/chat/completions accepts OpenAI-format input, routes internally to a specific key in the pool, and returns OpenAI-format output. Streaming is supported.
    • Integration with any client: Any OpenAI SDK or client can point baseURL to http://127.0.0.1:3080/llm-pool/v1 and provide any apiKey (routing is determined by pool entries) to transparently use balance hot failover.

Data and Security

  • Persistent storage: Entry configuration is persisted in the sandboxPolicy.workspaceRoot/.dsh-llm-api-pool.json file. This file contains API keys in plaintext and relies on local file permissions for protection. Do not commit this file to version control.
  • Network requests: In the Host process, the plugin sends read-only usage queries to opencode.ai and console.opencode.ai. It sends model requests to the entry’s baseUrl only when llm_pool_chat is invoked.

Uninstallation

To remove the plugin, use the following command:

dsh plugin --profile web remove dsh-llm-api-pool

After uninstallation, the configuration file on disk (.dsh-llm-api-pool.json) is retained. If it is no longer needed, delete the file manually.

Summary

dsh-llm-api-pool provides OpenCode Go users with a solution for centralized API key management, real-time official balance monitoring, and automatic failover. It ensures data accuracy through the official endpoint and offers both UI and CLI entry points, making it suitable for DSH users who need to manage multiple subscriptions or pursue high availability.

Related resources:
* GitHub repository
* Plugin catalog page