ChatGPTClaudeGrok / X / CursorGemini

DSH plugin runtime matrix: web, headless, and Electron

Plugin DevelopmentPublished 2026-11-17Author: DeepSeek Plugin Market
DSH pluginDeepSeek Harnessplugin developmentheadlessElectron
Works in local web, silent in headless, no UI in Electron. A capability matrix, existence probes, three fallbacks, and a test checklist.

Compatibility across runtimes rarely fails because of a bug; it fails because the code assumed something it had no right to assume. The same plugin behaves under dsh web, goes silent under headless, and shows no interface in Electron. For a DSH plugin, the differences are not in your business logic but in whether a page exists at all.

What actually differs across DSH plugin shapes

Two variables explain almost everything: is there a browser, and does the client bundle get loaded? (source)

ShapeHost halfBrowser halfPage entry
webloadedloaded via boot graphserved by HTTP server
headlessloadednot loadednone
Electronloadedbuilt files over file://not served by HTTP server

The table settles most "runtime-specific" failures. Host capabilities -- tools, services, events -- register in all three shapes. Anything that depends on UI only makes sense when a page exists.

So the first step is not writing branches. It is splitting the plugin into "host capability" and "page presentation", then being honest about which logic must live on the host side.

Probe, do not assume: DSH plugin existence checks

Check existence instead of reading an environment variable. (source)

The reliable way to know the current shape is to look for the thing you intend to use: did the injected service arrive, did the route register, is your entry present in the boot graph. Those are runtime facts, and facts beat a flag that claims "this is web".

Three probing habits:

  1. Required services go in inject -- if one is missing the framework refuses to load you, so no manual check is needed.
  2. Optional capabilities get a runtime check -- confirm the service exists before registering, and skip if it does not.
  3. Page logic stays in the client half -- the host half never assumes someone will render.

The anti-pattern is letting a config value decide the shape. Config describes deployment intent; only runtime facts tell you whether a capability is actually available.

Three DSH plugin ways to degrade

Skip, substitute, or fail -- the choice depends on whether the capability is your core job. (source)

  1. Skip -- do not register an optional capability, and log one reason. Right for "nice to have" features.
  2. Substitute -- cover it with a host capability, for example writing results to the log or returning them to the caller when there is no page.
  3. Fail -- let loading fail when a core capability is missing. Early failure is cheaper than mystery.

All three must be explicable: a skip needs a log line, a substitution needs its difference stated, a failure needs to name what is missing. Registering an empty implementation is the one outcome that must never happen, because callers then believe a feature exists.

The DSH plugin client half only matters on web

Without a page the client bundle never loads, so writing it changes nothing. (source)

The client half is declared under dsh.client, bundled, and scanned into the boot graph by the client module service. Headless has no page and therefore no boot graph, so that code simply does not run.

Accept the consequence: no initialization that "must happen first" belongs in the client half. Put initialization on the host side and let the client half render and interact.

The same logic applies to Electron, where the page loads over file:// and never touches the HTTP server. Client code that assumes a particular route exists will come up empty there.

One DSH plugin codebase, one branch

Confine the branch to one place and the rest of the code stops caring about the shape. (source)

A structure that works: the host half registers capabilities, a single probe at the registration entry decides whether client contributions get mounted, and business logic stays shape-agnostic.

Three details:

  1. One registration function -- pass in the probe result, return what was registered.
  2. Client contributions in their own module -- mounted only when the probe passes, never affecting the host half.
  3. Error messages name the shape -- "current shape lacks X" is worth far more than "initialization failed".

The result is full functionality on web, a graceful host-only degradation under headless, and no crash in Electron for a missing HTTP route.

How to test the DSH plugin matrix

Three shapes, one pass each, beats tweaking a single shape repeatedly. (source)

  1. web -- host capabilities work, the page entry appears, the client half loads.
  2. headless -- host capabilities still work and nothing throws over the missing page.
  3. Electron -- functionality works over file:// and depends on no HTTP route.
  4. Optional missing -- remove one optional service; the plugin skips instead of crashing.
  5. Core missing -- remove a required service; the plugin refuses to load instead of running on a stub.

Verification: the three-shape matrix

Run the matrix after every change and shape bugs never reach a release. (source)

  1. Boot under web and assert the tool is callable and your entry is visible on the page.
  2. Boot under headless and assert the same tool is callable, with no "page not found" exception in the log.
  3. Boot under Electron and assert the UI works and no request hits a nonexistent HTTP route.
  4. Remove an optional service and assert the plugin still loads, skips that feature, and records why.
  5. Remove a required service and assert the plugin does not load, with an error naming the missing service.

A failing tool call in step 2 usually means a host capability ended up in the client half. A 404 in step 3 means some code assumed an HTTP route.

Profile-level differences are collected in profiles and their differences; the client half itself is covered in interface development.

One line to close: the three shapes differ only in pages and client bundles -- probe by existence rather than environment, degrade by skipping, substituting, or failing with a reason, keep initialization on the host, and finish by walking the matrix once.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

DSH plugin works on web but is silent in headless. Why?

Start by checking whether the DSH plugin depends on something that only exists in a browser. DSH plugins have host and client halves; the client half enters the boot graph through the client module, and headless has no page, so that bundle never loads. Host-side registrations usually keep working, so the silent part is almost always UI-related.

How should a DSH plugin detect its runtime, not guess it?

A DSH plugin should probe for existence rather than read an environment flag. In DSH, rendering depends on the client module and boot graph while the host side only needs services on ctx. Check whether the service you injected actually arrived, which is accurate in all three shapes, instead of branching on a variable.

DSH plugin capability missing: skip it or register a stub?

Decide by whether the capability is core to the DSH plugin. DSH already refuses to load a plugin whose required service is absent; for optional capabilities, skip the registration and record why, and for core ones fail the registration. A stub that never works is the worst outcome.

Is DSH plugin Electron served by the same HTTP server?

No: an Electron build of a DSH plugin loads files over file:// and routes fetches through an IPC bridge, while the HTTP server only serves browser builds. A plugin that assumes some route must exist will break under Electron; what it can reuse is host-side capability, not the page entry.

Related Terms

WebBootGraph
WebBootGraph is the boot graph the host writes into window.__DSH_BOOT__, describing each browser-side entry and its dependencies; only the web shape uses it.— DeepSeek Harness Reference - Client Modules
client half
The client half is the browser-facing part of a plugin, declared under dsh.client in package.json and bundled so the client module service can scan it into the boot graph.— DeepSeek Harness Reference - Client Modules
HTTP server
The HTTP server is the browser carrier of the GUI host; it serves named routes and index injection, and Electron never takes this path.— DeepSeek Harness Reference - HTTP Server
IPC bridge
The IPC bridge is the channel that replaces HTTP requests inside Electron; the page talks to the host through it without touching dsh-host-webserver routes.— DeepSeek Harness Reference - HTTP Server

Sources