Skip to content
BSWEN
Blog

How to Install DeepSeek Harness and Run Your First Agent Task

Cowrie
Cowrie
Dev @ Bswen

Purpose

This post shows how to install DeepSeek Harness and run your first agent task: start the Web UI, connect a model, pick a workspace, and send a task.

Direct answer

Install with npm and run the Web UI directly:

Run the Web UI (no global install needed)
npx @deepseek-ai/dsh web
# -> Web UI at http://127.0.0.1:3080

In the Web UI, go to Settings → Models, paste your DeepSeek API key, choose a workspace, start a session, and send a task like “Summarize this repository.” That is the whole quickstart.

Environment

  • Node.js with npm (or pnpm/Bun if building from source)
  • No GPU or local model is required: the default path uses the DeepSeek API

What is DeepSeek Harness

DeepSeek Harness is DeepSeek’s open-source coding-agent harness. What makes it different is that every component is a plugin running on the Cordis framework: model adapters, tools, the agent loop, even the UI. In general, a harness has five layers:

The five layers of an AI coding harness

Because components are plugins, you can change them without restarting the server. That is why installation and configuration feel different from other tools.

Step 1: Install

Pick one of these options.

Option A: Web UI only (no global install)

Run the Web UI directly
npx @deepseek-ai/dsh web

This prints the URL and serves the Web UI at http://127.0.0.1:3080 by default.

Option B: Global CLI

Install the global CLI
npm install -g @deepseek-ai/dsh
dsh web

The @deepseek-ai/dsh package declares the dsh bin for profile boot, plugin management, and the browser UI alias.

Option C: Python SDK

Install the Python SDK
python -m pip install deepseek-harness-sdk

Option D: From source

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

Step 2: Configure a model

Open the Web UI and go to Settings → Models, then enter your DeepSeek API key. The model route becomes usable immediately, without restarting the server.

For other providers or local models, use the providers configuration in YAML with apiKeyEnv and an OpenAI-compatible baseURL:

providers config for a local llama.cpp endpoint
- id: llm
  name: '@deepseek-ai/dsh-llm-pi-ai'
  config:
    providers:
      local:
        apiKeyEnv: LOCAL_API_KEY
        api: openai-completions
        baseURL: http://127.0.0.1:8080/v1
        models:
          - id: qwen3-9b

This is how a local 9B Qwen 3.x model running in llama.cpp connects. A HN user reported it “works GREAT for small python projects” and was “very easy to connect” to the local model.

Step 3: Choose a workspace

Click Choose workspace and select your project directory. The dsh process uses its invoking directory as the default filesystem location, and the session composer stays disabled until a workspace is selected.

Step 4: Run your first task

Start a session and send:

First task
Summarize this repository and identify its main packages.

The agent can read and edit files, run commands, delegate work, and maintain a plan. It asks for approval where the permission policy requires it.

Step 5: Add a plugin (optional)

Plugins are managed per profile:

Add and remove plugins
dsh plugin --profile demo add ./hello-plugin
dsh plugin --profile tui add github:deepseek-harness/turtle-ui
dsh plugin --profile tui remove turtle-ui
dsh --profile tui

Common mistakes

  • Forgetting to select a workspace: the session composer is unavailable until one is chosen.
  • Skipping model configuration: the model route is unusable until an API key is saved or a provider is declared in the YAML settings.
  • Expecting a stable API: the project is a release candidate, and “the API is not yet stable and may change without notice,” so pin versions for production use.
  • Hard-coding keys into settings files: use apiKeyEnv environment variables instead.

Why this matters

DeepSeek Harness is designed so every component is a hot-reloadable plugin. You can add a plugin, change a model adapter, or swap a UI without restarting the server. Knowing the install path gets you to that workflow quickly, and connecting a local model keeps costs near zero.

Summary

In this post, I showed how to install DeepSeek Harness with one command, configure a model, choose a workspace, and run your first agent task. The key point is npx @deepseek-ai/dsh web gets you to a working Web UI, then you add a model key, a workspace, and a first task. Start with the Web UI, add the global dsh CLI when you want profiles and plugins, and point the providers config at a local model when you want to go cost-free.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: