DeepSeek Harness, whose command is dsh, is an open-source agent harness built by DeepSeek. Its README describes an "everything is a plugin" architecture built on the Cordis framework, so tools, skills and even parts of the interface are plugins you can add, remove or write yourself. DeepSeek's site says it can handle everyday office work, coding inside a repository, research with cited sources and long-running background jobs. The code is on GitHub under the MIT license.

It is still a developer preview. The README warns in capital letters that there will be compatibility-breaking changes, and DeepSeek's safety notice says the software has not had a security audit. Because the agent can run model-generated commands, load third-party plugins and touch the files and credentials it is given, DeepSeek recommends running it with the least access it needs, ideally in a virtual machine, container or other dedicated environment, keeping backups, and reviewing plugins and proposed commands before letting them run.

DeepSeek's interest in the tool is easy to see right now. When it released DeepSeek-V4.1-Flash-1017 on October 17, its change log said the model was specifically optimized for DeepSeek Harness, and it asked users to upgrade to Harness 0.2.1-rc.1 or later.

Desktop app, Web UI or command line

DeepSeek offers three ways in. The desktop app is the simplest: DeepSeek's Harness page has downloads for macOS on Apple silicon and for 64-bit Windows, and there is no Linux desktop download. According to the desktop README, the app wraps the full Web UI in a native window and ships its own Node.js, pnpm and Python runtimes, so you don't need Node.js installed on your system.

The second route is the Web UI from npm, which is what the README leads with. The third is running from a source checkout, which DeepSeek aims at people developing Harness itself. For Linux users the npm and source routes are the options, since DeepSeek doesn't offer a Linux desktop build. The README doesn't list supported operating systems for the npm route, though the separate Python SDK guide does name Linux x64 and arm64 alongside macOS 14 or later on Apple silicon and Windows x64.

How to install DeepSeek Harness

According to DeepSeek's README and its Web UI guide, getting a first session running from npm looks like this:

  • Install Node.js. The README doesn't specify a version.
  • Open a terminal in the project folder you want the agent to work on and run npx @deepseek-ai/dsh web. The Web UI starts on port 3080 of your own machine and opens in your default browser. Over SSH it only prints the address, and the --no-open flag starts the server without opening a browser.
  • In the Web UI, choose a workspace by adding the folder where you started dsh. The session box stays unavailable until a workspace is selected.
  • Configure a model, as described in the next section, then start a session.

To run from source instead, the README says to clone the repository, run pnpm install and pnpm run build, then start it with pnpm dsh web.

On Windows, the desktop installer installs for the current user only. The desktop README notes that closing the window hides the app to the system tray while running tasks carry on, and its application menu has a Manage dsh Command entry that adds the dsh command to your user PATH on Windows, or to /usr/local/bin on macOS, so you can use the command line without a separate npm install.

One detail matters for the upgrade advice below. As of 18:30 Beijing time on October 17, the default "latest" tag for @deepseek-ai/dsh on npm still pointed to 0.2.0-rc.2, while 0.2.1-rc.2 was published under the "next" tag. The README's command doesn't name a version, and DeepSeek's docs don't explain how to pick a particular release, so it's worth checking which version you end up running. If you want the newer build, npm's standard syntax for installing a tagged release works here too: npx @deepseek-ai/dsh@next web. That is general npm usage rather than something DeepSeek documents, and the tags may move after this article is published.

If the npx install gets stuck

DeepSeek's README and documentation don't cover an install that hangs, and none of the release notes mention a fix for one. In the Discussions section of the official GitHub repository, users have reported since August that npx @deepseek-ai/dsh web can sit at full CPU without finishing, with reports from Windows, macOS and Linux. A DeepSeek maintainer replied on August 22 that the team would look into it, and DeepSeek hasn't published an official workaround since. The workarounds in that thread come from other users, not DeepSeek. The only officially documented route that skips the npm install is the desktop app, which according to its README doesn't depend on a system Node.js or pnpm.

Connecting DeepSeek Harness to deepseek-flash

DeepSeek's model guide describes the API key route like this:

  • Get a DeepSeek API key from the DeepSeek platform.
  • In Harness, open Settings, then Models. The DeepSeek card has a single API key field. Enter the key and save it. Harness stores it in a credentials file in its home folder and only shows a masked version afterwards, and no restart is needed.
  • Pick deepseek-flash in the model picker. Harness's built-in DeepSeek catalog lists deepseek-flash, which accepts text and images, and the text-only deepseek-v4-pro, both with a 1M-token context window. The model you pick becomes the default for new sessions.
  • Optionally choose a reasoning level from the Effort menu. DeepSeek's own route offers off, low, high and max.

Because DeepSeek's API now serves V4.1-Flash-1017 under the name deepseek-flash, nothing else needs to change to use the new model. A session that has already sent a request keeps using the model recorded in its own log.

You can also sign in with a DeepSeek account instead of using an API key. Since v0.2.1-rc.1 the Web UI supports account sign-in when opened over local HTTP, and the desktop app has its own sign-in screen. In that mode, according to DeepSeek's docs, the model list comes from your account, and Harness hides any model that needs a newer client version. Requesting one fails with an error that names the version to install. DeepSeek hasn't said whether 1017 carries such a minimum version.

The headless command line mode, dsh headless followed by a task, works differently. Since the 0.2.1 alpha releases it no longer reads keys saved in the Web UI by default. It takes the key from the DEEPSEEK_API_KEY environment variable or a .env file instead.

Why upgrade to v0.2.1-rc.1 or later

DeepSeek's reason is short. Its October 17 change log says 1017 was tuned for DeepSeek Harness among other agent tools and recommends Harness 0.2.1-rc.1 or later "for the best experience with the new model." The same advice was in its announcement on X at 16:35 Beijing time.

The release notes show what that version brings. v0.2.1-rc.1 went up on GitHub at 13:22 Beijing time on October 17 as the first release candidate in the 0.2.1 series, and it rolls up changes since v0.2.0-rc.2. Among them are account sign-in in the Web UI, a DeepSeek account model list that stays in step with the models your account can use, per-model reasoning levels set from the interface, masking of keys and tokens you paste into messages, plugin installs from custom index sources, and manual context compaction with /compact. It also changes behavior in places, including the headless key handling described above and a renamed Azure provider. Those notes don't mention 1017 or Search and Fetch by name. That came in v0.2.1-rc.2 at 16:16 the same day, whose notes add support for DeepSeek-V4.1-Flash-1017 and for DeepSeek's Search and Fetch APIs, which can be turned on in the Web Search settings. GitHub marks both versions as pre-releases.

Desktop users get updates through the app's built-in update check and its Check for Updates menu item. DeepSeek doesn't say which Harness version the current desktop download contains.

Plugins, agents and other modes

Plugins are the core of the design. You can install existing plugins from the Plugins page, or use Creator mode to describe a plugin and have the agent write and install it. DeepSeek's site shows it building a Pomodoro timer this way. According to the rc.1 notes, the Official plugin list can install Claude Code and Codex bundles matching the current release, and there is an experimental Claude Code Mods compatibility layer, which DeepSeek says isn't meant to give full, practical compatibility yet. An experimental Custom plugin markets feature lets you browse third-party plugin indexes, but Harness ships without any index, and DeepSeek warns that market listings are third-party content. Developers can also add plugins from the command line with dsh plugin, and DeepSeek asks plugin authors to tag their repositories with the dsh-plugin topic on GitHub.

On the agent side, the docs describe an agent that reads and edits workspace files, runs commands, delegates work to subagents and keeps a plan, asking first before operations that need approval. Experimental plugins on the Plugins page include agent teams and scheduled tasks. Besides the Web UI, the dsh command has a headless mode that answers one task and exits, an ACP mode that serves clients over the Agent Client Protocol, and an SDK mode used by the Python SDK, which installs with pip as deepseek-harness-sdk. There's also an optional GitHub webhook setup that opens a read-only review session when a pull request is marked ready for review.

DeepSeek's docs don't mention a VS Code extension or any other editor integration. The README only notes that when Harness is started over SSH, the forwarded address belongs to the SSH client or editor.

What it costs

DeepSeek Harness itself is free, open-source software, and DeepSeek lists no price for it. What you pay for is model usage on the DeepSeek API. On DeepSeek's pricing page, deepseek-flash costs $0.3 per million input tokens on a cache miss, $0.006 on a cache hit and $1.2 per million output tokens at peak times, and half that off-peak. Peak hours are 09:00 to 12:00 and 14:00 to 18:00 Beijing time on weekdays, excluding Chinese public holidays. DeepSeek's docs don't explain how usage is billed when you sign in with an account rather than an API key.

Web search inside Harness has its own pricing. DeepSeek's pricing page says that when you use the DeepSeek API through DeepSeek Harness, Claude Code or Codex, server-side tool calls already use its Search and Fetch APIs, and those calls are free for now. Per-request billing starts at 00:00 Beijing time on November 1, 2026, at $0.75 per 1,000 successful requests for each API. We cover both APIs, and the 1017 model itself, in separate articles linked below.