dsh-freeroute

English | 简体中文

Free-tier model aggregation for the DeepSeek Harness (dsh): registers a freeroute model provider backed by a pool of free-quota upstreams (OpenCode Zen / B.AI / OpenRouter / SenseNova built in, plus remote catalogs and custom gateways; other vendors join via the remote catalog). Configure any one API key and you are running; when an upstream rate-limits, dies, or loses its key, requests fail over to the next one before the first token reaches your session. A local OpenAI-compatible endpoint is included.

Free here means providers' legitimate free tiers, with keys you register yourself. This is not a shared-account pool and does not bypass paid APIs.

Key management

• Multi-key rotation — free quotas are per-account, so each upstream accepts up to 8 keys (separated by newlines/commas in the field, or KEY_2…KEY_8 env vars). AUTH / rate-limit failures cool down that single key and rotate to the next one before any upstream is penalized; successes advance the cursor so free quota spreads evenly across accounts.
• Privacy by default — the key field shows a read-only •••••• mask until you click 显示 (show), which opens the editor prefilled with the full key ring (one key per line) ready to edit; saving returns straight to the masked state. Keys live only in the credentials service, never in plaintext config.
• Failure visibility — when a key is detected as dead mid-rotation, the panel warns 「第 N 把 Key 失效」 (which key failed and why), so a dying account is obvious without digging through logs.

How it works

1. Adapter registration — llm.registerAdapter(['freeroute'], adapter) exposes freeroute/auto (automatic failover) and freeroute/<upstream>/<model> (pinned model) in the model picker.
2. Translation — dsh internal messages ⇄ OpenAI Chat Completions SSE, with reasoning, tool_calls, and usage passed through. Keys live only in the credentials service, never in plaintext config.
3. Health & failover — failures cool down by class (auth/config 10 min, rate limit 60 s, others exponential backoff capped at 10 min). auto picks the highest-priority enabled, keyed, non-cooling upstream; failures before any output switch to the next candidate (empty responses included), failures after output surface to the caller. A pinned single model degrades to the auto chain when all of its providers fail (or sit in cooldown) instead of aborting the turn — picking one model is a preference, not exclusivity. Keys rotate individually on AUTH / rate-limit, and a per-key failure is surfaced in the panel.
4. Three-layer config — builtin catalog → remote catalog (JSON hosted on Cloudflare Pages/R2 for ship-free updates; native format or models.dev api.json, zero-cost models auto-filtered) → user patch persisted under the free-proxy settings namespace.
5. Local endpoint — http://127.0.0.1:<port>/freeroute/v1 is an
6. Global proxy (off by default): set one http://127.0.0.1:7890-style proxy under Settings → Models → Free → Advanced; every upstream without its own proxy (chat requests and model probing) goes through it. Per-upstream custom.proxy and catalog-declared proxy win over the global one; catalog sync always connects directly. One entry covers Clash/v2ray users — no per-upstream configuration

…