On this page+
Why “Everything Is a Plugin” Matters
DeepSeek Harness does not treat plugins as a thin add-on system around a fixed application core. The model adapter, tool registry, session log, agent loop, runtime services, Web application, policies, and other capabilities are all mounted through the same Cordis composition model.
This means extending Harness normally means adding or replacing a plugin in the tree rather than patching a privileged core. Registrations belong to plugin lifecycles and unwind when their owner unloads.
What Is a DSH Plugin?
At the framework level, a plugin is code that receives a Cordis Context and contributes behavior. The common function form exports apply(ctx), and inject can declare the services that must exist before activation.
A plugin does not have to be a model-facing tool. It can provide an LLM adapter, filesystem provider, shell backend, background jobs, approval policy, UI renderer, command, session behavior, or another documented extension point.
Consumer
Uses a capability already registered on Context.
Provider
Implements a service that other plugins can consume.
Observer / policy
Listens to lifecycle or capability events and changes how work is admitted or presented.
What Is a DSH Bundle?
A bundle is a distribution format for Cordis configuration rows and the code those rows mount. Its package manifest declares dsh.bundle and points to the patch file that contributes the bundle layer.
The important property is composability: rows inserted by a bundle remain patchable by layers applied above it. A bundle can therefore ship a coherent set of plugins without making the resulting configuration opaque or immutable.
{
"dsh": {
"bundle": {
"patch": "./cordis.patch.yml"
}
}
}What Is a DSH Profile?
A profile is a named composition stored under the Harness home. It lists the bundles it stacks, carries out-of-tree plugin dependencies installed for that profile, and keeps the profile’s own cordis.patch.yml.
The official Web and headless profiles are shipped as templates and auto-initialize on first use. Other named profiles can be created through the plugin-management path, which is why a TUI or specialized workflow can have its own extension set without changing Web.
{
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app"
]
}
}
}How the Layers Compose at Boot
Harness composes a profile over an empty entry list. Bundle patches apply in the order named by the profile, followed by the profile-level user patch, the Harness-home patch, and finally any command-line --patch overlays.
1. Bundle layers
Each bundle patch in dsh.profile.bundles order.
2. Profile patch
The selected profile’s own cordis.patch.yml.
3. Home patch
The machine-level $DSH_HOME/cordis.patch.yml layer.
4. CLI overlays
Any --patch files applied after the stored layers.
A higher layer can replace the configuration of an existing row or insert another row, which is why bundle-provided behavior remains customizable.
How Web and Headless Profiles Differ
The base bundle supplies the common Harness capabilities such as model adapters, tools, persistence, sandbox and approval policy, settings, credentials, and telemetry. A profile then stacks the surface-specific bundle it needs.
Web
Stacks the common base with the Web application bundle, producing the browser interface and its related client/runtime plugins.
Headless
Stacks the common base with the headless runner, producing a one-shot agent flow without a Web server.
Custom / community profile
Can stack different bundles and install additional out-of-tree plugins for a TUI or specialized workflow.
Inspect the Plugin Tree on Your Machine
When a plugin behaves differently from what you expect, inspect the final composition rather than reasoning only from package.json. The config dump shows the tree after the selected profile and patch layers have been applied.
dsh --profile web --dump-configdsh --profile web --dump-default-config- Use the dump to verify a plugin row exists and identify which layer contributes it.
- Check whether a later patch replaces configuration from a bundle.
- Compare profiles before assuming one install affects every DSH surface.
Primary references
This guide is grounded primarily in the current DeepSeek AI Harness repository and development documentation. Harness is still in developer preview, so exact commands and contracts can change with later releases.