Fix DeepSeek Harness Install Errors: npx & npm Permission

When a DeepSeek Harness install errors, first identify the step: the npx one-command run, npm permissions, or the DSH plugin install — then debug that step.

Overview

The install chain has three stages and the errors come in three matching kinds. npx fetches and runs the DSH core, npm/pnpm writes packages to disk, and installing a DSH plugin goes through package resolution once more. Check which stage the error appears in, then decide whether to inspect the Node version, network, permissions, or registry. DSH is still in developer preview (currently 0.1.0-rc.6) and commands may change — follow the official docs when unsure (source). For the full install flow, see How to install DeepSeek Harness. The three sections below follow "core run → permissions → plugin install", each with concrete commands.

DeepSeek Harness npx run fails: check Node version and network

npx errors are usually a Node version that is too old or a network problem. The one-command run (source):

npx @deepseek-ai/dsh web

Node.js 18 or newer is required. With an older version, npx cannot resolve @deepseek-ai/dsh's dependency declaration and fails during fetch or run. Check the version first:

node -v

If it is below 18, install a newer Node from the official site and run npx again. After changing the Node version, close the terminal and open a new one so PATH refreshes — otherwise node -v may still report the old version.

Network problems usually show up as ENOENT, ETIMEDOUT, or ECONNREFUSED — npx needs to reach the npm registry, and a source build additionally needs GitHub. If the network is unstable, switch the registry to a mirror and retry, or use a proxy. A quick judgment trick: run it again — if the error code is the same and it is a connection-class error, it is network; if the failure point moves around each time, it is more likely a local environment issue.

Another npx-class failure: npx itself is missing or stale (usually an outdated npm). Run npm -v and npx -v to confirm both are installed; if npx cannot be found, updating Node via the official installer brings a fresh npx along. Note that npx caches fetched packages locally — if the cache holds a broken copy, npx @deepseek-ai/dsh@latest web forces a fresh fetch and bypasses the stale entry.

npm permission errors: fix EACCES for DeepSeek Harness install

EACCES is the classic permission error: npm writes global packages into system directories that your user cannot write. Two common fixes (source):

1. Run with npx instead: npx @deepseek-ai/dsh web needs no global write permission and bypasses EACCES — this is also the officially recommended one-command way.
2. Move the global prefix into your home directory: npm config set prefix ~/.npm-global, so global packages install under your user directory. After that, add ~/.npm-global/bin to your PATH, or commands installed there will not be found.

Avoid sudo npm install -g to force elevated permissions — it buries the problem deeper. If you previously broke the global directory with sudo, set up ~/.npm-global and clean out the old directory.

How to tell it is a permission problem? The error contains EACCES or permission denied and happens when npm writes to node_modules, a global directory, or the npm cache; if it happens during the fetch stage, suspect the network first.

On Windows, the equivalent problem shows up as access denied when npm writes under C:\Program Files or the npm cache; the fix is the same in spirit — install under your user directory (npm config set prefix %USERPROFILE%\npm) or use npx instead. Whatever the platform, keep npm install -g out of system directories unless your account actually owns them.

DSH plugin install errors: registry and github source

When installing a DSH plugin errors, check whether the plugin is an npm package or a github source. The install command (source):

dsh plugin --profile web add <package-name-or-github-ref>

• npm package: errors are usually an unreachable registry or a wrong package name. Run npm view <package> to confirm the package exists and the registry is reachable; switch to a mirror if the download stalls.
• github source: a github:owner/repo reference may be blocked by pnpm's allowBuilds on first install — copy the allow key into the profile's pnpm-workspace.yaml and add again; a git distribution without committed build output (no lib/ entry files) reports a missing entry file.
• profile state: dsh plugin forwards arguments to the pnpm inside the profile directory (default ~/.dsh/profiles/web), so a manually corrupted package.json there also breaks add.

A quick way to tell the source: github.com or codeload in the error means a github source; registry, 404, or ETIMEDOUT usually points to the npm source. Missing build output is the most common github-source failure, and the entry-file troubleshooting is covered in more detail in the uninstall-failure article.

For github-source installs that keep failing on the entry file, the root cause is almost always that the repository was published without its build output committed — the lib/ directory is missing while main points at it. Before asking the author to fix it, check whether the same plugin exists on npm: the npm-published version ships with build output and installs cleanly. GitHub sources also reinstall slowly because pnpm clones the whole repository each time, so prefer the npm version for anything you install more than once.

If the CLI keeps failing, install directly from the plugin center in DSH Plugin Hub — every plugin there shows its source (npm or GitHub), the npm version avoids the missing-build-output problem of git distribution, and every install result is logged in the notification center for later review.

Notes

1. Install DSH first, then plugins: dsh plugin needs dsh web to have run once so the web profile is initialized.
2. A profile only affects its own environment: web and headless do not interfere.
3. Version compatibility: plugins usually state the DSH version they target (e.g. rc.6); confirm the match before installing.
4. Don't blindly retry one command: switching approaches (mirror registry, npm version, plugin center) is often faster than fighting it.

Source: official Quickstart, dsh CLI README, npm official docs