What is DeepSeek Harness? The dsh Agent Runtime Explained

TL;DR

DeepSeek Harness — short name dsh — is DeepSeek's open-source agent framework, announced as a developer preview. It's the layer that turns a model into an agent that can read files, run commands, search the web and keep working across long tasks. The official description is one line:

Agent = Model + Harness.

The model is the brain. The harness is the body: tools, permissions, session memory, and the loop that keeps the agent working. And the harness's defining idea is everything is a plugin — the model adapter, the tools, the UI, even the main agent loop itself are all replaceable components.

You can try it in two commands (requires Node.js):

npm install -g @deepseek-ai/dsh
dsh --profile web

Then paste your DeepSeek API key on the web page — or skip that if your machine's environment already has the key. Problems? See github.com/deepseek-ai/deepseek-harness.

Not "DeepSeek's Claude Code"

The closest mainstream comparison is Claude Code or OpenAI Codex, but dsh is a different shape of product. Codex ships a ready-made agent; DeepSeek Harness ships an agent runtime you assemble — and it can even call your local Codex or Claude Code as sub-agents instead of replacing them.

The difference shows in three places:

1. Everything is a plugin. Tools, model providers, approval policies, session logs, sandboxes, the agent loop, and the Web UI are all plugins. Removing a plugin removes everything it registered — nothing leaks.
2. Replayable sessions. Every session is an append-only event log: user messages, model output, tool calls, injected context, sub-agent activity. You can resume, fork, search and replay from the same event stream.
3. You build your own agent. With the creation mode you can tell the agent to design a new preset ("a read-only code reviewer"), and it drafts the config, mounts it and saves it.

Profiles and patches: how a dsh process is assembled

A running dsh is a plugin tree — a Cordis plugin system assembled from config layers that stack in a fixed order:

• Bundles — official sets of plugins shipped together.
• Profiles — named assemblies on your machine.
• Patches — your own override layer, which can target any single plugin entry and replace it.

Upper layers override lower ones. This is why "installing" a plugin usually means adding a line to a profile or patch file — each plugin's repository documents its own install. The layered config is essentially an ordered stack of cordis.patch.yml files.

The built-in patch layer is best understood as a dressing system for the agent — it decides what capabilities your agent wears. Through patches you can:

• mount your local Codex and Claude Code as sub-agents the harness can delegate to;
• install plugins that add tools, integrate external services, adjust run permissions, or turn on full-text search;
• replace UI modules — the interface itself is just more plugins;
• define rules as JavaScript expressions, so any of these capabilities can apply conditionally ("only in this repo", "only for these file types").

Agent presets and the four modes

The mode selector at the top of the UI picks an Agent Preset — a complete definition of what the agent in this session is: its tools, its system prompt, its skills and sub-agent setup.

• Standard — the default. The complete programming assistant: it understands the task, edits code, runs commands and checks the results.
• PTC — programmatic tool calling. Everything Standard has, plus the model can write a short TypeScript program that calls many tools in one shot — loops, conditions, concurrency included. Only the program's final output enters the context, so multi-step mechanical work gets faster and cheaper.
• Minimal — only a persistent terminal and basic text-replacement tools. Built for simple edits, benchmarks and teaching.
• Creation — everything Standard has, plus live runtime inspection, trying plugins in memory, and using presets for creative tasks. It can draft, mount and save a new preset for you. Treat it like shell access: it executes model-written code.

A session locks its preset once it has content — switching mid-session would make the old tool calls in history uninterpretable.

How the agent works

Work is organized in steps (one model request plus the tool calls it makes) and turns (the whole run from your task to completion). Every key position — before a step, around a tool execution, before a model request — is an interception point where a plugin can approve, rewrite, log or block.

The session log records everything the model sees, append-only: system prompts, chains of thought, tool calls and results, context injections, sub-agent traffic. It powers session resume, auto-titles, context compression, and cross-session search.

The agent can also plan before acting (you approve the plan first), track a task list, and pause to ask you questions when it needs a decision.

Safety model

• Sandboxes — three tiers: read-only, workspace-write, and danger-full-access, using OS-native isolation (bwrap/Landlock on Linux, Seatbelt on macOS, ACL restricted tokens on Windows). The backend honestly reports whether it delivered the promised isolation.
• Approvals — risky operations ask first; preset policy levels tune strictness.
• Guards — plugins that interrupt timed-out tools and detect repetitive loops.
• Secrets stay out of logs — credentials travel through a separate channel; logs only carry references.

The five ways to use it

1. Web UI — local browser interface for chat, approvals, modes and settings.
2. Headless CLI — run a single task and exit; CI/CD friendly.
3. Python SDK — bundled runtime, high-level turns API and low-level JSON-RPC.
4. TypeScript SDK — JSON-RPC protocol, server and client for deep integration.
5. ACP server — the Agent Client Protocol, for editors and tool vendors.

It also speaks MCP (any MCP server plugs into the same pipeline as built-in tools), and a hooks bridge keeps Claude Code / Codex hook scripts working.

Where plugins come in

Because everything is a plugin, the community has already built hundreds: UI skins, task-status bars, memory systems, desktop pets, mini-games, deep-research orchestrators and much more. Browse the directory to see what exists, or read the plugin development guide to build your own.

Keep exploring

• Quickstart: run dsh in 5 minutes
• Profiles, patches & presets
• Sandboxes, approvals & secrets
• Installing plugins you can trust