DSH Field Guide

How to read this guide

DeepSeek Harness is a pre-release project (version 0.1.1-rc.2, breaking changes expected) that moves fast enough for eight release candidates to ship in a week. Two of them landed on the same day. Any document about it is a photograph, not a map, so this one states its shutter speed: it describes commit b150a55 of 2026-08-21, and every factual claim carries a badge saying how it was established.

Contents

• 01What a harness is, briefly
• 02What DeepSeek Harness is
• 03"Everything is a plugin", qualified
• 04Bundle, Profile, Preset
• 05Host plane and agent plane
• 06The four presets that ship
• 07Composition and layer order
• 08Bringing your own model
• 09Writing a plugin
• 10What has already been built
• 11Security posture, honestly
• 12How it compares
• 13Commonly repeated errors
• 14Documentation drift at this commit
• 15How this was verified

What a harness is, briefly

A model produces tokens. Everything else that makes an agent useful is the harness: the tools it may call, the loop that decides when to stop, what goes into the context window and what gets evicted, which actions need approval, where the conversation is persisted, and what the process may touch on disk. The model is the engine; the harness is the rest of the car.

Three corrections to the usual framing are worth carrying into the rest of this guide. External

• A better harness does not always beat a better model. In one controlled comparison by Databricks, swapping harnesses changed cost by roughly 2x with quality essentially unchanged. The harness thesis is strongest for long-horizon, interactive work, not universally.
• Harnesses are decreasingly model-agnostic. Harnesses and models are increasingly post-trained together, so swapping the model under a harness tuned for another one tends to degrade it in ways that are hard to see.
• A harness is not an agent framework. LangGraph is a library for building harnesses. Claude Code is a harness. The distinction matters when comparing them.

This guide does not attempt a general introduction to harness engineering; that ground is well covered elsewhere, notably by walkinglabs/learn-harness-engineering. What follows is specific to DeepSeek Harness.

What DeepSeek Harness is

DeepSeek Harness (dsh on the command line) is an MIT-licensed, TypeScript agent harness published by DeepSeek. It is built on a vendored fork of Cordis, a dependency-injection and plugin framework, and its organising idea is that the harness should be assembled from plugin layers rather than configured within a fixed application. Source

You launch it as a profile: an ordered stack of plugin bundles under your own overrides. The documented entry point is npx @deepseek-ai/dsh web, which serves a local web UI on port 3080. There is also a headless profile for one-shot tasks, an ACP server for automation, and a JSON-RPC SDK. It is web-first in a field that is mostly terminal-first. Run

Scale, stated accurately

The repository contains 227 packages, all named @deepseek-ai/dsh-*. That number is widely quoted and it is nearly useless, because no deployment loads 227 packages. The number that describes what actually runs comes from asking the binary: Run

So a real web session boots 104 active plugins composed from 129 rows across two bundles. Of the 128 distinct packages in that tree, only two come from Cordis itself; the rest are harness packages. That is the honest measure of how much of this system is assembled rather than hard-wired.

Open source, but not open governance

CONTRIBUTING.md is unusually direct, and reading it changes how you should relate to the project: Source

• External pull requests are not accepted - "We are sorry that we cannot accept external pull requests at the moment."
• The issue tracker is disabled. GitHub Discussions is the only channel for reporting bugs.
• Community plugins are explicitly not second-class: "We do not believe that packages in the official repository are inherently more important than packages created by the community... You may consider this repository an idea, an official showcase, and a source of inspiration, but not a mandate from us."
• The project asks for exactly two things from outsiders: publish plugins under the dsh-plugin GitHub topic, and "write blog posts and how-to guides about DeepSeek Harness."

The result is a project that is source-available and freely licensed without being community-governed. That is a coherent position and the project states it plainly, but it is a different thing from the "open source" most readers will assume, and worth knowing before you build a business on it.

"Everything is a plugin", qualified

This is the project's signature line and the thing most repeated about it. It is an accurate description of the architecture's intent and a false literal statement, and the source says so. Source

There is a kernel. It consists of Cordis's Context, the root Fiber, and the built-in Reflect, Registry, Events and Logger services, plus host bootstrap. Bootstrap then mounts the Loader as a plugin, and from that point the generalisation holds - the model adapter, the tool registry, the session log and the agent loop are all plugins. But some things are deliberately not: Session, for instance, is a plain class rather than a service.

Is the idea novel?

Deep plugin architectures are old: OSGi Declarative Services dates to 1999, and Eclipse extension points, Emacs, VS Code, Spring and Guice all long predate this. Dependency-injected service registries are not new, and neither is around-middleware. The Cordis paper concedes much of this itself, noting that iPOJO's Gravity "directly prefigures Cordis's ctx.provide/ctx.get pattern" - the authors' own word. External

What is claimed as novel is narrower and more defensible. The first is composition of inverses, where you write an inverse only for each atomic effect and the inverse of any composite is derived. The second is asynchronous teardown, which OSGi's synchronous deactivation callback cannot express. The contested question is whether that justifies calling it a programming paradigm.

The sharpest public critique comes from a direct peer, the author of a competing harness, who granted that per-registration cleanup handlers are nice but doubted the rest: the cross-plugin dependency injection "comes with a lot of footguns... most plugins do not have dependencies on each other, so this more complex system doesn't win you much." A substantive Chinese-language review reached a similar verdict: the architecture has novelty, the orchestration paradigm has no breakthrough. It also observed that "everything is swappable" does not automatically yield better task success rates. External

Where the genuine novelty probably is

Not in pluggability, which is old, but in the agent modifying its own runtime. The cordis preset exposes model-facing tools that let the agent define and mount a plugin into the process it is currently running in. Every other harness lets you extend it; this one lets the agent extend itself mid-session. Reversible-effect machinery is over-engineering for a static plugin set, and becomes load-bearing the moment something is mutating the runtime while it runs. This paragraph is inference, not a claim from the source.

Bundle, Profile, Preset

These three words are the most common source of confusion about dsh, and nearly every secondary explanation of the project conflates at least two of them. Each is documented upstream; what is not documented anywhere is the contrast, which is the reader's actual problem. Run

Here is a real profile manifest, generated by the tool rather than transcribed from documentation: Run

// $DSH_HOME/profiles/web/package.json
{
  "name": "dsh-profile-web",
  "private": true,
  "dependencies": {},
  "dsh": {
    "profile": {
      "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app"]
    }
  }
}

Profiles are directories, and the shipped ones are created for you: asking dsh to dump its configuration was enough to bring both web and headless into existence on disk. An arbitrary new name is not auto-created. Until you run dsh plugin add against it, it resolves to nothing and composes zero rows.

Host plane and agent plane

Once you have more than one session in a process, the question of where a plugin registers becomes the thing that breaks. The shipped code preset explains this better than the architecture documentation does, in a header comment on the file itself: Run

So the split is:

The practical consequence for anyone building something real: a provider and its model-facing tool are two different roles that belong on two different planes. Mount the provider from a bundle patch on the host plane; mount the tool that consumes it from a preset on the agent plane. This is exactly how the shipped Codex subagent bundle is arranged.

The four presets that ship

Exactly four agent presets ship, discovered from directory names rather than declared in an enumeration. The table below was read from the installed npm package - the artifact users run. A recursive search of that tree for orchestrator returns nothing. Run

What Code Mode actually does

This is the most misdescribed feature in the project, so here is the shipped file's own header comment, verbatim: Run

Code Mode is a tool-presentation change that collapses round trips. The program is an ephemeral call executed in a fresh worker with no cross-run state. It is not a durable artifact, and not a conversion of your session into a standalone program.

Composition and layer order

A profile composes over an empty root in a fixed order. Each layer is a list of patch operations against rows identified by id: Source

1. each bundle's patch, in dsh.profile.bundles order
2. then the profile's own cordis.patch.yml
3. then $DSH_HOME/cordis.patch.yml
4. then any --patch overlays, in the order given

The best diagnostic in the product

--dump-config and --dump-default-config print the fully composed tree without booting it, annotated with which bundle contributed each row and which bundle patched it. No secondary explanation of this project mentions it, and it makes the layering model concrete in a way no diagram does: Run

$ dsh --profile web --dump-default-config

# == @deepseek-ai/dsh-base
- id: timer
  name: '@deepseek-ai/cordis-plugin-timer'
# == @deepseek-ai/dsh-base, patched by @deepseek-ai/dsh-web-app
- id: hmr
  name: '@deepseek-ai/cordis-plugin-hmr'
  config:
    root: [.]
  disabled: true

It needs no API key and makes no model call, so it is the cheapest way to answer "what is actually loaded?" and the first thing to reach for when a plugin appears to do nothing.

Bringing your own model

Composition is abstract until you use it for something you actually want. For most readers that something is the model. A harness published by a model vendor invites one obvious suspicion: that the model connection is welded in. It is not. The verdict is more interesting than either "DeepSeek-only" or "run anything", and the gap between those two is where the practical detail lives.

The seam is real

LlmAdapter is an abstract class in the LLM service, not a DeepSeek client with hooks bolted on. Its only required method is stream(). Adapters are registered with ctx.llm.registerAdapter(providers, adapter), and because registration is effect-owned, an adapter disappears when its plugin unloads, exactly like any other contribution described in section 03. Source

The service documents one obligation on adapter authors that is easy to miss: every provider HTTP request must include attributionHeaders(). The two shipped adapters satisfy it through completely different internals, one by direct fetch and one through a library header hook. Source

How far the catalog actually reaches

The llm-pi-ai adapter delegates to a pinned third-party catalog. Rather than repeat a figure from someone else's summary, the count below was produced by calling getBuiltinProviders() against version 0.82.1, the exact version the repository pins. It returns 37 provider IDs: Run

The Anthropic Messages, OpenAI Completions, and OpenAI Responses implementations behind these are real imported modules, not stubs. Source

Three limits worth knowing before you plan around this

What this means in practice

If you already pay for a frontier model, the useful reading is that anthropic, openai, and github-copilot are catalog entries, so reaching them is a settings exercise rather than an engineering one. If you run open weights locally, Ollama and most self-hosted servers expose an OpenAI-compatible endpoint, which is precisely the openai-completions protocol a hand-declared route supports. The community has already built at least one adapter of its own, an OAuth-based GitHub Copilot provider, which is the clearest available evidence that the seam is usable from outside the repository. External

A protocol outside those three still needs a new adapter plugin. That is not a workaround; it is the intended extension path, and it is the same three-files-and-one-command exercise as section 09. An adapter is simply a plugin whose contribution happens to be a model route.

Writing a plugin

An external plugin is three files and one command. No build step, no TypeScript toolchain, no bundler. The framework packages are peer dependencies supplied by the host at runtime, so plain JavaScript works. The sequence below was executed end to end. Run

1. package.json: the dsh.bundle key is what makes it installable

{
  "name": "dsh-hello-probe",
  "version": "0.1.0",
  "type": "module",
  "main": "index.js",
  "files": ["index.js", "cordis.patch.yml"],
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}

2. index.js: named exports only

export const name = 'hello-probe'

export function apply(ctx) {
  ctx.logger('hello-probe').info('external plugin loaded')
}

3. cordis.patch.yml: name must match the package name exactly

- insert:
    - id: hello-probe
      name: dsh-hello-probe

4. Install it

$ dsh plugin --profile probe add ./dsh-hello-probe
dsh: initialized profile probe at $DSH_HOME/profiles/probe
+ dsh-hello-probe
Done in 223ms

Three traps

Where you can attach

The documented extension seams, each consumed by declaring inject and calling a registration method that returns a disposer: Source

• Tools: ctx.tools.register(defineTool({...}))
• Tool policy: the tools/pre-execute, tools/execute, tools/post-execute and tools/result waterfalls
• Web: search and fetch providers
• Skills: a discovery provider, or one runtime skill
• Subagents: implement a provider, expose it with a configured delegation tool
• Workflows: an engine, plus observation events
• Session events: declaration-merge your own durable payloads
• Compaction: provide or consume the engine
• Context: dynamic request context, turn-specific injection, and system-prompt sections
• LLM adapters: ctx.llm.registerAdapter(...)

Two rules govern all of them. Every registration is an effect - it returns a disposer, and disposal must remove the contribution. Waterfall listeners must call next() to delegate; returning without it short-circuits the chain.

What has already been built

The most striking thing about this project is not its architecture. It is how fast people built on it. As of 2026-08-24, 11,258 GitHub repositories carry the dsh-plugin topic, on a harness still at 0.1.1-rc.2. That is a remarkable community response, and it is also a number that needs careful handling. External

Detail matters less than the shape, which is unambiguous: this is a real, active ecosystem with genuine traction. A sample of what has shipped: External

Two entries deserve attention beyond their star counts. weijiafu14/pi2dsh is an ABI compatibility layer that runs another harness's plugins inside DSH - cross-harness plugin portability already exists in the wild. And lujianjun19/dsh-llm-github-copilot is a GitHub Copilot OAuth adapter for the LLM seam, which is a concrete demonstration that the model layer really is replaceable by a third party.

Where the gaps are

If you are deciding what to build, the useful output of that audit is the distribution rather than the total. Categorised across the sample:

Security posture, honestly

The project documents its own limits unusually well, but does so scattered across a dozen package READMEs. Consolidated, the picture is this, and it is the section to read before letting anything autonomous loose inside a corporate network. Source

Two further caveats worth carrying. Installing a plugin from a git source requires granting permission to execute package code at install time, outside any sandbox. And the minimal preset wires its editor to the unsandboxed filesystem service, so its edits are governed by tool logic and account permissions rather than the session's workspace mode - which contradicts the blanket statement in the CLI reference that filesystem mutations are restricted.

None of this is unusual for the category. Every honest harness documents where its boundary leaks. One competitor notes its sandbox "does not run the CLI itself in a sandbox", another that its DNS-rebinding defence "does not eliminate" the risk. The failure mode to avoid is assuming "sandboxed" means "safe." External

How it compares

Positioning against the harnesses most readers already use. Licence and capability facts are from each vendor's own documentation. External

Three things that table understates

It ships wrappers for two competitors, with pinned versions. The subagent provider bundles depend on @anthropic-ai/claude-agent-sdk and @openai/codex, the latter invoked as app-server --stdio. "Keep your existing tooling and point it here" is not a metaphor; it is two npm dependencies. Source

Harness lock-in is being competed away by the vendors themselves. Copilot CLI reads AGENTS.md, CLAUDE.md and GEMINI.md; Codex sets a Claude plugin root variable; dsh ships bridges that execute both Claude Code and Codex hook files. The convergence on AGENTS.md is real and it flows through the closed players too.

"Public repo" is not "open source" is not "open governance." Claude Code's public repository contains no CLI source. Copilot CLI's licence permits running and unmodified redistribution but forbids derivative works. dsh is MIT-licensed and complete, and accepts no external pull requests, with issues disabled. Three different meanings of "open", and the distinction is worth making explicitly whenever someone compares them.

Commonly repeated errors

These circulate widely in secondary explanations of the project. Each correction below is cited to the shipped artifact or the source. No individual is named: the point is the correction, not who made it, and several of these are compressed summaries rather than mistakes.

Documentation drift at this commit

Four inconsistencies between the documentation and the tree, current as of b150a55. A project shipping this much this fast having four stale references is unremarkable; they are listed because each one will waste someone's afternoon, not as criticism. Run

Separately, and with more practical consequence: the latest npm dist-tag for @deepseek-ai/dsh-tools points at the first release ever published, while current versions ship under next. Anyone following the plugin tutorial's install instruction gets a stale package. External

Because the project accepts no external pull requests and has issues disabled, the only route for any of this is GitHub Discussions.

How this was verified

The part of this document that should determine how much you trust the rest.

What was executed Run

• Installed the published @deepseek-ai/dsh CLI from npm into an isolated prefix with a private DSH_HOME, and confirmed dsh --version.
• Dumped the composed configuration for the web and headless profiles, and counted rows, disabled rows and distinct packages.
• Read the shipped agent-preset directory from the installed package, including every preset.yml and the code preset's composition file.
• Searched the shipped preset tree for orchestrator, finding nothing.
• Wrote a three-file external plugin, installed it with dsh plugin add, confirmed it was appended to the profile's bundle list and appeared in the composed tree, and booted the profile.
• Confirmed the repository HEAD, the absence of packages/self-modification/, the length of BENCHMARK.md, and the 18 numbered entries in the vendoring log.
• Queried public registry metadata for the dist-tag discrepancy, cross-checked against two independent sources.
• Called getBuiltinProviders() against @earendil-works/pi-ai@0.82.1, the version the repository pins, and counted the 37 provider IDs listed in section 08.

What was read but not executed Source

• The entire security posture in section 11. Every statement there is sourced from package documentation and sandbox source, and none was tested by attempting to escape a sandbox.
• The trajectory-provenance correction in section 13.
• Composition layer order and the no-deep-merge behaviour of patches.
• The extension-seam inventory in section 09.
• The LLM adapter contract, the dormant multi-provider mount in the base composition, and the three-protocol limit on hand-declared routes in section 08. No model was invoked through any route.

Known limitations

No model was invoked at any point. Everything here is keyless, which means nothing in this guide describes how the agent behaves in a real task, only how the system is assembled. Tool-calling behaviour, loop dynamics, compaction quality and output quality are all outside what was tested.