dsh-plugin-model-proxy

Community DSH plugin: route specific provider/model pairs through specific proxies (http://, https://, socks5://, socks5h://) — with a Settings UI.

Why

Some model endpoints are only reachable through a proxy while their siblings connect fine — for instance opencode/muse-spark-1.2-contributor may answer 403 RegionError to direct connections that other models from the same provider never see. The coarse fixes don't help: process-wide proxy environment variables drag every request through the tunnel, and swapping a whole provider's baseURL hides the real upstream. This plugin routes specific provider/model pairs at the transport layer instead — everything else stays direct, and the configured endpoint is never rewritten.

Features

• Per-rule routing: {provider, model, proxyUrl, enabled} — specificity: exact model > prefix muse-* > *.
• Purpose filter: optional per-rule purpose (e.g. compaction) so chat goes through the proxy while background calls stay direct.
• credentialRef: keep proxy passwords in the DSH credentials service instead of settings.yaml; rules reference them by name (user:password entries). Soft dependency — installs without it keep working.
• Auto probe: newly configured proxies are connectivity-tested once (CONNECT/socks handshake, no model quota); results go to the host log.
• Protocols: http://, https:// (CONNECT via undici.ProxyAgent), socks5:// / socks5h:// (via optional socks, tunnelled by undici Agent + custom connect).
• Zero baseURL mutation — keep the real upstream.
• Live: change rules → next llm/stream uses them; in-flight streams unaffected.
• UI: Settings → Plugins → Model Proxy card (also works via ~/.dsh/settings.yaml).
• Provider picker: dropdown groups user-configured providers first (derived from llm.providers × settings mirror, same semantics as the built-in Models page); bare directory routes follow, and "Custom…" accepts anything — hand-written yaml rules, wildcards, gateways the catalog doesn't know. Provider and model fields are dropdowns fed by the live host catalog (llm.providers / llm.models, refreshed on llm/adapters-updated); a "Custom…" entry keeps free text for wildcards (muse-*, *) or not-yet-installed providers.
• Batch & grouped management: adding rules checks multiple models for one provider at once — one rule each, sharing proxy/purpose/credential; the list groups cards by provider with group-level apply-proxy, enable/disable-all, and delete (cross-provider grouping never affects match order).

Install

Recommended: profile-managed (bundle)

The package declares a dsh.bundle layer, so the DSH CLI links the dependency and appends the activation row in one step:

dsh plugin --profile <name> add dsh-plugin-model-proxy
# optional SOCKS support:
dsh plugin --profile <name> add socks

Verify the composed layer without booting, then run:

dsh --profile <name> --dump-config   # shows a "# == dsh-plugin-model-proxy" layer
dsh --profile <name>

Uninstall removes both the dependency and the layer:

dsh plugin --profile <name> remove dsh-plugin-model-proxy

Installing from GitHub (dsh plugin --profile <name> add github:<user>/dsh-plugin-model-proxy#<sha>) fetches sources; pnpm ≥10 asks you to allowlist the prepare build — copy the package key it prints into the profile's pnpm-workspace.yaml under allowBuilds:, then re-run the add. Pin a commit so later pushes cannot change what runs on your machine.

Manual: hand-written patch

If you manage compositions by hand, install the dependency into the profile directory first (dsh plugin --profile <name> add ./ from a checkout works; module resolution anchors at the profile). Then insert exactly ONE loader row:

# ~/.dsh/cordis.patch.yml  (or a --patch overlay)
- insert:
    - id: model-proxy/host
      name: dsh-plugin-model-proxy
      config: {}

Patch-file rules that trip people up:

• The file must parse as a top-level YAML array of patch entries. Comments are fine; a file of only comments (no - … rows and no []) fails to parse and breaks every boot/dump that reads it.
• The loader-entry specifier field is name: (the package name), not module:.
• New rows must be nested under insert: — a bare - id: row means "patch an existing entry".
• Only the host half is a loader entry. The browser half is discovered automatically from the package's dsh.client declaration and served at /plugins/dsh-plugin-model-proxy/client.js. Do NOT add a model-proxy/client row — it would run browser code inside the Node process.
• Never mix this path with the profile-managed install above. Once the dependency declares dsh.bundle.patch, dsh plugin add injects the host row automatically; keeping a hand-written copy in ~/.dsh/cordis.patch.yml inserts the same loader id twice and the composition collides at boot.

Uninstall = remove the inserted rows + pnpm remove dsh-plugin-model-proxy from the profile.

Configure

Via UI

Settings → Plugins → Model Proxy

Via file

~/.dsh/settings.yaml:

model-proxy:
  enabled: true
  debug: false
  defaultProxy: ""  # fallback when no rule matches
  rules:
    - provider: opencode
      model: muse-spark-1.2-contributor
      proxyUrl: socks5://127.0.0.1:1080
      enabled: true
    - provider: opencode
      model: "*"
      proxyUrl: ""  # direct for the rest of this provider

proxyUrl: "" means direct (exempt). socks5h:// resolves DNS at the proxy.

How it works (non-invasive)

1. Host registers model-proxy settings namespace (installSettingsSection, live).
2. Wraps globalThis.fetch reversibly.
3. Listens on llm/stream waterfall, resolves proxyUrl for (provider, model) via AsyncLocalStorage, then injects a dispatcher into the adapter's fetch — for proxied requests it routes through undici.fetch (Node's native global fetch ignores custom dispatchers), with undici.ProxyAgent for http(s) and an undici Agent + socks connect (with TLS) for socks5/h.
4. Browser registers settings.plugin.item with key model-proxy — automatically paired by the Plugins tab (served ∩ registered).

No Adapter fork, no baseURL rewrite. See DESIGN.md for full design and invasiveness analysis.

Invasiveness

Check	Result
Modifies packages/*	No
Requires fork of dsh-llm	No
Global side effect reversible	Yes (ctx.effect dispose restores fetch)
Client bundle purity gate	Passes (only type-only slot import)

Building

pnpm install
pnpm run build

Testing

Fully offline (local origin + CONNECT-capable toy proxy; no real network or proxy needed):

pnpm test        # builds host + client, then runs node --test tests/
pnpm run typecheck

License

MIT