dsh-opencode-free-model

English | 中文

A DeepSeek Harness plugin that puts the OpenCode Zen free model lane (opencode.ai/zen/v1/*) into your model picker with no API key.

It is a Host-only cordis plugin. It registers two provider routes on the llm service, decodes all three wire protocols the lane speaks (Chat Completions / Responses / Messages) into the harness StreamChunk protocol, and uses a background probe to decide which models get advertised.

dsh plugin --profile desktop add github:artorias-zj/dsh-opencode-free-model

Restart DSH afterwards and an OpenCode Free group appears in the model picker.

What it does

🔑 No key	The lane is keyed by a pooled credential, Authorization: Bearer public. The plugin holds no secret of yours, and stores none.
🔀 Three wire protocols	muse-spark-* goes to /zen/v1/responses, union-alpha to /zen/v1/messages, everything else to /zen/v1/chat/completions; all three SSE dialects decode into one host block protocol. (Routing is by model id, so a model the upstream withdraws simply stops being advertised — union-alpha is in that state today; the mapping itself still stands.)
🧭 Protocol decided by shape	The gateway lies in Content-Type (a JSON header over an SSE body is a real production incident). The verdict comes from the body's own shape, and the bytes spent sniffing it are replayed — not one token is buffered.
🖐 The fingerprint quartet	The free tier requires the request body to declare the tool names bash/glob/grep/read, or it answers 403 FreeTierError. A missing slot is filled by promoting a real tool that can answer for it (pwsh→bash on Windows) before it is faked, and the response side restores the caller's own spelling.
🧷 Stable sessions	One conversation maps to one stable ses_…. Minting a fresh session per request gets you rate-limited by the gateway's per-session accounting (429).
🔍 Availability probing	A background probe with concurrency 2 classifies every model as available / region-blocked / unavailable / throttled / unknown. An egress change re-probes immediately; an all-429 round backs off exponentially; an all-refused round does not empty the picker; 5xx never demotes a model.
🌍 Region routing	Egress-sensitive models (muse-spark-*) that the gateway refuses here move to the opencode-free-model-region route; exposeRegionModels: false hides it.
♻️ Reasoning-cutoff continuation	A turn cut off with reasoning and nothing visible — no text, no tool call, no finish token — is continued once from its checkpoint, with tools forced off.
🎚 Effort levels are real budgets	The lane ignores reasoning_effort and every thinking.* spelling; the only control it honours is max_tokens. So light/balanced/deep map to output budgets, and a model that cannot stop thinking (canDisableThinking: false) has every rung doubled, since thinking and the answer share one ceiling.

Routes

Route id	Picker group	Contents
opencode-free-model	OpenCode Free	Free models usable from this egress
opencode-free-model-region	OpenCode Free · region-limited	Models refused by region, advertised per probe result

The client hides a group with no models, so a VPN user sees one group and a user without sees the second one labelled with the reason.

Models inside a group are sorted alphabetically by display name (case-folded, digits in natural order: V2.6 before V2.10), with the id breaking ties, so the order is total and does not jump between refreshes. The sort lives in listModels() — the kernel maps its return order straight into the browser catalog and the settings client does not reorder, so that is the only place that decides what is on screen. It sorts on name rather than id, because name is the string in front of the user (ordering by id would file DeepSeek V4 Flash under d).

Configuration

Configuration comes from the bundle patch's config key. It applies on every mount, so a key written there always wins over a default; a key it omits falls back to the default instead of sticking from a previous mount. Only runtime bookkeeping (runtime.json) is written to disk.

- insert:
    - id: opencode-free-model
      name: 'dsh-opencode-free-model'
      config:
        enabled: true              # master switch; false advertises nothing and fails calls with CONFIG_DISABLED
        exposeRegionModels: true   # advertise region-limited models on the second route
        probeIntervalMinutes: 15   # background re-probe period, in minutes (>= 1)
        defaultMaxTokens: 32768    # per-turn output ceiling (further lowered by the model's own capacity)
        streamRecovery: true       # allow one reasoning-checkpoint continuation
        # wireOverrides:           # pin a model to a wire if the upstream moves it
        #   some-model-free: chat
        # baseUrl: https://opencode.ai

A key with the wrong shape is ignored with a warning rather than failing the plugin — a plugin that refuses to load is far worse than one running with a default.

The environment variable OPENCODE_FREE_MODEL_BASE overrides the upstream root (config.baseUrl takes precedence).

Install

# from GitHub
dsh plugin --profile desktop add github:artorias-zj/dsh-opencode-free-model

# or from a local clone / development directory
dsh plugin --profile desktop add D:\Project\DSH\dsh-opencode-free-model

# verify: dump-config should contain exactly one opencode-free-model row
dsh --profile desktop --dump-config

The CLI writes the dependency and the dsh.profile.bundles entry into the profile's package.json; cordis.patch.yml injects the loader row (name must be the bare package name, or a client half cannot resolve the package root — this plugin is Host-only and declares no dsh.client, but the rule still governs the loader row).

Restart DSH once after installing: host plugin code is cached by URL, so toggling the loader entry re-runs apply() from the cached module rather than reloading modules you changed on disk.

Compatibility & permissions

Profiles	Any profile that mounts @deepseek-ai/dsh-llm — verified on desktop and web. Host half only: no dsh.client declaration, no browser code.
Platform	Anywhere Node runs. Pure ESM, no native modules, no build step, no runtime dependencies.
Runtime	Node `^22.15.0
DSH version	Built and tested against DeepSeek Harness 0.2.0-rc.2. engines.dsh is deliberately not declared: only that one line has actually been exercised, and a SemVer range would claim more than has been verified.
Credentials	None. The lane is a public key-free allowance, so the plugin holds no secret and reads none — it never touches the credential service.
Registers	Two llm provider routes. It adds no tools, no commands, no slash commands, no keyboard shortcuts and no client UI.
Writes	Only under $DSH_HOME/opencode-free-model/ — runtime.json, catalog.json, availability.json, each written atomically. Nothing outside that directory.
Reads	Your own attached images, and only to inline one into a request the model is already answering (through the optional attachments service; if it is absent, image blocks fall back to the text projection the runtime already performs).
Outbound hosts	opencode.ai — inference and model listing, the only destination your prompts reach — plus api.ipify.org / ipinfo.io / ipapi.co, which are read once to learn this machine's public IP and country so the plugin knows whether a re-probe is needed. Details in Upstream.
Telemetry	None. Nothing is reported anywhere except the request itself.
Category	Models & Reasoning.

What it looks like

The picker groups, exactly as the plugin advertises them (alphabetical, as described under Routes):

OpenCode Free                    9 models
  Fledge Alpha Free
  Jev 1.13
  Ling 3.1 Flash Free
  Longcat 2.5 Preview Free
  MiMo V2.5
  MiMo V2.6 Flash
  Nemotron 3 Ultra
  Nemotron 3.5 Lightning
  Space Bunny

OpenCode Free · region-limited   2 models
  Muse Spark 1.2
  Muse Spark 1.3

And one real streamed turn, captured against the live lane — note the disjoint token accounting:

finish {"kind":"stop"}
usage  {"inputTokens":34,"outputTokens":11,"totalTokens":237,"cacheReadTokens":192,"reasoningTokens":8}
tools  0
answer "OK"

inputTokens is uncached input only — 34 = 226 prompt − 192 cached — which is what the harness expects and what the provider's raw prompt_tokens does not give you.

Layout

dsh-opencode-free-model/
├── cordis.patch.yml   the loader injection row
├── package.json       dsh.bundle.patch declaration (with the files allow-list)
├── icon.svg
├── LICENSE
├── README.md          this file
├── README.zh.md       Chinese
└── lib/               the plugin, 13 modules
    index.js     Host half: apply, registration, catalog refresh, probe loop, membership, config merge
    adapter.js   OcFreeModelAdapter: providerInfo/listModels/resolveModel/prepareCall/stream
    upstream.js  upstream vocabulary: base URL, three endpoints, fingerprint quartet, session/request ids, headers
    http.js      outbound HTTP: deadlines, byte sniffing, SSE framing, failure classification
    stream.js    three-wire SSE -> host StreamChunk (block allocation, usage accounting, terminal frames, error frames)
    messages.js  tool-pairing repair + three-wire message projection
    effort.js    effort levels -> output budgets
    recovery.js  checkpoint-continuation policy
    catalog.js   capability baseline + free-lane filter + listing parser + membership split
    probe.js     availability probing (concurrency 2, failure classification, egress detection)
    store.js     JsonStore (atomic writes, coalesced writes, corrupt files preserved)
    channel.js   single-producer / single-consumer async channel
    kernel.js    the only seam allowed to import @deepseek-ai/* (attribution UA)

kernel.js is the only file that names @deepseek-ai/*; every other module depends on the structural ctx contract alone, so the plugin pins no kernel version and the rule is checkable with one grep.

Upstream

One source, and it is not a relay: https://opencode.ai/zen/v1/*.

Purpose	Target	Credential
Inference	POST …/zen/v1/chat/completions, …/responses, …/messages (per model)	Authorization: Bearer public — a public, key-free allowance; the plugin holds no user secret
Model listing	GET …/zen/v1/models	same
Egress IP	api.ipify.org / ipinfo.io / ipapi.co (reads back this machine's public IP and country code, only to decide whether a re-probe is needed)	none

Known limitations

• GenerateOptions sampling is temperature / maxTokens / stop only, and the only one the lane honours is the output ceiling — so reasoningEffort means "budget rung" here, not "thinking intensity".
• An effort level is a budget: a lower rung shortens the thinking and the answer, because the lane gives you one shared ceiling and nothing else.
• Region verdicts require probing: the gateway does not disclose which models your egress may use, so the plugin has to ask.
• The probe period is read at mount time: changing probeIntervalMinutes needs a plugin reload to take effect.

License

MIT — see LICENSE.

The wire-protocol facts (the pooled key-free credential, the client fingerprint headers, the per-model endpoint split, the free-tier tool-fingerprint gate, the per-session quota accounting, and the regional gate) come from the MIT-licensed reference implementation dsh-our-free-model (Copyright © 2026 zouyuxuan122) and the zen-gate project. Both copyright notices are carried in LICENSE, which is kept as unmodified MIT text so the license is machine-detectable.