dsh-magpie-connector

English · 简体中文

Model picker recorded from an isolated DSH host with a local mock Magpie gateway; models and accounts are synthetic. A fresh settings screenshot is pending re-recording.

Repository · Releases · npm

Connect a self-hosted Magpie gateway to DeepSeek Harness as one provider route: models grouped by their upstream provider, read-only usage cards, and a per-session fast mode. Magpie keeps managing logins, accounts, routing and provider egress; this plugin adds the DSH side.

What you get

Capability	What it does
Gateway lines (basic)	Each line has its own URL and gateway key. The model catalog comes from the gateway's GET /models; Responses-capable models use Responses, everything else uses Chat Completions. Text, tool round trips, images, usage, cancellation and DSH-managed retries go through.
Automatic multi-line failover (signature)	Empty on first install; normally one line; add backup lines and let the order decide priority. Before every gateway operation the plugin picks the first reachable complete line with a ≤600ms TCP probe (10s positive / 15s negative in-memory cache, no background polling), so home uses the LAN while outside falls back to the public endpoint. Switching lines carries the catalog over (no flash), clears usage cards and re-syncs the new line; single-line users keep 0.1.x behavior.
Grouped by upstream provider (signature)	The model picker shows Magpie (Claude), Magpie (GPT) and Magpie (<other owner>) headings while the real route stays one dsh-magpie-connector. Settings and usage cards use the same grouping, and a provider that only appears in usage is never dropped.
Per-line Cloudflare Access	Each line independently chooses Direct or Cloudflare Access. Access-enabled line requests carry the service token pair plus the bearer key; the token is never sent to a plain-HTTP line.
Read-only usage cards	Each upstream account shows plan, expiry, window readings and Codex reset credits when the gateway provides them. Cards are read once when settings open and only re-read when you press Refresh on that card; bars turn orange above 70% and red at 90%.
Model visibility and default effort	Per provider, leave visibility untouched to follow the gateway catalog, or save an explicit allowlist so new models stay hidden. Per model, save a default reasoning effort; DSH applies it on the next request.
Per-session fast mode	Models advertising the priority service tier get a standard/fast switch next to the composer. The choice is per session and in host memory only; it adds service_tier: "priority" to requests.

Install

dsh plugin --profile web add dsh-magpie-connector

Restart DSH and refresh the Web page. Inside ohmydsh you can instead enable the local dsh-magpie-connector manifest entry and rebuild. Tested with DSH 0.2.0-rc.2, Web UI, Node.js >=22.19.

The model picker headings need the managed five-package Host extension that ohmydsh's Pet compatibility layer builds for the reviewed 0.2.0-rc.2 pin. Stock rc.2 still uses the route and generation normally, with a flat provider list.

Configure

Open Settings → Magpie.

1. In line 1, enter the gateway API URL including /v1, for example http://192.168.1.20:3425/v1, and that line's gateway key. The line list, addresses, visibility and default efforts live at $DSH_HOME/plugins/dsh-magpie-connector/settings.json — keys and Access values are never written there or returned by the settings API.
2. For multiple ingresses press Add backup line; each line has its own address and key. Use the move-up/move-down buttons to change priority (number 1 wins). Saving keeps only the active line expanded; the 4×4 green marker after its number shows the current line, and the info icon explains priority and automatic fallback.
3. Inside each line's Advanced connection choose Direct or Cloudflare Access. LAN and Tailscale are Direct; Cloudflare Access requires an HTTPS line and switching back to Direct clears that line's two Access credentials on save. Cloudflare Free/Pro returns 524 when the origin sends nothing for 100 seconds.
4. Saving synchronizes the catalog; Refresh model list synchronizes again, and there is no catalog polling.

0.2.0 BREAKING upgrade: settings are now a single lines[] format. A legacy single-address settings.json (top-level baseUrl) and the legacy fixed credential refs (MAGPIE_API_KEY / MAGPIE_ACCESS_*) are not read or migrated; re-add your lines and enter each line's key/Access in Settings. Model visibility and default efforts are preserved; old credential records can be deleted manually in DSH credentials. Back up settings.json and the old refs first if you want to keep a rollback path.

Need another method — custom headers, mTLS, another zero-trust gateway? Issues and pull requests are welcome; describe your deployment and the gateway version.

Where things happen

Where	What you do
Model picker	Search across group headings, model names and full ids. Headings come from the gateway's owned_by; the route behind every item is still dsh-magpie-connector, so model ids, visibility keys and default effort do not change.
Model menu groups	A model with a non-empty owned_by appears under Magpie (<owner>); claude and codex are shown as Claude and GPT. Missing ownership falls back to Magpie (Other) instead of guessing from the model name.
Composer speed control	Shows only for the current model when the gateway advertises the priority tier (on current Magpie: the Codex/GPT models), and updates as soon as the selection changes. Hover the model menu to see effort; the official picker shows one effort value.
Settings → Magpie	Connection, advanced connection mode, per-provider model sections with visibility checkboxes and default effort selects, plus the usage cards for that provider.
Usage card refresh	Each card has its own Refresh, which asks Magpie to re-read that one account. A cold gateway may return no cards at all; the connection panel then offers Fetch models and usage, which first re-synchronizes the catalog and then asks Magpie to read every account once. A restricted held key cannot initialize an empty cache — ask the Magpie administrator to read usage first.

Behavior worth knowing

• Failed requests are retried by DSH, not replayed by the plugin. The adapter declares the same llm-retry policy as dsh-plugin-subscriptions (10 attempts, exponential backoff from 1s to 60s, ±20% jitter, honoring Retry-After). TIMEOUT, TRANSPORT, SERVER, RATE_LIMIT and EMPTY_RESPONSE are retryable; 401/403, exhausted quota, context overflow and other 4xx are not.
• The default output budget reserves room for compaction. The gateway's max_output_tokens is the model's capacity, not the per-request default. The default budget handed to DSH is min(capacity, max(1, window/4, window/2 − 65536)), leaving context space for DSH compaction; an explicit maxTokens is unaffected. Models with a window below 104,026 tokens follow the same formula but are not guaranteed to pass DSH's compaction checks.
• Only silence ends a stream. Headers, SSE events and heartbeats all count as liveness; 300 seconds without any data ends the request with TIMEOUT (message contains MAGPIE_STREAM_TIMEOUT). Long reasoning survives as long as the gateway keeps the stream alive.
• Connection changes do not abort work. A new address or key immediately hides the old catalog and cards, but generations already prepared or running finish with their captured address and key. User cancellation and plugin disposal still stop them.
• The transport is deliberately narrow. Host requests go through a private undici dispatcher straight to the configured gateway, never through a global proxy dispatcher. Redirects are rejected; only GET /models, POST /responses, POST /chat/completions, GET /magpie/quotas/cards and POST /magpie/quotas/refresh are allowed; Magpie GUI /api/* management endpoints are never called. Provider egress proxies belong in Magpie.
• Not supported: stop sequences fail before any network access (MAGPIE_STOP_UNSUPPORTED) because Magpie cannot preserve them across every upstream translation. Usage cards and Codex reset credits are display-only; the plugin never calls account-management or reset endpoints.
• Secrets stay out of responses and logs. Gateway-reflected text is redacted with the current key before it can reach the settings API or logs. Files are written 0600; the settings API reports only configured / writable.

Architecture

Entry: index.ts. Adapter and request/stream mapping: adapter.ts. Routes: routes.ts. Transport allowlist: transport.ts. Settings page: SettingsPage.ts. The diagram source, with credential-free repository evidence: architecture.en.json.

Development

npm install
npm test --workspace=dsh-magpie-connector
npm run typecheck --workspace=dsh-magpie-connector
npm run build --workspace=dsh-magpie-connector

Tests use local mock gateways and the real wire library; no real key is required. Build output is not committed. Both prepare and prepack build the package.

Removal

dsh plugin --profile web remove dsh-magpie-connector

Restart DSH and refresh the page. Disposal releases registrations, timers and connections; it does not remove credentials or settings. To erase data, delete each line's MAGPIE_LINE_<ID>_* refs (plus any pre-0.2.0 MAGPIE_API_KEY / MAGPIE_ACCESS_* leftovers) through DSH credentials management and remove the plugin settings file after locating it from the installed plugin's data directory. Do not remove a credential if another integration still uses it.

Inside ohmydsh, set the manifest entry to enabled: false and rebuild instead.

License

MIT. @earendil-works/pi-ai and undici are separate MIT-licensed dependencies; the bird artwork follows the notice in THIRD-PARTY-NOTICES.