Introduction¶

DeepSeek Harness (DSH) uses a single global credential reference by default (typically DEEPSEEK_API_KEY), causing all sessions and workspaces to share the same API key. This makes it difficult to associate API usage costs with specific development or testing tasks. The dsh-workspace-api-key plugin solves this cost attribution and key management problem by assigning independent keys to different scopes within a hierarchical structure.

Plugin Overview¶

This is a DeepSeek Harness plugin maintained by COH2357, used to bind a separate DeepSeek API key to each workspace or individual session. It intercepts the credential resolution flow and implements hierarchical key overrides from “system default” to “workspace” to “session,” ensuring that if a level has no custom key, it automatically inherits the configuration from the level above.

Core Features¶

• Hierarchical Key Management
  The plugin supports three levels of key configuration: session level, workspace level, and system default level. The configuration logic follows the priority order session key → workspace key → system default.

• Sidebar Interface
  Adds an API Key Assignment row in the DSH sidebar, located directly below the host plugin row. Expanding this row displays all workspaces and their sessions, with an independent key input field at each level.

• System Default Card
  Displays the currently effective global default reference (DEEPSEEK_API_KEY), its source (such as a file, environment variable, etc.), and the masked value.

• Connection Testing
  Performs a real POST <baseURL>/messages request using the bound key (with max_tokens: 1) and returns an ok, invalid, quota, rate-limit, or unreachable status. A successful test can clear expired flags.

• Expiration and Mismatch Warnings
  If a bound key returns 401/403, it is marked as invalid; 402 is marked as quota; 429 is marked as rate-limit. If a key does not match the currently used Provider, a warning is displayed via an overlay when entering the session, but the key is not automatically switched.

• Security and Control
  The plugin does not silently replace keys; the decision remains entirely with the user. Responses never contain plaintext keys; only masked values are displayed. API access is restricted to Loopback calls (127.0.0.1, ::1, etc.).

• One-Click Rollback
  Clearing the key configuration for a session or workspace restores the previous level of configuration (a session falls back to the workspace, and a workspace falls back to the system default).

Installation and Enablement¶

The plugin is installed by directly adding the GitHub repository via a package manager. Run the following command in the DSH configuration directory (for example, ~/.dsh/profiles/desktop):

pnpm add "dsh-workspace-api-key@github:COH2357/dsh-workspace-api

After installation, the plugin automatically registers into the credentials.resolve flow and creates the corresponding entry in the sidebar.

How It Works¶

The plugin works through two cooperating components: the Host side (lib/index.js) handles credential resolution, while the Browser side (lib/client.js) handles UI rendering and interaction.

The Host side wraps credentials.resolve using ctx.effect and reads the current session directory and ID each time credential resolution occurs. It matches the directory against workspaceRegistry.list() (normalizing path casing and suffixes) and generates unique reference names for matching workspaces:
- Workspace reference: DEEPSEEK_API_KEY_WS_<first 16 hex chars of sha1(normalized path), upper-cased>
- Session reference: DEEPSEEK_API_KEY_SS_<first 16 hex chars of sha1(session id), upper-cased>

The plugin only rewrites the references actually read by the Provider (the default reference, the adapter’s apiKeyEnv configuration, and generated references); all other references remain unchanged. It records information such as invalidation flags and Provider mismatches to the local storage file $DSH_HOME/storages/dsh-workspace-api-key.json.

The Browser side registers with React into slots such as sidebar.panellist and shell.overlay to render the key assignment panel. It retrieves the session list from sessionController or the sessions service and filters out sub-agent sessions and blank sessions, ensuring that the panel contents match the sidebar.

HTTP API¶

The plugin provides a set of REST API endpoints, restricted to Loopback calls only, and responses do not contain plaintext keys.

Notes¶

• The plugin runs with the permissions of the current DSH process; it is recommended to review the source code before installation.
• Only Loopback calls are accepted, and responses do not contain plaintext keys.
• The plugin does not perform silent replacement and does not automatically switch keys due to warnings, which aligns with its design goal of attributing spending to specific sessions.
• Some features depend on the workspaceRegistry and sessionController services. If these services are unavailable or return errors, the panel may fail to display the session list correctly.

Summary¶

dsh-workspace-api-key provides a fine-grained DeepSeek API key management solution. Through hierarchical overrides and clear warning feedback, it helps developers achieve independent billing and key management per workspace or per session without changing the core logic of DSH.