Fix DeepSeek Harness install and version errors

What the DeepSeek Harness install really is

The DeepSeek Harness install is one command: npx @deepseek-ai/dsh web. There is no installer, and there is no service to configure. Most of the trouble people hit is not installation at all. It is version resolution: which build of @deepseek-ai/dsh npx decided to run today, and whether your Node.js version can run it.

Two facts drive everything below. First, every version of @deepseek-ai/dsh published to npm so far is a release candidate, and the latest tag points at one of them. As of 18 August 2026 that is 0.1.0-rc.7, published on 17 August 2026. Second, the project README says the harness is in developer preview, is iterating rapidly, and will have compatibility-breaking changes. A flag that worked last week can be gone this week. Pin a version before you build anything on top of it.

Some terms first. dsh is the DeepSeek Harness command line tool. Node.js is the JavaScript runtime it needs. npx is the package runner that ships with npm (node package manager), and it fetches a package on demand instead of installing it permanently.

Which Node.js version does dsh need?

The repository's root package.json declares "engines": {"node": "^22.19.0 || >=24.0.0"}, read on 18 August 2026 at version 0.1.0-rc.7. So Node 22.19.0 or newer inside the 22 line, or Node 24 and above. Node 20 is out.

Check what you have before anything else.

node -v
npm -v

Here is the part that surprises people. The published @deepseek-ai/dsh package carries no engines field of its own. Only the monorepo root declares one, and that root file is never published to npm. npm therefore has nothing to check, so it prints no EBADENGINE warning and it refuses nothing. On Node 20 the install looks like it worked, and the failure arrives later, when the loaded code touches syntax or an API that your runtime does not have. There is no single stable error string to search for, because which line fails first depends on which module loads first. Read node -v rather than reading the crash.

If your Node is too old, nvm (node version manager) is the least invasive fix on a VPS, because it installs under your home directory and leaves the system Node alone.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash
exec $SHELL -l
nvm install 24
nvm use 24
node -v

node -v should now print a version starting with v24.. If the shell still reports the old version, the nvm shell function was not loaded, so open a new login shell and try again. Node 24.19.0 is the active LTS (long term support) release as of August 2026, and it is the better target for a second reason covered below.

Why does npx run a different version every day?

npx @deepseek-ai/dsh web names no version, so npx asks the registry for whatever the latest tag points at. That tag moves. When DeepSeek publishes 0.1.0-rc.8, the command sitting in your notes starts running different code, with no prompt and no changelog in front of you.

You can inspect every moving part from the command line.

npm view @deepseek-ai/dsh dist-tags
npm view @deepseek-ai/dsh versions --json
npm view @deepseek-ai/dsh time --json

dist-tags shows where latest points right now. On 18 August 2026 both latest and next pointed at 0.1.0-rc.7, so there is no separate stable channel to switch to. The versions list is more interesting, because it has holes in it: 0.0.1-rc.1, 0.0.1-rc.2, 0.0.1-rc.5, 0.1.0-rc.2, 0.1.0-rc.3, 0.1.0-rc.6, 0.1.0-rc.7. Numbers are missing from that sequence because some release candidates were never published. Guessing the next -rc.N in a deploy script will fail, so read the list instead of counting upward.

Why does npx keep running an old version?

This is the opposite complaint, and both are true, depending on which npm you are running.

npx keeps its own package directory, separate from the tarball cache, in a folder called _npx inside the npm cache. Print the path and look at it.

npm config get cache
ls "$(npm config get cache)/_npx"

For years npx reused whatever it found there for a bare package name and never asked the registry again. npm 11.2.0 changed that. When the spec is a bare name or a version range, npx now fetches the manifest and reuses the cached copy only when the resolved tarball matches what the registry just returned.

Which behaviour you get is decided by your Node release, because Node bundles a specific npm:

• Node 20.20.2 bundles npm 10.8.2.
• Node 22.19.0 bundles npm 10.9.3.
• Node 22.23.2, the newest 22 release, bundles npm 10.9.8.
• Node 24.19.0 bundles npm 11.17.0.

So the entire Node 22 line, which the harness officially supports, ships an npm older than 11.2.0. On Node 22 a bare npx @deepseek-ai/dsh web will keep running the release candidate it cached weeks ago. The same command on Node 24 re-resolves on every run. One command, two behaviours, and neither one warns you. Ask the tool what it is:

npx @deepseek-ai/dsh --version

Clearing the npx cache

On npm 11.2.0 and newer there are dedicated subcommands.

npm cache npx ls
npm cache npx rm --force

Without --force, npm refuses to wipe everything and prints Please use --force to remove entire npx cache. Use npm cache npx ls first when you want to remove one entry by key rather than all of them.

On npm 10 those subcommands do not exist, so delete the directory yourself.

rm -rf "$(npm config get cache)/_npx"

npm cache clean --force does not help here. It clears _cacache, the tarball store, and it leaves _npx alone. That separation is exactly why npm later added the npm cache npx subcommands. Clearing _npx also costs you nothing permanent: it holds downloaded packages, while your harness state lives under $DSH_HOME/profiles/<name> and is untouched.

How do I pin an exact release candidate?

Name the full version string, including the -rc.N part.

npx --yes @deepseek-ai/dsh@0.1.0-rc.7 web

--yes matters in a script, because npx otherwise prints a prompt before installing a package it has not seen and waits for an answer that never comes.

An exact version is also the fast path. npx keys its cache directory on the spec string you typed, and for an exact version it compares that against the package id already installed there and runs it with no registry round trip at all. On npm 11.2.0 and newer, a bare name costs you a manifest fetch on every single start.

A global install pins the same way, and gives you a short command.

npm install -g @deepseek-ai/dsh@0.1.0-rc.7
dsh --version

No matching version found for @deepseek-ai/dsh@^0.1.0

A caret or tilde range fails against this package. npm install -g @deepseek-ai/dsh@^0.1.0 answers with error code ETARGET and the line No matching version found for @deepseek-ai/dsh@^0.1.0. The registry is fine. This is a semver rule: a version range does not match a prerelease version unless the range itself names a prerelease. Every published build of this package is -rc.N, which is a prerelease, so ^0.1.0 matches nothing. Write the exact version.

That rule has a useful side effect. Because ranges cannot drift onto a new release candidate, there is no half-pinned state to reason about. You are either on an exact version or on a moving tag.

Should I use npx or install dsh globally?

Use npx for a first look, because nothing is left behind except a cache directory you now know how to clear. Use a pinned global install for anything that has to still work after a reboot, such as a coding agent you keep running on a VPS.

The two can disagree on a box where you have used both, so compare them.

which dsh
dsh --version
npx @deepseek-ai/dsh --version

which dsh finding nothing right after a successful global install almost always means npm's global bin directory is missing from your PATH. Run npm prefix -g to print the root, and the binaries sit in the bin folder under it.

One security note. npx fetches and executes code from the registry whenever it resolves something new, which on a server is a real exposure rather than a theoretical one. Pinning is part of the answer. The rest is in how npm supply chain attacks reach a server.

What developer preview means for reproducibility

0.1.0-rc.6 was published on 13 August 2026 and 0.1.0-rc.7 on 17 August 2026. Four days apart. At that pace, instructions written a month ago can describe a command line that no longer exists, and that includes this page. Date every version claim you write down, including your own notes.

Two habits make the preview survivable. Pin the exact version in every command and every script, so that rebuilding a server produces the same harness. Then read the help output from the pinned build rather than from any guide.

npx @deepseek-ai/dsh@0.1.0-rc.7 --help
npx @deepseek-ai/dsh@0.1.0-rc.7 web --dump-config

The second half of reproducibility is the profile. dsh --profile <name> boots the profile stored at $DSH_HOME/profiles/<name>, and the web and headless profiles create themselves from shipped templates on first use. In-box bundles resolve from the dsh installation that is currently running, which means changing your pinned version changes those bundles too. Out-of-tree plugins behave differently. They live in the profile directory, and dsh plugin --profile <name> add <package> forwards its arguments to pnpm to install them. So pnpm has to be on your PATH, and dsh says so plainly when it is not. The profile's own package.json is what pins those plugins, so a complete pin covers two files, not one.

That split will feel familiar if you have kept Python tools in isolated environments on a server: the tool and the things you add to it are pinned in separate places. Once the harness starts, the next question is usually networking rather than versions, which is where reaching the dsh Web UI on a remote VPS and the longer walkthrough in installing DeepSeek Harness on a VPS take over.

Argument errors you will actually see

These come from the CLI's own parser, so they are stable across the release candidate line and each one names the exact problem.

error: --profile <name> is required

You ran npx @deepseek-ai/dsh with no subcommand and no profile. The bare command boots a profile, so it needs a name. dsh web is the subcommand that takes no --profile, because it boots the shipped web profile for you.

error: --patch needs a path

--patch was passed with nothing after it. The flag is repeatable, and each occurrence takes one file path.

error: --dump-config and --dump-default-config are mutually exclusive

Pick one. --dump-default-config prints the shipped bundle layers and accepts no --patch. --dump-config prints the composed configuration for a profile. Both print and exit without starting the harness, which makes them the safe way to see what a new release candidate changed under you.

error: plugin needs pnpm arguments to forward (e.g. add <package>)

dsh plugin --profile <name> was given nothing to pass on. The subcommand initialises the profile when it is missing, then hands the rest of the command line to pnpm, so it needs arguments such as add @scope/dsh-plugin-example.

FAQ

Which Node.js version does DeepSeek Harness need?

The repository declares ^22.19.0 || >=24.0.0 in its root package.json, read on 18 August 2026 at version 0.1.0-rc.7. So Node 22.19.0 or later in the 22 line, or Node 24 and newer. Node 20 will not work. The published npm package has no engines field of its own, so npm never warns you and never blocks the install, and the failure appears at runtime instead. Check node -v first. Node 24 is the better choice anyway, because it bundles npm 11, which fixes npx version reuse.

How do I force npx to use the newest dsh instead of a cached one?

On npm 11.2.0 and newer, npx @deepseek-ai/dsh already re-checks the registry for a bare package name on every run. On npm 10, which every Node 22 release bundles, it does not. Clear the npx cache with npm cache npx rm --force on npm 11, or delete the folder with rm -rf "$(npm config get cache)/_npx" on npm 10. Then confirm with npx @deepseek-ai/dsh --version. Note that npm cache clean --force clears a different directory and will not fix this.

Why does installing @deepseek-ai/dsh@^0.1.0 fail?

npm returns error code ETARGET with the line No matching version found for @deepseek-ai/dsh@^0.1.0. Every published build is a prerelease such as 0.1.0-rc.7, and a semver range does not match prerelease versions unless the range itself names one. Install the exact version string, -rc.N suffix included. Run npm view @deepseek-ai/dsh versions --json to see which versions exist, because the sequence has gaps where release candidates were never published.

Should I install dsh globally or run it through npx?

npx suits a first look, since nothing persists except a cache directory. A pinned global install such as npm install -g @deepseek-ai/dsh@0.1.0-rc.7 suits anything that has to keep working, because the version changes only when you change it. If the dsh command is not found after a global install, npm's global bin directory is missing from your PATH, and npm prefix -g prints the root it lives under.

Is DeepSeek Harness stable enough to build on?

Not yet, by its own description. The README states that the project is in developer preview, is iterating rapidly, and will have compatibility-breaking changes. Release candidates 0.1.0-rc.6 and 0.1.0-rc.7 were published four days apart in August 2026. Pin an exact version and read --help from that pinned build rather than from any guide. Date your own notes, so you can tell how stale they have become.