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.
Install DSH Desktop step by step
Thirteen screenshot-verified steps for the most-starred community client: the real download endpoints, the macOS DMG and the Windows NSIS wizard, first run, and four checks on the file you actually got.
Ollama & free models
Point DeepSeek Harness at OpenRouter free models or a local Ollama server and run sessions without a paid API key.
Run dsh on free models via OpenRouter
Skip the DeepSeek key, add OpenRouter's :free models in settings, and verify the setup with a real README task — a screenshot-checked walkthrough.
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.
Make DSH see images: two working ways
Way one: plug a GLM vision model into DSH. Way two: install the free dsh-vision-router plugin — paste a screenshot, get a real answer.
Connect DSH to WeChat and Feishu
Install dsh-im, scan a QR code, and chat with your harness from WeChat or Feishu — countdowns, phone-side approval and bot replies on real screens.
Office work in DSH: one prompt to PPT
Install dsh-univer-office, ask for a stock-market deck in one sentence, and watch a six-slide PPT get researched, built, reviewed and presented.
Merge Excel sheets with one prompt
Three expense sheets, 1,800 rows: rules, mapping and acceptance in a single prompt — illustrated walkthrough.
Mini games inside DeepSeek Harness
Install the mini-games panel, play Tetris or Minesweeper while the model works, and keep an eye on your balance.
Build a plugin by chatting (no code)
Idea → co-created spec → Creator mode build → version approval: a full plugin born from one sentence.
Run dsh on a server 24/7
Thirteen screenshot-verified steps from an empty VPS to an always-on DeepSeek Harness: SSH and browser console, custom models with context windows, plugins without leaving the tab, and a public URL for every build.
Create a reusable dsh Skill
Seven screenshot-verified steps from a tuned workflow to SKILL.md: where the file lives, what goes in name, description and whenToUse, and how to test it with a planted secret.
Build a business agent preset, verified end to end
Twelve frame-verified steps: acceptance criteria first, then a helper plugin, one permission approval, and a checked 1,800-row summary.
Context compaction & long tasks
How the 80% trigger, /compact and tool-result pruning keep long sessions from falling apart
dsh-tui terminal onboarding
Profiles, the skill manager and background jobs in the community terminal, frame by frame
Voice plugins: speak and listen
Dictate with local speech-to-text, then let dsh talk back with TTS — both verified on real setups
How to find dsh plugins (illustrated)
The in-app market, the awesome-dsh directory and the official Plugins manager — three finding paths verified frame by frame
Turn Obsidian into a dsh knowledge base (illustrated)
API key → workspace → AGENTS.md skeleton → notes in your own vault’s style: a 7-step integration walkthrough, every frame deep-linked
Fully automatic video generation with dsh + ComfyUI (illustrated)
A prompt template becomes an installed skill, a ComfyUI workflow renders a 15-second 9:16 film, GPU memory is freed in a background task — frame-verified end to end
dsh raw-html rendering: make chat answers visible (illustrated)
The raw-html plugin turns plain replies into HTML cards, charts, canvas animations and themed style systems — with trusted-mode script gating explained
Track dsh balance with the whale widget
Link dsh-whale-widget into the web profile and configure the corner bubble that shows your remaining DeepSeek balance, today's spend and a refresh countdown.
Beautify dsh with AI-made themes
The wallpaper-plugin walkthrough: the appearance three-state switch, the preset studio with its layer-composite wallpaper editor, and one chat message that spins a full light-and-dark theme.
Essential dsh plugins, hands-on
The must-install walkthrough: put a searchable market inside the manage panel, vet with stars and a script audit, then run vision, sidebar and background-task plugins — every step a verified video still.
Verifiable architecture diagrams
Let the agent draw your system map instead of a throwaway sketch: install the archify skill, ask in one sentence, and read the 9/9 validation receipt before you trust the picture.
dsh creator mode: chat a custom agent preset
From the preset dropdown and one sandbox approval to the mount check, a coffee-shop analysis and an Excel formula audit — creator mode end to end in 9 frame-verified screenshots.
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.
Set up MCP servers in DeepSeek Harness
Wire an MCP server into dsh: the Claude Code / Codex field mapping, the registered-server cards, the mcpServers block you paste, and a real dsh session calling the Amap Maps MCP.
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.
chinese tutorials
Chinese-language deep-dive tutorials
Systematic Chinese-language learning resources curated by the community — read them alongside our own tutorial to understand DeepSeek Harness concepts, installation and the plugin system from zero.
Systematic Chinese tutorial repo
A chapter-by-chapter Chinese tutorial repository maintained by ht426 — install, core concepts and the plugin system, built for learning DSH end to end.
Read the guideBeginner-friendly explainer guide
JingHao-Leon's hand-holding guide: plain-language mental models and a learning path for DeepSeek Harness — ideal if you are new to agent harnesses.
Read the guideDSH blue-book docs site
The dsh.hicyou.com blue-book documentation site: quick reference, field notes and advanced usage, updated as new versions ship.
Read the guideDeepSeek Harness: the 10-step tour
From git clone to headless mode — install, providers, presets, creator-mode plugins, sandboxing and receipts, in one guided walkthrough.
Read the guidefaq
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.