---

dsh-freetap 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-freetap.

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.

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-freetap/releases/download/v0.5.1/dsh-freetap-0.5.1.tgz

That is the whole install — one command, no extra flags, exit code 0. Then restart DSH and pick a model from the dsh-freetap 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.

The install pulls seven small packages and runs no dependency build scripts, so it succeeds on a clean machine with pnpm's default (strict) build policy. That is a deliberate property of this package — see Why the install needs no flags.

Why the install needs no flags

Earlier builds depended on the full @earendil-works/pi-ai provider matrix at runtime. Two of its transitive dependencies declare install scripts, which pnpm blocks by default, and pnpm turns that into a hard failure:

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

Worse than a plain failure: pnpm had already written the dependency into the profile's package.json, and DSH registers a package as a profile bundle only when the run exits 0. So the plugin ended up installed but never loaded — no model in the picker, nothing in the output explaining it.

The fix is at the source rather than in the instructions: the wire layer is bundled into the shipped lib/, so none of those packages are installed at all. Today's published package depends only on yaml, undici, partial-json and @deepseek-ai/schemastery — none of which run scripts.

Verify it registered: dsh-freetap 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-freetap/releases/download/v0.5.1/dsh-freetap-0.5.1.tgz

It installs in one pass. No approval dialog appears, because the package no longer depends on anything that declares an install script.

If you ever do see an "Install scripts need permission" panel, you are on a build older than 0.5.1 — upgrade, or click Allow these scripts and retry.

Other ways to install

From GitHub directly (no registry involved):

dsh plugin --profile web add github:ddldxiacan/dsh-freetap

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-freetap#v0.5.1

From npm (once the package is published):

dsh plugin --profile web add dsh-freetap

Verify: restart dsh web, open the model picker, and pick a model from the dsh-freetap 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.5.1 with the release you are moving to
dsh plugin --profile web add https://github.com/ddldxiacan/dsh-freetap/releases/download/v0.5.1/dsh-freetap-0.5.1.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-freetap
dsh plugin --profile web add https://github.com/ddldxiacan/dsh-freetap/releases/latest/download/dsh-freetap.tgz

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

dsh plugin --profile web add github:ddldxiacan/dsh-freetap

npm install:

dsh plugin --profile web add dsh-freetap@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-freetap/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-freetap for a git install, for the release tarball and for npm alike — there is one name now.

- id: dsh-freetap
  name: dsh-freetap
  config:
    mode: adapter        # adapter (default) | sidecar
    providerId: dsh-freetap
    refreshSeconds: 300  # catalog refresh cadence

Option	Default	Description
mode	adapter	adapter: native LlmAdapter streaming straight from Zen. sidecar: legacy local-agent mode, not bundled — build the agent from legacy/agent and pass agentPath.
providerId	dsh-freetap	Provider name shown in DSH.
refreshSeconds	300	Live catalog refresh interval. Pricing metadata refreshes every 24 h.
agentPath	auto-resolved	Sidecar only: path to the agent binary.
agentArgs	—	Sidecar only: extra CLI args for the agent.
restartDelayMs / restartMaxDelayMs / maxConsecutiveCrashes	1000 / 60000 / 5	Sidecar only: restart backoff and circuit breaker.
firstEventMs / bodyIdleMs / responsesBodyIdleMs	30000 / 120000 / 300000	Adapter only, plugin 0.3.7+: stream-liveness watchdogs, in ms (integers from 1 to 600000). Time to the first stream event, mid-response body silence, and the body-idle floor for Responses models (muse-spark-*). Increase firstEventMs for slow cold starts. Unset keeps the defaults; restart DSH after editing.

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-freetap/adapter-status.json

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

Symptom	Likely cause & fix
403 FreeTierError / "OpenCode's free tier can only be used from within OpenCode"	The upstream restricts free-tier clients. The plugin preserves the explanation instead of reporting an invalid API key. Use the supported OpenCode client or an official API service.
Boot screen shows Failed to load plugins … list slot "plugins.item" requires options.id, or the IP 池 entry has no configuration page	Your DSH predates the 0.1.7 Plugins page contract. Upgrade DSH to 0.1.7 (latest recommended). On 0.1.6 and older the page never mounts (it is gated on configForms.whileServed) — model routing is unaffected.
DSH 0.1.7/0.2 cannot start after plugin installation (pending … settingsScope)	Upgrade the plugin to 0.3.5. On DSH 0.2, configure IP pooling through the installed dsh-freetap row on the Plugins page.
Only 3 models	Startup fetch raced your network; retries land within ~1 min. Check adapter-status.json for lastError.
lastError: "fetch failed" persisting	Outbound HTTPS to opencode.ai blocked; check proxy/VPN rules.
Rate-limit errors in chat (429 … Endpoint is unavailable)	The anonymous lane is quota-per-IP and free models are contended. Since the fix for #51 the plugin's provider retry policy rides out 429 bursts silently (8 retries, ~1s→20s backoff, ≈90s worst case per step) instead of surfacing them; when contention still wins, lower the reasoning effort, pick a less contended -free model, or enable IP pooling (multi-exit rotation) on the plugin settings page.
Output limit reached after reasoning with no answer	Plugin 0.3.6 retries once with thinking Off when the model supports it. Any answer text or tool-call event prevents replay. The retry preserves the original output cap and may still fail; both requests' usage is counted. Models without Off, including Muse, require a manual change of settings or model.
Muse reports REGION_BLOCKED / "This model is not available in your country"	Zen has rejected the current network region for this model. Plugin 0.3.5 preserves that explanation; older versions mislabeled the same 403 as an invalid API key. The anonymous lane does not need a personal key. Use a model available in your region.
Connection error to 127.0.0.1:*	A stale sidecar route shadows the adapter; plugin ≥ 0.2.1 removes it at startup.
Install fails with ERR_PNPM_IGNORED_BUILDS	You are on a build older than 0.5.1, whose pi-ai dependency dragged in @google/genai and protobufjs (both ship install scripts). Upgrade to 0.5.1+, which bundles that layer and depends only on script-free packages. If you must stay on the old build, pass --config.strict-dep-builds=false.

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-freetap.git
cd dsh-freetap/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