Introduction

The web_search tool in DeepSeek Harness (DSH) uses the officially provided search capability by default. In real-world use, a single route or single provider is often insufficient for quota management, fault tolerance, and flexibility. The dsh-tavily plugin replaces DSH’s official web search with the Tavily Search API, providing multi-API key management, balance polling, and automatic failover.

What Is This

dsh-tavily is a persistent plugin for DeepSeek Harness, maintained by Yuuz12. It belongs to the “Web Search” category and follows the MIT license.

This plugin is designed to address the single-source limitation of DSH’s official web search. It allows users to manage multiple Tavily keys in the DSH interface and call them based on balance or a custom order, while also supporting local usage statistics and retry-on-failure mechanisms.

Core Features

  • Replaces the official web search: Once toggled in the settings, when the model calls the web_search tool, it routes through the Tavily API. When disabled, it automatically falls back to the official search.
  • Multi-API key pool management: Supports adding any number of Tavily API keys.
  • Intelligent scheduling strategies:
  • Balance-first rotation: The default strategy. Keys are ordered by remaining quota, with higher quotas used first. Keys with equal quotas are used in rotation.
  • Manual order: Supports defining a custom usage order for keys.
  • Automatic failover on failure: If a key encounters an authentication failure, quota exhaustion, or rate limiting (429), it automatically switches to the next key. 429 rate limiting imposes a 30-second cooldown, while other errors impose a 5-minute cooldown.
  • Local usage statistics and refresh: Locally records call counts, success/failure statuses, and credit consumption. Supports a one-click refresh of balances from Tavily’s official API.
  • Settings integration: Configuration items are directly integrated into the cards in the “Plugin Configuration” interface in DSH.
  • Security integration: Supports integration with dsh-webui-auth to protect API endpoints using session validation.
  • Zero dependencies: Implemented in pure JavaScript with no build steps.

Install and Enable

Before installation, ensure the DeepSeek Harness version is no lower than 0.1.2-alpha.2 (DSH Desktop 2.0.4).

Use the officially recommended npm installation command:

npx @deepseek-ai/dsh plugin --profile web add @yuuz12/dsh-tavily

After installation, DSH must be restarted for the changes to take effect. If an older version is already installed, it is recommended to uninstall it first and then reinstall:

npx @deepseek-ai/dsh plugin --profile web remove @yuuz12/dsh-tavily

Usage

  1. Open Settings → Plugins → Plugin Configuration.
  2. Find and expand “Tavily Web Search” in the card list.
  3. Paste a Tavily API key in the key area (available for free registration at app.tavily.com, with 1,000 credits per month), then click Add Key.
  4. Click the Refresh All Usage button in the top-right corner of the key area to fetch official balance data for each key.
  5. Turn on the Replace Official Web Search switch at the top.
  6. Adjust parameters such as the multi-key strategy (balance-first / manual order), search depth, and maximum number of results per request.

Multi-Key Scheduling Rules

The plugin provides two scheduling modes. The behavior is as follows:

Strategy Behavior Description
Balance-first (default) Keys with more remaining credits are used first; plans without limits have the highest priority; keys whose usage has never been refreshed are placed after known balances as a fallback; tied top keys are used in rotation by request count.
Manual order Keys are used strictly top-down based on the list order, with no rotation.
Failover If any key fails, the next key is automatically tried; an error is reported to the model only if all keys fail.
Cooldown mechanism 401/403 (authentication failure) and 432/433 (over-limit) cause a 5-minute cooldown; 429 (rate limiting) causes a 30-second cooldown. A key in cooldown sinks to the bottom but continues to participate in failover.

Data and Security

  • Storage location: Keys and usage statistics are stored locally. When installed via npm, the data file is located at <profile>/dsh-tavily.json.
  • Privacy protection: Keys are stored locally only and their full contents are not returned in HTTP responses. They are masked in the UI (for example, tvly-…xxxx).
  • Data safety: Upgrading or reinstalling the plugin does not lose keys or statistics; uninstalling the plugin does not automatically delete the data file.
  • dsh-webui-auth integration: The plugin probes the sessions.jsonl file to enable session validation. If found, all /dsh-tavily/* endpoints require a valid dsh_wua_session Cookie; if not found, endpoints remain open.

Conclusion

By introducing a multi-key pool and intelligent scheduling, dsh-tavily provides DSH users with more controllable web search capabilities. It does not depend on external build tools, and all sensitive data is processed locally, making it suitable for scenarios requiring fine-grained management of search quotas.