ChatGPTClaudeGrok / X / CursorGemini

DSH plugin profiles: web has an entry, headless does not

Plugin DevelopmentPublished 2026-11-05Author: DeepSeek Plugin Market
DSH pluginprofileheadlesswebDeepSeek Harness
The same plugin shows an entry in web and vanishes under headless. Profiles are three separate installs, with different dependencies and different UI.

One plugin opens a settings card under dsh web. Under dsh --profile headless "run a task", the tool still exists but the card is gone. Someone starts wondering which file the build dropped.

Nothing was dropped. You are looking at three separate installs.

One plugin, three fates

The same DSH plugin behaves correctly in all three profiles; only the interface differs. Put the same plugin into three profiles and the outcomes are predictable:

web: the tool runs, settings show an entry, tool results render as cards. It loads both the host half and the browser half.

headless: the tool runs, results appear in output, no interface. It runs one task and prints the answer; there is no browser.

sdk: the tool runs, the caller receives results over JSON-RPC, again with no interface.

All three are correct behavior. The difference is not plugin quality but whether the hosting profile has a UI and loads client resources.

DSH plugin profiles are separate installs, not modes

DSH plugin profiles are three separate installs, not launch modes. Reading profiles as "the same thing in different launch modes" is the root of most confusion; they behave more like three independent projects:

text
$DSH_HOME/
└── profiles/
    ├── web/      # own node_modules, patch, bundles
    ├── headless/ # another set
    └── sdk/      # another

Each profile directory holds two important files:

  1. package.json: outside dependencies plus the dsh.profile bundle list;
  2. cordis.patch.yml: the user's own patch layer, applied after bundle layers.

Installing with dsh plugin --profile <name> add installs into that one profile. That is why the same package shows a settings card in web and is absent from headless entirely.

Profiles initialize on first use. web, headless, sdk, sdk-minimal, and acp are prepared from bundled templates; desktop is reserved and the CLI refuses startup or config dumps for it.

Why a DSH plugin has an entry in web but not headless

Entries belong to the interface, not the plugin. A plugin with a settings card usually has two halves:

HalfResponsibilityIn headless
HostServices, tools, eventsLoads normally
BrowserSettings cards, tool renderingDoes not exist

Headless has no browser, so the browser half has nowhere to attach. That is not a load failure; that layer was never there.

The reverse is also true: components, styles, and assets used by the browser half are meaningless outside web. Forcing them into headless produces a pile of ineffective registrations.

Classify your plugin: if it only registers tools or events, it is naturally cross-profile; if the host half imports browser components, it belongs to web only.

DSH plugin design rules for multiple profiles

The first DSH plugin rule: the host half must never import browser code. This is the hard rule. Once the host references a browser-only module, headless either fails to load or silently skips it.

Second, expose capabilities through services and tools, not through UI. If headless should use it, register it as a tool or service; the interface is just another entry.

Third, never assume a UI exists. Do not write "error if the interface is missing"; under headless that manufactures a failure.

Fourth, split entries by profile. Put the interface half on its own row in a layer that only applies to web, rather than using one entry for both jobs.

A practical check: start under headless and look for "module not found" or "component undefined" in the log. Either means browser dependencies leaked into the host half.

The DSH plugin verification matrix

For a DSH plugin, "installed" is not "usable in this profile". Walk the matrix:

bash
dsh web                                  # web: UI and tool list
dsh --profile headless "list workspace files"   # headless: output
dsh --profile sdk                        # sdk: JSON-RPC connection
dsh --profile web --dump-config          # composition layers
  1. Start in web: the tool list and the interface entry both show it;
  2. Run one task in headless: the tool is callable and output contains a result;
  3. Connect through sdk: the service responds without a UI;
  4. Run --dump-config in each profile and confirm the plugin's layer exists;
  5. Remove it and repeat step one: the entry disappears with no residue.

Step four separates "not installed" from "installed but ineffective". No layer means an installation problem; a layer with wrong behavior means a code problem.

Never claim headless support after testing only web. Support means the tool runs under headless.

Three common DSH plugin misjudgments

Installing into web and looking in headless. Dependencies are per profile; install into each profile where you need the plugin.

Assuming a profile reset only resets config. --from-default-profile replaces the whole profile, bundles and plugins included. Record the bundle list first.

Treating desktop as an ordinary profile. desktop is reserved; the CLI refuses startup and config dumps for it, and the desktop app manages it. Create a named profile for command-line debugging.

One more subtle case: the plugin is installed, but startup points at a different profile. At launch, check the name after --profile; it must match the one you installed into.

Cross-profile reuse is not "package it again"; it is "separate the interface from the capability". Once separated, web is one entry, headless and sdk are the others, and the plugin only has to keep its host half clean. For how bundles relate to profiles, read packaging a bundle; for splitting the interface half, read plugin UI development; for a stuck load, read local debugging.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

My plugin has an entry in dsh web but disappears under headless. Was it installed wrong?

The DSH plugin was most likely installed into the web profile. Each profile has its own dependencies under $DSH_HOME/profiles/<name>, so a plugin installed into web never appears in headless, and UI entries only exist in profiles that ship a UI.

Can tools registered by a plugin be used in the headless profile?

DSH plugin tools are usable in the headless profile, but there is no interface entry. Headless runs one task and prints the final answer with no Web UI, so confirm registration from logs or output rather than from a page.

What does a plugin need to support both web and headless?

A DSH plugin that supports both web and headless separates the host half from the interface half. The host registers services and tools and must not import browser code; the interface half loads only in web. Then headless can run the host without UI assets.

Does resetting a profile with --from-default-profile remove installed plugins?

Yes, resetting a DSH plugin profile removes installed plugins. It replaces the profile with a fresh copy from a bundled template, overwriting its bundles and dependencies. Record the bundle list and plugin names before resetting and reinstall afterwards.

Related Terms

profile
A profile is a named assembly environment under $DSH_HOME/profiles/<name>, keeping its own dependencies, patches, and bundle list.— dsh CLI README
headless
Headless is a profile that runs a single task and prints the final answer, with no graphical interface, suited to scripts and automation.— dsh CLI README
sdk profile
The sdk profile is a profile that serves SDK clients over JSON-RPC on stdio until the connection closes and provides no Web UI.— dsh CLI README
bundle list
A bundle list is the ordered bundles entry in a profile manifest, determining which layers compose when that profile starts.— DeepSeek Harness CLI reference

Sources