How to change DSH plugin config: config and patch layers

Every config: block of a DSH plugin in DeepSeek Harness can be set from a cordis.yml entry, and the official config catalog lists the options package by package; changes override through patch layers, with later layers winning. This guide covers how to write plugin entries, how the override order stacks and how to look up fields.

Where DeepSeek Harness plugin options come from: config blocks and the catalog

The DeepSeek Harness rule is that every config: block can be set from a cordis.yml entry, where a plugin entry names the plugin with name and passes parameters with config, and the configurable fields are listed package by package in the official config catalog (source). Work through it like this:

1. Read the plugin entry shape — a plugin config is made of name (the plugin) and config (the parameter dictionary), plus an optional id and insert to control placement. Expected: when name does not match, the plugin never loads at all.
2. Consult the official catalog — look up the plugin by package name in the config catalog. Expected: @deepseek-ai/dsh-agent-default-model has provider and model, while dsh-agent-instructions has dshHome, maxBytes and instructionFileCandidates.
3. Know the field types — numbers, booleans and string arrays each carry different meaning, such as the numeric maxParallelToolCalls and the list agents[] in dsh-agent-loop. Expected: a wrong type fails config validation.
4. Write the entry — put the keys you want to change into that plugin's config. Expected: after saving, the lifecycle decides whether a restart is needed.

How to override DeepSeek Harness plugin defaults: patch layers and --patch

Plugin defaults stack in four layers: each bundle's own patch, then the profile cordis.patch.yml, then the home-level $DSH_HOME/cordis.patch.yml, then the startup --patch, where later layers sit further out and win (source). Choose the layer by goal:

1. Change one profile's plugin — write $DSH_HOME/profiles/<name>/cordis.patch.yml. Expected: only that profile is affected; others never read it.
2. Reach every profile on the machine — write $DSH_HOME/cordis.patch.yml. Expected: it is stacked as the home-level layer by all profiles.
3. Temporary experiment — pass an override file with --patch at startup. Expected: highest priority, no persistent file touched, gone on restart.
4. Confirm the lifecycle — check whether the profile's patchReload is live or startup. Expected: under startup, changes need a restart to apply.
5. Verify with a dump — --dump-config prints the actual merged values, --dump-default-config prints the defaults. Expected: diffing the two shows which layer won.

How to inspect settable DSH plugin fields: --dump-config-schema

--dump-config-schema prints the structural definition of config options without starting a server, the authoritative answer to what can be configured, while --dump-config answers what is actually configured (source). Debug plugin config in this order:

1. Dump the schema first — run --dump-config-schema and find the plugin by name. Expected: you confirm field names, types and required flags instead of guessing from memory.
2. Then dump actual values — run --dump-config. Expected: what you see is the final result after all layers stack.
3. Compare against defaults — run --dump-default-config. Expected: you can tell whether a value is the default or something you changed.
4. Locate the override source — if actual values differ from expectation, check the profile and home-level patches layer by layer. Expected: you find the outer line that overrode the inner one.

To change plugin config through a graphical panel instead of handwritten YAML, look for plugins with a settings page in the DSH Plugin Hub.

Caveats and limits of DeepSeek Harness plugin configuration

1. name must be exact: a wrong plugin name throws no config error and the plugin simply does not load, so confirm the package name first.
2. Outer layers reach further: a home-level patch affects every profile, so to touch one, write at profile level.
3. --patch does not persist: it is good for verification, not as a permanent config.
4. patchReload: startup needs a restart: not every change applies live.
5. Settable is not the same as sensible: read the config catalog field notes first and avoid undefined keys.

For how config layers relate to file locations, see Where DeepSeek Harness config files live; for where plugins are installed per profile, see How to create an isolated profile in DeepSeek Harness.

Sources: Config catalog (official docs), dsh CLI README (official repository)