DeepSeek Harness: Fix npx Failures and Port 3080

This is not another quickstart

The npx quickstart assumes npx @deepseek-ai/dsh web eventually prints a URL. This article is for the other half of first-run traffic: the terminal hangs, 3080 never answers, or the UI loads then every chat dies on API errors. Pair it with the searchable checklist on Troubleshoot — here we explain order of checks so you do not thrash three variables at once.

Upstream still owns the exact flags. When README and this page disagree, the README wins.

Ladder 1 — Prove Node before you touch DSH

Upstream preview docs ask for Node.js ^22.19.0 or >=24.0.0. Run node -v and npm -v in the same shell you will use for npx. nvm/fnm versions selected in another window do not count.

Symptoms of the wrong engine: package fetch starts, then engines checks fail; or node is missing entirely. Fix PATH, reopen the terminal, and only then retry. Do not “upgrade Node inside the hanging npx process.”

Ladder 2 — Make @deepseek-ai/dsh fetchable

First run downloads a large dependency tree. Failures here look like timeouts, 404s, or an ancient cached rc.

1. Confirm the scope: @deepseek-ai/dsh — typos waste half a day.
2. If a corporate mirror is stale, retry with --registry=https://registry.npmjs.org.
3. Clear a poisoned npx cache only after you have ruled out network and scope typos.

Keep the terminal open. Killing the process mid-download leaves you debugging a half-written cache.

Ladder 3 — Port 3080 is a local socket problem

The Web UI commonly binds http://127.0.0.1:3080/. If something else owns 3080, the process may start while the browser never shows DSH.

• Find the occupant (OS-specific: netstat / lsof / Resource Monitor).
• Stop it, or start with the port flag documented upstream (community reports often use --port on dsh web).
• First tests stay on localhost. Binding 0.0.0.0 is a security decision, not a convenience tip.

Blank page with a healthy terminal: try a clean browser profile — extensions sometimes block local scripts.

Ladder 4 — UI up, chat dead (keys and credentials)

Local UI is usually a control plane, not offline weights. DeepSeek-routed calls need a platform API key. Check model id, quota, and accidental spaces when pasting.

Headless/CLI paths may read $DSH_HOME/.credentials.yaml (often ~/.dsh/.credentials.yaml). On Unix, overly open file modes can make the runtime refuse the file — chmod 600 is a common fix. This independent site never issues keys.

Ladder 5 — pnpm missing when plugins enter the story

Even if you launched via npx, dsh plugin add often shells out to pnpm. A missing global pnpm looks like “install failed” after the UI already worked. Install pnpm, ensure its bin is on PATH, then retry add — see the plugin guide.

What not to do

• Do not point the first workspace at your entire home directory while debugging ports.
• Do not stack three new community plugins while 3080 is still flaky.
• Do not treat a blog from last week as CLI law — pin a preview version for evaluation.

Where to go next

1. Healthy install narrative: npx quickstart.
2. OS one-liners: Install.
3. Itemized symptoms: Troubleshoot.
4. After it runs, pick a mode before you drown in packages.