dsh-opencode-free

---

dsh-opencode-free registers a native DSH LlmAdapter that streams directly from OpenCode Zen's anonymous free lane — the same models OpenCode's own CLI uses without an account, served to your DSH model picker as a regular provider called dsh-opencode-free.

Requests leave your machine looking exactly like traffic from the OpenCode CLI (same user agent, same correlation headers), and the model catalog stays fresh through a three-tier fallback chain. There is nothing to log into and nothing to host.

Upgrading from opencode2dsh? This project was renamed. The plugin now installs as @dsh-opencode-free/dsh-plugin with the provider, settings entry and data directory all under the new name. Your saved IP-pool settings and the old ~/.opencode2dsh cache are copied once on first start — see Renamed from opencode2dsh.

Highlights

• Zero credential, zero setup — the anonymous lane needs no key; install, restart, chat
• Native adapter, no sidecar — one npm package, no child process, no binary, no local port (the legacy Go sidecar is not part of the published package; see legacy/)
• CLI-identical disguise — requests carry the OpenCode CLI user agent and its session/request/project header set, derived per conversation
• Selectable thinking levels — reasoning-capable free models expose an effort picker in DSH's model selector (declared ladders where the model metadata provides them, Off/Minimal/Low/Medium/High otherwise); Responses-only muse-spark-* models expose only upstream-supported effort levels, and no selection keeps the provider default
• Image input where it is declared — image attachments are accepted for every model whose models.dev entry lists image in modalities.input, and refused for the ones that declare text only; models.dev being silent falls back to the live-verified vision family
• Live catalog with a fallback chain — live upstream list ∩ free-by-metadata, falling back to offline cache and a verified static list
• Self-healing — fast startup retries, periodic refresh, and a written health snapshot for diagnostics
• Proper error surfaces — upstream failures (rate limit, auth, timeout, transport) arrive in DSH as classified finish reasons, and retries stay owned by DSH

Install

Installs from a prebuilt release, so no build step and no toolchain is needed.

dsh plugin --profile web add https://github.com/ddldxiacan/dsh-opencode-free/releases/download/v0.4.3/dsh-opencode-free-dsh-plugin-0.4.3.tgz --config.strict-dep-builds=false

That is the whole install — one command, exit code 0. Then restart DSH and pick a model from the dsh-opencode-free group in the model selector.

Requirements: DSH (DeepSeek Harness) 0.1.7 or newer with a web profile, Node.js ≥ 20 (already present if DSH runs), and outbound HTTPS to opencode.ai and models.dev.

What that flag is for

@earendil-works/pi-ai transitively pulls in @google/genai and protobufjs, which ship build scripts. pnpm blocks dependency build scripts by default, and in strict mode that disagreement is a hard failure:

Error: ERR_PNPM_IGNORED_BUILDS
  × adding a new package
  ╰─▶ Ignored build scripts: @google/genai@1.52.0, protobufjs@7.6.6

Those scripts are not needed at runtime (upstream ships both as false), so --config.strict-dep-builds=false tells that single pnpm run to report the skip as a warning and carry on. Verified: exit 0, no script executed, plugin registered as a bundle.

Equivalents, if you prefer to be explicit rather than relax the check for one run — both also work and record allowBuilds: {'@google/genai': false, protobufjs: false} in the profile:

# deny the two scripts explicitly
dsh plugin --profile web add <same-url> --allow-build='!@google/genai' --allow-build='!protobufjs'

⚠ If you installed the bare add URL and hit that error

Do not simply retry — first remove. This is worse than it looks: pnpm has already written the dependency into the profile's package.json when it errors, and DSH registers a package as a profile bundle only when the run exits 0 and the package counts as new. A plain retry therefore prints Already up to date and exits 0 while dsh.profile.bundles never gains the plugin — it sits in node_modules, never loads, and no model appears. Nothing in the output says so.

Recover with an explicit remove + add:

dsh plugin --profile web remove @dsh-opencode-free/dsh-plugin
dsh plugin --profile web add https://github.com/ddldxiacan/dsh-opencode-free/releases/download/v0.4.3/dsh-opencode-free-dsh-plugin-0.4.3.tgz --config.strict-dep-builds=false

Verify it really registered: @dsh-opencode-free/dsh-plugin must appear under dsh.profile.bundles in the profile's package.json, not only under dependencies.

Installing in the Web UI (recommended if you never use a terminal)

Settings → Plugins → Install, then paste the tarball URL:

https://github.com/ddldxiacan/dsh-opencode-free/releases/download/v0.4.3/dsh-opencode-free-dsh-plugin-0.4.3.tgz

The first attempt always fails once. That is by design, not a bug:

1. The dialog reports the failure and shows an "Install scripts need permission" section listing @google/genai and protobufjs;
2. Click "Allow these scripts and retry";
3. The second run succeeds and asks you to restart.

This path does not hit the silent-retry trap described below: after every failed run the page restores package.json and pnpm-lock.yaml, so the retry still counts as a new dependency and registers as a profile bundle. Verified end to end on a real profile: fail → allow → retry succeeded, and dsh.profile.bundles gained @dsh-opencode-free/dsh-plugin at 0.4.3.

If you close that dialog and use the Install button again later, it fails again and re-opens the same approval section — it will not pretend to have succeeded. Click "Allow these scripts and retry" and it goes through.

Other ways to install

From GitHub directly (no registry involved):

dsh plugin --profile web add github:ddldxiacan/dsh-opencode-free --config.strict-dep-builds=false

This works because the repository root is the installable plugin: it carries the dsh manifest, and the built output is committed under packages/plugin/lib/. A git install cannot run a build — pnpm blocks prepare scripts for git dependencies — so shipping the build is what makes this path work. Pinning a tag is recommended for stability:

dsh plugin --profile web add github:ddldxiacan/dsh-opencode-free#v0.4.3 --config.strict-dep-builds=false

From npm (once the package is published):

dsh plugin --profile web add @dsh-opencode-free/dsh-plugin

Verify: restart dsh web, open the model picker, and pick a model from the dsh-opencode-free group.

Updating

Pick the source you installed from; each updates in place.

Release tarball. Use the tag-scoped asset, not the version-free one:

# replace 0.4.2 with the release you are moving to
dsh plugin --profile web add https://github.com/ddldxiacan/dsh-opencode-free/releases/download/v0.4.2/dsh-opencode-free-dsh-plugin-0.4.2.tgz

The version-free releases/latest/download/... URL does not update an existing install: pnpm resolved it once and pinned the URL plus its integrity hash in pnpm-lock.yaml, so re-adding it is a no-op ("Lockfile is up to date, resolution step is skipped") — even with --force, pnpm update, pnpm install --force, or a deleted node_modules. Only a URL that differs per release re-resolves. If you are stuck on an older build that predates the versioned asset, do the one-time move with an explicit remove + add (or the versioned URL, which works even then):

dsh plugin --profile web remove @dsh-opencode-free/dsh-plugin
dsh plugin --profile web add https://github.com/ddldxiacan/dsh-opencode-free/releases/latest/download/dsh-opencode-free-dsh-plugin.tgz

git install: follow master (a git spec re-resolves each time):

dsh plugin --profile web add github:ddldxiacan/dsh-opencode-free --config.strict-dep-builds=false

npm install:

dsh plugin --profile web add @dsh-opencode-free/dsh-plugin@latest

Then restart DSH. To confirm the new version landed, compare the profile's node_modules/<pkg>/package.json with the release you expected, and check the health snapshot at ~/.dsh-opencode-free/adapter-status.json.

If an update ever leaves the plugin installed but not loaded, it is the ERR_PNPM_IGNORED_BUILDS trap described under Install: remove and re-add, so the package counts as new and DSH registers it as a bundle.

Configuration

Defaults work out of the box. Override via the profile's cordis.patch.yml. The name must be the package you installed as: dsh-opencode-free for a git install, @dsh-opencode-free/dsh-plugin for the tarball or npm.

- id: dsh-opencode-free
  name: dsh-opencode-free   # or '@dsh-opencode-free/dsh-plugin'
  config:
    mode: adapter        # adapter (default) | sidecar
    providerId: dsh-opencode-free
    refreshSeconds: 300  # catalog refresh cadence

How it works

DSH session
   │  harness chunks (block-start / text-delta / usage / finish …)
   ▼
ZenAdapter (registered LlmAdapter)
   │  pi-ai openai-completions stream (chat models)
   │  pi-ai openai-responses stream (`muse-spark-*`, Responses-only on Zen)
   ▼
https://opencode.ai/zen/v1        ← Authorization: Bearer public
   with CLI-identical headers:
     user-agent: opencode/…
     x-opencode-client, x-opencode-session, x-session-affinity,
     X-Session-Id, x-opencode-request, x-opencode-project

• Session correlation — session/project ids are SHA-256 derived from the conversation's first user turn (stable per conversation, non-reversible), and each request gets a fresh random id, mirroring the CLI.
• Catalog fallback chain — S1: live GET /v1/models; S2: models.dev pricing metadata decides "free"; S3: a compile-time verified static list. A disk cache (~7-day TTL) covers upstream outages.
• Resilience — the adapter registers immediately at startup; if the first catalog fetch races your network (VPN/TUN reconnects, DNS), the plugin retries on a short cadence (~1 min) before settling into the periodic refresh.
• Sidecar mode (mode: sidecar, legacy) — spawns a local Go agent (a single-tenant port of opencode2api) on 127.0.0.1:<random>, token-authenticated, and registers a standard llm-pi-ai route. Not part of the published package; build it from legacy/agent (go build ./cmd/agent) and point agentPath at the binary.

Health & troubleshooting

The plugin writes a health snapshot after every refresh round:

~/.dsh-opencode-free/adapter-status.json

{
  "status": "ready",
  "total": 64,
  "exposed": 9,
  "lastError": "",
  "writtenAt": "2026-08-29T07:01:54.915Z"
}

Renamed from opencode2dsh

This project used to be called opencode2dsh. The rename is complete: the npm package, the DSH provider id, the settings entry and the data directory all use the new name dsh-opencode-free.

Upgrading is automatic. On the first start after the update the plugin copies your state from the old name, once, without deleting anything:

Two things the migration deliberately does not do:

• It never deletes or moves the old state. A downgrade keeps working, and a failed migration can simply be retried on the next start.
• It never overwrites what you set under the new name. Only keys missing from the new section are copied; anything already configured there wins.

After upgrading you will see the provider as dsh-opencode-free in the model picker. Saved IP-pool settings appear on the second start: the Loader resolves the entry's volatile ipPool value while composing a boot, so a copy made during that boot is read on the next one. The cache and health files take effect immediately. A deployment that cut over before this rename existed may still list a opencode2dsh entry under DSH's Settings → Plugins; remove that stale entry (an orphan opencode2dsh provider route left by a sidecar install is swept automatically at startup).

If you prefer to start clean rather than migrate, delete ~/.opencode2dsh/ and the opencode2dsh: section of ~/.dsh/settings.yaml before upgrading; the plugin then starts with defaults.

Security

• No secrets involved: the anonymous lane's key is the literal string public; nothing is stored, nothing telemetry.
• Install paths restricted to lib/ only; no build scripts run from dependencies.
• All requests go directly from your machine to opencode.ai / models.dev.

Development

git clone https://github.com/ddldxiacan/dsh-opencode-free.git
cd dsh-opencode-free/packages/plugin
pnpm install
pnpm typecheck && pnpm test
pnpm build                    # bundle to lib/

The legacy Go sidecar lives in legacy/agent (go test ./...). Architecture notes and the porting record live in docs/.

Releasing: pnpm pack in packages/plugin (prepack builds and syncs docs).

Acknowledgments

• opencode2dsh by @FishBottle7 — the upstream project this one was forked from and is renamed after. Its architecture, catalog fallback chain and request-disguise work are the foundation of this fork; issue numbers cited above refer to that repository.
• opencode2api by @jasonxu114514 — the legacy Go sidecar in legacy/agent is a port of its anonymous-lane implementation, and the catalog fallback chain and request-disguise details are derived from it. This project stands on its shoulders.
• OpenCode — for running the free anonymous Zen lane.
• @earendil-works/pi-ai — the wire layer used by adapter mode.
• DeepSeek Harness and the dsh-market community.

Friends

License

MIT © 2026 ddldxiacan, based on opencode2dsh © FishBottle7