DeepSeek Harness Explained: Setup, Plugins, Costs, and What Actually Matters

Key Takeaways

• DeepSeek Harness is an official open-source agent application and runtime, also called dsh. It connects language models with tools, files, sessions, and executable workflows.
• Its defining feature is replaceable infrastructure. Cordis powers a plugin architecture that includes the model adapter, tool registry, session log, and agent loop.
• There are desktop and local Web UI entry points. The documented npm command is npx @deepseek-ai/dsh web.
• Open-source software does not mean free model usage. API tokens, external services, and infrastructure can contribute to operating costs.
• It remains preview software. DeepSeek explicitly warns about breaking changes and states that the project has not undergone a security audit.

Updated October 26, 2026.

What Is DeepSeek Harness?

DeepSeek Harness is DeepSeek’s environment for giving an AI model access to practical work: inspecting repositories, modifying files, executing commands, processing documents, and using additional capabilities supplied by plugins.

The official source code lives in deepseek-ai/deepseek-harness, under the MIT license. Its command-line name is dsh.

Understanding the product starts with separating three layers:

In DeepSeek Harness, Cordis supplies that third layer. The architecture documentation explains that even the agent loop is a replaceable plugin. This makes DSH relevant both to people using an agent and to developers building their own agent environment.

For a coding task, the practical difference is substantial: a useful answer must eventually become a working change. That requires access to the correct files, an executable test environment, interpretable error messages, and a clear stopping condition.

Current Release: What Changed Recently?

As of October 26, 2026, the official release list shows v0.2.1-rc.3, released on October 23, as its newest listed release. It is marked as a prerelease.

Its notes include additional plugin discovery and creation menus, a fix for an unsent draft disappearing after switching sessions, and changes that align API-key model-list updates with account sign-in behavior. Check the official releases before following instructions written for an earlier preview.

DeepSeek’s October 17 model announcement recommends Harness v0.2.1-rc.1 or later for the best experience with DeepSeek-V4.1-Flash-1017. The model release and the harness release are separate upgrades.

For reproducible work, record both versions. A result described only as having used DeepSeek leaves out the runtime, provider, configuration, and tools that helped produce it.

How the Cordis Plugin Architecture Works

DSH composes its runtime from plugins rather than reserving extensibility for a small collection of optional tools. Its architecture includes named profiles, bundles, and configuration patches.

A profile describes a runtime composition. A bundle distributes configuration and the code it loads. Patches customize that composition. Documented profiles include web, headless, sdk, sdk-minimal, and acp.

The Cordis research paper explains two ideas behind this design:

• Spatial composability: components declare dependencies, and the runtime reacts when those dependencies become available or disappear.
• Temporal composability: a component’s tracked effects can be cleaned up when that component is removed.

The practical engineering implication is that replacing a component should not require leaving behind its old registrations or manually reconstructing every dependent component. This is an architectural benefit, not a benchmark claim.

There is also an important boundary: plugin cleanup is not a universal undo function. Removing a registered tool or closing a connection does not automatically restore a file that an earlier command deleted. Runtime lifecycle management and recovery of external data are different responsibilities.

What Can DeepSeek Harness Do?

The official product page demonstrates several categories of work:

The page also labels features such as agent teams, automatic approval review, scheduled tasks, and voice input as experimental. Availability depends on the installed version and enabled plugins.

These capabilities become useful when the requested output is verifiable. For example, a spreadsheet task should specify which columns to calculate and how to handle missing values. A coding task should identify the failing behavior and the checks that establish a successful repair.

How to Install DeepSeek Harness

Desktop installation

The official download page currently presents desktop downloads for Apple silicon macOS and 64-bit Windows. Use that page to select the appropriate installer.

Local Web UI installation

The current repository manifest specifies Node.js 24.9.0 or newer. This requirement is more recent than the Node 22 instructions still visible in some older guides. Check the current package manifest when choosing a runtime.

Check the Node version in the terminal that will launch DSH:

node --version

From a suitable project directory, use the documented launch command:

npx @deepseek-ai/dsh web

The default local address is http://127.0.0.1:3080. For a normal local launch, the command also opens the browser. To suppress that behavior:

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

For a source checkout, the repository documents this sequence:

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

The build step prepares the artifacts consumed by the subsequent launch.

Complete the initial setup

Follow the Web UI quickstart:

1. Open Settings → Models.
2. Enter and save a DeepSeek API key.
3. Click Choose workspace.
4. Add and select the intended project directory.
5. Start a session.

A fresh Web UI has no selected workspace, even though the process has a working directory. The composer remains unavailable until a workspace is selected.

A useful first request is deliberately narrow:

Inspect this repository without modifying files.
Identify its application entry points, package manager, and test commands.
Explain one small improvement that can be verified with an existing test.
Do not install dependencies or run deployment commands.

This establishes whether the agent understands the project before it begins changing it. Prompt instructions should complement the configured permission controls.

Configure Models and Custom API Providers

DSH supports providers beyond DeepSeek. The model configuration guide documents built-in provider entries and a Custom model API option for gateways or self-hosted endpoints.

Custom providers require a provider ID, base URL, protocol, credentials where applicable, and at least one model. The supported protocol choices are:

• OpenAI Chat Completions.
• OpenAI Responses.
• Anthropic Messages.

Choose the protocol your endpoint actually implements. A compatible-looking URL alone does not establish compatibility. Model discovery is optional; an endpoint without a supported listing response can still work with manually entered model IDs.

The same guide identifies gateway failures involving the developer role and the difference between max_completion_tokens and max_tokens. Relevant compatibility settings include supportsDeveloperRole and maxTokensField; apply them only when they match the endpoint’s requirements.

Model configuration changes take effect on subsequent requests without restarting the server. However, a session that has already sent a request retains its recorded model. Use a fresh session when comparing configurations.

DeepSeek Harness Pricing: What Actually Costs Money?

The open-source license and the cost of operating an agent are separate questions. A useful budget includes model requests, paid tools, computing resources, and repeated attempts.

For the direct DeepSeek API, the official pricing page currently maps deepseek-flash to DeepSeek-V4.1-Flash-1017 and lists these USD rates:

These are API usage rates, not a quote for every Harness account or third-party provider. Consult the pricing page for the applicable time windows and subsequent changes.

An illustrative token-cost calculation

Suppose a completed task uses these aggregate totals across all its model requests:

• 900,000 cached input tokens.
• 100,000 uncached input tokens.
• 20,000 output tokens.

At the listed peak rates:

Cached input:   0.9 × $0.006 = $0.0054
Uncached input: 0.1 × $0.30  = $0.0300
Output:        0.02 × $1.20 = $0.0240
Total model cost           = $0.0594

This is an arithmetic example, not a measured DSH workload or a promised cache-hit rate. Use actual provider usage records for a real estimate.

Search and Fetch introduce another cost dimension

The Search and Fetch documentation lists each endpoint at $0.75 per 1,000 successful requests. For server-side calls made through Harness using the DeepSeek API, the current free period ends on November 1, 2026, at 00:00 Beijing time, equivalent to October 31 at 16:00 UTC.

Billable requests must return successful, usable results. Empty searches, failed requests, and timeouts are not billed under the documented rules. Search pricing is per request, not per returned result.

After that billing change, 20 billable searches plus 80 billable fetches would cost $0.075. Combined with the hypothetical token usage above, the total would be $0.1344, before other services or infrastructure.

The implication is concrete: for research-heavy tasks, external tool charges can exceed model-token charges. Track both rather than optimizing only the model’s advertised token price.

Skills, Plugins, and Plugin Markets

Use a skill for a repeatable procedure

The skills reference describes skills as optional instructions supplied through providers. The local provider recognizes project locations including .dsh/skills and .agents/skills.

It supports directory bundles such as <name>/SKILL.md and flat Markdown entries such as <name>.md. Arbitrarily nested recursive discovery is not supported.

A skill is suitable for instructions such as how to review a pull request, validate a report, or follow a repository’s release checklist. It does not, by itself, implement a new runtime service.

Use a plugin for executable capabilities

The first-plugin tutorial introduces a TypeScript module with an apply function and a Cordis context. Plugins use that context to register capabilities and declare required services through inject.

The tutorial also demonstrates loading a local plugin through a configuration overlay. One easily missed detail: its plugin module path must be absolute because an overlay does not change the directory used to resolve modules.

Understand lifecycle behavior before adding complexity

The lifecycle documentation explains that plugins wait for their dependencies, unload when required services disappear, and can load again when those services return.

Context-managed registrations are removed during unloading. Custom resources need an appropriate disposer through ctx.effect().

A subtle point matters for advanced plugins: asynchronous cleanup operations do not have a guaranteed serial completion order. When cleanup steps depend on one another, put them in one disposer and await them in the required order.

Treat markets as discovery infrastructure

The experimental Custom plugin markets feature adds a Discover tab backed by JSON indexes. DSH ships no index source; users add sources themselves.

The documentation states that market metadata is third-party content. DSH validates the index format but does not verify every claim about an author or package. Inspect the actual installation source and compatibility information before installing.

For developers, the design suggests a practical opportunity: build a small plugin that solves one recurring workflow problem, and package its instructions separately where possible. Validate that users repeatedly need the capability before expanding it into a large bundle.

Permissions, Privacy, and Local Execution

Local execution does not establish that all processing stays local. Determine which model provider receives the request and which tools contact external services.

The Harness privacy policy distinguishes official model services from custom model services. For custom services, it states that inputs go directly to the configured provider and outputs return from that provider, without Harness storing or processing those inputs and outputs server-side.

The policy also describes session-log collection for its services, including inputs, outputs, authorized content, and tool invocation information, alongside diagnostic information. Evaluate the relevant service path rather than treating every configuration as having identical data handling.

Permissions combine separate controls

The permission preset reference distinguishes sandbox mode from approval policy. Its documented preset table includes workspace-write with an asking policy, and danger-full-access with a never-ask policy.

A permission label therefore represents more than whether a confirmation dialog appears. Review the effective execution access as well.

DeepSeek’s safety notice explicitly says that sandboxing and approval controls do not guarantee isolation. It recommends restricted privileges, disposable or dedicated environments, backups, and review of plugins and commands.

For an initial evaluation, use a copied repository or a dedicated development environment with only the credentials the task needs. Expand access after the workflow has demonstrated that it requires it.

Common Problems and Practical Fixes

These checks follow the project’s quickstart, plugin tutorial, and subsystem documentation.

For remote hosting, the reverse-proxy guide makes an important distinction: --public-url advertises the browser-facing address, while --trusted-host affects which authorities are accepted.

Neither setting protects the listening port by itself. The proxy also needs correct WebSocket forwarding, path handling, and cookie behavior. Keep the backend reachable only through the intended proxy or trusted network.

When troubleshooting, isolate one layer at a time: installation, model connection, workspace, then optional plugins. Changing all four simultaneously makes failures harder to attribute.

How to Evaluate Performance Without Misleading Benchmarks

DeepSeek’s October 17 announcement reports model improvements and recommends an updated Harness version. However, one featured DeepSWE cost-performance chart explicitly uses mini-swe-v2. That chart should not be relabeled as a direct measurement of DeepSeek Harness.

Independent research reinforces the need to evaluate complete configurations. The October 2026 preprint Finding the Right Fit: Model-Harness Interactions across Agent Tasks evaluates 66 configurations and reports that model rankings can change across harnesses and tasks. Its findings do not support assuming that a model’s own vendor harness is always its best pairing.

A practical evaluation should use representative tasks and record:

• Completion: Did the result satisfy predefined acceptance criteria?
• Verification: Did relevant tests or output checks pass?
• Intervention: How many human corrections were required?
• Duration: How long until a usable result was available?
• Cost: What did all attempts and paid tools consume?
• Change quality: Were the edits focused and maintainable?

Keep the repository revision, permissions, task instructions, and available tools comparable. Record the exact model and harness versions. Repeat enough tasks to distinguish a consistent benefit from one unusually successful run.

For an individual developer, the most useful metric is often cost per accepted result, including review and repair time. A cheap attempt that repeatedly needs manual recovery may be less economical than a more expensive attempt that reliably passes verification.

Who Should Use DeepSeek Harness?

Based on its documented architecture, DSH is particularly worth evaluating when the workflow benefits from configurable providers, custom capabilities, and inspectable execution.

These are workflow recommendations, not guarantees of performance. The decision should depend on whether configuration and extensibility save more effort than they add.

Conclusion

DeepSeek Harness provides an unusually configurable foundation for agent work: models, tools, sessions, and execution behavior can be composed through plugins. Its value becomes measurable when that flexibility helps complete a real task with less intervention and reliable verification.

Start with the official release, one model, one workspace, and one bounded task. Record the result, time, and total cost. Add skills or plugins only when they solve an observed limitation. That process provides a stronger basis for adoption than a feature list or an isolated demonstration.