Installing DeepSeek Harness (dsh)

Prerequisites

You need Node.js. The repository declares an engines range of ^22.19 || >=24, so an older runtime will either refuse to install or fail later in ways that look like a bug in the harness. Check what you have before you start:

node -v

For the npx route, that is the entire list of requirements. If you want to build from source you also need git and pnpm, which is the package manager the repository is set up for. Nothing on this page asks you to install dsh system-wide, and while the preview is moving this fast, a version pinned to a project is easier to reason about than a global binary.

Quickstart with npx

One command gets you a running harness with its web interface:

npx @deepseek-ai/dsh web

npm fetches the package, and the harness serves its Web UI at http://127.0.0.1:3080. That address is loopback: it answers on your machine and nowhere else, which is the right default for a tool that can read your files and run commands.

The CLI also takes a --profile flag — dsh --profile <profile> — which selects the bundle of plugins that loads at startup. The shipped profiles include headless. Run dsh --help against your own version rather than trusting a list written a day after release: the available profiles and bundles are exactly the sort of thing a preview reshuffles between releases.

Running from source

Building from the repository is worth the extra minutes if you plan to write a plugin, because you get to read the real package APIs instead of inferring them from a README:

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

Run the build before the first pnpm dsh web — the documented sequence expects it. You land on the same Web UI at port 3080, but now against the working tree, so you can patch a package, rebuild, and see the result. This is also the fastest way to find out what actually changed in a release, since a preview moving this quickly tends to outrun its own documentation.

Where cordis.yml fits

The organising idea of dsh is that everything is a plugin. Models, tools, skills, sessions, sandboxes, filesystems, the agent loop, orchestration and the user interface are all plugins loaded into one shared runtime. That runtime is Cordis, the meta-framework the harness is built on; @deepseek-ai/cordis is a peer dependency of every harness package.

Which plugins load, and with what options, is decided by a cordis.yml loader config:

# cordis.yml
plugins:
  dsh-example-plugin:

Each key under plugins: names a plugin; the block beneath it is that plugin's configuration, or nothing at all if the defaults are fine. Official packages are published as @deepseek-ai/dsh-<name>, and the loader key is generally the package name with the npm scope stripped off. Plugin authors sometimes choose a different key, so the README of the plugin you are adding wins over any rule of thumb — including this one.

Adding a community plugin

Adding a plugin is two steps: install the package, then register it in your loader config.

npm install dsh-example-plugin

# cordis.yml
plugins:
  dsh-example-plugin:

Restart the harness and the plugin loads with everything else. To find something worth installing, browse the 632 indexed repos or narrow by category. Of those, 348 are verified — meaning we found a dependency on the Cordis runtime or a cordis.yml in the repo, so they will actually load. The rest carry a dsh-plugin GitHub topic without any wiring behind it, which matters because that topic is also how discovery works: if you publish a plugin, adding the topic is how the ecosystem finds you.

Troubleshooting

The install fails with an engine or syntax error

Almost always an old Node.js. The repo requires ^22.19 || >=24; anything below that can fail at install time or throw a parse error deep in a dependency, which reads like a broken package but is not. Check node -v and upgrade — a version manager such as nvm or fnm is the least disruptive way if other projects on the machine need older runtimes.

Port 3080 is already in use

Something else is holding the port — frequently an earlier dsh run that never exited. On macOS or Linux, find it with:

lsof -i :3080

Stop that process and start again. If you would rather move the harness than the other service, check dsh --help and the web plugin's options in your cordis.yml instead of guessing at a flag name: the preview's option surface is still changing, and a flag that worked in a blog post last week may not exist in your build.

It worked last week and now it doesn't

This is the expected failure mode of a developer preview rather than a mystery. The README says outright that compatibility-breaking changes are coming, and a plugin built against an older loader format can quietly stop loading after a harness upgrade. Two habits help: pin the version you tested with, and check when a plugin was last pushed before you blame your own config — our listings show that date on every plugin page.

npx @deepseek-ai/dsh@<version> web

When something is genuinely broken rather than merely renamed, the project runs GitHub Discussions and a Discord, and both are more current than any third-party guide can be during a week like this one.

Frequently asked questions

Do I need to install dsh globally?

No. The npx quickstart downloads and runs the package on demand, and the from-source route runs the CLI through pnpm inside the cloned repository. Because the preview ships compatibility-breaking changes, a version pinned per project ages better than a global binary you forget you installed.

Is DeepSeek Harness free to use?

The harness itself is open source under the MIT license, so you can run, modify and redistribute it without a fee. The model you point it at is a separate matter, and whatever that provider charges is not covered by the harness license.

Why does the Web UI listen on 127.0.0.1 instead of my network address?

That address is loopback, meaning the interface answers only on the machine that started it. Nothing on your local network can reach http://127.0.0.1:3080 unless you deliberately put a proxy or tunnel in front of it, which is a sensible default for a tool that can run commands on your machine.

Can I use dsh for production work today?

Not safely. DeepSeek Harness is a developer preview released on 13 August 2026, and its README warns in capitals that there will be compatibility-breaking changes. Treat it as something to experiment with and build plugins against, not as infrastructure you would put on an on-call rotation.

What exactly is cordis.yml?

It is the loader config that decides which plugins your harness starts with and how each one is configured. Because dsh treats models, tools, skills, sessions, sandboxes and even the UI as plugins, cordis.yml is effectively the definition of what your install can do.

Where to next

If the plugin model is new to you, start with what an agent harness actually is — it explains why dsh puts so much behind a loader config. If you are weighing dsh against a tool you already use, we compare it with Claude Code, including the parts where dsh is plainly not ready yet.