No invite needed
MIT licensed
Developer preview

DeepSeek Harness install

DeepSeek Harness install guide: one command, no invite required

There is no closed beta, no waitlist, and no application form. DeepSeek Harness is MIT-licensed and published on npm, so a single command installs and starts it. Install Node.js, run npx @deepseek-ai/dsh web, and open http://127.0.0.1:3080 in a browser. Add a model key and pick a workspace before your first task.

This page is the install path a first-time user actually walks, in order, with the failure at each step written next to it. Everything below was re-read from the repository on the verification date rather than copied from a release post.

New to it? Start with what DeepSeek Harness is

Start here

npx @deepseek-ai/dsh web

Verified 2026-08-14 against dsh 0.1.0-rc.6 · Node.js ^22.19.0 || >=24.0.0 · serves http://127.0.0.1:3080

Install facts at a glance

npm package: @deepseek-ai/dsh
Version verified: 0.1.0-rc.6 (published 2026-08-13)
One-line start: npx @deepseek-ai/dsh web
Default address: http://127.0.0.1:3080
Node.js: ^22.19.0 || >=24.0.0
Source install: pnpm 11.7.0
License: MIT
Status: Developer preview

Quick start

Install DeepSeek Harness: npx @deepseek-ai/dsh web opens port 3080

The npm route needs nothing but Node.js. Running npx @deepseek-ai/dsh web downloads the dsh CLI, boots the web profile, and starts a local server on http://127.0.0.1:3080 by default. The command prints its own URL. Two things are still missing at that point: a model API key and a selected workspace. Both are set inside the browser UI, not on the command line.

01
Check your Node.js version first
The repository targets Node ^22.19.0 || >=24.0.0. The published CLI package declares no engines field, so npm will not stop you on an older runtime — it will simply fail later, further from the cause.
```
node -v
```
02
Start the web UI
One command, no global install and no clone. dsh web is an alias of dsh --profile web, and the web profile auto-initializes from a shipped template on first use.
```
npx @deepseek-ai/dsh web
```
03
Open the address it prints
The default is 127.0.0.1:3080 — loopback only, not exposed on your network. If that port is taken, see the known problems section for the flag that moves it.
```
http://127.0.0.1:3080
```
04
Add a model API key in the UI
Open Settings → Models, enter a DeepSeek API key on the DeepSeek card, and save. The model route becomes usable immediately without restarting the server. Keys never enter your repository — see the requirements table for where they land.
```
Settings → Models → DeepSeek → save
```
05
Choose a workspace, or you cannot type
A fresh Web UI has no selected workspace. Click Choose workspace, add the project directory you started dsh in, and select it. Until you do, the session composer stays unavailable — this is the single most common first-run dead end.
```
Choose workspace → add directory → select
```
06
Send the first task
Start a session and ask it something scoped to the repository you just selected. The agent can read and edit workspace files, run commands, delegate work, and maintain a plan, and it asks before operations that need approval under the active permission policy.
```
Summarize this repository and identify its main packages.
```

Requirements

What you need before you install: Node.js, a key, a workspace

Three hard requirements and one non-requirement. You need a supported Node.js, an API key for whichever model provider you configure, and a workspace directory selected inside the UI. You do not need beta access, an invitation, or an application. The pnpm requirement applies only if you build from a repository checkout instead of using npx.

What you need before you install: Node.js, a key, a workspace
Requirement	What is needed	Notes and source
Node.js	^22.19.0 \|\| >=24.0.0	Declared in the repository root package.json. The published @deepseek-ai/dsh package carries no engines field, so npx will not warn you on an older runtime.
Beta access	Not required	MIT licensed, public on npm and GitHub. There is no closed beta, no waitlist and no application form for the harness itself.
Model API key	Required before the first task	Set it in Settings → Models. Stored in $DSH_HOME/.credentials.yaml; the page receives a redacted descriptor after saving, never the literal secret, so nothing lands in your repository.
Workspace	Must be selected in the UI	The dsh process uses its invoking directory as the default filesystem location, but a fresh Web UI has no selected workspace until you add one.
Browser	Required for dsh web	dsh web starts a local web server you open in a browser. The profiles that auto-initialize are web and headless; there is no shipped terminal UI.
Default port	3080 on 127.0.0.1	Change it with dsh --profile web --port 8080. --port is parsed by the web app, not by the launcher, so it must come after the profile flag.
pnpm	11.7.0 — source installs only	From the root package.json packageManager field. The npx route does not need pnpm; dsh plugin does, because it forwards to pnpm.
Operating system	Linux, macOS, Windows	The repository runs separate Windows CI gates alongside its primary Linux gates, so Windows is a maintained target rather than an assumption.

From source

Install DeepSeek Harness from source with git and pnpm

Build from a checkout when you want to read the code, track master ahead of the next release candidate, or develop a plugin against the live tree. It costs a clone, a pnpm install and a full build. Production runs need built package and frontend artifacts, so pnpm run build is not optional before pnpm dsh web.

01
Clone the repository
The default branch is master, not main — a raw file URL built against main returns 404, which is worth knowing before you script anything against it.
```
git clone https://github.com/deepseek-ai/deepseek-harness.git
```
02
Install dependencies and build
This is a pnpm workspace pinned to pnpm 11.7.0 through the packageManager field. The build step produces both the library artifacts and the web frontend the CLI serves.
```
cd deepseek-harness
pnpm install
pnpm run build
```
03
Run the built tree
pnpm dsh runs the TypeScript entry point and forwards every argument to it, so the same flags apply as with the npm install. Skipping the build leaves the frontend missing.
```
pnpm dsh web
```

Plugins

How dsh plugin add works, and where the docs hide it

Installing someone else's plugin is one command: dsh plugin add <package>. Finding that command is the hard part. The repository README never contains the string plugin add at all; the plain form appears once, at line 177 of a tutorial about publishing your own plugin. That is an information gap, not a missing feature — the command works exactly as written.

From npm
```
dsh plugin add your-package
```
Installs prebuilt code. Nothing needs to be compiled on your machine.
From a tarball
```
dsh plugin add ./hello-plugin-0.1.0.tgz
```
The output of pnpm pack. Also prebuilt, so no build permission is involved.
Into a named profile
```
dsh plugin --profile demo add ./hello-plugin
```
Any profile other than web and headless must be created through dsh plugin first.
From a git host
```
dsh plugin --profile demo add github:you/hello-plugin
```
Fetches sources, not build artifacts. This is the form that trips the pnpm build gate below.
Removing one
```
dsh plugin --profile demo remove dsh-hello-plugin
```
Removes both the dependency and its layer from the profile.

What the command actually is

A thin pnpm forwarder: dsh plugin --profile <name> <args...> initializes the profile on first use, then runs pnpm <args...> inside the profile directory. Every pnpm verb works, because it is pnpm.
Then a reconcile pass: After pnpm finishes, dsh reconciles the dsh.profile.bundles layer list against the installed state. A dependency that resolves to a package declaring dsh.bundle joins the layer stack; a removed or bundle-less dependency leaves it.
Reconciled by state, not by diff: Because it reads the installed state rather than a dependency diff, dsh plugin update can activate a package that only gained its dsh.bundle declaration in a newer version.
A package without dsh.bundle still installs: It just lands as a plain dependency: dsh plugin prints a warning and activates no layer. That is the correct format for a library other plugins import, not for a plugin users enable.

Known trap

A git-hosted plugin fails on its first add under pnpm 10 and later

A git install fetches sources, not built artifacts, so a TypeScript package arrives without its lib/ output and fails to load. Authors are expected to ship a prepare script that builds it. pnpm 10 and later refuses to run a git dependency's prepare script until it is explicitly allowed, so the first add fails. dsh points at the fix: copy the exact package key pnpm printed into the profile's pnpm-workspace.yaml, then re-run the add.

profile pnpm-workspace.yaml

allowBuilds:
  dsh-hello-plugin: true

Treat that allowance as what it is: permission to execute the package's code on your machine at install time, outside any sandbox the agent runs under. The official docs say so in as many words. Only allow packages whose source you trust, and pin a commit — github:you/hello-plugin#<sha> — so a later push cannot silently change what runs.

Community plugins are published by third parties and are not security audited by DeepSeek or by SpringBrand.

Browse the dsh plugin ecosystem

Known problems

Six things that break a first dsh install

These are the six failures a first run actually produces, in rough order of how often they stop someone. Four of them are not errors at all — they are a working install behaving in a way the user did not expect, which is worse, because there is no message to search for. Each fix below is traced to a source at the bottom of the page.

It fails on an old Node.js and nothing warned you
Why it happens
The published @deepseek-ai/dsh package declares no engines field, so npm and npx do not gate on your Node version. The repository itself targets Node ^22.19.0 || >=24.0.0, and you find that out only when something downstream breaks.
Fix
Check first with node -v. If it is below v22.19.0, or on a v23 line, upgrade to Node 22.19+ or 24+ and re-run npx @deepseek-ai/dsh web.
Port 3080 is already in use
Why it happens
`dsh web` is an alias of `dsh --profile web`, and the web app binds 127.0.0.1:3080 by default. A second dsh, or anything else already holding 3080, collides with it.
Fix
Move the port: dsh --profile web --port 8080. --port belongs to the web app, not to the launcher, so it must come after the profile flag — dsh --port 8080 web is not the same command.
You cannot find where the API key goes
Why it happens
There is no key prompt on the command line and no key file to edit in your project. Configuration lives in the browser UI, which is not where a terminal user looks first.
Fix
Open Settings → Models, enter the key on the DeepSeek card, and save. It applies on the next request with no restart. Keys are stored in $DSH_HOME/.credentials.yaml and the page only ever receives a redacted descriptor back, so the secret never reaches your repository.
The message box is greyed out and you cannot type
Why it happens
A fresh Web UI has no selected workspace, and the session composer stays unavailable until one is selected. Nothing errors — the input is simply inert, so it reads like a broken build.
Fix
Click Choose workspace, add the project directory where you started dsh, and select it. If the composer instead shows Select model, the cause is different: a saved default is naming a provider that was deleted, and input stays blocked until you pick a model.
You expected a TUI and got a browser tab
Why it happens
A lot of people search for a DeepSeek CLI or DeepSeek TUI and land here. dsh is a launcher, and the profile it ships for interactive use is a local web app, not a terminal interface.
Fix
For a non-browser run, use headless mode: dsh --profile headless "run the tests" runs one fresh persisted session, prints the final answer, and exits. dsh --profile tui appears in the docs only as an example that assumes you installed a tui profile yourself; web and headless are the profiles that auto-initialize.
You installed a different project with the same name
Why it happens
Two unrelated packages sit on the obvious names. On npm, `dsh` is a shell written in JavaScript at v1.0.1. On PyPI, `deepseek-harness` is a protocol client for the DeepSeek API at v0.2.0 — a different project, a different language, and not a harness.
Fix
The DeepSeek AI package is scoped, and the scope is the whole signal: npx @deepseek-ai/dsh web. There is no pip install route to this project, so any instruction starting with pip install is describing something else.

FAQ

DeepSeek Harness install questions

Answers verified against dsh 0.1.0-rc.6 on 2026-08-14. Version-sensitive answers carry the source they came from.

No invite or beta access
MIT licensed
Runs on 127.0.0.1:3080
Node.js 22.19+ or 24+

No. The project is MIT licensed, the repository is public, and @deepseek-ai/dsh is published on the public npm registry. There is no closed beta, no waitlist, and no application form for the harness itself. If you have Node.js installed, npx @deepseek-ai/dsh web is the entire access process.

Glossary

Terms you hit in the first ten minutes of dsh

The dsh docs assume its own vocabulary from the first page. These seven terms are the ones that appear in error output and configuration files before anything has explained them, which is why an otherwise correct install reads as broken.

dsh: Both the command and the npm package @deepseek-ai/dsh. It is a launcher for profiles, not the agent itself — the agent is assembled from the plugins a profile activates.
Profile: A directory under $DSH_HOME/profiles/<name> holding a package.json — its out-of-tree plugin dependencies plus the dsh.profile manifest with its ordered bundles list — and a cordis.patch.yml for your own overrides.
Bundle: A package that declares dsh.bundle and therefore contributes a patch layer to a profile. A package without that declaration installs as an ordinary dependency and activates nothing.
web / headless: The two profiles that auto-initialize from shipped templates on first use. dsh web is an alias of dsh --profile web. Any other profile must be created through dsh plugin.
$DSH_HOME: Where dsh keeps state that is not part of your project: profiles, settings.yaml, and .credentials.yaml. Deliberately outside the workspace, which is why keys never reach your repository.
allowBuilds: A key in the profile's pnpm-workspace.yaml that permits a specific git dependency's prepare script to run at install time. Required by pnpm 10 and later, and equivalent to letting that package execute code on your machine.
Cordis: The plugin kernel DeepSeek Harness is built on. You do not install it separately, but its vocabulary — patch layers, injections, composition — leaks into dsh configuration and error messages.

Sources

What this page was checked against

Every claim above was read from the repository at master or from the npm registry on the verification date, not from a release announcement. dsh is a developer preview and its own README promises compatibility-breaking changes, so treat anything here as true of 0.1.0-rc.6 and re-check the source before relying on it.

README.md
npx start command, 127.0.0.1:3080 default, source-install sequence, MIT license, developer-preview warning.
docs/user/guide/index.md
Settings → Models flow, and the workspace requirement that leaves the session composer unavailable.
docs/user/guide/providers.md
Write-only key handling, $DSH_HOME/.credentials.yaml storage, catalog and custom providers, Select model blocking input.
docs/user/develop/basic/publish.md
dsh plugin add forms at lines 177 and 178, the git build-script catch, and the allowBuilds fix with its security warning.
apps/cli/README.md
Entry modes table, --port belonging to the web app, profile layout, and the note that a tui profile is an example rather than a shipped one.
apps/cli/src/plugin.ts
The module docblock describing dsh plugin as a thin pnpm forwarder that reconciles dsh.profile.bundles against installed state.
package.json (repository root)
engines ^22.19.0 || >=24.0.0, packageManager pnpm@11.7.0, and the separate Windows CI gates.
npm registry
Latest version 0.1.0-rc.6 published 2026-08-13, MIT license, and the absence of an engines field on the published CLI package.

Verified 2026-08-14 against dsh 0.1.0-rc.6. Version numbers, default ports and CLI grammar are all preview-stage and expected to move.

If it did not work

Stuck on the install? Six known problems, with the fix next to each

Most first runs fail on one of six things, and four of them produce no error message at all — a greyed-out input, a browser tab where a TUI was expected, a port already taken, or the wrong package entirely.

dsh is at 0.1.0-rc.6 and its own README warns in capitals that there will be compatibility-breaking changes. This page carries the date and version it was verified against, and gets re-checked against the repository rather than rewritten from release notes — so when the command grammar moves, come back and diff it.

Jump to the six known problems

DeepSeek Harness install guide: one command, no invite required

Install facts at a glance

Install DeepSeek Harness: npx @deepseek-ai/dsh web opens port 3080

Check your Node.js version first

Start the web UI

Open the address it prints

Add a model API key in the UI

Choose a workspace, or you cannot type

Send the first task

What you need before you install: Node.js, a key, a workspace

Install DeepSeek Harness from source with git and pnpm

Clone the repository

Install dependencies and build

Run the built tree

How dsh plugin add works, and where the docs hide it

What the command actually is

A git-hosted plugin fails on its first add under pnpm 10 and later

Six things that break a first dsh install

It fails on an old Node.js and nothing warned you

Port 3080 is already in use

You cannot find where the API key goes

The message box is greyed out and you cannot type

You expected a TUI and got a browser tab

You installed a different project with the same name

DeepSeek Harness install questions

Do I need beta access or an invitation to install DeepSeek Harness?

Is DeepSeek Harness free?

How do I change the default port 3080?

Where does dsh store my API key?

Can I run DeepSeek Harness with a model other than DeepSeek?

Is there a terminal UI instead of the browser?

Should I install DeepSeek Harness on a production machine?

Do I need pnpm to install DeepSeek Harness?

Terms you hit in the first ten minutes of dsh

Where to go once it runs

What DeepSeek Harness actually is

DeepSeek Harness vs Claude Code

dsh plugin directory

Official repository

What this page was checked against

Stuck on the install? Six known problems, with the fix next to each