How to install DeepSeek Harness

Installing DSH is not hard. Getting it into a state where it is actually useful takes a few more steps than the quickstart suggests, mostly because the quickstart stops before the interesting part. This guide covers the whole path: install, provider setup, the plugins that make it usable, verification, and the failure modes you are most likely to hit.

Before you start: what you need

• Node.js 20 or newer. Check with node -v. Anything below v20 will produce obscure module errors rather than a clear version warning, so check first.
• An API key from a supported provider, or a local model endpoint if you are running models yourself.
• A terminal. On Windows, PowerShell or WSL both work; WSL is less likely to produce path problems. The desktop clients exist precisely so you can skip this step entirely.
• About 500MB of disk for the core plus a typical plugin set. More if you install image or document processing plugins.

Step 1 — install the core

npm install -g @deepseek/harness
dsh --version

If dsh is not found after a successful install, your global npm bin directory is not on your PATH. Run npm bin -g to see where it went, then add that directory to your shell profile. This is the single most common first-run problem and it has nothing to do with DSH.

On macOS and Linux you may need sudo for a global install, or better, configure npm to use a user-owned prefix so you never need it.

Step 2 — configure a model provider

DSH ships with a minimal shell and no model attached. On first run it asks for a provider and a key. Provider selection is itself a plugin, which matters later: switching between DeepSeek, another vendor, and a local endpoint does not require reinstalling anything.

dsh config set provider deepseek
dsh config set apiKey <your-key>
dsh auth check

dsh auth check is the step people skip. It makes a real request and tells you whether the key works before you spend twenty minutes debugging a plugin that was never the problem.

If you are using a local model

Point the provider at your local endpoint instead of a hosted API. You will need enough VRAM for the context you want, and a model that supports tool calling — an agent runtime with a model that cannot call tools is just an expensive chat window.

Step 3 — install the plugins that matter

This is the step that turns DSH from an interesting shell into a tool. A minimal useful set:

dsh plugin install context
dsh plugin install vision
dsh plugin install tui

• context — gives visibility into the context window. You will otherwise have no idea why a session degraded at message forty.
• vision — routes images through a multimodal model so a text-only model can read a screenshot. Essential for UI work and for debugging anything with an error dialog.
• tui — replaces the default interface with a terminal UI. Skip it if you prefer the web interface.

Add a safety guard before you give the agent write access to anything. These plugins intercept destructive commands — recursive deletes, force pushes, database drops — before they execute. Retrofitting one after an incident is the wrong order of operations.

Browse the full set in the plugin directory. Install syntax varies slightly between plugins, so read each README rather than assuming the command above generalises.

Step 4 — verify it actually works

dsh doctor
dsh run "list the files in this directory and summarise each one"

dsh doctor checks four things: provider connectivity, plugin load order, permission settings, and version compatibility. If a plugin failed to load it will usually tell you why.

The second command is a better test than it looks. It exercises provider auth, file tooling, and context assembly in one shot. If it produces a sensible summary of your current directory, your installation is sound.

Common problems, ranked by frequency

1. A plugin installs but does nothing

Most plugins need an explicit enable step after install. Check the README: if it says dsh plugin enable <name>, that is not optional. The second most common cause is that the plugin requires a capability the core only enables with a config flag.

2. Version mismatch after installing an older plugin

Plugins declare a compatible DSH version range. Installing a plugin written for an older core on a newer core is the most common breakage in the ecosystem — more common than bugs. Pin your DSH version while you stabilise a setup, and read the plugin's compatibility field before installing.

3. Everything is slow

Almost always provider latency, not DSH. Test the same prompt against the provider's own API directly. If it is equally slow there, you have a provider problem. Routing plugins let you fail over to a second provider automatically, which is the real fix.

4. The context fills up immediately

Agent work generates enormous tool output. Install a context manager; they compress tool results before they reach the model, which is where the bulk of context goes. If you have one installed and still fill up fast, check whether it is actually enabled.

5. The agent does the wrong thing confidently

Usually a permission problem rather than an intelligence problem. Give the agent narrower tools and clearer constraints rather than a longer prompt. This is also where a safety guard earns its place.

Upgrading without breaking things

The ecosystem moves fast enough that updates are a real risk. The pattern that works:

• Pin the core version in your configuration rather than always taking latest.
• Upgrade one plugin at a time and run dsh doctor after each.
• Keep a known-good plugin list somewhere you can restore from.

Treat it like a dependency tree, because that is what it is.

Prefer not to use a terminal?

Several desktop clients bundle Node and the core, so you get a GUI and one-click plugin installation on first run. They trade a little flexibility — and usually some lag behind core releases — for a much shorter path to a working setup. For evaluating whether DSH fits your workflow, a desktop client is the faster answer.

Next steps

Once it runs, read the plugin shortlist to see which additions actually change what the runtime can do, and the comparison guide if you are still deciding whether DSH is the right runtime for your work.