How to Install and Set Up DeepSeek Harness (dsh)

What DeepSeek Harness actually is

An "agent harness" is the scaffolding around a model that turns it from a chat window into something that can read a repository, run shell commands, edit files, and carry a multi-step task to completion — the system prompt assembly, the tool registry, the loop that decides "call another tool or stop and answer," and the sandboxing around all of it. DeepSeek Harness is DeepSeek's entry in that category, and its defining choice is architectural: everything is a plugin.

It's built on Cordis, a small plugin runtime whose design is documented as "a programming paradigm for spatiotemporal composability." In practice that means there's no privileged core to patch — the session log, the tool registry, the system-prompt assembler, the LLM adapter, and the agent loop are all plugins that register services and events on a shared context. Swap one out — point the filesystem and subprocess providers at a remote sandbox, for instance — and everything downstream that consumes that capability (bash, PTY, LSP) follows automatically, because they all talk to the same seam rather than a hardcoded implementation.

The project is young: it ships as v0.1.0-rc.7, is explicitly labeled developer preview, and its own README warns "there will be compatibility-breaking changes" before it stabilizes. It's MIT-licensed and open source at github.com/deepseek-ai/deepseek-harness.

Prerequisites

If you only want to try it, skip straight to the npx quickstart below. The source build is only necessary for plugin development or if you want to track master.

Quickstart: the two-minute path

No cloning required — this pulls the published package and starts the web UI directly:

npx @deepseek-ai/dsh web

This serves the UI at http://127.0.0.1:3080. Open it in a browser and jump to configuring the web UI below.

Installing from source

Worth it if you plan to write plugins, want the latest unreleased changes, or need the test/dev tooling.

1. Clone and enter the repository

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

2. Install dependencies

pnpm install

This also wires up worktree-local Lefthook git hooks and a merge driver for translation files. If dependencies were served from cache and the hooks didn't get installed, run the fallback:

node scripts/install-lefthook.mjs

3. Add your API key

Create a .env file at the repository root:

DEEPSEEK_API_KEY=sk-...
# optional — defaults to the public DeepSeek API
DEEPSEEK_BASE_URL=https://...

Never commit this file. Tests and demos that need a live model call skip themselves automatically when the key isn't set.

4. Build

pnpm run build

Under the hood this runs the host and client TypeScript projects through separate tsc -b passes — the repo keeps two isolated TS aggregates (tsconfig.host.json for server-side code, tsconfig.client.json for the browser bundle) so both sides can extend Cordis's Context type differently without colliding — then builds the web assets.

5. Verify and run

pnpm run typecheck
pnpm dsh web

typecheck is a good smoke test that setup succeeded. pnpm dsh web starts the same UI as the npx path, at http://127.0.0.1:3080.

First run: configuring the web UI {#web-ui}

Whichever way you started it, the UI opens with no model and no workspace attached — two things to set before you can send a task.

Add a model. Go to Settings → Models and paste in your DeepSeek API key. It becomes usable immediately, no server restart needed. The same settings page covers pointing it at other providers or any custom OpenAI-compatible endpoint instead — you connect your own provider and it bills you directly for tokens. Choose a workspace. Click Choose workspace and select the project directory you started dsh from. The session composer stays disabled until a workspace is picked. Start a session. With a model and workspace set, start a session and give it a task. The agent can read and edit workspace files, run commands, delegate work, and keep a running plan — it pauses and asks for approval before anything that needs permission clearance.

Running without a browser

For scripting or CI, skip the UI and drive the agent from the CLI directly. This requires DEEPSEEK_API_KEY to be set:

pnpm dsh --profile headless "summarize the changes in this repository"

Two demos are worth knowing about once headless mode works: pnpm run demo:cordis for live plugin inspection, and pnpm run demo:acp for the ACP automation server. A Python SDK also lives under python/sdk for callers who'd rather not shell out to the CLI.

Your first plugin: cordis.yml

Agents are composed from a cordis.yml file — a flat list of plugin entries. name is a module specifier, either a relative path or an npm package name, and the loader mounts every entry in the list:

- name: './hello.ts'

Each entry can carry a config block, validated against a schema the plugin exports — bad config fails at load time with a precise error rather than starting the plugin half-configured:

import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'

export const name = 'config-demo'

export interface Config {
  greeting: string
  targets: string[]
}

export const Config = Schema.object({
  greeting: Schema.string().default('Hello'),
  targets: Schema.array(String).default(['world']),
})

export function apply(ctx: Context, config: Config) {
  for (const target of config.targets) {
    console.log(config.greeting + ', ' + target + '!')
  }
}

The same file carries both the TypeScript Config interface and a runtime Config schema under one name — consumers get the type, Cordis gets the validator. To try a local plugin against the web UI, point an overlay entry at its absolute path.

Where to go from here

The repository's docs/ folder is large and bilingual (English and Chinese). Worth bookmarking:

• docs/architecture.md — the capability-seams model, context keys, bundles and profiles
• docs/development.md — build system, TS project layout, environment setup
• docs/cordis-tutorial/ — seven runnable chapters from "your first plugin" to wiring one into the harness
• docs/user/guide/ — the end-user walkthrough of the web UI
• docs/subsystems/ — deeper notes per subsystem

Bugs and feedback go through GitHub Discussions on the repo, and there's a Discord for the project. Community plugins tend to surface under the dsh-plugin topic on GitHub — apply the same skepticism there as anywhere else and verify a plugin's source before pointing cordis.yml at it.

DeepSeek Harness is pre-1.0 software under active development. Commands, defaults, and config formats shown here reflect v0.1.0-rc.7 and may drift — the repository is the source of truth.

---

Want the concept explained before you dive in, plus an honest pros-and-cons breakdown? → DeepSeek Harness Explained Curious how DeepSeek's models stack up? → DeepSeek V4 Pro: How a 1.6 Trillion Parameter Model Beat Everyone Comparing coding-agent setups? → AGENTS.md and local coding agents