What is DeepSeek Harness? A Practical Introduction

DeepSeek open-sourced DeepSeek Harness — everyone calls it DSH — in August 2026, and it pulled more than 150,000 GitHub stars in its first days. That is not normal for a developer tool. This introduction explains what DSH actually is, what its architecture does under the hood (verified against the official docs and code-level analysis), and why a small YAML file called a preset became the unit of sharing for the whole ecosystem.

The one-sentence version

DSH is an open-source (MIT) agent runtime, written in TypeScript, in which every capability is a plugin — the model adapter, the tools, the sandbox, the session log, the scheduling loop, even the UI — so you assemble your agent by composing plugins instead of forking a product.

The project’s own framing is the equation Agent = Model + Harness: the model is the reasoner, the harness is everything that lets it understand its environment, use tools, and keep working in real-world conditions.

It runs locally:

npx @deepseek-ai/dsh web   # opens the web UI at http://127.0.0.1:3080

Headless, CLI, and Python SDK interfaces ship alongside; the dsh process treats the directory you launch it from as the default workspace.

“Everything is a plugin” — concretely

Most agent CLIs have a hard core with extension points bolted on. DSH inverts that. The Cordis kernel only manages plugin mounting, unmounting, and dependencies — and configuration composes onto an empty root: profile → bundles (npm packages carrying config patches) → your home patch → --patch overlays, applied in order. There is no privileged core to patch. The model adapter, the tool registry, session persistence, the agent loop, even the web UI mount as plugins.

Two things make this more than a slogan:

• Uninstalling is a first-class operation. The Cordis paper (A Programming Paradigm for Spatiotemporal Composability, preprint) formalizes “temporal composability” — every side effect a plugin registers is tracked with an inverse, so removing it genuinely reverts the system — and “spatial composability”, reactive inter-plugin dependency management. Unlike a VS Code extension living in a shared host, components come and go at runtime without restarts.
• DeepSeek owns the whole stack. Code analysis of the release found dsh vendors its own patched Cordis fork under the @deepseek-ai scope — roughly 453,000 lines of TypeScript across ~219 workspace packages, all of it mounted through the same plugin machinery. The framework layer isn’t a dependency; it’s theirs.

The closest historical analogy isn’t an IDE, it’s an operating system for agents: a kernel plus userland, where even what looks load-bearing can be swapped.

The four runtime modes

DSH ships four built-in configurations that demonstrate the range:

1. Standard — the everyday full agent: file editing, shell, file and web search, skills, planning, goals, subagents, and workflows.
2. Code — Standard plus the Code Mode SDK: the model writes one TypeScript program that orchestrates multi-step tool calls, instead of one tool call at a time.
3. Minimal — deliberately stripped to two tools (a persistent bash and str_replace_editor) for benchmarking models in a controlled environment.
4. Creator — built for authoring new presets: runtime inspection, in-memory plugin experiments, and preset-authoring guidance, so the agent helps you build agents.

Models and providers

The default model catalog wires up DeepSeek V4-Flash and V4-Pro (launched the same week, with thinking mode on by default in the API), configured with a 1M-token context window, up to 256K output tokens, and reasoning-effort levels of off / high / max.

Setup is deliberately boring: npx @deepseek-ai/dsh web, then in the UI Settings → Models → add a DeepSeek API key — no restart needed. Because model adapters are plugins, the docs’ providers page covers additional providers and custom OpenAI-compatible endpoints. There are also hook bridges for Claude Code and Codex interoperability, and MCP support — client-side (dsh can consume MCP servers; it doesn’t expose itself as one).

Sessions: the part competitors can’t easily copy

Everything the model sees is recorded in an append-only session log: system prompts, reasoning, tool calls and results, subagent scheduling, every context injection. The invariant is stated as “model-visible means logged” — if the model saw it, it must be reconstructable from the log. At the code level the agent loop enforces this hard: outgoing messages must byte-match the session’s derived message list at every LLM dispatch.

Resume, fork, search, and replay all operate on that same event stream, and the Trajectory view in the UI inspects it by source. One artifact is the source of truth for replay, debugging, and the UI itself. For context on why this matters: Anthropic shows only summarized thinking traces, and OpenAI hides raw chains of thought for its closed models. Full-fidelity traces you control are a genuine differentiator.

Sandboxing and permissions

Tools resolve a per-call sandbox policy with a clear ladder: read-only, workspace-write, and danger-full-access. Enforcement rides the OS: bubblewrap or Landlock on Linux, seatbelt on macOS, a write-restricted token on Windows — and the UI asks for approval per the active permission policy. (Honest caveat from the code analysis: the Windows sandbox restricts writes only; reads, network, and process visibility stay open.)

Where presets come in

A preset is a named combination of plugins, persona, and prompt segments — the configuration layer that turns the general runtime into your specific agent. The built-in modes above are themselves presets, and you create your own by copying one and editing two small YAML files inside .agent-presets/.

That is the whole trick. Because a preset is just files:

• you can read exactly what an agent will and won’t do before running it,
• you can share one with a curl command, and
• you can fork one without touching anyone’s code.

The built-in modes above are the honest starting point: duplicate one, keep its groups intact, and trim rows until the toolset says exactly what your agent should be. DSH is in developer preview and will ship compatibility-breaking changes between releases, so pin what you run and re-verify on every upgrade.

The honest part: weaknesses today

A runtime this young has real rough edges, and pretending otherwise helps no one:

• Version drift — the GitHub repo and npm package were briefly out of sync (rc.5 vs rc.6), and the license flipped BSD-3 → MIT mid-RC. Expect churn.
• BENCHMARK.md is a three-line stub — no methodology or eval harness shipped.
• The Python SDK is 0.0.0.dev0 — currently a stdio wrapper over the Node binary.
• No eval tooling, artifacts surface, session sharing, or metering yet.
• The logging invariant costs throughput — full message history is serialized on every dispatch.
• The git history is one squashed commit — though it’s partially offset by 1,372 bilingual, agent-authored decision records in .agents/notes/.

Yet the reception cuts through: Armin Ronacher — co-founder of Earendil, which steers the Pi agent — wrote that DSH isn’t perfect, but it’s “the first time I have been looking at something new in the space and felt quite inspired to revisit some of our choices.” When the person building a competing harness says that, the ideas are worth studying.

Should you care yet?

• Model freedom with receipts — adapters are plugins; the session log is yours.
• The engineering is serious — keyless CI that replays committed session logs as both input and expected output is a genuinely clever testing strategy.
• The ecosystem moment — the conventions forming now (plugin ids, preset formats, the dsh-plugin GitHub topic, the Discord) will define the tooling for years. Early participants shape them.

Next steps

• Create your first preset — a hands-on walkthrough
• DeepSeek Harness vs. Claude Code — which harness should you run