What is DeepSeek Harness? A complete guide
Published 16 August 2026
DeepSeek Harness — package name dsh — is an MIT-licensed open-source agent harness published by DeepSeek AI. This is the plain-language version: what it is, how to run it, how it is put together, and whether you should care.
What an agent harness actually is
A model generates text and tool calls. That is all it does. Everything else that makes an agent useful is the harness: assembling the prompt, executing the tools the model asked for, enforcing what it is allowed to do, recording what happened, managing the loop that decides whether to call the model again, and delegating work to child agents.
This distinction is worth internalising before anything else, because most of what an agent does well or badly is harness behaviour rather than model behaviour. Two teams running the identical model can get very different results and very different bills, and the difference lives here.
What DeepSeek Harness does
It runs coding and automation agents. In practice the agent reads and edits files, runs shell commands, searches the codebase, delegates to subagents, plans work, and asks for confirmation according to whatever permission policy is active. There is a browser UI, a headless mode for one-shot runs, and an automation server that speaks JSON-RPC over standard input and output for scripting.
The one design idea: everything is a plugin
The harness runs on Cordis, a plugin runtime where plugins contribute services, typed events, and reversible effects into a shared context. There is no privileged core. The model adapter is a plugin. The tool registry is a plugin. The session log is a plugin. The agent loop itself is a plugin.
Most extensible systems give you a fixed core plus hooks — you can observe and decorate, but not replace, and replacing means forking. A plugin runtime inverts that: the pieces you would most want to replace are the units of composition.
Getting it running
The fast path
npx @deepseek-ai/dsh webThat starts a local web UI at http://127.0.0.1:3080.
From source
git clone https://github.com/deepseek-ai/deepseek-harness
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh webRequirements: Node 22.19 or newer (CI covers 22.19, 24, and 26), Git 2.26 or newer, and pnpm pinned through Corepack. A DeepSeek API key is optional at install time but needed to do anything useful; it can come from the environment or a gitignored .env at the repository root.
The two steps people miss
- Settings → Models. Enter your API key. The route enables immediately, no restart needed.
- Choose workspace. Add and activate your project directory. The session composer stays unavailable until a workspace is active, which is the usual reason a fresh install appears broken.
Headless
pnpm dsh --profile headless "summarize this workspace"This is the mode that matters for automation, because a harness that only works interactively cannot be put in CI, and a harness that cannot be put in CI cannot be measured on a schedule.
The concepts you need to read the docs
| Term | Meaning |
|---|---|
| Step | One model request plus the tool calls it produces |
| Turn | One drain of input, ending when the model stops or policy intervenes |
| Round | An outer policy iteration above turns, such as a fresh attempt at a goal |
| Session | An append-only log of typed events — the single source of truth for the run |
| Capability seam | A service interface with several interchangeable implementations |
| Profile | A named composition: an ordered list of plugin bundles plus user patches |
| Scope | The unit of per-agent registration for tools, prompts, and restrictions |
Configuration resolves in four layers, later winning: profile bundles, then profile patches, then home-level patches, then command-line overlays. Knowing that order turns "why is it using that model" from an investigation into a lookup.
How to configure it
Composition runs through profiles. Three templates ship: a base runtime, a browser UI variant, and a headless one-shot runner. A profile stores an ordered list of bundles — packages that distribute configuration rows and code — plus your own patches on top.
The registry keys you will see referenced across the documentation are the subsystems: sessions, system prompt, tools, agents, the agent loop, and the model service. Each is a plugin contributing into the shared context under one of those names.
What makes it worth looking at
- Model choice is swappable. The model service is an interface with several backends behind it, including one that replays a recorded session without paying for inference again. The agent loop consumes a provider-neutral stream and never learns which backend is live.
- The record is complete by construction. The governing principle is that model-visible means logged: anything the model could see appears in the session log, because the log has to be able to reconstitute the run. Token usage travels attached to the output that incurred it.
- Enforcement points are explicit. One before the model request goes out, whose decision is documented as authoritative, and one before any tool body executes. Permission guards can deny or abstain but never grant, and an unanswerable approval prompt denies.
- It runs headless. Which means it can be scripted, scheduled, and measured.
When to use it, and when not to
Use it to evaluate, to prototype, and as a concrete benchmark for whatever agent stack you already run. The five questions worth carrying to your own system are: is model choice swappable, is there a complete session record with usage attached, are there enforcement points before the model call and before tool execution, does it run headless, and is the configuration layering documented.
Do not standardise on it this quarter. The project describes itself as a developer preview and states plainly that there will be compatibility-breaking changes. Pin whatever version you build against, and do not schedule production migration work off a preview API.
What it costs to run
The harness is MIT-licensed and free. Inference is not. You supply a DeepSeek API key, or point the model seam at another provider. The practical implication is that your bill is a function of steps per turn, tools in the catalogue, delegation depth, and how many rounds an open-ended objective is allowed to run — all harness-level decisions, none of them the token price you negotiated.
Related
- DeepSeek Harness: install, profiles, and first run — the longer setup walkthrough.
- What "everything is a plugin" actually buys you — the architecture in depth.
- The DeepSeek Harness session log as a cost record — reading the event log.
- Where to put spend guardrails in DeepSeek Harness — the enforcement points.
Want this applied to your own LLM spend? FinOps LLM runs a free audit of your AI costs and shows where the savings are. Book free audit →
FAQ
What is DeepSeek Harness?
DeepSeek Harness, package name dsh, is an MIT-licensed open-source agent harness published by DeepSeek AI. It runs coding and automation agents that read and edit files, run commands, delegate to subagents, and plan work. Its design premise is that everything is a plugin, built on the Cordis plugin runtime.
How do you install DeepSeek Harness?
The quickest path is npx @deepseek-ai/dsh web, which starts a local web UI on port 3080. From source, clone the repository, run pnpm install, pnpm run build, then pnpm dsh web. It needs Node 22.19 or newer and Git 2.26 or newer, with pnpm pinned through Corepack.
Is DeepSeek Harness free?
The harness itself is MIT-licensed and free to run. Model inference is not: you supply a DeepSeek API key, or point it at a different provider through the model seam. The cost of running agents is inference cost, not licence cost.
Is DeepSeek Harness production ready?
No. The project describes itself as a developer preview and states plainly that there will be compatibility-breaking changes. It is suitable for evaluation and prototyping, and as a benchmark against whatever agent stack you already run, but not for standardising on this quarter.
What is the difference between an agent harness and a model?
The model generates text and tool calls. The harness is everything around it: assembling the prompt, executing tools, enforcing permissions, recording the session, managing turns and steps, and delegating to subagents. Most of what an agent does well or badly is harness behaviour, not model behaviour.