DeepSeek Harness is not a new model and it is not merely another API client. It is DeepSeek AI's open-source framework for connecting models to files, terminals, tools, sessions, subagents, permissions, and user interfaces.
Its defining idea is simple but ambitious: everything, including the agent loop itself, is a plugin. That makes DeepSeek Harness less like a fixed coding assistant and more like a modular runtime for building coding agents.
This guide covers the official deepseek-ai/deepseek-harness project. It explains how to install the developer preview, how the Cordis-based architecture works, where DeepSeek V4 fits in, and what developers should verify before adopting it.
Last verified: August 14, 2026. The project is moving quickly, so pin a package version and verify the current documentation before adopting it.
DeepSeek Harness in 60 Seconds
| Question | Answer |
|---|---|
| What is it? | An open-source agent harness developed by DeepSeek AI |
| Is it a model? | No |
| Is it official? | Yes |
| Current status | Developer preview |
| License | MIT |
| Quick start | npx @deepseek-ai/dsh web |
| Default interface | Local Web UI at http://127.0.0.1:3080 |
| Core architecture | Cordis, where capabilities are plugins |
| Does local UI mean local inference? | No. The default DeepSeek route calls an API and requires a credential |
| Tested package version | @deepseek-ai/dsh 0.1.0-rc.6 on Node.js 22.23.2 |
The project is unusually explicit about its status: it is a developer preview and compatibility-breaking changes are expected. The repository uses the MIT License, but model inference is still billed by whichever API provider you configure.
How to Install DeepSeek Harness
The official quick start is one command:
Prerequisites
The repository currently requires Node.js ^22.19.0 or >=24.0.0. An older Node installation may not satisfy the package's engine requirement even if npx itself works.
We installed the public npm package on macOS using:
The install completed with 531 npm packages and no reported vulnerabilities. The launcher then printed:
The first run opened the local browser interface successfully. It displayed a preview notice, then offered DeepSeek API-key setup. No key appears in the screenshot below.
A verified English-language local run shows the workspace, model, preset, and first-session controls readers encounter after launch. Source: DeepSeek Harness public package.
Complete the first-run setup
- Open
http://127.0.0.1:3080if the browser does not open automatically. - Add a DeepSeek API key during onboarding, or configure it later under Settings → Models.
- Choose a workspace. The Web UI disables the session composer until a workspace is selected.
- Select a model from a configured provider. The selection becomes the default for new sessions.
- Choose an Agent preset and review the permission mode.
- Start with a bounded task, such as:
Summarize this repository and identify its main packages. - Review requested approvals before allowing writes or shell commands.
The default filesystem location is the directory from which you launched dsh. The standard permission preset uses workspace-write with approval prompts. DeepSeek Harness also exposes danger-full-access; that setting deliberately bypasses filesystem confinement and should not be used casually.
The local Web UI is a control surface, not evidence of local model inference. The default DeepSeek adapter sends requests to a DeepSeek-compatible API. A self-hosted or company gateway can be added as a custom provider if it exposes a compatible endpoint.
The provider screen makes the boundary clear: a local browser interface can still call a remote API that requires credentials. Source: DeepSeek Harness provider guide.
Official DeepSeek Harness vs the Third-Party deepseek-harness
Two GitHub repositories currently share the same phrase. They are different projects.
| Official project | Independent project | |
|---|---|---|
| Repository | deepseek-ai/deepseek-harness |
HenryZ838978/deepseek-harness |
| Maintainer | DeepSeek AI | Independent GitHub author |
| Primary purpose | Full coding-agent framework and runtime | Protocol-aware adapters for DeepSeek V4 Pro and Flash |
| Main implementation | TypeScript monorepo | Python package plus CLI, MCP server, and skill files |
| Primary package | @deepseek-ai/dsh |
deepseek-harness, deepseek-harness-cli, plus an MCP package described in the repository |
| Browser agent UI | Yes | Not its primary purpose |
| Agent loop, sessions, tools, permissions | Core project scope | Adapts protocol behavior for other clients |
| Developed by DeepSeek AI | Yes | No |
| License | MIT | MIT |
This article covers the official deepseek-ai/deepseek-harness project. HenryZ838978/deepseek-harness is a separate, independently maintained, unofficial protocol adapter for DeepSeek V4 Pro and Flash. We found no evidence that the repository is affiliated with or endorsed by DeepSeek AI.
The independent project may still be useful. It addresses details such as reasoning-content round trips and streaming tool-call aggregation across Python, CLI, MCP, and skill wrappers. Its repository describes an @deepseek-harness/mcp package, although a direct npm registry check returned 404 during our August 14 review. It is not the official framework described here.
What an AI Coding Harness Actually Does
A language model predicts text and tool calls. The harness turns those predictions into controlled work.
In a coding session, the surrounding runtime decides:
- which repository files and instructions reach the model;
- which file, shell, search, web, or planning tools are visible;
- how tool arguments are validated and executed;
- how results and failures return to the model;
- how the agent continues across multiple model requests;
- when history is compacted or reconstructed;
- what requires approval and what the sandbox permits;
- how sessions, plans, subagents, and background work are persisted;
- when a task stops, resumes, or fails.
DeepSeek Harness defines a step as one model request plus its tool calls. A turn can contain several steps. The loop assembles prompt sections and tool schemas, streams a model response, executes tools through guarded pipelines, logs the result, and decides whether another step is owed.
That runtime changes the problem the model receives. A model paired with precise file search, clean tool errors, retained session state, and cheap verification can outperform the same model inside a loop that sends noisy context, truncates failures, or stops before running tests.
Inside the Everything-Is-a-Plugin Architecture
DeepSeek Harness runs on Cordis, a vendored plugin framework. Cordis provides a shared context, service discovery, typed events, and reversible effects. The practical result is that model adapters, tools, sessions, the agent loop, permissions, persistence, and interfaces can be composed or replaced through configuration.
The official turn flow covers prompt assembly, model streaming, tool execution, durable events, and stopping conditions. Source: DeepSeek Harness architecture documentation.
The parts developers need to understand
Cordis Context. A context is a registry of services such as ctx.llm, ctx.tools, and ctx.sessions. Plugins depend on service keys instead of importing one concrete implementation.
Model adapters. The LLM layer maps the harness request vocabulary to a provider. The repository ships a DeepSeek adapter and a provider-neutral Pi AI route for configured providers.
Tool registry. Plugins register model-visible tools and schemas. Each call passes through validation, permission, execution, post-processing, and durable result logging.
Agent loop. The default loop claims input, assembles the system prompt and tool catalog, requests a model response, executes calls, and continues until the turn is settled.
Session log. An append-only event stream is the source of model history. Replay, persistence, resume, forks, titles, telemetry, and UI state derive from it.
Filesystem, shell, and sandbox. Service definitions separate the model-facing tool from its backend. Local, sandboxed, or remote providers can sit behind the same capability seam. The shipped sandbox focuses on filesystem effects; it is not a general network or process-isolation boundary.
Subagents and workflows. The standard preset can delegate work, track child agents, and run workflows while keeping parent and child lifecycle state explicit.
Interfaces. The npm quick start exposes a Web UI. The repository also includes a headless profile, JSON-RPC and TypeScript SDK components, Agent Client Protocol support, and a published Python SDK with a bundled runtime. A TUI profile can be installed, but it is not one of the two auto-initialized default profiles.
The composition itself is inspectable:
This prints the ordered plugin tree after bundles and local patch layers have been applied.
Standard, PTC, Minimal, and Creator Modes
The installed Web UI exposed four Agent presets during our test.
The actual selector makes Standard, PTC, Minimal, and Creator modes—and their different trust boundaries—immediately visible. Source: DeepSeek Harness public package.
| Mode | Best for | Main trade-off |
|---|---|---|
| Standard | General coding tasks with files, shell, search, planning, goals, skills, subagents, and workflows | Larger tool and prompt surface |
| PTC | Multi-step tool workflows that can be composed into one TypeScript program | More complex execution model and generated SDK layer |
| Minimal | Direct, tightly scoped coding with persistent Bash and str_replace_editor |
No compaction and far fewer built-in capabilities |
| Creator | Building Agent presets and experimenting with the Cordis runtime | Higher trust: runtime inspection and model-written plugin experiments expand the risk boundary |
PTC is the UI label for the repository's code preset. It keeps the standard capabilities but presents them through Code Mode: the model writes a TypeScript program against a generated SDK, and run_code dispatches the nested tool calls. This can collapse several tool round trips into one program.
Creator is the UI label for the cordis preset. It adds self-referential Cordis tools to the standard agent. The repository warns that model-written JavaScript can run against the live runtime and that a generated composition can affect later sessions. Treat Creator Mode as shell-level trust, not as an ordinary chat mode.
Why DeepSeek V4 Can Behave Differently Across Tools
The model is only one variable in an agent run. The official framework makes the other variables visible.
Two tools can call the same DeepSeek V4 model and still differ because they provide different:
- system instructions and project rules;
- tool names, schemas, and output formats;
- repository retrieval and file-observation policies;
- context compaction and replay logic;
- parallel execution and background-job behavior;
- patch application and read-before-edit checks;
- permission prompts, sandbox scope, and approval policy;
- retry, cancellation, recovery, and termination rules.
That is why a token-price table cannot predict coding-agent performance. A cheaper model that repeats invalid tool calls or loses state after compaction may cost more per successful task than its list price suggests.
Choosing the harness is only half of the decision. Model selection still requires matched tests of price, task success, retries, tool behavior, and latency. Treat workload-routing advice as a hypothesis until those measurements exist.
The practical unit to test is:
Changing any one of those can change the result.
What the Early Demos Prove, and What They Do Not
The official project and its launch material show agents generating games, interactive web experiences, 3D work, and other multi-file artifacts. Those demos show that the harness can support long tool trajectories, file and command execution, subagents, and complex interactive output.
They do not prove that:
- DeepSeek Harness beats Codex, Claude Code, or another coding tool;
- the framework increases the model's underlying intelligence;
- V4 Pro always outperforms V4 Flash;
- the developer preview is ready for production;
- the harness reduces retries or cost under controlled conditions.
Those claims require the same model, task, repository state, permissions, run budget, and evaluator across harnesses. Screenshots from different prompts are not a controlled benchmark.
Developer Preview Limitations
DeepSeek Harness is moving quickly. The root README states that compatibility-breaking changes will occur.
Developers should plan around these boundaries:
- Configuration and APIs can change. Pin a package version and preserve the effective plugin tree for reproducible tests.
- Documentation can move with the code. Use the repository docs for the exact revision or installed package version.
- Local UI does not mean local inference. The default model route still needs an API endpoint and credential.
- MIT software does not make the API free. Inference and any external services retain their own pricing.
- Filesystem sandboxing is not complete machine isolation. The shipped local sandbox documents unchanged network access and process visibility.
danger-full-accessis intentionally unconfined. It bypasses the sandbox rather than creating a wider safe profile.- Creator Mode expands trust. It can evaluate model-written JavaScript against the runtime.
- The Python minimal example is also high-trust. Its docs say it uses a bare local filesystem and
danger-full-access, so it belongs in a disposable checkout or container. - No production-readiness guarantee is published. The repository calls the project a developer preview.
- Vendor or launch benchmarks are not substitutes for your own task runs. Measure task completion, retries, tool failures, latency, and operator intervention.
Who Should Try DeepSeek Harness?
DeepSeek Harness is a strong fit for:
- coding-agent and runtime developers who want inspectable composition;
- DeepSeek V4 users who need more control than a fixed assistant provides;
- plugin authors building tools, model adapters, policies, or interfaces;
- teams that want to own the agent control layer while using hosted model APIs;
- researchers comparing how context, tools, and recovery change one model's behavior.
Teams may want to wait if they need a mature, fixed coding assistant with long-term compatibility guarantees. The project is also a poor fit for production systems that require a stable public API, verified isolation, or a completed security review today.
The most responsible starting point is a disposable workspace, a pinned package version, workspace-write, and a small task with objective acceptance criteria.
FAQ
Is DeepSeek Harness official?
Yes. deepseek-ai/deepseek-harness is maintained under DeepSeek AI's GitHub organization and its README describes it as developed by DeepSeek AI.
Is DeepSeek Harness a model?
No. It is the runtime around a model. It handles tools, sessions, context, permissions, execution, and interfaces.
Is DeepSeek Harness free?
The source code is available under the MIT License. Model API calls and third-party services can still incur charges.
Does DeepSeek Harness run models locally?
Not by default. The local Web UI connects to configured model providers. You can add a self-hosted compatible endpoint, but the browser interface alone does not provide local inference.
How do I install DeepSeek Harness?
Install a supported Node.js version, then run npx @deepseek-ai/dsh web. The default Web UI address is http://127.0.0.1:3080.
What is Cordis?
Cordis is the plugin framework under DeepSeek Harness. It supplies service contexts, typed events, dependency injection, and reversible plugin effects.
Does DeepSeek Harness support models other than DeepSeek?
Yes. The Web UI can add catalog providers such as Anthropic and OpenAI, plus custom compatible providers. Support depends on the installed adapter and the endpoint's actual capabilities.
How is it different from Claude Code?
Claude Code is an opinionated coding product. DeepSeek Harness is a composable agent framework whose model adapters, tools, loop, persistence, policies, presets, and interfaces are plugins. Both can run coding workflows, but they expose different levels of runtime control.
What is the difference between the two deepseek-harness repositories?
deepseek-ai/deepseek-harness is DeepSeek AI's official coding-agent framework. HenryZ838978/deepseek-harness is a separate, independently maintained, unofficial protocol-adapter project. Its repository documents Python, CLI, MCP, and skill wrappers; we found no evidence of DeepSeek AI affiliation or endorsement.
Should I use DeepSeek V4 Pro or Flash with it?
Flash has the lower official token price, while DeepSeek positions Pro for harder agentic coding and reasoning. Choose only after matched tests under the same harness, preset, tools, permissions, and evaluator.
Sources
- Official DeepSeek Harness repository
- DeepSeek Harness architecture
- DeepSeek Harness Web UI guide
- Model configuration guide
- Cordis primer
- Python SDK tutorial
- Independent protocol-adapter repository
Want to use AI agents without configuring a local harness? Explore AI coding agents on Atoms or see how Atoms coordinates specialized AI agents.
