dsh-freellmapi

dsh-freellmapi

Free-tier multi-provider routing for DeepSeek Harness. Eighteen provider entries behind one DSH provider route — five of them enabled by default, and all five of those with a free tier — plus a per-request complexity classifier, capability/speed ranking, and automatic 429/5xx failover.

install the plugin  →  start DSH  →  pick provider "freellmapi" + model "auto"  →  it answers

No external process. No gateway to run. No API key required to get a first answer — the built-in pool contains keyless providers that the maintainer verified with real, credential-free requests.

Unofficial plugin — please read

This is a community project. It is not affiliated with, endorsed by, sponsored by or supported by any of the upstream providers it talks to, nor by DeepSeek. It is not an official DSH plugin. Provider names and "DeepSeek Harness" / @deepseek-ai/* belong to their respective owners. Licensed under the MIT License. You are responsible for complying with each provider's terms of service, and for what you send to a free tier that may log and train on it.

---

Table of contents

• Quick start
• What you get
• Zero config: what works with no key at all
• Adding keys
• How to read the model list
• Pinned models are strict
• How it picks a model
• Long-running agent sessions: read this before you pick auto
• Failover and health
• Two modes: direct and gateway
• Configuration
• How to see what it did
• Just one key? No keys?
• Architecture
• Troubleshooting
• Limitations and unverified claims
• Compatibility
• Development
• Upstream and credits
• License

Quick start

1. Install — open the DSH web GUI, go to the Plugins manager in the sidebar, install the bundle and paste one of these specs:

   github:lion231226/dsh-freellmapi          # from GitHub (no npm publish needed)
   github:lion231226/dsh-freellmapi#v0.7.18   # pinned to a tag
   dsh-freellmapi                            # from npm, once published
   

   CLI equivalent, and the manual path, are in Install details.

2. (Optional) paste a few keys — see Adding keys. Skipping this step is a supported configuration: the two keyless providers still answer.

3. Pick the model — in the DSH model picker choose provider FreeLLMAPI (Auto) and model auto.

4. Watch it work — with logRouting on (the default) every request logs one line:

   dsh-freellmapi: tier=complex -> openrouter/nvidia/nemotron-3-ultra-550b-a55b:free (capability=5, speed=3, 2 candidates tried)
   

That is the whole setup. Everything below is detail.

Install details

The package ships its own cordis.patch.yml (- insert: [{ id: freellmapi, name: 'dsh-freellmapi' }]), so a correctly installed bundle needs no hand-written patch row. Never add a second row with the same id in the profile's own cordis.patch.yml: two entries with one id abort bundle composition with duplicate loader entry id "freellmapi".

What you get

Zero config: what works with no key at all

The pool marks three providers keyless (no Authorization header at all). The maintainer verified them with real requests on 2026-10-13 (_lead/live-probe-2026-10-13.md), sending no credential:

kilo and llm7 are enabled by default, so those two carry the "install and it works" promise. ovh is keyless too but disabled by default (2 requests/minute — far too tight to be in the default candidate set); enable it explicitly if you want it.

Three things you should know before you rely on a keyless pool:

• Keyless is not unlimited. Kilo is documented at ~200 requests/hour per IP, LLM7 at ~100/hour, OVH at 2 RPM. Quota numbers throughout this document come from the upstream registry baseline (2026-04) and may be stale; the plugin reacts to them rather than trusting them — a 429 parks that candidate and moves on.

• Free traffic may be recorded and used for training. Kilo states this in its own provider registry (free prompts and completions are logged for training). If that is not acceptable to you, disable it:

  providers:
    kilo:
      enabled: false
  

  With kilo off, zero-config still works through llm7 alone.

• Free model catalogs drift. During the 2026-10-13 probe, llm7 answered 400 model_unavailable for gpt-oss-20b and GLM-4.6V-Flash — the same kind of id that worked the day before. The router treats model_unavailable as a per-model condition: it parks that (provider, model) pair and tries the next candidate instead of failing your request. Seeing one of these is normal operation, not a bug.

Adding keys

Keys are the single biggest quality upgrade: the default candidate pool is groq, cerebras, openrouter, kilo, llm7, and adding the first three gives you the strong-and-fast models.

Set a key by exporting the environment variable named in apiKeyEnv — or store it through DSH's credentials service, which is the first thing resolution consults. Resolution order is: credentials service → config.providers[id].apiKey → environment variable named by apiKeyEnv → the convention <PROVIDER_ID>_API_KEY. Empty values count as "not configured".

Where to edit in the GUI. Settings → Models lists this plugin's provider route (FreeLLMAPI) as an ordinary card, and the key rows render inside that card — one per upstream that is enabled but has no usable credential, each with a link to its key page, the environment-variable name it will be stored under, a password field and Save. Saving writes through DSH's credentials service, which is read without caching, so the key takes effect on the next request with no restart.

Two notes on the host's own editor, so its behaviour is not mistaken for a bug:

• The 编辑 button next to that card opens DSH's provider editor, which can only render fields for its own two provider families (llm-deepseek, llm-pi-ai); for any other namespace it shows "other fields live in cordis.patch.yml" and disables Save. That is a current host limitation and the key rows above are the answer to it.
• The card shows a missing-credential dot while the root apiKeyEnv (FREELLMAPI_API_KEY) is unset. Direct mode needs no such key — the dot refers to the optional gateway credential and can be ignored.

The full field set (including the per-upstream providers map and the routing knobs) is on the plugin's own settings page: Settings → Plugins → dsh-freellmapi, generated from the schema; it is also editable in cordis.patch.yml.

The card offers a key field for the pool's default-enabled providers (groq, cerebras, openrouter, llm7, kilo). The browser table is generated at build time from those defaults, so a provider you enable yourself through providers.<id>.enabled will not grow a key row — set its apiKeyEnv and store the credential directly in that case. That applies to all six providers added in 0.7.0, which ship disabled on purpose: enabling one of them does not make a key row appear in the card (this is the known gap recorded in the 0.6.1 changelog, not a bug).

Which providers are actually reachable — and how to ask

Free-tier access is network-sensitive, so this section tells you how to measure, not what to believe. It previously carried a table claiming groq and cerebras were region-blocked "and a key changes nothing". That table was wrong, and the reason is worth keeping: the probe sent no Authorization header. Measured 2026-10-15:

So a 403 is never self-explanatory. It means one of three different things depending on what you sent: anonymous request rejected, credential rejected, or region rejected. Reporting one without the other is how the wrong table got written.

Probe correctly, per provider:

• keyless providers (llm7, kilo, ovh) — send no Authorization header; 200 is healthy.
• key-required providers — send a syntactically valid but bogus Authorization: Bearer … header; 401 is healthy (the endpoint exists and refused politely), 200 is fine too.
• Treat 403 as ambiguous: it needs a second probe with the other method before it means anything.
• 404/400/422 usually mean the path differs, not that the host is down.

The request body is part of the method too. Probing a chat endpoint with a model id that does not exist yields the opposite conclusion: modelscope answers 400 Invalid model id and sambanova answers 404 model_not_found, and neither can be told apart from "this provider's chat needs no credential" — the request never reached the credential check. Replaying the same request with a real id from the catalog returned 401 from both. Same URL, same headers, different body, opposite verdict.

The gate automates the header split: node tools/gate.mjs --online → G7 probes every pool provider with the method that suits it and prints the method beside each result, so the verdict can be audited rather than trusted. G7 asks GET {baseURL}/models only, so read its green as "the host answers", not as "this provider will serve you a completion once you add a key".

G10 answers the question G7 cannot. A host that answers says nothing about whether the specific model ids we ship are still served — and that gap let the same defect ship three times: four OpenRouter ids and two Groq ids that the provider had retired, each found by a person rather than by the gate. G10 compares every declared id against what the catalogue actually lists. For a default-enabled provider a dead id blocks; for a default-disabled one it is reported as latent and blocks the moment that provider is enabled. Catalogues that need a credential are recorded as not checked — a 401 is not evidence that an id is missing.

Measured this way on 2026-10-15:

• All 12 pre-0.7 pool providers answer (G7, 2026-10-15) — including the two the old table called blocked.
• The six 0.7.0 additions, probed anonymously and with a bogus header: modelscope, xfyun, siliconflow, sambanova and huggingface are reachable. routeway's anonymous chat path is the one open AMBIGUOUS: without a credential its POST /chat/completions gets a Cloudflare interstitial (403, HTML, "Attention Required"), while the same request with a bogus Authorization header reaches the origin and gets a plain-JSON 401 Invalid API key. A single response cannot separate anonymous rejected from region rejected; a real key, or a second egress IP, would settle it. Nothing in this README depends on that path being open.

Which egress each probe used is part of the result. The probe host runs a VPN in split-tunnel mode: traffic to mainland-Chinese destinations goes out direct, everything else goes through the proxy, whose exit is US-Los Angeles. The LA exit is the overseas path's location — it is not the host's location, and this README does not claim otherwise. So the results above split by path, and the split is stated rather than left to inference:

• Direct (within mainland China): modelscope, xfyun and siliconflow — the three mainland-Chinese hosts in the 0.7.0 additions. Each answered its probe over the direct path (xfyun and siliconflow returned 401 to the bogus-credential probe; modelscope was also reached, see the doc-site note below).
• Through the proxy (overseas exit, US-LA): the other three additions and all 12 pre-0.7 providers. routeway's Cloudflare behaviour is measured on this path, which is why its 403 still cannot be separated from a region rejection — see the AMBIGUOUS note above.
• The application-layer verdicts (401, RFC 6750 credential challenges, origin error JSON) do not depend on the egress at all; "reachable from your network" does, which is why the path is recorded per provider.

A tool limit is not a property of the site. An earlier draft of this section reasoned from a failed web_fetch of a Chinese vendor documentation site — "hostname resolves to a non-public IP address" — to "Chinese vendor and documentation sites are unreachable from this machine." That inference was wrong. The message is this project's own DNS guard: a split-tunnel VPN answers DNS with fake-IP addresses from the reserved benchmarking range 198.18.0.0/15, and web_fetch refuses to fetch any hostname that resolves there. It rejected www.xfyun.cn and github.com in the same session with the same sentence, which is what exposes it as a guard rather than a measurement. Re-measured (2026-10-15) over the direct path with an ordinary HTTP client:

So the Chinese documentation sites were always reachable from this machine; only web_fetch could not read them. Any verdict about "sites in country X cannot be reached" needs a reachability measurement (an HTTP client speaking to the host), never a fetch-tool error, because the latter reports the tool's policy and the former reports the network.

And when a provider genuinely is unreachable from your network, turning it off is the whole change, in $DSH_HOME/profiles/<profile>/cordis.patch.yml (or the plugin's own providers field):

- id: freellmapi
  config:
    providers:
      someprovider: { enabled: false }

Key request pages (the first seven were verified reachable on 2026-10-14): groq https://console.groq.com/keys, cerebras https://cloud.cerebras.ai/, openrouter https://openrouter.ai/keys, mistral https://console.mistral.ai/api-keys, zhipu https://open.bigmodel.cn/usercenter/apikeys, volcengine https://console.volcengine.com/ark, longcat https://longcat.chat/platform/api_keys. The six 0.7.0 additions' key pages below are the pool's own keyURL values and were not independently verified — only modelscope's carries an upstream citation. (An earlier draft justified that gap with the claim that Chinese vendor/documentation sites "resolve to non-public addresses" from this machine. That claim is withdrawn: it was a web_fetch DNS-guard artefact, and the vendor doc page was in fact fetched over the direct path — see the reachability table above. The key pages themselves remain unverified; only the reason previously given for that was wrong.)