What is DeepSeek Harness (dsh)? The Open-Source Claude Code Rival, Explained

DeepSeek shipped something unusual on August 13, 2026: not a model, but the machine that runs one. DeepSeek Harness (dsh) is the company’s official open-source agent harness—the software layer that turns a large language model into a coding agent with a session loop, tool execution, permission checks, and a local web UI. It launched alongside DeepSeek V4-Pro on the API, and VentureBeat framed it as an open-source rival to Claude Code.

Try Apidog today

The developer community reacted quickly. As of August 20, the deepseek-harness repository had roughly 169,000 stars and 18,100 forks—one week after release. That level of interest suggests developers want an agent harness they can inspect, modify, and connect to different models.

What DeepSeek Harness actually is

A harness is everything around the model. The model predicts tokens; the harness decides:

• What context the model receives
• Which tools it can call
• How file edits and shell commands are approved
• How multi-step sessions are stored and resumed

Claude Code, Codex CLI, and Gemini CLI are all harnesses wrapped around their vendors’ models. For background on two of those tools, see Claude Code vs Codex CLI.

DeepSeek Harness has three defining properties:

• Official: It is a first-party project from DeepSeek AI, not a community wrapper around the DeepSeek API.
• Open source: It is MIT licensed, with third-party dependencies documented in the repository’s THIRD_PARTY_NOTICES file. You can inspect the agent loop that operates on your codebase.
• Developer preview: The README warns: “THERE WILL BE COMPATIBILITY-BREAKING CHANGES.” Treat that as an operational constraint.

The launch timing also matters. dsh arrived alongside DeepSeek V4-Pro on the API, so the harness and its flagship default model were introduced as a pair. For the model side, see the guide to the DeepSeek V4-Pro API, including endpoints, model IDs, and request examples.

The architecture: everything is a plugin

Most coding-agent harnesses are monolithic. The agent loop, model client, tool definitions, and session store ship as one application. You may be able to configure or extend them, but you cannot replace the core components.

dsh takes the opposite approach. Its design principle is “everything is a plugin,” built on a framework called Cordis. Cordis’s design is described in the paper “A Programming Paradigm for Spatiotemporal Composability.”

In practical terms, components that are usually tightly coupled become replaceable modules:

• Model adapter: The plugin that communicates with the LLM API.
• Tool registry: The tools available to the agent, such as file editing, shell execution, and search.
• Session log: The mechanism for recording and replaying sessions.
• Agent loop: The decide-act-observe cycle itself.

This matters when you want to experiment with context management, permission policies, or repository-specific tool sets. With a monolithic agent, you wait for the vendor to implement your idea. With dsh, you can build a plugin.

The trade-off is compatibility risk. A system where every component is replaceable has more ways to break, especially when the project explicitly warns about compatibility-breaking changes. The current trade-off is flexibility now in exchange for stability later.

Quick start: run a local agent

Start the local web UI with one command:

npx @deepseek-ai/dsh web

This launches the UI at http://127.0.0.1:3080 and opens it in your browser. To prevent the browser from opening automatically, use:

npx @deepseek-ai/dsh web --no-open

There is no global install, and account creation is not required as an installation step.

Build from source

To run the project from source:

git clone https://github.com/deepseek-ai/deepseek-harness
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

Complete the first-run setup

The first-run flow has three steps:

1. Configure a DeepSeek API key. Add it in Settings. Credentials are stored in $DSH_HOME/.credentials.yaml, separate from the main settings file, which stores references to them.
2. Choose a workspace. Select the project directory where you started dsh. The session composer remains unavailable until a workspace is selected. This gives the agent an explicit scope for the files it can inspect and modify.
3. Run a task and approve operations. The web UI asks for approval before operations covered by the active permission policy. File writes and shell commands appear as prompts instead of running silently.

Use profiles and headless mode

The web UI is one entry point into the underlying profile system:

dsh web

This is shorthand for:

dsh --profile web

Profiles are stored under:

$DSH_HOME/profiles/<name>

For scripts and CI, use headless mode:

dsh --profile headless "job"

This runs one fresh session, prints the result, and exits.

You can also manage profile plugins through pnpm:

dsh plugin

To inspect the composed configuration without starting the harness:

dsh --dump-config
dsh --dump-default-config

See the CLI README for the complete command reference.

What models can it run?

DeepSeek models are the default, with V4-Pro as the headline pairing. DeepSeek also made its off-peak discount permanent, which affects the cost of running an agent that uses tokens continuously. See the post on the DeepSeek V4-Pro price cut, and consult the official DeepSeek API documentation.

The model adapter is a plugin, so dsh supports more than DeepSeek’s models through two paths:

• Catalog providers: Built-in provider entries for Anthropic, OpenAI, Bedrock, Vertex, and Azure, with provider-specific credential handling.
• Custom providers: Any OpenAI-compatible endpoint can be registered in $DSH_HOME/settings.yaml with a base URL, an environment variable for the API key, and a model list. This includes local runtimes and API gateways.

Selecting a model makes it the default for new sessions. Each session records the model it started with, so changing models does not obscure your project history.

The providers guide documents the configuration format. For the complete YAML setup for custom endpoints, see how to run any model in DeepSeek Harness.

The plugin ecosystem, one week in

Plugins are discoverable through the dsh-plugin GitHub topic. The community also coordinates through GitHub Discussions and a Discord server.

One week after launch, the ecosystem already includes several categories:

• Desktop wrappers: Projects such as deepseek-harness-desktop (Tauri) and dsh_desktop (Windows) package the web UI as native applications. These are community projects, not official DeepSeek releases. Review them carefully because they may access your API keys.
• Capability plugins: Community repositories such as dsh-context and dsh-vision-router extend what sessions can see and how requests are routed.
• MCP support: The core does not include native Model Context Protocol support as of this writing. The community plugin dsh-mcp-manager adds an MCP Settings page supporting remote HTTP or local stdio servers, OAuth or static-token authentication, tools named with the mcp__<name>__* pattern, and per-project server configuration inside the workspace’s .dsh directory.

The MCP distinction is important. Saying that dsh “supports MCP” is only accurate through the community plugin. The core may support MCP directly in the future, but it does not as of this writing.

Where your API workflow fits

An agent harness ultimately executes API calls:

1. The model API that powers the agent
2. The APIs inside the project you provide as its workspace

When dsh writes code against your backend, it relies on the API behavior it can infer from the codebase. If the implementation does not match the specification, the agent may generate code against the wrong contract and fail only at runtime.

A practical workflow is to verify the API surface before giving the repository to the agent:

1. Design or import the OpenAPI specification.
2. Test the real endpoints against that specification.
3. Create mock servers with stable, spec-accurate responses.
4. Let the agent develop against those mocks while the backend changes.

Apidog covers this API design, testing, and mocking workflow. Working against a verified mock reduces the chance of hallucinated integrations caused by stale code or incomplete endpoint documentation.

There is also a direct integration path. The Apidog MCP Server exposes API specifications to AI tools over MCP. In dsh, connect it through the community dsh-mcp-manager plugin:

1. Install dsh-mcp-manager.
2. Register the Apidog MCP Server.
3. Start a session in the relevant workspace.
4. Let the agent query the API specification instead of inferring it from source code.

The complete workflow, including CLI-based test runs that the agent can trigger, is covered in using Apidog CLI in DeepSeek Harness.

If you want to prepare the API side first, Download Apidog and import your specification before experimenting with dsh.

Should you try it now or wait?

The right answer depends on how you plan to use it.

Try it now if

• You want to understand agent internals. dsh is highly inspectable, and reading a real agent loop is a practical way to learn how coding agents work.
• You need model flexibility. The pluggable model adapter supports different hosted and self-hosted providers.
• You build developer tooling. The plugin ecosystem is new, so early contributors may have an opportunity to shape it.
• You already use DeepSeek’s API. dsh provides a first-party agent experience for V4-Pro.

Wait if

• You need a stable daily driver. The compatibility-breaking-change warning means configurations, plugins, and workflows may break between versions.
• Your organization requires supported tooling. A developer preview with community plugins has a different risk profile from a generally available product with a support contract.
• You expect mature UX. Claude Code has had a longer head start on ergonomics, and a one-week-old preview will not match it in every area.

For most developers, the pragmatic approach is to use both: keep your current agent for production work, run dsh in a side project, and evaluate it before relying on it for critical repositories. For a direct comparison with Claude Code, see DeepSeek Harness vs Claude Code.

FAQ

Is DeepSeek Harness free?

The harness is free and open source under the MIT license. The model may cost money: API usage on DeepSeek’s platform, or through whichever provider you configure, is billed by that provider.

Because the adapter layer is pluggable, you can also connect dsh to a locally hosted model and avoid per-token API charges. See run any model in DeepSeek Harness for the setup.

Does dsh only work with DeepSeek models?

No. DeepSeek models are the default, but the model adapter is a plugin. Catalog providers include Anthropic, OpenAI, Bedrock, Vertex, and Azure. You can also add any OpenAI-compatible endpoint through $DSH_HOME/settings.yaml.

Is DeepSeek Harness safe to run on my codebase?

Safety depends on the permission model, the installed plugins, and your review process.

The web UI requires a workspace before a session can run and prompts before operations that require approval under the active policy. However, dsh is still a developer preview, and community plugins—including desktop wrappers—are third-party code that may handle your API keys.

Review every plugin before installing it, and avoid using the preview on repositories where an accidental edit could cause serious damage.

How is a “harness” different from a model?

The model is the reasoning engine; the harness is the system that lets it act.

Session management, tool calls, file access, permission prompts, and context assembly all belong to the harness. Two agents using the same model can behave very differently because their harnesses implement different tools, policies, and session loops. That is why the harness layer has become a major area of coding-agent development.