DeepSeek Harness (dsh) hit 100K stars in two days, but "developer preview + plugin architecture" means a wrong approach wastes hours. This SOP lays out the shortest path from zero: environment prep -> one-line launch -> mode selection -> trajectory replay -> first plugin -> cost control, plus 5 pitfalls. News background in the Harness hotspot; tool selection in the Agent Harness comparison.
Boundaries: steps assembled from the official README and launch docs (as of 2026-08-15); v0.1 iterates fast - commands and UI per the official repo; this is a curated guide from official docs and public tutorials, not a keystroke-by-keystroke log.
Step 1: Environment Prep (10 minutes)
dsh is a Node.js project; prerequisites are just two things:
# 1. Node.js (LTS recommended; confirm with node -v)
node -v
# 2. A DeepSeek platform API key (for the model plugin; other providers' keys work too)
# Export as an environment variable; the UI guides you on first launchTwo pre-checks: ensure npm registry reachability (switch to a mirror if needed) and model API endpoint connectivity; source-based installs additionally need pnpm.
Step 2: One-Line Launch (2 minutes)
npx @deepseek-ai/dsh webThe Web UI opens by default at http://127.0.0.1:3080. On first launch, configure the model plugin per the UI prompts (API key, model choice), then start your first session. From source:
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh webNote the Web UI is a local service (127.0.0.1); opening it in a browser is its designed form, not an unfinished product - the community gripes about the spartan look, but the features are all there.
Step 3: Pick a Mode per Task (5 minutes to learn, benefits for life)
| Mode | Tool surface | When to use |
|---|---|---|
| Standard | Full set: file edit, shell, file/web search, skills, planning, sub-agents | Default for daily dev tasks |
| Code (PTC) | All of Standard + Code Mode SDK | Complex tasks where the model composes many tools in one TypeScript program |
| Minimal | Persistent bash + str_replace_editor only | Evaluating raw model capability; the official Code Agent benchmark environment |
| Creator | Runtime inspection + plugin experiments | Developing/debugging your own plugins and presets |
Mnemonic: work in Standard, orchestrate in Code, test models in Minimal, write plugins in Creator.
Step 4: Use Trajectories to Debug a Runaway Agent
dsh writes system prompts, chain of thought, tool calls and results, sub-agent dispatch, and every context injection to an append-only session log. In the trajectory view you can filter by source and resume, fork, search, and replay any run. Three practical uses:
- Wrong result -> replay the trajectory to locate which tool call introduced the drift, instead of rerunning on luck
- Want to try a different path -> fork from a node and compare both paths on cost and outcome
- Prompt review -> check whether the system prompt and context injections took effect as intended
Step 5: Your First Plugin
Plugins are dsh's core extension mechanism; the official route: tag your plugin repo with the dsh-plugin topic for discoverability (~300 plugins in the ecosystem so far). Development flow: inspect the live runtime in Creator mode, experiment with Cordis plugin combinations, then solidify the winners into your own preset mode. Make your first plugin minimally useful: wrap one internal tool you use daily (a query, a deploy, a notification). Don't start by rewriting the loop or orchestration.
Five Pitfalls (Read Before Doing)
- Don't weld production onto v0.1: the official warning of compatibility-breaking changes is explicit; core plugins and APIs keep moving. Production waits for a stable release; today's positioning is experiments and learning.
- Audit third-party plugins before installing: ~300 community plugins with no review mechanism - read the source, run in a sandbox, never hand model credentials to an unknown plugin.
- Budget before you run: the companion V4-Pro-0813 is strong but metered, and DeepSeek raised peak-hour prices (V4-Flash output ¥2->¥9/M). Multi-tool long tasks amplify token burn linearly - price it on small tasks first.
- Two network chokepoints: npm package pulls and model API connectivity - either failing stalls startup; test both before debugging anything else.
- The spartan UI is not a bug: a local Web UI in the browser (127.0.0.1:3080) is the designed form; don't wait for a "native app." For a mature terminal experience today, see the Agent Harness comparison.
FAQ
Q1: What's the minimum environment for DeepSeek Harness?
A1: Node.js (LTS recommended) + one model API key (DeepSeek or another provider). The fastest path is npx @deepseek-ai/dsh web with no cloning; source installs additionally need pnpm for pnpm install && pnpm run build && pnpm dsh web.
Q2: How do I choose among the four run modes? A2: Mnemonic: "work in Standard, orchestrate in Code, test models in Minimal, write plugins in Creator." Standard is the full-toolset daily default; Code (PTC) uses the Code Mode SDK to compose multi-tool operations in a single TypeScript program; Minimal keeps only bash + file editing - the official benchmark environment; Creator experiments with plugins at runtime to build new presets.
Q3: The Web UI opens as a browser page - did the install fail?
A3: No, it succeeded. dsh's interface is a local Web UI; after npx @deepseek-ai/dsh web it serves at http://127.0.0.1:3080 by default, and browser access is by design. The community gripes about the look, but sessions, trajectories, and plugin management all live in that UI.
Q4: How is the trajectory feature actually used? A4: Every run's events (system prompts, chain of thought, tool calls and results, sub-agent dispatch, context injections) go into one append-only log; the trajectory view filters by source and supports resume, fork, search, and replay. Typical flow: replay to locate the drifting tool call on a wrong result; fork mid-run to compare paths; audit prompt injections.
Q5: Is it worth migrating daily development to dsh now? A5: Not yet. v0.1 is a developer preview with official breaking-change warnings, unreviewed plugins, and a builder-oriented experience. The sensible posture today: work in Claude Code/OpenCode (see our DeepSeek × Claude Code SOP for the cost-saving DeepSeek setup) and treat dsh as a learning and experiment platform until its API stabilizes.
References
- GitHub: deepseek-ai/deepseek-harness README (install commands, port, developer-preview warning, dsh-plugin topic, Discord)
- DeepSeek official launch docs: four run modes, append-only trajectory, Cordis plugin architecture
- NetEase Tech (2026-08-13): install methods and the four modes
- Zhihu hands-on posts (2026-08-14):
npx @deepseek-ai/dsh weblaunch experience and UI form - EastMoney/Sina Finance (2026-08-14): V4-Flash peak-hour price hike (output ¥2->¥9/M)
Curated from official docs and public tutorials (2026-08-15), not a step-by-step log; commands and UI per the official repo. Related: Harness hotspot | Agent Harness comparison | DeepSeek × Claude Code SOP