DeepSeek Harness on macOS: Homebrew, PATH, Full Disk Access

macOS is not a different product

DeepSeek Harness on macOS is still Node.js plus npx @deepseek-ai/dsh web, then a browser on http://127.0.0.1:3080/. The command matches the install checklist and the npx quickstart. What changes is the Mac environment: Homebrew vs official pkg vs nvm, which Terminal session owns PATH, and whether macOS privacy (TCC) silently blocks workspace writes.

This is the macOS-only companion to DeepSeek Harness on Windows. If the process never binds or 3080 is taken, jump to the npx / port 3080 ladder instead of rereading OS one-liners.

Upstream still owns exact flags. When the official README disagrees with this page, the README wins. Official product framing also lives on deepseek.com/harness — this portal is the operator rewrite for local npx, not a second desktop storefront.

Pick one Node install path and stick to it

On the same Mac you can have Homebrew Node, an official nodejs.org pkg, nvm/fnm, and a stale Xcode CLI node that is too old. Each Terminal tab can see a different binary — or none.

1. Decide how you will manage Node for the first hour. Homebrew (brew install node) or the official pkg are fine; nvm/fnm are fine if you nvm use / fnm use in the same window that runs npx.
2. In that window only, run node -v and npm -v. Upstream preview expects Node ^22.19.0 or >=24.0.0.
3. Prefer ^22.19.0 or a current >=24.2-class release when community notes warn about silent-exit quirks on early Node 24.0/24.1 — always re-check upstream engines before you chase “Mac-specific” ghosts.
4. Do not mix: install with Homebrew, then launch npx from a tab whose PATH still points at Node 18 from an old nvm default.

Apple Silicon vs Intel rarely changes the npx command. It changes which binary you downloaded. If node -v works in one architecture slice and fails in another (Rosetta Terminal vs native), fix the Node install — do not invent a second Harness package.

Launch from a disposable project folder

1. Install or select Node in range, then quit and reopen Terminal so PATH refreshes.
2. cd into a disposable clone (for example ~/scratch/dsh-demo), not your entire home directory.
3. Run:

npx @deepseek-ai/dsh web

Keep the terminal open. Killing it stops the local server. First-run downloads can look like hangs on slow networks; registry and cache issues belong on Troubleshoot.

Full Disk Access is not a day-one checkbox

macOS may prompt for folder access when the agent touches the workspace. That is expected. Full Disk Access (System Settings → Privacy & Security) is a wider grant — useful later for odd tooling, dangerous as a first-run “just in case.”

• Start with a disposable repo the agent is allowed to read/write.
• If writes fail while the UI looks healthy, check TCC prompts for Terminal / your browser helper — not only the chat error string.
• Do not point the first session at ~ or Documents mixed with iCloud Drive sync while you are still learning Trajectory.
• Corporate MDM profiles that block unsigned npm scripts look like product bugs; verify Node and registry first.

After the UI loads: paste a DeepSeek platform API key in settings, pick the disposable workspace, send a low-risk prompt (list top-level files). Local UI is usually a control plane, not offline weights.

Port 3080 on loopback

Default Web UI is http://127.0.0.1:3080/. Find an occupant with:

lsof -iTCP:3080 -sTCP:LISTEN

Stop that process or start with the port flag documented upstream. First tests stay on localhost — binding 0.0.0.0 is a security decision. Blank page with a healthy terminal: try a clean browser profile; extensions sometimes block local scripts.

Desktop wrappers are optional, not the default path

Community and official desktop installers appear in search for “DeepSeek Harness Mac.” They may skip Node for some users. This article documents the npx / CLI Web UI path that matches Install. If you use a packaged app, still keep a narrow workspace and treat shell tools as software review — see the plugin security checklist.

What this article is not

• Not a second full quickstart — narrative install stays in npx quickstart.
• Not a decision tree for every launch failure — use Fix npx and port 3080.
• Not the Windows PATH article — that is DSH on Windows.
• Not an endorsement of any third-party Mac App Store clone.

Where to go next

1. OS one-liners and verify steps: Install.
2. First-hour script: npx quickstart.
3. Symptom ladder: Troubleshoot and the port 3080 article.
4. After it runs, pick a mode before stacking community plugins.