How to Use DeepSeek Harness: Install, Set Up, and Run Your First Agent

Name

Soren Atelier

Updated on 8/26/2026

The one-command answer: if you have Node.js installed, this starts DeepSeek Harness with its web UI:

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 (opens in a new tab) 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 (opens in a new tab), 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.
• 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):

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):

npx @deepseek-ai/dsh web --no-open

Path B — from source (if you want to build plugins or track main):

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?

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 (opens in a new tab) (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 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:

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 (opens in a new tab) lists 11,944 public repositories — two weeks after release.

A starter pack worth knowing about, by current star count:

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). 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 covers that field, and 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 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.

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 (opens in a new tab) is built for, and the distinction between repo-agents and notebook-agents is covered in Jupyter AI RunCell.

FAQ

Related Guides

• How to Use Codex
• Oh My OpenCode and OpenCode: Install, Setup, and Fixes
• Best AI Coding Tools in 2026
• Best Vibe Coding Tools
• Hermes Agent vs OpenClaw
• DeepSeek vs Other Chinese LLMs