Tutorial · npx

Run DeepSeek Harness with npx — npx deepseek-ai dsh web

Run npx deepseek-ai dsh web — canonical npx @deepseek-ai/dsh web — on macOS, Windows or Linux to start the open-source harness Web UI at http://127.0.0.1:3080 in under ten minutes. This guide covers prerequisites, Node setup, API key configuration, running the command, opening the browser, and fixing the eight most common errors. Prefer a no-terminal path? See the GUI alternative on the homepage.

Before you start

You need three things before npx deepseek-ai dsh web will work:

1. Node.js — required version node ^22.19.0 || >=24 and pnpm@11.7.0 if you later build from source (from downloads/manifest.json:build.requires). Check with node -v and npm -v. If your Node is older, upgrade via your system manager (see next section).
2. A terminal — macOS Terminal or iTerm, Windows PowerShell, or any Linux shell. You will run exactly one command: npx @deepseek-ai/dsh web.
3. A model API key — a DeepSeek API key works out of the box; Anthropic, OpenAI, or any OpenAI-compatible endpoint is also supported. The harness is MIT-licensed; you only pay the provider for tokens.

Network: first run downloads the package, so you need internet access. If you are behind a proxy, allow registry.npmjs.org and the model provider endpoints.

Check and install Node.js

Run this first — it decides whether npx deepseek-ai dsh web will even start:

node -v
npm -v
# expected: v22.19.x or v24.x, npm 10.x

• macOS: brew install node@22 or use nvm: curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash then nvm install 22 and nvm use 22.
• Windows: winget install OpenJS.NodeJS.LTS then restart PowerShell and verify node -v is on your PATH. If node : command not found, reopen the shell or add Node to PATH.
• Linux: use nvm or your distro package, then node -v.
• pnpm: not needed for npx deepseek-ai dsh web, but if you later build from source you will need pnpm@11.7.0. Install when needed with npm i -g pnpm@11.7.0 or corepack enable then corepack prepare pnpm@11.7.0 --activate.

Pin: the version matrix above comes from downloads/manifest.json:build.requires — we do not invent older versions.

Run npx deepseek-ai dsh web

This is the authoritative one-liner. The scoped package name is @deepseek-ai/dsh; search engines also index the bare query npx deepseek-ai dsh web without the scope, so both forms appear here.

npx @deepseek-ai/dsh web

npx deepseek-ai dsh web

Local: http://127.0.0.1:3080

Quick alternative: install from source (summary)

If you need to edit the harness itself, use the source path: git clone https://github.com/deepseek-ai/deepseek-harness then pnpm install, pnpm run build and pnpm dsh web. Full steps, pnpm pitfalls and a side-by-side comparison with npx deepseek-ai dsh web live on the upcoming Source Clone guide — this page keeps only this summary to avoid duplicating the long-tail.

Configure a model

With the Web UI open at http://127.0.0.1:3080, configuration lives in the UI:

1. Open Settings → Models.
2. For DeepSeek: paste your API key in the DeepSeek card and Save. For another provider: click Add provider and choose Anthropic or OpenAI.
3. For a company gateway or self-hosted server: click Add a custom provider and supply a provider ID, base URL, API protocol, credential and at least one model. It must be OpenAI-compatible or use a supported protocol.

API key security: keys are write-only — after saving the UI shows only a redacted descriptor. The raw value lives in $DSH_HOME/.credentials.yaml on your machine. It is never sent to deepseek-harness.io; your key stays local, calls go directly from your harness to the provider. The route becomes usable immediately without restarting the server. If you rotate a key, just overwrite it in Settings → Models; no restart needed.

Add your API key once and reuse it — invalid or mismatched keys are the #1 cause of 401 errors (see Troubleshooting #4).

Choose a workspace

Click Choose workspace, add the project directory where you started npx @deepseek-ai/dsh web, and select it. The session composer stays unavailable until a workspace is selected — the agent needs to know where it may read and edit files. You can add multiple workspaces and switch between them.

Run your first task

Start a session and send a prompt such as:

Summarize this repository and identify its main packages.

The agent can read and edit workspace files, run commands, delegate work and maintain a plan. When the active permission policy flags an operation, the UI asks for your approval before the agent proceeds.

Troubleshooting

Eight fixes for the errors you will actually hit with npx deepseek-ai dsh web. Each entry is cause → command/path → verify.

1. Node version too old (EBADENGINE / engine mismatch)

Symptom: EBADENGINE or required: node ^22.19.0 || >=24.

Cause: Node 18/20 is too old for the harness.

Fix: nvm install 22 && nvm use 22 or brew upgrade node@22 or winget upgrade OpenJS.NodeJS.LTS. Verify node -v prints v22.19.x or v24.x.

2. command not found: npx / node: command not found

Symptom: zsh: command not found: npx or node: command not found.

Cause: Node not on PATH.

Fix: Reopen terminal, or add Node to PATH. Windows: restart PowerShell after install, check where node. macOS/Linux: echo $PATH and which node, then export PATH="/opt/homebrew/bin:$PATH" if using Homebrew.

3. Port 3080 already in use (EADDRINUSE)

Symptom: Error: listen EADDRINUSE: address already in use 127.0.0.1:3080 or blank page at http://127.0.0.1:3080.

Cause: Another process occupies 3080, or a previous npx @deepseek-ai/dsh web is still running.

Fix: lsof -i :3080 (macOS/Linux) or netstat -ano | findstr :3080 (Windows), then kill PID or close the old terminal. Retry npx @deepseek-ai/dsh web and verify http://127.0.0.1:3080 loads.

4. API key missing or invalid (401 / Invalid API key)

Symptom: Model requests fail with 401, Invalid API key, or authentication failed.

Cause: Key not saved, pasted with whitespace, or for the wrong provider.

Fix: Open Settings → Models, re-paste the key (trim spaces), Save, and check the redacted descriptor appears. Confirm the provider card matches the key (DeepSeek key in DeepSeek card). Inspect $DSH_HOME/.credentials.yaml exists and is not empty.

5. Network / proxy / fetch failed (ETIMEDOUT, fetch failed)

Symptom: fetch failed, ETIMEDOUT, or first-run npx download hangs.

Cause: No internet, firewall, or corporate proxy blocking registry.npmjs.org or provider endpoints.

Fix: Check curl -I https://registry.npmjs.org and ping api.deepseek.com. If behind proxy: npm config set proxy http://proxy:port and https-proxy, or set HTTP_PROXY/HTTPS_PROXY env vars. Retry npx @deepseek-ai/dsh web.

6. Permission denied (EACCES, permission)

Symptom: EACCES: permission denied on cache or ~/.npm.

Cause: npm cache owned by root after a sudo install.

Fix: sudo chown -R $(whoami) ~/.npm (macOS/Linux) or run PowerShell as normal user (not elevated) on Windows. Avoid sudo npx. Check npm config get cache points to a writable path.

7. Model or provider mismatch (404 / model not found)

Symptom: 404 model not found or provider mismatch even with a valid key.

Cause: Selected model does not exist for the provider, or custom base URL/protocol is wrong.

Fix: In Settings → Models, verify the model name spelling and provider pairing (e.g., DeepSeek-V3 for DeepSeek, not OpenAI). For custom gateways, ensure base URL ends correctly and protocol is OpenAI-compatible.

8. Workspace not selected (composer disabled)

Symptom: Session composer is greyed out, hint says choose workspace.

Cause: No workspace selected.

Fix: Click Choose workspace → Add the folder where you ran npx @deepseek-ai/dsh web → Select it. Verify composer becomes active. On Windows, use an absolute path like C:\projects\my-app.

Bonus — Nothing prints a URL: if npx @deepseek-ai/dsh web exits silent, check exit code with echo $? (should be 0) and try http://127.0.0.1:3080 directly. Run with npx --yes @deepseek-ai/dsh web to skip the install prompt.

Prefer a GUI?

If the terminal steps above feel heavy, the Desktop GUI wraps the same open-source engine with a one-click install, guided API key setup, and your key stays local — no terminal needed. It is a third-party community wrapper, not affiliated with DeepSeek, and every run remains fully traceable.

Live build: GitHub Release dsh-desktop-v0.1.0 (dsh-desktop-0.1.0-mac-arm64.zip, SHA 118168931c3e3064b0a785e35011f08f0c4100c7c923ab1671933266f8886439) is available now as an unsigned, not-notarized experimental asset for macOS Apple Silicon (arm64) only, requires macOS 13+. Gatekeeper will block it — right-click → Open or xattr -cr "DeepSeek Harness Desktop.app" at your own risk. Also see the homepage waitlist and overview.

This site is an independent community page. We are not affiliated with or endorsed by DeepSeek.