- id: opencode-zen

August 31, 2026 · View on GitHub

DSH OpenCode Zen

Bring OpenCode Zen's free models to DeepSeek Harness.
No signup, no API key, no balance to top up.

What's new in this fork (v0.2.1)

Free quota rate-limit tracker — records 429s, estimates reset time, shows countdown
Persistent quota state — survives DSH restarts via ~/.dsh/cache/opencode-zen-quota.json
8 verified free models (cross-checked against live Zen — no phantom entries)
Persistent file cache — catalog survives DSH restarts
Retry with exponential backoff — 2 retries, 500ms/1s delay
Improved error messages — clearer guidance on quota limits
Updated config schema — cachePath option for custom cache location

All models are verified to exist on both models.dev (cost=0) and Zen's /v1/models endpoint.

Install it and configure nothing. Zen's free models accept anonymous calls, so once the plugin boots, a group of working models simply appears in the model picker.

Model picker
├─ nemotron-3-ultra-free         1M context
├─ muse-spark-1.2-contributor-free 1M context
├─ nemotron-3.5-lightning-free   256K context, 256K output too
├─ ling-3.0-flash-fin-free       256K context
├─ laguna-s-2.1-free             256K context
├─ deepseek-v4-flash-free        200K context, 128K output
├─ big-pickle                    Zen's own anonymous evaluation model
└─ mimo-v2.5-free                200K context

All support tool calls and reasoning content, enough to run a full agent loop — not a chat-only cut-down.

The list is not hardcoded; it is fetched at runtime: models.dev decides which are free and how large, Zen's model endpoint decides which still exist, and the plugin takes the intersection. Free models are offered for a limited time, so any hardcoded list is guaranteed to go stale. The bundled snapshot is only a fallback for when both sources are unreachable.

Install

Not published to npm — install from GitHub:

dsh plugin --profile web add -w github:randomix777/dsh-opencode-zen

Then restart dsh once, and the opencode-zen group appears in the model picker.

Three notes:

-w is not optional. The profile directory ships a pnpm-workspace.yaml, so pnpm treats it as a workspace root; without the flag you get ERR_PNPM_ADDING_TO_ROOT.
No build-script authorisation needed. The repository ships its build output and has no prepare script, so pnpm runs no build for a git source. You do not need allowBuilds, nor a build toolchain on your machine.
--profile is whichever you already use (web or headless). This is an LLM provider; it does not depend on the web GUI.

To confirm it really entered the Loader tree:

dsh --profile web --dump-config | grep -A 1 opencode-zen
# - id: opencode-zen
#   name: dsh-opencode-zen

To hack on it, install locally:

git clone https://github.com/randomix777/dsh-opencode-zen
cd dsh-opencode-zen && pnpm install && pnpm build
dsh plugin --profile web add <absolute path to that directory>

Do I need an API key

No. Anonymous calls draw on Zen's shared free quota. It is rate-limited by source — plenty for trying things out, though sustained volume will hit FreeUsageLimitError.

For a private quota, grab a key at opencode.ai/zen:

export OPENCODE_API_KEY=<your key>

The variable name matches opencode's own, so if you already use opencode, one key serves both. You can also store it in the credentials service from dsh's Models page; the plugin reads that first.

When the quota runs out, the plugin does not just say Rate limit exceeded — it tells you whether you are anonymous or keyed, and what to do next.

Configuration

All optional. An empty config gives the behaviour described above.

plugins:
  dsh-opencode-zen:
    apiKeyEnv: OPENCODE_API_KEY        # credential reference (an env var name)
    baseURL: https://opencode.ai/zen/v1
    catalogUrl: https://models.dev/api.json
    catalogTtlMs: 3600000              # catalog TTL, one hour by default
    catalogTimeoutMs: 8000             # catalog request timeout
    maxTokens: 32000                   # output cap; the model's own lower cap wins
    defaultContextWindow: 128000       # assumed when the catalog has no entry
    cachePath: ~/.dsh/cache/opencode-zen-catalog.json  # persistent cache (default)

Set cachePath: "" to disable file caching entirely.

Known limits

The free quota is shared, and anonymous calls hit the limiter most easily. That is Zen's policy; all the plugin can do is state the reason clearly.
Reasoning is not sent back. OpenAI-compatible chat/completions has no request field to carry the previous turn's thinking, so reasoning blocks are displayed, not replayed.
Text only. All models take text alone; an image in a tool result is replaced with a one-line placeholder rather than dropped silently.
Paid models are excluded. Zen also offers Claude, GPT and others, but this plugin exists so that things run with zero configuration — mixing paid models into the same list makes it unclear which choice costs money. To use them, add an llm-deepseek entry pointing at the same endpoint.

Development

pnpm install
pnpm check      # type check
pnpm test       # unit tests
pnpm build      # bundle to lib/

lib/ is committed on purpose. This package is not published to npm; everyone installs from a git source, and whether pnpm can build a git source depends on the other machine's toolchain and allowBuilds grants. Shipping the output removes that variable — commit the pnpm build output along with your code changes.

File	Responsibility
`src/index.ts`	Plugin entry: config validation, credential resolution, provider registration on `ctx.llm`
`src/adapter.ts`	`LlmAdapter` implementation: requests, error mapping, model metadata
`src/stream.ts`	State machine turning SSE deltas into the harness block sequence
`src/discovery.ts`	Two-source merge, caching (in-memory + file), fallback and retry for the free catalog
`src/quota-tracker.ts`	Rate-limit detection: tracks 429s, estimates reset time, persists state to disk
`src/fs-cache.ts`	File-based cache helpers (no-op on browsers)

OpenCode Zen — the model gateway itself; keys come from here
DeepSeek Harness — the host
dsh-plugin-subs — OAuth sign-in for subscription LLMs
dsh-sprite-gen — AI sprite generation plugin
Original: keman-ai/dsh-opencode-zen

License

_{If this is useful to you, a Star goes a long way}