learn
DeepSeek Harness Guide: Install, Configure & Build Plugins
A practical guide for users and plugin developers: run the harness, understand profiles and presets, install plugins safely, and build your own.
Install globally, start the web profile, then paste your API key — skipped if your env already has one. Everything else is a plugin.
What this dsh guide covers
DeepSeek Harness (dsh) is DeepSeek's open-source agent runtime: the model is the brain, the harness is the body, and every part of that body is a plugin. This DeepSeek Harness guide is the missing manual — no marketing, no fluff, just how the harness actually fits together.
Work through the guides in order the first time, or jump straight to the section you need.
- /01Run dsh — install, first task, the four modes
- /02Understand the assembly — bundles, profiles, patches, presets
- /03Stay safe — sandbox tiers, approvals, secrets
- /04Join the ecosystem — find, install and publish plugins
guides
Start here
What the harness is, and a five-minute first run.
What is DeepSeek Harness?
Agent = Model + Harness, profiles and patches, presets and the four modes.
What Are dsh Plugins?
What a dsh plugin actually is, what it can change, and how the plugin tree fits together.
Quickstart: run dsh in 5 minutes
Install DeepSeek Harness, start the Web UI, run your first task, and pick the right mode.
DeepSeek Harness: the 10-step tour
From git clone to headless mode — install, providers, presets, creator-mode plugins, sandboxing and receipts, in one guided walkthrough.
From spec to shipped: a real project in DSH
The full delivery loop — interrogate requirements into CONTEXT.md and ADRs, turn them into a PRD, slice GitHub issues, then develop and merge task by task.
DeepSeek Harness subagents: run agent teams in parallel
Spawn a five-subagent squad, monitor each child from the header, read completion reports and pin models per subagent — frame-verified steps
Replay & review your dsh sessions
Open the trajectory viewer, read structured receipts, locate failures by turn and branch a new chat from any step — illustrated walkthrough
Install DeepSeek Harness on Windows
A 10-step, screenshot-by-screenshot Windows walkthrough: Node.js, npm install, the Web UI on port 3080, your API key.
Install DeepSeek Harness on Mac
A screenshot-verified macOS walkthrough: one npx command, no API key required, provider connected by step seven.
Install DeepSeek Harness on Linux
A frame-verified Linux walkthrough: Node.js, one npx command, provider setup — plus a WSL section for Windows users.
DeepSeek Harness desktop app: official vs community
The official Web UI, community clients like DSHDesktop, and a safe-download checklist.
Ollama & free models
Point DeepSeek Harness at OpenRouter free models or a local Ollama server and run sessions without a paid API key.
Switch models & custom providers
Change models mid-session, add NVIDIA NIM or Ollama as a custom provider, and verify what you're really talking to.
Track dsh token usage & costs
Read the per-request receipt, spot context hogs in Trajectory, then cut costs with model tiers and usage plugins.
Update DSH & plugins
Verified update commands: check your version, upgrade the dsh CLI, refresh plugins from the terminal or the Web UI market, and roll back safely.
Uninstall DSH plugins & clean up
Remove a plugin, uninstall the dsh CLI, and wipe ~/.dsh for a truly clean slate — verified against real terminal output.
Remote access from your phone
Expose the dsh web UI with a free ngrok tunnel and drive your home agent from any outside browser — no companion app, eight verified steps.
The four modes: Standard, PTC, Minimal, Creator
What each agent preset includes, when it wins, and how to build a preset of your own in Creator mode.
Plan mode: /plan, review, approve
How the /plan command works in DeepSeek Harness — the orange plan marker, the exit_plan_mode review card, and how it differs from running direct, in ten verified screenshots.
dsh vs Claude Code
An honest side-by-side: openness, pricing, model freedom, and extensibility.
DeepSeek Harness vs OpenClaw
Both open source, both MIT — but one is an agent runtime you assemble and the other an assistant in your chats. Six dimensions compared, with a verdict.
DeepSeek Harness vs Cursor
An honest editor-vs-harness comparison: pricing, model freedom, the plugin ecosystem, and running both together.
DeepSeek Harness vs Gemini CLI
Free 1M-token context versus a harness where the model is a plugin — six-dimension comparison, verdicts, and how to use both together
Free Claude Code Alternatives
Open-source agentic coding tools that cost nothing — and where dsh fits in.
Plugins vs Skills: the Difference
One swaps harness capabilities, the other teaches the agent. Side-by-side comparison with real screenshots and two worked examples.
Install skills the right way
Seven verified steps from mkdir to a trajectory receipt: create .dsh/skills, write SKILL.md, confirm the catalog injection — no restart needed.
Best DeepSeek Harness skills to install
Which skills are worth installing and what each one actually does once enabled — demonstrated step by step
AI novel-writing workbench for DeepSeek Harness
Mount a three-pane fiction workbench: outline deduction, chapter drafting, character tracking and AI-cliche review — your drafts stay on your machine.
Turn a novel into a short drama with storyboards
Adapt a novel into episodes, auto-write dialogue and twists, generate shot-by-shot storyboards with image-model prompts, and export structured data.
Configure & build
Profiles, presets, and writing your own plugins.
Profiles, patches & presets
How a dsh process is assembled from stacked config layers — and how to make it yours.
Build a custom DSH agent preset
Use Creator mode to design your own DeepSeek Harness preset, wire in plugins, and read the run stats — verified frame by frame.
Plugin development 101
How a Cordis plugin is built, published and listed — with the official anchors.
Create your own DSH plugin
The full build walkthrough: minimal contract, Config Schema, profile install, and a live MCP Apps demo to verify it works.
Troubleshooting & error encyclopedia
Symptom → cause → fix: install failures, pnpm workspace allowlist errors, cordis.patch.yml conflicts, bundle format errors, and profiles that won't apply.
Safety & ecosystem
Sandboxes, plugins you can trust, and the wider dsh world.
Sandboxes, approvals & secrets
The dsh safety model: three sandbox tiers, approval policies, guards, and where your secrets go.
Installing plugins you can trust
How plugin installation actually works in dsh, plus a checklist for vetting third-party code.
Must-Have dsh Plugins
Twelve plugins worth installing first — picked from the whole catalog, across every category.
The dsh plugins ecosystem
Official packages, community orgs, the dsh-plugin topic, and how this DeepSeek Harness plugins catalog stays fresh.
Plugins API & RSS
Public read-only JSON API and RSS feed for the plugin catalog — no API key required.
faq
Frequently asked questions
The short answers everyone looks for in a DeepSeek Harness guide.
What is DeepSeek Harness?
DeepSeek Harness (dsh) is DeepSeek's open-source agent framework: the runtime that turns a model into an agent that reads files, runs commands and searches the web. Its defining idea is that everything — tools, model adapters, the UI, even the main loop — is a plugin.
Read the guideIs DeepSeek Harness free?
The harness itself is open source (MIT). Model usage is separate: you connect your own provider (for example the DeepSeek API), and that provider bills you directly for tokens. Most community plugins are open source too — check each repo's license.
How do I install it?
Install the CLI globally (npm install -g @deepseek-ai/dsh), run dsh --profile web to open the Web UI, and paste your API key on the page — skipped if your environment already has one. A headless CLI, Python and TypeScript SDKs, and an ACP server are also available.
Read the guideHow do I install a dsh plugin?
In dsh, installing usually means adding an entry to your profile or patch config — each plugin's README documents its own install line. The plugin is then loaded into the plugin tree, and removing the line removes everything it registered.
Read the guideIs dsh the same as Claude Code or Codex?
Not quite. Claude Code and Codex ship a ready-made agent; DeepSeek Harness ships an agent runtime you assemble, where plugins replace or extend any part. Same job family, different philosophy.
How do I get my plugin listed here?
Add the dsh-plugin topic to your public repo, and open a PR to the community lists this directory syncs from. The topic route is automatic; curated entries add a category and description.
Read the guideReady to go further?
Browse the plugin directory, or ship your own plugin into the ecosystem.