--- title: "How to Use DeepSeek Harness: Install, Set Up, and Run Your First Agent" description: "Install DeepSeek Harness (dsh) with one command: npx @deepseek-ai/dsh web. Then connect a model key, pick a workspace, and run your first agent session. Includes the four runtime modes explained, a plugin starter pack, and what the official docs don't cover yet." source: https://docs.kanaries.net/topics/AICoding/deepseek-harness-how-to-use updated: 2026-08-26 site: Kanaries Docs --- # How to Use DeepSeek Harness: Install, Set Up, and Run Your First Agent **The one-command answer:** if you have Node.js installed, this starts DeepSeek Harness with its web UI: ```bash copy npx @deepseek-ai/dsh web ``` The server starts on `http://127.0.0.1:3080` and opens your browser. From there: **Settings → Models** to paste an API key, **Choose workspace** to point it at a project folder, then give it a first task. That is the whole loop. The rest of this guide covers each step in more detail, the four runtime modes, and the plugin ecosystem — which is the actual reason this project passed 196k GitHub stars two weeks after release. > All commands and settings in this guide come from the official README, deepseek.com/harness, and the developer docs as retrieved on August 26, 2026. DeepSeek Harness is a **developer preview** and the team explicitly warns about ongoing breaking changes — if something below stops matching, trust the [repo README](https://github.com/deepseek-ai/deepseek-harness) over any tutorial, including this one. ## What DeepSeek Harness actually is *DeepSeek Harness (`dsh`) is DeepSeek's open-source agent framework, released on August 13, 2026 under the MIT license.* Its design slogan is "Everything is a Plugin," and that is meant literally: models, tools, skills, sessions, sandboxes, storage, agent loops, scheduling, and even the UI are all plugins running on [Cordis](https://github.com/cordiverse/cordis), an open-source plugin runtime. You can swap or recompose any of these in configuration without touching the framework source. Two practical consequences follow from that architecture: - **It is a coding agent out of the box** — file editing, shell, search, and workflow planning ship in the default (Standard) mode, so you can use it the way you would use Claude Code or [OpenCode](https://docs.kanaries.net/topics/AICoding/opencode-how-to-use). - **It is also a chassis for building your own agent** — if you want a different sandbox, a different model router, or a different loop, you replace that one plugin instead of forking an application. Everything the model sees is written to an append-only session log — system prompts, reasoning, tool calls and results, subagent scheduling, every context injection. If you have ever tried to debug an agent that behaved strangely and had no record of what it actually saw, that single feature explains a lot of the project's early traction. ## Step 1 — Install **Prerequisite: Node.js.** The official quick start assumes a working `node`/`npx` on your PATH and nothing else. **Path A — npm (recommended for first contact):** ```bash copy npx @deepseek-ai/dsh web ``` `npx` downloads the package on first run, so expect the first launch to take noticeably longer than later ones. Add `--no-open` if you want the server without a browser window (for example on a remote machine): ```bash copy npx @deepseek-ai/dsh web --no-open ``` **Path B — from source (if you want to build plugins or track main):** ```bash copy git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness pnpm install pnpm run build pnpm dsh web ``` Which one should you pick? | Your situation | Pick | Why | | --- | --- | --- | | Trying it out, normal usage | `npx` | Zero setup, always fetches a published build | | Writing or modifying plugins | Source | You need the workspace to develop against | | Pinning against breaking changes | `npx @deepseek-ai/dsh@` | Developer preview moves fast; pinning a version keeps a working setup working | | Benchmarking / CI | Source, Minimal mode | Reproducible build plus the two-tool minimal runtime (see modes below) | ## Step 2 — Connect a model The web UI starts without any model configured. To make it usable: 1. Open **Settings → Models**. 2. Paste credentials from [platform.deepseek.com](https://platform.deepseek.com/) (or another supported provider — the models settings page covers alternative providers). 3. Save. Per the official docs, the model route becomes usable immediately, without restarting the server. Because models are plugins like everything else, provider choice is a configuration decision, not an installation decision. This matters if your team is standardizing on one vendor today but wants the option to reroute later — the point of the harness architecture is that rerouting is a config edit. ## Step 3 — Pick a workspace and run a first task 1. In the web UI, click **Choose workspace** and add a project directory. 2. Start a session. 3. Give it a read-only first task before you let it edit anything. The official quickstart's own suggestion is a good one: > "Summarize this repository and identify its main packages" The agent supports file operations, command execution, task delegation, and workflow planning, with approval prompts before actions. Treat the first session as a calibration run: you are checking that it reads the right workspace, that approvals appear, and that the session log captures what happened — before you grant it anything destructive. This is the same discipline we recommend for every terminal agent (see [How to Use Codex](https://docs.kanaries.net/topics/AICoding/codex-how-to-use) for the equivalent ritual there). ## The four runtime modes, and when each one is right DeepSeek Harness ships four runtime presets. This table is the decision most tutorials skip: | Mode | What it is | Use it when | | --- | --- | --- | | **Standard** | Full coding agent: file editing, shell, search, workflows | Default. Day-to-day coding-agent work | | **Code** | Standard plus model-generated TypeScript orchestration for multi-step operations | Long multi-step refactors or pipelines where you want the model to compose operations programmatically instead of tool-call-by-tool-call | | **Minimal** | Two tools only: bash and editor | Benchmarking models fairly, or reproducing a bug without plugin noise | | **Creator** | Adds runtime inspection and plugin experimentation | Developing plugins; inspecting what the runtime is actually doing | A useful mental model: **Standard is for using the agent, Creator is for changing the agent, Minimal is for measuring the model.** If you are evaluating whether DeepSeek's models are good enough for your workload, Minimal mode is the honest way to test — the harness stops helping and you see the raw model. ## Plugins: where the real leverage is The plugin ecosystem is growing faster than any comparable agent framework we have tracked. As of August 26, 2026, the [`dsh-plugin` topic on GitHub](https://github.com/topics/dsh-plugin) lists **11,944 public repositories** — two weeks after release. A starter pack worth knowing about, by current star count: | Plugin | Stars | What it does | | --- | --- | --- | | [awesome-dsh-plugin](https://github.com/topics/dsh-plugin) | 12.8k | Curated index — start here to browse the ecosystem | | open-design | 91.6k | AI design: prototyping, landing pages, dashboards, HTML/PDF/PPTX export | | ruflo | 69.4k | Multi-agent swarm coordination with adaptive memory and RAG | | DeepSeek-Reasonix | 35.2k | Terminal-based coding agent tuned for DeepSeek models | | OpenViking | 33.4k | Self-evolving context database: agent memory, knowledge, skills | | distilly | 24k | Turns expertise into reusable agent skills | | WeKnora | 20.7k | Documents → queryable RAG knowledge base | | dsh-desktop | 20.4k | Desktop app for the DSH ecosystem | Discovery convention: plugins tag themselves with the `dsh-plugin` topic on GitHub, so that topic page is the closest thing to a package index right now. Expect churn — star counts in a two-week-old ecosystem measure attention, not maturity. Check an actively maintained plugin's issues before wiring it into anything you care about. ## What the official docs don't cover yet (honest gaps) This is a developer preview and the documentation is thin in places. As of this writing: - The **quickstart page defers installation to the README** — if a step here and a step in the docs disagree, the README is the source of truth. - **Configuration file formats are underdocumented.** Model setup is done through the web UI (Settings → Models); if you need file-based, reproducible configuration, expect to read plugin source or the `apps/cli` README for the CLI modes. - **No pricing page exists for the harness itself** — the framework is MIT and free; your cost is whatever model API you connect (DeepSeek's platform pricing, or your other provider's). - **Breaking changes are promised, not just possible.** If you build anything durable on it this month, pin versions. We have deliberately not included a troubleshooting matrix in this guide: the failure modes of a two-week-old preview change weekly, and copying stale error fixes from tutorials causes more damage than it prevents (a lesson the OpenCode ecosystem [already learned](https://docs.kanaries.net/topics/AICoding/opencode-how-to-use)). When you hit an error, the useful paths are the repo's GitHub Discussions and the project Discord. ## Where DeepSeek Harness fits in the current agent landscape If you are choosing between agents rather than committing to this one, the short version: - **DeepSeek Harness** optimizes for *recomposability* — swap any part, inspect everything, MIT-licensed chassis. - **Claude Code / Codex-style products** optimize for a polished, opinionated end-to-end experience. Our [2026 AI coding tools roundup](https://docs.kanaries.net/articles/best-ai-coding-tools-2026) covers that field, and [Best Vibe Coding Tools](https://docs.kanaries.net/articles/best-vibe-coding-tools) covers the broader market. - **Runtime-centric frameworks** like Hermes Agent occupy similar "own the runtime" territory — the architectural comparison in [Hermes Agent vs OpenClaw](https://docs.kanaries.net/articles/hermes-agent-vs-openclaw) applies almost unchanged here, with dsh sitting firmly on the runtime side. - For background on DeepSeek the company and its models, see [DeepSeek vs Other Chinese LLMs](https://docs.kanaries.net/articles/deepseek-vs-other-chinese-llm). One boundary worth stating: DeepSeek Harness is a general coding agent. If your daily work is Jupyter notebooks and dataframes rather than repositories, a notebook-native agent that operates on kernel state directly is a better fit than pointing a repo agent at `.ipynb` JSON — that is the problem [RunCell](https://www.runcell.dev) is built for, and the distinction between repo-agents and notebook-agents is covered in [Jupyter AI RunCell](https://docs.kanaries.net/articles/jupyter-ai-runcell). ## FAQ ## Related Guides - [How to Use Codex](https://docs.kanaries.net/topics/AICoding/codex-how-to-use) - [Oh My OpenCode and OpenCode: Install, Setup, and Fixes](https://docs.kanaries.net/topics/AICoding/opencode-how-to-use) - [Best AI Coding Tools in 2026](https://docs.kanaries.net/articles/best-ai-coding-tools-2026) - [Best Vibe Coding Tools](https://docs.kanaries.net/articles/best-vibe-coding-tools) - [Hermes Agent vs OpenClaw](https://docs.kanaries.net/articles/hermes-agent-vs-openclaw) - [DeepSeek vs Other Chinese LLMs](https://docs.kanaries.net/articles/deepseek-vs-other-chinese-llm) ## Frequently asked questions ### How do I install DeepSeek Harness? With Node.js installed, run: npx @deepseek-ai/dsh web. This downloads the package and starts the web UI at http://127.0.0.1:3080. To install from source instead: clone github.com/deepseek-ai/deepseek-harness, then run pnpm install, pnpm run build, and pnpm dsh web. ### What is DeepSeek Harness? DeepSeek Harness (dsh) is an open-source, MIT-licensed agent framework from DeepSeek, released August 13, 2026. It is built on the Cordis plugin runtime with the principle that every capability — models, tools, skills, sessions, sandboxes, storage, loops, scheduling, and the UI — is a swappable plugin. It works as a coding agent out of the box and as a chassis for building custom agents. ### Is DeepSeek Harness free? The framework itself is free and MIT-licensed. You pay only for the model API you connect to it, such as DeepSeek platform credits or another provider. ### How do I set up an API key in DeepSeek Harness? Open the web UI, go to Settings → Models, paste credentials from platform.deepseek.com or another supported provider, and save. Per the official docs the model route becomes usable immediately without restarting the server. ### What is the difference between the Standard, Code, Minimal, and Creator modes? Standard is the full coding agent with file editing, shell, search, and workflows. Code adds model-generated TypeScript orchestration for multi-step operations. Minimal strips down to two tools (bash and editor) for benchmarking. Creator adds runtime inspection and plugin experimentation for plugin developers. ### How do I find DeepSeek Harness plugins? Plugins are tagged with the dsh-plugin topic on GitHub, which listed 11,944 public repositories as of August 26, 2026. The awesome-dsh-plugin repository maintains a curated index. ### Does DeepSeek Harness require a DeepSeek model? No. Models are plugins, and the model settings page covers alternative providers. DeepSeek platform credentials are the documented default path. ### Is DeepSeek Harness production-ready? It is officially a developer preview with explicitly announced breaking changes. For anything durable, pin a specific package version and expect to track the changelog closely.