Fix DeepSeek Harness install and version errors
The latest DeepSeek Harness build is still a prerelease. Pin an exact dsh version, clear the npx cache, and check which npm you actually run.
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. When it does start, localhost is the default binding; --host and --port override the listener settings, and the printed address uses --public-url when configured. The default binding and why the Web UI answers only on 127.0.0.1:3080 are a separate problem from the ones on this page.
Two facts drive everything below. First, every version of @deepseek-ai/dsh published to npm as of 27 October 2026 was a prerelease. Most are release candidates (-rc.N), and since 30 August 2026 there have been alpha builds (-alpha.N) as well. The latest tag points at a release candidate. As of 6 November 2026 that is 0.2.2-rc.1. 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. If the word harness is doing unfamiliar work in that sentence, an agent harness is the program wrapped around the model, holding the loop, the tools, the permissions and the session state, which is why a version number you did not choose can change how your agent behaves.
Which Node.js version does dsh need?
On 10 October 2026, when the repository was at version 0.2.1-alpha.2, its root package.json declared "engines": {"node": "^22.19.0 || >=24.0.0"}. That is no longer the requirement. Read on 27 October 2026, with the repository at version 0.2.1-rc.3, the root package.json declares "engines": {"node": ">=24.9.0"}, and the CLI's own source package.json now declares the same. A project decision note dated 15 October 2026 says Node 22 installations must upgrade, and that Node 24.0 is not enough either, because the entry points rely on import.meta.main, which 24.0 lacks. So Node 24.9.0 or newer. Node 20 and Node 22 are out, and so is any Node 24 release before 24.9.0. When checked on 27 October 2026, the release tags for 0.2.1-rc.2, then the build latest pointed at, and 0.2.1-rc.3 still carried the old range, so the new floor landed after them. Plan for 24.9.0 anyway, because that is the range the project now declares.
Check what you have before anything else.
node -v
npm -vHere is the part that surprises people. As of 27 October 2026 the published @deepseek-ai/dsh package still carried no engines field of its own, in any of its 38 versions up to 0.2.1-rc.4. The monorepo root declares one, and that root file is never published to npm. The CLI's source package.json gained one in a commit dated 15 October 2026, but none of the published builds checked on 27 October carried it. Those builds therefore gave npm no dsh-specific Node requirement to check. As of 6 November 2026, the published 0.2.2-rc.1 package declares "engines": {"node": ">=24.9.0"}. npm treats engines as advisory unless you set engine-strict, so expect a warning at most with the default setting. On an unsupported Node 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 -vnode -v should now print a version starting with v24.. If the shell still reports the old version, run which node. A path outside ~/.nvm has two usual causes. Either the nvm shell function was not loaded, so open a new login shell and try again, or a line in your shell profile changes PATH after the lines that source nvm and puts another Node in front, so move that line above the nvm lines. Node 24 was the active LTS (long term support) line on 10 October 2026 and moved to maintenance on 20 October 2026. Its newest release as of 29 October 2026 is 24.22.2, well above the 24.9.0 floor. Node 26, which the >=24.9.0 range also allows, entered active LTS on 28 October 2026 with version 26.13.0. Either one meets the floor, and both bundle npm versions with the range-cache fix covered below. Official Node 26 Linux binaries also require libatomic, which your distribution may need to install separately.
Why does npx run a different version every day?
npx @deepseek-ai/dsh web names no version. Unless the project in your current directory already has @deepseek-ai/dsh installed, in which case npx runs that copy, npx asks the registry for whatever the latest tag points at. That tag moves, and often. 0.1.0-rc.8 arrived on 19 August 2026, two days after 0.1.0-rc.7. By 10 October 2026 latest pointed at 0.2.0-rc.2, and by 27 October 2026 at 0.2.1-rc.2. Each time it moves, 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 --jsondist-tags shows where latest points right now. On 10 October 2026 both latest and next pointed at 0.2.0-rc.2, and a third tag, alpha, pointed at 0.2.1-alpha.2, published the day before. On 27 October 2026 latest pointed at 0.2.1-rc.2, next at 0.2.1-rc.4, published the day before, and alpha at 0.2.1-alpha.5. As of 6 November 2026, latest points at 0.2.2-rc.1. On 4 November 2026, next pointed at 0.2.1-rc.5, and alpha at 0.2.2-alpha.3. The latest tag still selects a prerelease. The versions list is more interesting, because it has holes in it. On 10 October 2026 it held 31 versions, from 0.0.1-rc.1 to 0.2.1-alpha.2, and by 27 October 2026 it held 38, every one still a prerelease. The 0.0.1 line jumps from -rc.2 to -rc.5, the 0.1.0 line jumps from -rc.3 to -rc.6, the alpha builds begin at 0.1.2-alpha.2 and 0.1.3-alpha.2, and there is no 0.1.4 at all. Numbers are missing from the published list, and alpha builds and release candidates are interleaved in the same list. 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 the package spec, the local installation and 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"npm 10.9.3 already checks the registry for a bare package name outside a project installation. npm 11.2.0 changed cache freshness checks for version ranges. When the spec is a bare name and the package is not already installed in the current project, npx fetches the manifest with preferOnline: true and reuses the cached copy in _npx only when the resolved tarball matches what the registry returned. A bare name still matches whatever version the current project has installed, with no registry check. For a version range, npm 10.9.3 accepts a matching cached version; npm 11.2.0 and newer check whether the range resolves to something newer.
Which behaviour you get is decided by the npm you actually run. Unless you have upgraded npm separately with npm install -g npm, that is the npm your Node release bundles:
- Node 20.20.2 bundles npm 10.8.2.
- Node 22.19.0 bundles npm 10.9.3.
- Node 22.23.4, the newest 22 release as of 27 October 2026, bundles npm 10.9.9.
- Node 24.9.0, the harness's current floor, bundles npm 11.6.0.
- Node 24.19.0 bundles npm 11.17.0.
- Node 24.22.2, the newest 24 release as of 29 October 2026, bundles npm 11.19.1.
- Node 26.13.0, the newest 26 release as of 29 October 2026, bundles npm 11.20.0.
So the entire Node 22 line ships an npm older than 11.2.0. The harness supported Node 22 until mid-October 2026 and no longer does, but a server that ran dsh before then may still be on it. Node 22.19.0's bundled npm 10.9.3 already re-checks a bare npx @deepseek-ai/dsh web against the registry outside a project installation, so an old _npx entry alone does not explain an old release candidate. Every Node release the harness now accepts, from 24.9.0 up, bundles npm 11.6.0 or newer, which also includes the range-cache fix. A project installation can still take precedence. Ask the tool what it is:
npx @deepseek-ai/dsh --versionClearing the npx cache
On npm 11.2.0 and newer there are dedicated subcommands.
npm cache npx ls
npm cache npx rm --forceWithout --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 separately under $DSH_HOME, including profiles/<name>, sessions, storages, and .credentials.yaml, 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 webThe examples on this page use 0.1.0-rc.7. Substitute the build you have actually tested. On 27 October 2026 the latest tag pointed at 0.2.1-rc.2.
--yes accepts npx's package-install confirmation without an interactive prompt.
An exact version pins the dsh package, but does not guarantee an offline start. npx keys its cache directory on the spec string you typed and can reuse an exact version already installed there. If no matching local installation exists, however, the preceding local-tree check fetches the manifest with preferOnline: true before inspecting _npx. A matching exact version installed in the local project avoids that manifest lookup. A bare name run outside a project that installs dsh also triggers a manifest lookup, including on npm 10.9.3.
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 --versionNo matching version found for @deepseek-ai/dsh@^0.1.0
As of 27 October 2026, a plain caret or tilde range failed against this package. npm install -g @deepseek-ai/dsh@^0.1.0 answered 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 one of the range's own comparators names a prerelease with the same major, minor and patch numbers. Every published build of this package as of 27 October 2026 was a prerelease, either -rc.N or -alpha.N, and ^0.1.0 named none, so it matched nothing. Write the exact version.
That rule cuts both ways. A plain range never drifts onto a new release candidate, but a range that names a prerelease can. ^0.1.0-rc.7 means >=0.1.0-rc.7 <0.2.0-0, so it accepts 0.1.0-rc.8 and would accept a final 0.1.0, while 0.1.1-rc.1 stays out because its numbers differ. That is a half-pinned state between an exact version and a moving tag, and it changes what runs without you changing anything. If you want the build you tested and nothing else, write the exact version.
Should I use npx or install dsh globally?
Use npx for a first look, because the package stays in 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 --versionwhich 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. The pace has not slowed since: 24 more versions were published between 19 August and 9 October 2026, including 0.2.0-rc.1 on 28 September and 0.2.0-rc.2 the next day, and seven more followed between 14 and 26 October 2026, up to 0.2.1-rc.4. 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 selects the same dsh release. That alone does not reproduce its dependencies: the published 0.2.2-rc.1 package uses ranges such as js-yaml: ^4.3.2 and commander: ^15.0.0, and ships without an npm shrinkwrap. For repeatable dependency installs, keep dsh in a local project with a committed package-lock.json and rebuild with npm ci. 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-configThe 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. The profile patch can hold model and endpoint settings, but saved API keys live in $DSH_HOME/.credentials.yaml, while settings retain credential references, so a pinned version and a working configuration are two separate things to get right. Home-level and command-line patches can override the profile settings. 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. Each one you add runs with the same permissions your agent has, which is worth checking what a plugin can reach before you install it. The profile's own package.json declares those plugins; preserve its pnpm-lock.yaml and use pnpm install --frozen-lockfile to reproduce their dependency versions too.
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, and each one names the exact problem. The wording has mostly held steady across builds, but not entirely, so the messages below were checked against 0.2.0-rc.2 on 6 October 2026.
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 works without --profile because the parser reads a bare first word as the profile name, so 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. In 0.2.0-rc.2, the build latest pointed at on 6 October 2026, the message names a third flag and reads error: --dump-config, --dump-default-config, and --dump-config-schema are mutually exclusive, because --dump-config-schema, which prints the JSON Schema for profile entries and patches, has joined the other two. --dump-default-config prints the shipped bundle layers and accepts no --patch. --dump-config prints the composed configuration for a profile. All three avoid starting the harness, but schema collection imports plugin modules and can invoke getters and lazy builders; inspect only trusted plugins and enforce an external timeout in scripts.
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?
Node.js 24.9.0 or newer. Read on 27 October 2026, with the repository at version 0.2.1-rc.3, its root package.json declares >=24.9.0. On 10 October 2026 it declared ^22.19.0 || >=24.0.0, but a project decision note dated 15 October 2026 dropped Node 22 and raised the floor above 24.0. Node 20 and Node 22 will not work, and neither will a Node 24 release older than 24.9.0. As of 27 October 2026 no published npm build had an engines field of its own, so npm could not warn or block based on dsh's own Node requirement, and an unsupported runtime failed later instead. The published 0.2.2-rc.1 package checked on 6 November 2026 now declares >=24.9.0 in engines.node; npm warns by default and refuses an incompatible runtime when engine-strict is enabled. Check node -v first. Every Node release that meets the floor bundles npm 11 or newer, which includes the npx range-cache fix introduced in npm 11.2.0.
How do I force npx to use the newest dsh instead of a cached one?
npm 10.9.3 and current npm already re-check the registry for a bare package name, unless the current directory is a project with dsh installed, in which case npx runs that local copy. Use npx @deepseek-ai/dsh@latest --version to request the registry's latest tag explicitly. npm 11.2.0 changed freshness checks for version ranges, not bare names. Clear the npx cache with npm cache npx rm --force on npm 11.2.0 and newer, 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?
As of 27 October 2026, npm returned error code ETARGET with the line No matching version found for @deepseek-ai/dsh@^0.1.0. Every published build at that check was a prerelease such as 0.2.0-rc.2 or 0.2.1-alpha.2, and a semver range does not match prerelease versions unless the range itself names a prerelease with the same major, minor and patch numbers. Install the exact version string, suffix included. Run npm view @deepseek-ai/dsh versions --json to see which versions exist, because the sequence has gaps.
Should I install dsh globally or run it through npx?
npx suits a first look, since the package stays in its cache directory; the harness also creates persistent profile state. 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, 0.2.0-rc.1 and 0.2.0-rc.2 one day apart in September 2026, and 0.2.1-rc.1 and 0.2.1-rc.2 on the same day in October 2026. The supported Node range changed in October 2026 too. 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.