DeepSeek Harness Tutorial: Getting Started with dsh

Published Sep 21, 2026 · dshpacks Research · ~9 min read

A practical, source-checked walkthrough of DeepSeek Harness (dsh): install it, start the Web UI, connect a model, pick a workspace, run a first task, and add your first plugin. Every command here is the one the upstream project publishes — nothing is paraphrased from memory.

What DeepSeek Harness is

DeepSeek Harness — dsh for short — is an open-source agent harness published by DeepSeek AI under the MIT license. Its own repository describes it in four words: Everything is a Plugin. The harness core is built on Cordis, a plugin framework, which is why almost every capability — the Web UI, tools, memory backends, model providers — arrives as a plugin rather than as a built-in feature.

Two facts matter before you install anything. First, dsh is in developer preview and the project's README warns in capitals that there will be compatibility-breaking changes. Second, it is experimental software that has not had a security audit — it runs model-generated code and loads third-party plugins, so it can touch your files, processes, network and credentials. The project's own safety notice is blunt about this; see Are DSH plugins safe? for the practical version.

What you need before you start

Step 1 — Start the Web UI

The fastest path does not require a clone. With Node.js installed, run:

npx @deepseek-ai/dsh web

The command starts the Web UI at http://127.0.0.1:3080 and opens it in your default browser for a local launch. Pass --no-open to run the server without opening a browser. If you launched over SSH, dsh only prints the host URL, because the SSH client or editor owns the local forwarded address.

Step 2 — Connect a model

Open Settings → Models, paste a DeepSeek API key and save. The model route becomes usable immediately, without restarting the server. The docs/user/guide/providers.md guide in the repository covers other providers and custom OpenAI-compatible endpoints — the same settings page is where those live.

Step 3 — Choose a workspace

The dsh process uses the directory it was launched from as its default filesystem location, but a fresh Web UI has no selected workspace yet. Click Choose workspace, add the project directory, and select it. The session composer stays unavailable until a workspace is selected — this is the most common first-run confusion.

Step 4 — Run your first task

Start a session and send something concrete, for example:

Summarize this repository and identify its main packages.

The agent can read and edit workspace files, run commands, delegate work, and maintain a plan, and the Web UI asks before operations that require approval under the active permission policy. Approvals are a feature, not friction: they are the only thing standing between a model mistake and a command that runs on your machine.

Step 5 — Add your first plugin

Capabilities are added per profile. A profile is an ordered stack of plugin bundles plus your own patch layer, stored under $DSH_HOME/profiles/<name>, and plugin management forwards to pnpm inside that profile directory:

dsh plugin --profile web add <package-name>

Among the 1,349 reviewed plugins on dshpacks that publish a harness-managed install command, 1,188 name the web profile — the surface the Web UI uses. The full step-by-step is in our install guide; every dshpacks plugin page prints the exact command copied from that plugin's own README, or says install command not yet confirmed when the README publishes no runnable one.

The shipped profiles auto-initialize on first use from templates, so you rarely create one by hand: web, headless, sdk, sdk-minimal and acp. The name desktop is reserved for the Electron-owned profile. To create a new profile from a template, add --from-default-profile <template>.

Other ways to run dsh

The launcher takes a profile name, so the same install can run headless or serve automation clients:

dsh --profile headless "run the tests"
dsh --profile acp
dsh --profile sdk

dsh <name> and dsh --profile <name> boot the named profile; dsh --profile headless "job" runs one fresh persisted session, prints the final answer and exits. Flags after the launcher's own arguments are handed to the booted profile, which is why dsh --profile web --port 8080 changes the web app's port rather than the launcher's behaviour.

Run dsh from source

For a repository checkout — the path the project's contributor docs assume — the four commands are:

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

pnpm run build prepares the repository artifacts, and pnpm dsh web runs against them without rebuilding. The development guide notes that setup is complete when pnpm run typecheck exits successfully.

Safety before you start

The project's SAFETY.md is explicit that sandboxing, approval prompts and permission controls reduce risk but do not guarantee isolation, and that dsh should not be the sole security control for untrusted workloads. Its own recommendations: run with the least privilege you can, prefer a disposable VM or container, keep backups of anything dsh can reach, and review plugins and proposed commands before you allow them to run. That advice applies double to third-party plugins — a dsh plugin is code the harness loads and runs as you.

Where the ecosystem is, by the numbers

This tutorial is published by dshpacks, a directory that tracks the dsh plugin ecosystem. At build time it lists 2,961 English-visible plugins across 27 categories, of which 1,651 carry a completed review and 1,583 publish a verified install command. Those numbers are measured from the directory's own data on every build, not typed by hand; the September 2026 ecosystem report breaks them down further.

Sources

Where to go next

deepseek harness tutorialdeepseek harness documentationwhat is deepseek harness

Browse the directory by category

Web UI Enhancements 367 · Agent Capabilities 261 · Infrastructure & Deployment 196 · Development & Runtime 87 · Sessions & Messages 50 · Skills 40 · All 27 categories · All 1,651 reviewed plugins