DeepSeek Harness install by platform: Windows, macOS, Linux

DeepSeek Harness has exactly three install paths on every platform: run it with npx, install the package globally, or build from source; the real differences are not the commands but each platform's paths, permissions and runtime. This walks through shared prerequisites, choosing a path, per-platform differences and the first-launch check, pointing every platform pitfall at its own troubleshooting guide.

DeepSeek Harness prerequisites on every platform: Node.js, a terminal and network

The prerequisites are identical on all three platforms: a working Node.js, a terminal you can run commands in, and network access to the npm registry and GitHub (source). Four checks:

1. Confirm Node.js works — run node -v and npm -v. Expected: both print a version; a not-recognized or command not found error means Node is missing or off PATH, covered by fixing pnpm and node PATH errors.
2. Confirm the package manager — the source path uses pnpm, so run pnpm -v and enable it through Corepack if missing. Expected: pnpm -v prints a version.
3. Confirm the network — the zero-install path reaches the npm registry, and the source path also needs git clone against GitHub. Expected: the first npx run does not hang on the download; mirror problems are in slow downloads.
4. Windows only: switch terminal and path habits — use PowerShell rather than legacy cmd, and keep both install and data directories free of non-ASCII characters and spaces. Expected: with a clean path, the truncation-class errors never appear.

Choosing a DeepSeek Harness install path: npx, global npm or from source

The official README ships two ready paths — the zero-install npx @deepseek-ai/dsh web and a source build — while the third option installs that same package globally to skip npx resolution on each start (source). Pick by intent:

Building from source in four steps:

1. Clone the repository — git clone https://github.com/deepseek-ai/deepseek-harness.git. Expected: you get a deepseek-harness directory.
2. Enter it and install dependencies — cd deepseek-harness, then pnpm install. Expected: dependencies install with no ERR_PNPM_* class failure.
3. Build before running — pnpm run build prepares the repository artifacts, then pnpm dsh web starts it. Expected: pnpm dsh web uses the built artifacts and does not rebuild, so source edits need another build to show up.
4. Match the error word if it will not start — a missing node or pnpm goes to the environment guide, a port problem to the port guide. Expected: the error word maps to one article, so you never have to guess.

For the full trade-offs and uninstall notes across all three paths, read the three install methods compared.

DeepSeek Harness platform differences: Windows, macOS and Linux

The commands are one set across all three platforms, and the differences sit in paths and permissions: Windows is PATH and non-ASCII paths, macOS is launchd and filesystem format, Linux is global-install write permission and restricted environments. Go platform by platform:

1. Windows — PATH and the not-recognized error — when the npm global prefix directory is missing from PATH, dsh cannot be typed even after a successful install. Expected: adding that directory to the user PATH and reopening the terminal fixes it, as detailed in dsh command not found.
2. Windows — non-ASCII paths, sandbox and runtimes — non-ASCII paths get truncated, the sandbox makes the HTTPS handshake fail, and native modules such as sharp may fail to load. Expected: match the error word and follow Windows platform errors.
3. macOS — launchd does not inherit PATH — a startup job runs in the launchd environment, cannot find the node from your terminal, and crash-loops. Expected: writing the full PATH into the plist restores it, per macOS platform errors.
4. macOS — keep it off external volumes — formats such as exFAT lack an inode ownership check, so install or data directories on them fail. Expected: moving to an APFS local volume resolves it.
5. Linux — fix global-install permissions first — with a system-wide Node, npm install -g writes into system directories and easily raises EACCES; the standard fix is nvm or an npm prefix under your home directory rather than escalating with sudo. Expected: npm config get prefix points into your home directory and installs stop asking for privileges.
6. Linux — a restricted environment may lack toolchain — a container or minimal image may not carry the toolchain needed to compile native modules, so the build step fails first. Expected: add the build dependencies or sidestep the build with the zero-install npx path.

First DeepSeek Harness launch: port, page and the plugin market

There is one success criterion: the terminal prints http://127.0.0.1:3080 and opening that address renders the Web UI (source). Confirm in three steps, then do the first useful thing:

1. Read the terminal output — a local start prints http://127.0.0.1:3080 and opens your default browser. Expected: a rendered page means success; add --no-open to run the server alone without a browser.
2. Change the check when starting over SSH — only the host URL is printed and no browser opens. Expected: that is expected behaviour, not a failure; the local forwarding address belongs to the SSH client or editor.
3. Route around a page that will not open — first confirm the server is still running in the foreground, then look at port usage. Expected: connection refused (ECONNREFUSED) means the service never started, see port 3080 unreachable.
4. First thing after it starts: open the plugin market — the top navigation leads to the market, where you browse community plugins by category and stars. Expected: plugin cards render, which proves both the app and the catalog endpoint are working.

The plugin market is the official discovery surface built into DeepSeek Harness, folding search, categories, versions and updates into one page so installing a plugin never sends you back to the command line. For the workflow and filtering tips, see using the plugin market.

DeepSeek Harness per-platform install caveats

1. The commands are uniform, the environments are not: all three install paths work everywhere, so the failures are environmental — PATH, permissions, filesystem format, native modules — so classify by platform before reading the exact error word.
2. Do not reach for sudo to bypass permissions: on Linux and macOS, sudo npm install -g changes ownership of global directories and leaves a worse mess; change the prefix or switch to nvm instead.
3. External and network volumes are not install targets: exFAT is confirmed to fail on macOS, and synced or network drives are equally poor hosts for install and data directories on any platform.
4. The source path needs a rebuild: pnpm dsh web runs the built artifacts, so a source edit is invisible until pnpm run build runs again.
5. The data directory is the same everywhere: whichever path you choose, user-level data defaults to ~/.dsh, with the layout documented in where the DSH config files are.

Once the runtime is up, the next step is filling in plugins. DSH Plugin Hub is both the plugin market and the plugin manager, holding the installed list, update checks, logs and diagnostics in one place.

Sources: DeepSeek Harness README (official repository), user guide (official docs), dsh CLI README (official repository), dshplugin/dsh-plugin-hub