How to Install DeepSeek Harness (dsh): npx One-Liner, Source Build, Headless, and Plugins

To install Deep​Seek Harness (dsh), the open-source agent runtime Deep​Seek shipped on August 13, 2026, run npx @deepseek-ai/dsh web on a machine with Node.js 22.19 or newer. That one command downloads the 0.1.0-rc.6 preview, starts a local web UI at http://127.0.0.1:3080, and walks you through adding a model API key and a workspace on first launch. Two things to know before you start: dsh is not a model — it's the harness layer that connects a model to tools, files, and a terminal — and it's a developer preview, so expect breaking changes between releases. This guide covers both official install methods, headless mode, plugins, MCP, and the honest rough edges.

What Deep​Seek Harness is — and what it is not

Deep​Seek's internal formula, confirmed by senior researcher Chen Deli, is Model + Harness = Agent. The model is the brain; the harness is everything that turns it into something that gets work done: context and memory management, tool calling, task planning, file reads and writes, terminal execution, error feedback, and deciding when a task is done. Deep​Seek Harness is that layer, open-sourced under the MIT license on August 13, 2026 — the same day the DeepSeek V4 Pro 0813 build landed on the Deep​Seek API.

Two facts define the install experience. First, the architecture is "everything is a plugin," built on Cordis, a TypeScript plugin container — so what you install is a small core plus a set of plugins that provide model adapters, tools, sessions, and UI. Second, the version on npm today is 0.1.0-rc.6, a release candidate that the project itself flags as a developer preview: the README warns, in capital letters, that compatibility-breaking changes are coming. The popularity is real — 50,000 GitHub stars in its first 12 hours, 100,000 in about 42 hours, and past 120,000 by August 16 per Chinese tech press — but stars measure interest, not stability. Plan your install like you plan a preview: fast to try, cheap to throw away.

Before you start: the real system requirements

The single hard requirement is Node.js. The project targets the engine range ^22.19.0 || >=24.0.0 — in plain terms, Node 22.19 or newer, or any Node 24.x. Check yours with node --version. If you're on an older Node, the npx install will fail or misbehave, not degrade gracefully.

Everything else is lighter than the model-first crowd assumes:

• A model API key. dsh runs a real model; it needs a key for Deep​Seek's API or any Open​AI-compatible provider you configure. You can add one in the web UI after first launch.

• pnpm — only for the from-source build. Install once with npm install -g pnpm.

• ~1 GB of free disk for the npm package, workspace, and session logs, plus whatever a local model would need (dsh itself does not run weights).

• OS: the npm route works on Windows, macOS, and Linux. The Python SDK is narrower (Linux x64/arm64, macOS 14+ arm64 — no native Windows), covered below.

You do not need a GPU. The harness only orchestrates; the model runs remotely through an API.

Method 1 — the npx one-liner (recommended for almost everyone)

The official quick start is one command, and it is genuinely one command:

npx @deepseek-ai/dsh web

npx fetches the @deepseek-ai/dsh package (current version 0.1.0-rc.6), installs it into npm's cache, and starts the Web UI profile. Watch the output for the line that tells you it's listening — by default that is http://127.0.0.1:3080. Open it in your browser. Note the 127.0.0.1 loopback address: the UI binds to localhost only, which is the right default for a tool that can read and write files in your workspace — it also means you won't casually expose it on your network.

First launch has exactly two setup steps:

• Add a model key. Settings → Models → enter your API key. It's stored in $DSH_HOME/.credentials.yaml and not shown in plaintext afterwards. On a stock install DSH_HOME defaults to ~/.dsh.

• Pick a workspace. Add the project directory dsh is allowed to work in. The input stays locked until both steps are done.

Then send a first task — a good smoke test is "Summarize this repository and identify its main packages." If the summary comes back and the tool calls show up in the run trace, your install works.

Method 2 — build from source

Prefer to run from the repository? The official path is:

git clone https://github.com/deepseek-ai/deepseek-harness.git

cd deepseek-harness

pnpm install

pnpm run build

pnpm dsh web

You need pnpm for this (contributors pin pnpm 11.7.0). Choose the source build when you want to run latest main rather than the published release candidate, when you plan to read or modify the harness, or when you want to build a custom preset from the repo's apps/cli/config/agent-presets/ directory. For everyone else, the npx route is the same software with less ceremony — the source build does not unlock features the npm package lacks.

The three profiles: web, headless, and tui

dsh ships as three run profiles, and which one you use depends on where the work happens:

• web (default) — the full browser UI on port 3080. This is what npx @deepseek-ai/dsh web starts, and it's the profile most people will install first.

• headless — one task, then exit. dsh --profile headless "run the test suite and report failures" starts a session, runs the task, writes its results, and terminates. The headless runtime is explicitly a one-task process: you can't inject follow-ups mid-run, and corrections are a new run against the same workspace. This is the profile to wire into scripts and CI.

• tui — a terminal UI for keyboard-driven sessions: dsh --profile tui.

All three share the same config (~/.dsh/profiles/<name>/) and the same plugin system, so moving a task from the web UI to headless is a command swap, not a reinstall.

Adding plugins

Plugin management is a first-class CLI command, not an edit-in-place affair:

npx @deepseek-ai/dsh plugin --profile web add <source>

The source can be an npm package name, a GitHub repo (github:user/repo), a tarball, or a local folder. The most useful first install is the official plugin market, which turns plugin discovery into a UI:

npx @deepseek-ai/dsh plugin --profile web add dshmarket

Then restart the web service and open Settings → Plugin Market to browse and one-click install from the catalog. Two rules that trip people up: plugin bundles mount at profile startup, so a newly added plugin needs a restart of dsh web; and a plain npm install does not register a plugin into a profile — you must use dsh plugin. The ecosystem is young but not empty: the community-maintained awesome-dsh-plugin list already catalogs hundreds of plugins across categories like UI, skills, tools, providers, and notifications.

MCP, the four presets, and trajectory replay

Three features matter once you're past a basic install:

MCP. dsh speaks the Model Context Protocol through a built-in @deepseek-ai/dsh-mcp-client plugin. Today that's configured in files, not in the UI: you edit ~/.dsh/profiles/web/cordis.patch.yml (or a project-local patch) and declare each server's transport — stdio for local commands like npx @playwright/mcp@latest, streamable-http for remote URLs. It works, but it is the least polished surface in the preview; expect occasional instability and no GUI to toggle servers.

Presets. dsh loads one of four agent presets per session, and each is a different trade-off:

• Standard — the full tool set: file editing, shell, file and web retrieval, skills, planning, subagents, workflows. The everyday default.

• PTC (Programmatic Tool Calling) — Standard plus a Code Mode SDK that lets the model write TypeScript programs to orchestrate multi-round tool calls. More powerful, more side effects.

• Minimal — only bash and a file editor, nothing else. Built for model benchmarking and minimal reproduction; the mode the DeepSeek V4 Flash API docs referenced when they disclosed their own agent scores ran on "Deep​Seek Harness minimal mode."

• Creation — a runtime playground: inspect and load Cordis plugins in memory, experiment, and solidify a working combination into a new preset.

Trajectory replay. Every run writes an append-only session log — system prompts, reasoning, tool calls and their results, subagent scheduling. The Trajectory view lets you inspect by source, resume, fork, search, and replay a run. That is the debugger for agent work: when a task fails, you don't re-run and hope; you replay the failed trajectory, fork it at the bad step, and test a fix without discarding the original.

The Python SDK option

If you'd rather drive the harness from Python than from a browser, there's an official SDK: pip install deepseek-harness-sdk. It bundles the dsh runtime (the pip wheel carries the Node runtime, so no separate Node install), and usage is a context manager: build a Deep​SeekHarness instance, call run("task"). It inherits standard env vars like DEEPSEEK_API_KEY and DEEPSEEK_BASE_URL, so a provider swap is a config change. The catch: it's Python 3.10+ and supports Linux x64/arm64 and macOS 14+ arm64 only — there is no native Windows wheel, which is a real gap if Windows is your host. On Windows, stick with the npm route.

Pointing dsh at the models you pay for

dsh needs a model API key, and it is deliberately provider-agnostic: Settings → Models accepts a custom provider with an Open​AI-compatible base URL (in settings.yaml that's api: openai-completions, baseURL, and a models list). The default is Deep​Seek's own API; a custom provider is where a routing gateway becomes useful.

OrcaRouter is an Open​AI-compatible endpoint that passes Deep​Seek's list price through with zero markup — https://api.orcarouter.ai/v1. That gives you DeepSeek V4 Flash (deepseek/deepseek-v4-flash-0731, about $0.15 per million input tokens and $0.29 per million output) and DeepSeek V4 Pro (about $0.44/$0.88), both at provider list price with no token markup, plus automatic failover if a provider wobbles. For dsh, the practical win is that you can run the cheap V4 Flash for the bulk of everyday agent tasks and switch the same harness to V4 Pro for the hard passes — one key, one base URL, and the swap is a model name in the settings, not a reinstall.

To be clear about boundaries: OrcaRouter hosts the models dsh calls; it does not host dsh itself. dsh is a local agent runtime, and you run it on your own machine.

Where this guide is wrong for you — honest problems with the preview

An install tutorial that only tells you what to type is doing half the job. Here is what the preview gets wrong today, so you don't discover it at 2 a.m.:

• Breaking changes are a promise, not a warning. You are on 0.1.0-rc.6. Config keys, the plugin API, and preset formats can all shift without notice. Treat ~/.dsh as throwable state — the cost of a bad update is a reinstall, and that's acceptable at this stage only because the install is one command.

• You don't need dsh to use Deep​Seek models as an agent. If your only goal is DeepSeek V4 Flash or DeepSeek V4 Pro inside an agent today, Deep​Seek's Anthro​pic-compatible endpoint already works in Claude Code and other agent tools with zero new software. dsh is a first-party option, not a prerequisite. Skip this install until you specifically want the native harness.

• MCP is file-configured and occasionally flaky. No GUI, no per-server start/stop toggle, and hands-on reports describe intermittent failures. Budget time for YAML debugging if your workflow depends on MCP servers.

• Plugin trust is a security decision. Third-party plugins run inside the harness's core process, and there's no signing or source verification at install time. Only install plugins you've read or that come from a source you trust, and test them in a disposable workspace before pointing them at real work. The danger-full-access sandbox profile can modify any visible file — keep it to throwaway checkouts.

• Known bugs exist in the preview. A hung bash loop is a documented failure mode (interrupt and retry), and behavior around long-running sessions is still settling.

• Unofficial desktop builds are a trap. Several community wrappers package dsh as a click-to-install desktop app with a bundled Node runtime. They work, but they are unsigned and not maintained by Deep​Seek; if you use one, you're trusting a third party with a tool that will hold your filesystem permissions.

• If you need production stability, wait for a non-rc release. The harness is powerful but green. For a production agent stack, a mature, battle-tested harness — or the Anthro​pic-compatible endpoint route — is the defensible choice until dsh reaches a stable tag.

Bottom line

Installing Deep​Seek Harness is genuinely a one-command job on any machine with Node 22.19+: npx @deepseek-ai/dsh web, add a model key and a workspace, send a test task. Choose the source build only if you want to modify or track main; use headless for scripts; add the plugin market early; and treat MCP as a work-in-progress. The honest caveat is the same one the project prints in its own README: this is a 0.1.0-rc preview and it will break things on the way to stable. That's the right trade if you want to see where Deep​Seek is taking the agent layer — and the models it runs, DeepSeek V4 Flash and DeepSeek V4 Pro, are available today at list price through OrcaRouter, ready to power the harness on the other side of the install.