What Is DSH Plugin? DeepSeek Harness Plugin Explained (2026 Guide)

Key Takeaways

A DSH plugin (also called dsh-plugin) is a modular TypeScript component that extends DeepSeek Harness (dsh), the open-source agent framework released by DeepSeek AI in developer preview.
DeepSeek Harness follows a strict “everything is a plugin” architecture built on the Cordis kernel—models, tools, sessions, UI, agent loops, and even core services are all plugins.
Plugins register capabilities through a simple apply(ctx) function and automatically clean up when unloaded, enabling safe, reversible extension without touching the core codebase.
Plugins are distributed as bundles or repository plugins, installed via the dsh plugin CLI into named profiles, and composed through ordered configuration layers.
The ecosystem already includes dozens of community plugins covering UI enhancements, tools, workflows, notifications, and diagnostics, discoverable via the dsh-plugin GitHub topic.
Proper dependency declaration, absolute-path registration, and effect-based cleanup are critical to avoid common loading and residual-state pitfalls.

What Is DeepSeek Harness?

DeepSeek Harness (commonly abbreviated dsh) is an open-source agent harness developed by DeepSeek AI. It enables large language models to operate as fully capable local agents that can read and edit files, execute commands, use tools, manage sessions, and complete real-world tasks.

Unlike traditional chat interfaces, dsh treats the model as only one component. The harness itself supplies the environment, tool access, safety boundaries, persistence, and orchestration needed for sustained work. The official design principle is explicit: everything is a plugin. This means every capability—model adapters, tool registries, session logs, approval policies, sandboxes, scheduling, and the web UI—is implemented and replaceable as a plugin.

The framework runs locally (default web UI at http://127.0.0.1:3080) and can be launched with a single command:

npx @deepseek-ai/dsh web

It is currently in developer preview and iterates rapidly, with expected compatibility-breaking changes. The architecture rests on the Cordis kernel, which handles plugin mounting, unmounting, dependency resolution, services, and typed events.

Defining a DSH Plugin

A DSH plugin is a TypeScript module that exports an apply function. When the harness loads the plugin, it calls apply and passes a shared Context object (ctx). Through this context the plugin registers services, tools, event listeners, effects, UI components, or any other capability.

The minimal form looks like this:

import type { Context } from '@deepseek-ai/cordis'

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  console.log('[hello-plugin] plugin loaded!')
}

Three equivalent forms are supported:

Function form (most common)
Object form (with explicit name and inject)
Class form (for service providers that extend Cordis Service)

Plugins may declare dependencies with an inject array (for example ['tools']). The loader waits until those services are available before calling apply. Any registration performed through ctx is automatically reversed when the plugin unloads. For explicit resources such as timers, developers use ctx.effect() to return a disposer function.

This design guarantees that adding or removing a plugin never leaves residual state or requires core code changes.

How the Plugin System Works

At boot time, dsh constructs a plugin tree from ordered configuration layers applied to an empty root:

Bundles listed in the profile’s dsh.profile.bundles (in declaration order)
The profile’s own cordis.patch.yml
The machine-level $DSH_HOME/cordis.patch.yml
Any temporary --patch overlays supplied on the command line

A bundle is an npm package that ships a configuration patch (declared under package.json → dsh.bundle). A profile is a named directory under $DSH_HOME/profiles/ that stacks bundles and holds out-of-tree plugin dependencies.

Official base layers include:

@deepseek-ai/dsh-base – models, tools, persistence, sandbox, credentials, telemetry
@deepseek-ai/dsh-web-app – browser UI
@deepseek-ai/dsh-headless – one-shot CLI runner

Because every component is a plugin, any layer can replace or insert rows by targeting an id. Upper layers always override lower ones. Services and events provided by Cordis allow plugins to collaborate without tight coupling—one plugin can define a tool interface, another implement the backend, and a third expose it to the model.

Types of DSH Plugins and Distribution Formats

Two primary packaging formats exist:

Bundle plugins – Full npm packages that contribute configuration patches and code. Installed with dsh plugin --profile <name> add <source>.
Repository plugins – Lightweight .dsh-plugin directories (often with a package.json entry point). Added to the repository-plugins configuration list and loaded at runtime.

Community plugins typically cover:

UI enhancements (side panels, generative HTML cards, TUI front-ends, status labels)
Sessions & messages (editing, branching, sharing, import)
Tools & capabilities (vision, browser, interconnect, custom tools)
Workflow & automation (multi-agent orchestration, persistent workflows)
Notifications & integrations
Development & runtime (diagnostics, doctor-style checks)
Just-for-fun utilities

The GitHub topic dsh-plugin and curated lists such as awesome-dsh-plugin already index nearly 100 plugins, with daily compatibility tracking against mainline snapshots.

Installing and Managing DSH Plugins

After launching dsh, plugins are managed per profile:

# Add a GitHub-sourced bundle
dsh plugin --profile web add "github:owner/repo#commit"

# Link a local development copy
dsh plugin --profile web add link:/absolute/path/to/plugin

# Forward any pnpm command inside the profile
dsh plugin --profile web install

Repository plugins are registered by editing $DSH_HOME/cordis.patch.yml (or the profile-level patch) to populate the repository-plugins configuration. Changes take effect after restarting the web service and hard-refreshing the browser.

Analysis of community installation patterns shows that pinning exact commit hashes prevents unexpected breakage during the rapid developer-preview cycle.

Creating Your Own DSH Plugin

Create a TypeScript module exporting apply(ctx) (and optionally name / inject).
Register capabilities using the appropriate ctx APIs (ctx.tools.register, ctx.on, ctx.effect, UI slots, etc.).
For local testing, place an absolute-path entry in a temporary cordis.yml and launch with --patch.
Package as a bundle by adding a dsh.bundle field that points to a patch file, or as a repository plugin under a .dsh-plugin directory.
Publish to GitHub, add the dsh-plugin topic, and optionally request inclusion in community catalogs.

Official documentation emphasizes reversible side-effects and early failure on misconfiguration. Plugins that violate these rules are rejected by the loader.

Common Pitfalls and Advanced Tips

Relative paths fail: Plugin module paths in patches must be absolute; the loader resolves from the profile directory, not the patch file location.
Missing inject declarations: A plugin that uses ctx.tools without listing 'tools' in inject will load before the service exists and throw.
Hard-coded state: Because unload is automatic, any external resource (file watches, network listeners, intervals) must be wrapped in ctx.effect().
Compatibility during preview: Daily community matrices track patch application, seam availability, peer dependency ranges, and compile success. Prefer plugins that pass all four checks against the current mainline.
Hot-path discipline: Advanced plugins avoid modifying the agent-loop skeleton; they register only through documented extension seams so they introduce zero measurable overhead.
Profile isolation: Keep experimental plugins in a dedicated profile rather than the default web profile to prevent interference with production sessions.

Edge-case testing reveals that combining repository plugins with bundle overlays can produce subtle ordering issues; the recommended practice is to keep machine-level patches minimal and prefer profile-level composition.

Conclusion

A DSH plugin is the fundamental unit of extensibility in DeepSeek Harness. By treating every capability as a Cordis-managed plugin, the framework achieves unprecedented modularity: any model, tool, UI surface, or orchestration strategy can be swapped through configuration alone. The result is a local agent platform that is simultaneously powerful, safe, and infinitely customizable.

Developers and power users who master the plugin model gain the ability to reshape the entire agent runtime without forking the core. Start by exploring the official documentation, install a few high-quality community plugins, and then build a minimal apply(ctx) module to see the system in action.

Ready to extend DeepSeek Harness? Launch npx @deepseek-ai/dsh web, add the first plugin, and begin composing the agent environment that matches your exact workflow.