DeepSeek Harness is the dsh command line tool DeepSeek released into open-source developer preview on August 13, 2026 — a free, MIT-licensed agent runtime built as a plugin-based alternative to Claude Code. Getting it running takes one command, a supported Node.js version, and an API key for whichever model you want it to use.
Short answer: Install DeepSeek Harness by running
npx @deepseek-ai/dsh web, which needs Node 22.19 or newer and opens a local web UI. Add a DeepSeek, Anthropic, or OpenAI key under Settings, pick a project folder as your workspace, and start a session. The harness itself is free — you only pay for the model tokens you use.
Last updated August 14, 2026.
In my testing, the install itself was the first thing that tripped me up. I ran npx -y @deepseek-ai/dsh web on a machine with Node v20.20.2, and the command sat there using close to a full CPU core with zero console output. After 45 seconds I killed it — no error, no hint that the Node version was the problem. Once I switched to Node 24, the same command printed a URL and opened the web UI in under a minute. That gap between what the docs ask for and what actually happens when you ignore them is the whole reason this guide exists.
What you'll need
A Node.js install that meets the stated engine range — ^22.19.0 or >=24.0.0 — is non-negotiable; anything older doesn't error, it just hangs, which is the single most common way this setup goes sideways. You'll also need an API key for at least one model provider: a DeepSeek key from platform.deepseek.com if you want to use DeepSeek's own models, or an Anthropic or OpenAI key if you'd rather run the harness's agent loop against Claude or GPT instead. No payment method is required to install the harness — it's free and open source under the MIT license — but every model request you send afterward is billed by whichever provider answers it. Budget five minutes for the install and first session on a supported Node version.
Step-by-step: installing and running DeepSeek Harness
1. Confirm your Node.js version first
Run node --version before anything else. If it doesn't start with 22.19 or higher, or with 24 or higher, upgrade before you touch dsh — a mismatched version fails silently instead of telling you what's wrong, and you'll waste time debugging a "hang" that's actually just an unmet requirement.
2. Start the web UI with npx
Run npx @deepseek-ai/dsh web. This downloads the package fresh each time unless it's cached, then starts the harness's web server at http://127.0.0.1:3080 by default. Open that address in a browser and you'll land on the web UI with no workspace selected yet.
3. Or install it globally instead
If you'll be using dsh daily, npm install -g @deepseek-ai/dsh avoids the re-download on every launch, and you can then run dsh web directly. Both paths install the same package; the global install is purely a convenience once you're past the first test run.
4. Add a model provider under Settings
Open Settings → Models in the web UI. The DeepSeek card takes a single API key field. To use a different model, choose Add provider for a catalog option like Anthropic or OpenAI, or Add a custom provider for any OpenAI-compatible endpoint that isn't in the built-in catalog. Providers with their own auth — Bedrock, Vertex, Azure, Codex — need their native credentials, not just an API key field. Changes take effect on your next request; no restart needed.
5. Choose a workspace and start a session
Click Choose workspace and point it at a real project directory — the session composer stays disabled until you do. Once selected, start a session and send a task. The agent can read and edit files in that workspace, run shell commands, and maintain a plan across turns, and it'll ask for approval before anything outside the default workspace-write permission preset.
6. Try headless mode for one-shot tasks
For scripting or CI, skip the browser entirely: dsh --profile headless "summarize this repository" boots a fresh session, runs the task, prints the final answer to stdout, and exits — 0 if it completed, 1 if it didn't. This is the mode to reach for when you don't need a back-and-forth conversation, just an answer.
7. Add a plugin if you need one (optional)
Everything in DeepSeek Harness — tools, sandboxes, even the UI — is a plugin, so extending it means installing one: dsh plugin --profile web add <package-or-git-spec> forwards to pnpm inside your profile directory. Note that the harness ships an MCP client as a dependency but enables no MCP servers by default, since each one is trusted executable code running outside the agent's normal sandbox — install and enable them deliberately, not by default.
Web UI vs. headless: which mode to use
Web UI (dsh web) |
Headless (dsh --profile headless) |
|
|---|---|---|
| Command | npx @deepseek-ai/dsh web |
dsh --profile headless "task" |
| Interface | Browser, http://127.0.0.1:3080 |
Terminal only, no server started |
| Best for | Exploring the agent, reviewing diffs, multi-turn work | Scripts, CI jobs, one-shot answers |
| Output | Interactive chat with approval prompts | Final answer printed to stdout, then exit |
| First-run time (my test) | Under a minute on a supported Node version | Same install, no extra setup |
Example prompts you can copy
These are close to what I actually typed while testing the steps above:
- First session, web UI: "Summarize this repository and identify its main packages." This is the harness's own suggested first prompt, and it's a good gut check that a workspace is wired up correctly before you ask for anything real.
- Headless, one-shot:
dsh --profile headless "list every TODO comment in this repo and the file it's in"— good for a quick scripted audit without opening a browser. - Scoped edit, web UI: "Add input validation to the signup endpoint and a test in the existing test file's style. Don't touch anything else outside that file."
- Provider check: "Which model and provider are you running as right now?" — worth asking right after switching providers in Settings, since the model picker can silently keep an old default if a session already sent a request under it.
Keep prompts scoped to one outcome, the same rule that applies to any coding agent — a vague "clean this up" produces a bigger diff than a specific ask, and a bigger diff takes longer to review than the code you started with.
Common mistakes to avoid
The mistake that cost me the most time: assuming any reasonably recent Node install would work, when the harness needs ^22.19.0 or 24+ specifically and fails with total silence — not an error message — on anything older. Second, trying to send a task before selecting a workspace; the composer simply won't accept input, and it's easy to miss why. Third, treating DeepSeek's own chat-completions route as image-capable — it's text-only by design, and attaching an image gets refused before it's even sent, naming the model that can't take it. Fourth, installing an MCP server plugin without reading what it does first; the harness deliberately enables none by default because a server command is executable code outside the sandbox, and that's not a restriction worth routing around casually. Fifth, expecting production stability from a project that says, in its own README, to expect compatibility-breaking changes during developer preview — pin a version if you're building anything you depend on.
Tools that make this easier
If you want the fuller picture before installing anything — what broke in a real hands-on run, pricing, and whether it's worth it yet — my DeepSeek Harness developer preview review covers the pros, cons, and verdict in more depth than a setup guide has room for. If you'd rather skip the harness entirely and just wire DeepSeek's models into a coding agent you already use, how to use DeepSeek for coding covers Claude Code, OpenCode, and direct API setups. For the plain chat app instead of any agent workflow, see how to use DeepSeek. Since the harness is explicitly positioned against Anthropic's product, my Claude Code coverage is worth reading before you decide which one to build on. And if you're comparing coding agents generally rather than committing to this one, best AI tool for code tests several on identical tasks, while my broader AI coding assistant guide covers habits that apply no matter which tool you land on. If you're curious how cheap the model side of this actually is, DeepSeek V4 Flash breaks down the pricing on the model most people will point the harness at first.
Frequently Asked Questions
Is DeepSeek Harness free?
Yes. The harness itself is MIT-licensed and free with no seat pricing or paid tier — the GitHub repository had already crossed 85,000 stars within its first day and a half. What you pay for is model traffic: point it at DeepSeek's own API and, as of this writing, DeepSeek-V4-Flash runs $0.14 per million input tokens and $0.28 per million output tokens, or connect it to Claude or GPT and pay those providers' rates instead, confirmed on DeepSeek’s pricing page.
How long does it take to set up DeepSeek Harness?
On a supported Node version, under a minute — npx @deepseek-ai/dsh web, add an API key, pick a workspace. On an unsupported Node version, budget extra time you didn't plan for, since the command hangs with no error instead of telling you to upgrade.
What is the easiest way to start using DeepSeek Harness?
Run npx @deepseek-ai/dsh web on Node 22.19 or newer, add a DeepSeek API key under Settings → Models, choose your project folder as the workspace, and send the harness's own suggested first prompt: "Summarize this repository and identify its main packages."
Can I use DeepSeek Harness with Claude or GPT models instead of DeepSeek's own?
Yes. The installed catalog includes Anthropic and OpenAI as providers you can add directly in Settings, plus Bedrock, Vertex, Azure, and Codex through their native credentials, and any OpenAI-compatible endpoint through a custom provider. The harness's plugin architecture isn't locked to DeepSeek's own models.
Is DeepSeek Harness ready to replace Claude Code?
Not yet, in my testing. It's genuinely capable infrastructure, but DeepSeek itself warns of breaking changes during developer preview, and I hit a silent install failure in the first few minutes. See my DeepSeek Harness developer preview review for the full pros-and-cons breakdown if you're deciding between the two.