Open source · MIT

DeepSeek Harness

DeepSeek's local agent harness gives models a plugin-composed body: tools, sessions, permissions, subagents, workflows, and multiple ways to run. This guide turns the official repository and community technical walkthrough into a practical starting point.

Run Harness View sourceDeveloper preview

Agent = Model + Harness

Give the model a body built from plugins.

DeepSeek Harness is not just a chat box. It assembles the model, tools, session history, approval rules, workspace access, and delegation behavior into a local coding agent.

License: MIT
Default UI: 127.0.0.1:3080
Status: Developer preview

terminal

$ npx @deepseek-ai/dsh web

dsh web: http://127.0.0.1:3080

Open npm package Downloads

Developer preview

The official README says DeepSeek Harness is iterating rapidly and will introduce compatibility-breaking changes. Treat copied configuration, plugin APIs, and RC package behavior as versioned material, and check the repository before automating an upgrade.

Architecture

The important ideas, without reading the whole monorepo

The V2EX walkthrough is useful because it follows the system from plugin composition to modes, Code Mode, session events, delegation, and governance. The summary below keeps that path but uses the public repository as the factual baseline.

Everything is a plugin

Model adapters, the tool registry, the session log, and the agent loop are mounted as Cordis plugins. A plugin can add or replace a capability without patching a privileged core.

Four built-in agent presets

Standard, PTC, Minimal, and Creator presets package different tools, prompts, and behaviors. A running session keeps the preset it started with.

Code Mode

PTC mode exposes tools through a generated TypeScript SDK, allowing the model to combine conditions, loops, parallel calls, and filtering in one program.

Append-only session log

Model-visible inputs, assistant output, tool calls, and tool results are reconstructed from durable session events so sessions can be inspected, resumed, and replayed.

Multi-agent workflows

An agent can delegate to child agents, continue background children, or run scripted workflows that coordinate multiple agents with bounded lifecycle and cleanup.

Sandbox and approvals

Read-only, workspace-write, and full-access policies separate file effects from approval decisions. Operations that need approval pause for a user decision.

Composition model

Profiles stack bundles, then patches

A running dsh process is a plugin tree. A profile selects ordered bundles; profile, home, and command-line patches can then replace or insert configuration rows. That makes the shipped Web and headless surfaces different compositions of the same system.

Read the official architecture

Profile

Named composition stored in the Harness home

Bundles

Base, Web UI, or headless plugin rows

Patches

Profile → home → optional CLI overlay

Cordis plugin tree

Model · tools · session · loop · policies

Agent presets

Four modes, four plugin compositions

Selecting a mode selects the complete tool, prompt, and capability set for the next session. Running sessions keep their original preset so earlier tool calls remain reproducible.

Standard mode

standard

The full coding agent: file editing, shell, file and web search, Skills, planning, goals, subagents, and workflows.

PTC mode

code

All Standard capabilities, with tools presented through Code Mode so multi-step work can be composed in TypeScript.

Minimal mode

minimal

A focused two-tool coding agent with persistent Bash and str_replace_editor.

Creator mode

cordis

Standard capabilities plus runtime inspection, plugin experiments, and guidance for authoring a custom agent preset.

Quick start

From zero to the first workspace task

The npm path is the shortest way to open the Web UI. Use the source path when you want to inspect, modify, or contribute to the plugin tree itself.

Start the Web UI

Install a supported Node.js version, run the npm command, and open the printed local URL. The default address is 127.0.0.1:3080.

Configure a model

Open Settings → Models, add a DeepSeek API key, or configure another installed provider or custom compatible endpoint.

Choose a workspace

Add the project directory where dsh was started and select it. The session composer stays disabled until a workspace is selected.

Run a real task

Create a session, choose an agent preset, then ask the agent to inspect the repository, edit files, run commands, or delegate work.

Fastest path

Run from npm

npm

$ npx @deepseek-ai/dsh web

The command starts the local Web UI. Keep it local unless you intentionally configure a trusted network boundary.

Contributor path

Run from source

source

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

Check current prerequisites

More ways to use Harness

Web UI, one-shot CLI, SDKs, and plugins

Web UI

Local browser interface for sessions, workspaces, model settings, approvals, and preset selection.

Headless profile

A one-shot runner that accepts a task, prints the final assistant response, and opens no HTTP port.

Python SDK

A high-level turns API and lower-level JSON-RPC client with a packaged runtime for programmatic use.

Plugin development

Build tools, providers, services, events, and complete agent presets on top of the Cordis composition model.

Downloads and links

Use the official distribution paths

There is no desktop installer advertised by the official README. Run the published npm CLI, download the source archive, or use the Python SDK for programmatic integration.

npm

@deepseek-ai/dsh

Open the published CLI package used by the one-command Web UI quick start.

Open npm

Source archive

Download master.zip

Download the current repository source as a ZIP archive without cloning Git history.

Download ZIP

Python SDK

deepseek-harness-sdk

Install the packaged Python client and bundled runtime for JSON-RPC-driven agent tasks.

Open PyPI

Source

GitHub repository

Browse the monorepo, issues, license, source instructions, and latest development activity.

Browse source

Documentation

Web UI guide

Configure a model, select a workspace, and run the first task in the official interface.

Read guide

Community

GitHub Discussions

Send product feedback, report bugs, and follow questions from other Harness users.

Open discussions

Want to build a Harness plugin?

Start with the official minimal plugin tutorial, then use the architecture and generated configuration catalog as the source of truth for current interfaces.

Open plugin guide

Sources

Product status, install commands, and architecture claims are grounded in the official DeepSeek repository. The V2EX article is included as the community technical walkthrough requested for this page; its private-test anecdotes and unverified ecosystem counts are not repeated as official facts.