Introduction

DeepSeek Harness (dsh) provides plugin-based extensibility. dsh-freeroute is a plugin for model inference workflows. It aggregates multiple upstream model services that offer free quota, addressing issues caused by a single model source being unstable or running out of quota.

Plugin Positioning

This is a free model aggregation plugin maintained by 0xrushmoon, and it belongs to the model inference tool category. It registers the freeroute model provider and connects to built-in and remote free-quota upstreams.

Core Features

  • Transparent failover: Before the first token is delivered to the session, the system can automatically switch upstreams. If the current upstream fails, is rate-limited, or its key is invalid, the request is routed to the next available node.
  • Multi-key rotation: Each upstream supports up to 8 API keys. When an individual key encounters authentication or rate-limit errors, the system cools down that key and switches to the next one until an available key is found.
  • Failure visibility: The panel displays a warning explicitly stating “Key N is invalid,” making troubleshooting easier.
  • Privacy protection: By default, API keys are masked (••••••). The full key is shown only after clicking “Show”. Keys are stored only in the credentials service and are not written to plaintext configuration files.
  • Built-in free upstreams: It integrates built-in free upstreams such as OpenCode Zen, B.AI, OpenRouter, and SenseNova.
  • Three-tier configuration: Configuration priority is built-in catalog -> remote catalog -> user patch.

Installation and Enablement

Make sure the environment satisfies Node.js ≥ 18, then run the following command to install:

dsh plugin --profile web add dsh-freeroute

After installation, the model selector will include freeroute/auto (automatic failover) and freeroute/<upstream>/<model> (fixed model) options.

Typical Usage

The plugin includes an OpenAI-compatible local endpoint (default port 3080). Other tools can call this endpoint directly to use the free model pool.

  1. API call example:
    curl http://127.0.0.1:3080/freeroute/v1/chat/completions \
      -H 'content-type: application/json' \
      -d '{"messages":[{"role":"user","content":"hello"}]}'
  1. Configure API key: Configure the upstream API key in the plugin’s “Free” panel settings.
  2. Use a model: In the OpenAI-compatible endpoint, set the model name to auto and let the system automatically select the highest-priority upstream.

Notes

  • Runtime environment: The plugin runs with the permissions of the current dsh process.
  • Proxy settings: The global proxy is disabled by default and can be configured in settings.
  • Free quota: This refers to the provider’s legitimate free quota, not a shared account pool.

Ecosystem Background

The philosophy of DeepSeek Harness (dsh) is “everything is a plugin.” The community directory has no official affiliation with DeepSeek.

  • Plugin homepage: https://www.skillhub.cn/plugins/0xrushmoon/dsh-freeroute
  • Source code: https://github.com/0xrushmoon/dsh-freeroute