Six preflight checks before installing DeepSeek Harness
A failed DeepSeek Harness install is usually not the install command's fault; one of six preconditions was already false. Two minutes of checks beats rolling back a half-finished install.
Why preflight a DeepSeek Harness install first
Install failures split in two: the environment is short of something, or the install method is wrong. The second is fixed by changing commands; the first fails identically no matter how many commands you try.
Preflight converts "failed halfway" into "knew before starting". On someone else's machine, a CI image, or a fresh server, environment differences are larger than expected.
Six items listed together beat checking whichever one you happen to remember.
Run all six, then install. Reference:
| Item | Command | Passing | If it fails |
|---|---|---|---|
| Node | node -v | Prints a version | Command not found |
| Package managers | npm -v, pnpm -v | At least npm works | Plugins report pnpm missing |
| Disk | df -h ~ | Enough free space | Unpack aborts, cache fills |
| Permissions | test -w ~ && echo ok | Prints ok | Config and sessions cannot be written |
| Network | npm ping | Returns PONG | Timeouts, certificate errors |
| Port | lsof -i :3080 | Empty or known owner | Startup fails, install is fine |
The first three decide whether it installs; the last three decide whether it runs. Do not stop after three.
Runtime checks for dsh: Node, npm, pnpm
A mismatched version is more common than an outdated one. In order:
- Run
node -vand record the version this terminal actually uses; - Run
which -a nodeto reveal multiple runtimes (nvm, Homebrew, system); - Run
npm -vandnpx -vand confirm they come from the same install; - Run
pnpm -v; install it now if missing, so plugin work is not blocked later; - Open a brand-new terminal and repeat, confirming the config applies to new windows.
Why the new terminal matters: PATH changes take effect only after a reload, so an old window's result does not describe the next one. This is where most "installed but command not found" reports originate (source).
System checks for dsh: disk, permissions, port
These three never complain until they matter, then they are the hardest to diagnose.
- Disk:
df -h ~. The npx cache, per-profile dependencies, and a desktop runtime are three separate footprints; low space interrupts unpacking. - Permissions:
test -w ~ && echo ok. Not ok means the user cannot write home, so config lands elsewhere and later changes appear to be ignored. - Port:
lsof -i :3080. Output means something is bound; decide whether to change the port or stop that process before you start.
A busy port does not affect installation. People have uninstalled unrelated services under the belief that it does.
Network checks for dsh: registry, proxy, certificates
Network problems show up in three forms, so test them separately.
- Reachability:
npm ping; PONG means the registry answers; - Proxy:
env | grep -i proxy; confirm the proxy matches the network's actual egress; - Certificates:
curl -I https://registry.npmjs.org; TLS errors indicate a missing or replaced intermediate certificate; - Mirror: a company mirror may lag or miss packages; temporarily switch to the official registry to compare.
Certificates are the quiet one. They rarely say "network unreachable"; they emit TLS errors that look like a broken installer.
Reading dsh preflight results and running all six at once
Each failure maps to a class of downstream symptom.
- Node missing → command not found; fix PATH, do not reinstall DSH;
- pnpm missing → plugin stage fails; install pnpm and retry;
- Permissions → install looks fine but config is unwritable; fix directory permissions;
- Network or certificate → downloads abort; fix the network, then re-run the install.
Preflight classifies; it does not repair. Each class has its own fix, so do not change all six at once; putting all six into one script lets every teammate start from the same baseline.
#!/usr/bin/env bash
echo "node: $(node -v 2>/dev/null || echo MISSING)"
echo "npm: $(npm -v 2>/dev/null || echo MISSING)"
echo "pnpm: $(pnpm -v 2>/dev/null || echo MISSING)"
df -h ~ | tail -n 1
test -w ~ && echo "home writable" || echo "home NOT writable"
npm ping >/dev/null 2>&1 && echo "registry OK" || echo "registry FAIL"
lsof -i :3080 >/dev/null 2>&1 && echo "3080 BUSY" || echo "3080 free"
Six lines of output; stop at the first anomaly. The script does not install anything, it only keeps you from repeating an install that cannot succeed.
Next steps: install DeepSeek Harness after preflight
Pick an install method only after all six pass. For a full first install, read installing DeepSeek Harness for the first time. For environment errors, read install and environment errors. For port conflicts, read port 3080 conflicts. For a missing command, read dsh command not found.
Sources: DeepSeek Harness docs, dsh CLI README, deepseek-harness repository
FAQ
To install DeepSeek Harness, check six things in order: node -v prints a version, npm works, home is writable, there is disk headroom, the registry answers npm ping, and port 3080 is either free or knowingly taken. All six passing is the minimum bar.
The base DeepSeek Harness install works with npm alone. pnpm matters when you manage plugins, because profile plugin operations are forwarded to it. Check pnpm -v before you need it, not in the middle of a plugin install.
No; a busy port only blocks DeepSeek Harness startup, not installation. Decide early whether to change the port or stop the other process, but do not reinstall just because startup fails.
Check TLS and proxies when dsh downloads fail after a successful npm ping. A ping can succeed over a cached path while downloads fail on certificate validation; curl -I against the registry surfaces certificate errors that npm reports as generic network failures.
Related Terms
- preflight
- A preflight is a short set of checks run before an install so that environment problems surface early, rather than halfway through a download.— DeepSeek Harness docs
- PATH
- PATH is the list of directories a shell searches for executables; a runtime installed outside those directories behaves as if it were missing.— dsh CLI README
- registry
- A registry is the package source npm resolves against, public by default and often mirrored inside a company network.— npm docs
- DSH_HOME
- DSH_HOME is the data root for DeepSeek Harness, defaulting to ~/.dsh, holding profiles, sessions, logs, and credentials.— DeepSeek Harness docs
Sources
- DeepSeek Harness docs· deepseek-harness
- dsh CLI README· deepseek-ai
- deepseek-harness repository· deepseek-ai