DeepSeek Harness (dsh): What It Is, How to Install It, and What Is Actually Inside

DeepSeek released dsh (DeepSeek Harness), an open-source agent harness built on the Cordis plugin framework in which the agent loop, model adapters, tool registry and session log are all swappable plugins rather than a fixed core. The web profile on version 0.2.1-rc.2 composes 193 separate @deepseek-ai/dsh-* plugin packages, and the tool runs via a single npx command, serving a Web UI on localhost with headless, SDK and ACP profiles also available.

DeepSeek Harness, or dsh , is DeepSeek's open-source agent harness : the software that wraps a language model and turns it into an agent that can read files, run commands, search the web and work on a task over many steps. Its design idea is unusual - everything is a plugin , including the agent loop itself. I installed it on Windows, ran its command-line tool, and dumped the configuration of its web profile to see what it is really made of. This guide covers what an agent harness is, how to install dsh, what is inside it, which models it can use, how its permission modes work, and the safety warnings DeepSeek itself attaches to it. A language model on its own only produces text. An agent harness is everything around the model that lets it act: Claude Code, OpenAI's Codex CLI, OpenCode and Hermes are all harnesses. The model is the engine; the harness is the rest of the car. Two harnesses running the same model can behave very differently, which is why "harness engineering" has become a topic of its own. Most harnesses have a fixed core and an extension system bolted on. dsh is built on Cordis https://github.com/cordiverse/cordis , a plugin framework in which plugins contribute services, typed events and reversible effects to a shared context. DeepSeek's architecture document says there is "no privileged core to patch": the model adapter, the tool registry, the session log and the agent loop are all plugins, so each one can be swapped through configuration. In practice that means: web , headless , sdk , sdk-minimal and acp , and the CLI help also shows a tui example. cordis.patch.yml overrides or adds plugin rows without forking anything. You need Node.js. The quickest start is one command: npx @deepseek-ai/dsh web That boots the web profile and serves the Web UI at http://127.0.0.1:3080 add --no-open to stop it opening a browser . Then go to Settings → Models , add an API key, choose a workspace folder, and start a session. The agent cannot do anything until a workspace is selected. Other ways to run it, from the CLI's own help: dsh headless "run the tests" answer one task, print the result, exit dsh --profile sdk JSON-RPC server for the Python SDK dsh --profile acp automation clients over ACP dsh --profile web --dump-config print the composed plugin tree and exit dsh plugin --profile tui add install a plugin into a profile On my machine, npx -y @deepseek-ai/dsh --version reported 0.2.1-rc.2 and ran fine on Node.js 22.18.0. There is also an official Electron desktop app in the repository, and a crop of unofficial "DeepSeek Harness desktop" wrappers on GitHub - check that you are installing from deepseek-ai/deepseek-harness or the @deepseek-ai/dsh npm package, because several projects reuse the name. What is inside: 193 plugins Running dsh --profile web --dump-default-config prints the full plugin tree without booting anything. On version 0.2.1-rc.2 the web profile is composed of 193 separate @deepseek-ai/dsh- plugin packages . Grouped by job: - Agent core: dsh-agent-loop , dsh-system-prompt , dsh-agent-instructions , dsh-agent-preset , dsh-plan-mode , dsh-persona , dsh-goal . - Tools: filesystem and file search, Bash and PowerShell each with a persistent variant , web fetch and search, to-do lists, background jobs, scheduling, ask-the-user, skills and a workflow tool. - Subagents: spawn and fork in-process subagents, and control them. - Context management: basic compaction, a tool-result pruner, image offload and a token meter - the parts that keep long sessions from overflowing. - Safety: a local sandbox, a sandbox policy, separate Bash and PowerShell sandboxes, a filesystem sandbox, user approval and permission presets. - Models: a DeepSeek API-key adapter, a DeepSeek account adapter, a retry layer and an adapter called dsh-llm-pi-ai for other providers. - Sessions and storage: JSONL persistence, SQLite queries, checkpoints, export, titles and telemetry OpenTelemetry . - MCP: a dsh-mcp-resources plugin is part of the profile. - The Web UI itself: chat, file browser, terminal, document preview, plan view, settings pages - each one a plugin too. That granularity is the point. If you want a different compaction strategy or a remote sandbox, you replace one row in the patch file rather than forking the project. Which models can it use? DeepSeek's models are built in: Settings → Models has a DeepSeek card with a single API-key field, and DeepSeek's models offer "off", "low", "high" and "max" reasoning levels. It is not DeepSeek-only, though. According to the provider guide you can add: - Third-party providers from a catalogue, including ids such as anthropic , openai , moonshotai Kimi and zai GLM . - Custom endpoints - a company gateway or a self-hosted server - speaking one of three protocols: OpenAI Chat Completions, OpenAI Responses or Anthropic Messages. Keys are stored in $DSH HOME/.credentials.yaml , and provider settings live in the profile's cordis.patch.yml . Permission modes The dumped configuration shows three permission presets: | Preset | Sandbox | Approval | |---|---|---| | read-only | read-only | ask | | workspace-write default | workspace-write | ask | | danger-full-access | full access | never | The default comes from the DSH PERMISSION MODE environment variable and falls back to workspace-write , which means the agent can change files in your chosen workspace but asks before operations that need approval. Only danger-full-access turns approvals off - and the name is an honest warning. The safety notice: read it before you run it DeepSeek describes dsh as experimental developer-preview software that has not had a security audit, and warns that there will be compatibility-breaking changes. Its safety notice is blunt: the harness can run model-generated commands, modify or delete files it can reach, and access the network and any credentials made available to it, and third-party plugins may be untrusted. Sandboxing and approvals reduce the risk but "cannot protect resources that the project is allowed to access". The recommendations are the same ones I would give for any agent harness: 1. Run it in a disposable virtual machine or container for anything important. 2. Give it the narrowest workspace and the fewest credentials possible - never your production keys. 3. Keep backups of anything it can touch. 4. Review plugins and proposed commands before approving them. DeepSeek Harness vs Claude Code and OpenCode People search for these comparisons, so here is what can be said honestly without running a benchmark: - Claude Code is Anthropic's harness, tuned for Claude models, mature and terminal-first, with hooks, skills and MCP support. dsh is younger, open source under MIT, web-first, and designed around replacing any part of itself. - OpenCode is an open-source, provider-agnostic terminal harness. dsh is also provider-agnostic, but its plugin model goes further: even the loop and the session log are swappable. - Maturity: dsh is a developer preview 0.2.x release candidates at the time of writing . For day-to-day client work I would still reach for a mature harness; dsh is the one to study if you want to understand, or build, an agent harness. I have not measured task success between them, so treat anyone's "X beats Y" chart with care unless they publish the tasks, the model and the settings. Who should try it? - Developers building their own agents - the plugin tree is a working reference architecture. - Teams that need a self-hosted agent pointed at their own model gateway. - DeepSeek API users who want an official interface beyond the chat app. If you only want to run DeepSeek's models locally without an agent, my guide to running DeepSeek R1 locally on Mac, Windows and Linux https://knowledgemarkg.com/blog/how-to-run-deepseek-r1-locally-for-free-on-macwindowslinux is the simpler place to start, and DeepSeek vs ChatGPT https://knowledgemarkg.com/blog/deepseek-ai-vs-chatgpt-which-ai-best-fits-your-needs-2025 covers the models themselves. For the other big agent story of 2026 - agents driving disassemblers - see AI reverse engineering with Ghidra and IDA https://knowledgemarkg.com/blog/ai-reverse-engineering-ghidra-ida-mcp . FAQ What is DeepSeek Harness? DeepSeek Harness dsh is DeepSeek's open-source agent harness: the software around a language model that lets it read and edit files, run commands, search and work on multi-step tasks. It is built on the Cordis plugin framework, so every part - including the agent loop - is a plugin. How do I install DeepSeek Harness? With Node.js installed, run npx @deepseek-ai/dsh web. It serves the Web UI at http://127.0.0.1:3080. Add an API key in Settings, choose a workspace folder, and start a session. What is an agent harness? An agent harness is everything around a model that turns it into an agent: the loop that runs tools and feeds results back, the tools themselves, context management, sandboxing and approvals, and the user interface. Claude Code, Codex CLI, OpenCode and DeepSeek Harness are all harnesses. Does DeepSeek Harness only work with DeepSeek models? No. DeepSeek models are built in, but you can add third-party providers from its catalogue, including Anthropic, OpenAI, Kimi and GLM, or any custom endpoint that speaks the OpenAI Chat Completions, OpenAI Responses or Anthropic Messages protocol. Is DeepSeek Harness safe to use? Its own safety notice calls it experimental, unaudited developer-preview software that can run commands and modify files it can reach. The default mode asks before risky operations, but you should run it in a VM or container, give it minimal credentials, and keep backups. Is DeepSeek Harness free and open source? Yes, the harness is open source under the MIT licence. You pay only for the model API you connect, such as DeepSeek's API, unless you point it at a self-hosted model. What are the DeepSeek Harness permission modes? There are three presets: read-only and workspace-write, which both ask for approval before sensitive operations, and danger-full-access, which turns approvals off. The default is workspace-write, set by the DSH PERMISSION MODE environment variable. --- Originally published on knowledgemarkg.com https://knowledgemarkg.com/blog/deepseek-harness-dsh-guide .