DeepSeek Harness plugins directoryDSH Pluginsdsh plugins directory
Back to guides

DeepSeek Harness Tutorial: Run dsh in 5 Minutes (Quickstart)

The shortest DeepSeek Harness (dsh) tutorial: npx @deepseek-ai/dsh web on Node.js 24.9+, Web UI at http://127.0.0.1:3080, API key in Settings → Models, first task in five minutes.

Last updated: 2026-11-12

Quick answer

DeepSeek Harness (dsh) is DeepSeek's open-source, plugin-composable agent runtime — still a developer preview, so expect compatibility-breaking changes between releases. Install Node.js 24.9 or newer (the floor the official README and the @deepseek-ai/dsh npm package declare), then run:

npx @deepseek-ai/dsh web

The Web UI starts at http://127.0.0.1:3080 and usually opens itself. Paste your API key under Settings → Models, choose a workspace, then ask the agent to run one small task. For a one-off terminal job instead of the UI:

npx @deepseek-ai/dsh --profile headless "Summarize this project and tell me what its main files do."

A global npm install -g @deepseek-ai/dsh followed by dsh web still works, but it is the optional path — the official zero-install entry point is npx. Everything on this page was checked against the official README and the published npm package on 2026-11-12; if the two ever disagree with a third-party tutorial, the README wins.

Install: one command

npx @deepseek-ai/dsh web

The first run downloads the package (answer y when it asks "Ok to proceed?"), starts the harness with the web profile, and opens the Web UI in your browser.

Prefer a permanent CLI? Install it once and skip the download on every run:

npm install -g @deepseek-ai/dsh
dsh web          # dsh --profile web is the same thing

Anything breaks along the way? Check github.com/deepseek-ai/deepseek-harness — the README and issues live there, and the README is the authority on the exact supported Node.js version.

The API key, or not

In the Web UI, open Settings → Models, paste your DeepSeek API key and save — the model route becomes usable immediately, no restart. If your machine already has the key in an environment variable, dsh picks it up — so skip that step entirely.

The harness is the body; the model is the brain. If you'd rather use another model, any OpenAI-compatible endpoint works — configure it in the UI settings (see What is DeepSeek Harness?).

Before the first task

One thing is worth sorting out first: start dsh from the folder you want the agent to work in. The default sandbox only lets it touch that workspace, so the launch directory is also a safety boundary.

Your first task

The Web UI opens on a chat. Describe the outcome you want, not the keystrokes — the agent plans its own steps. Good first tasks:

  • "Summarize the TODOs in this repo and propose a plan to finish them."
  • "Fix the failing tests in this project and run them to confirm."
  • "Explain how this codebase is structured, as a short document."

Watch what happens: the agent may ask a clarifying question, propose a plan and wait for approval, then start making tool calls. The session log records everything the model sees, which is why you can resume or fork the session later.

If a risky operation comes up — writing outside the workspace, network calls, running unfamiliar commands — the harness will ask before doing it. That is the approval system working, not a bug.

Picking a mode

The mode selector at the top of the UI picks the session's Agent Preset. For your first run, leave it on Standard. The four modes:

ModeWhat it isUse it when
StandardThe complete programming assistant: understands the task, edits code, runs commands and checks the resultsEveryday coding and research
PTCEverything Standard has, plus programmatic tool calling: the model writes small TypeScript programs that compose many steps into one automated flowTasks with many mechanical steps
MinimalOnly a persistent terminal and basic text-replacement toolsSimple edits, benchmarking, or teaching the loop
CreationEverything Standard has, plus runtime inspection, trying plugins in memory, and building presets for creative tasksDesigning your own preset — treat it like shell access

A session locks its preset once it has content, so switch modes before you start typing.

After the first session

  • Sessions are resumable. Close the tab, come back, and the event log lets you resume, fork, search and replay.
  • Installing a plugin is one command: dsh plugin --profile web add <package-or-github:owner/repo>, then restart dsh web. It forwards to pnpm inside the profile directory — read Installing plugins you can trust before your first one.
  • Profiles, patches and presets are how the harness gets assembled around you — the configuration guide explains the stacking order. The patch layer is where dsh really diverges from other agents: sub-agents, conditional rules, permissions, UI replacement — all of it is config.

If it doesn't run

  • Node.js version — the most common first-run failure. dsh needs Node.js 24.9 or newer; node --version is the first thing to check, and the official README is the authority if that floor moves.
  • No model response — check your API key under Settings → Models, and that your machine can reach the provider's endpoint.
  • Port 3080 already in use — run npx @deepseek-ai/dsh web --port 8080 and use the URL the terminal prints.
  • Commands being refused — that is the sandbox or approval policy; either widen the sandbox deliberately (see the safety guide) or work inside the workspace.

Where next

DSH Plugins is an independent community directory of DeepSeek Harness plugins. Not affiliated with or endorsed by DeepSeek. Third-party plugins are not security-audited — review the source before installing.

New DeepSeek Harness plugins, weekly. No spam.