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.
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.
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.
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.
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.
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.
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.
Plugin development 101
How a Cordis plugin is built, published and listed — with the official anchors.
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.