deepseek-harness

A beginner’s field guide · 2026

Everything
is a plugin.

DeepSeek Harness is an open-source runtime for building and running coding agents. Its defining idea is simple: the model, tools, session log, agent loop and user interface are all replaceable parts.

DeepSeek Harness · dshUse ← → or swipe to move through the story
Source: repository README

01 · TL;DR

Think of it as Lego for agent workflows.

You get a working agent, then swap or add the pieces you care about: models, tools, memory, approval rules, interfaces, and automation triggers.

01

Compose instead of fork. Add behaviour beside the existing system through plugins and patch layers.

02

Keep the same core across surfaces. Use a browser, a one-shot CLI, a Python/TypeScript client, or ACP automation.

03

Make work inspectable. Sessions are durable event streams that power replay, UI history and downstream consumers.

Local coding cockpitChat with an agent over a selected workspace in the Web UI.
CI and batch jobsRun one task headlessly and use the exit code in a script.
Product integrationDrive a persistent harness from Python or TypeScript over JSON-RPC.
Event-driven workflowsUse patches for MCP memory, scheduled reminders or GitHub review sessions.
Sources: architecture · Web UI guide

02 · Mental model

One shared context. Many replaceable capabilities.

Cordis is the plugin framework underneath dsh. Plugins contribute services, typed events and reversible effects to a shared context.

The important shift: there is no privileged “core feature” you have to patch. You mount a plugin beside the others, and its registrations unwind when it unloads.
shared
contextctx
model adapterctx.llm
tool registryctx.tools
session logctx.sessions
agent loopctx.agentLoop
Source: DeepSeek Harness architecture

03 · How composition works

The composition is the product.

A running dsh process is a plugin tree assembled from ordered layers. You can see the tree, patch it, and reuse the same composition across launch surfaces.

Rule to remember: a patch replaces a row’s whole config. Later layers win, so restate the settings you want to keep.
bundle

Reusable distribution layer. A package of Cordis config rows plus the code they mount.

profile

Named application recipe. For example: web, headless, sdk, or acp.

patch

Your overlay. Insert a plugin, replace a provider, or change a policy without editing the core.

Source: profiles and bundles

04 · Choose your surface

Same harness. Different way in.

Web UI

Interactive, multi-turn work in a browser. Select a workspace, configure a model, and chat with the agent.

dsh web
Best forInteractive exploration
Startshttp://127.0.0.1:3080
Key boundaryWorkspace must be selected
Source: application launch · headless profile

05 · Under the hood

One user request becomes a durable, observable turn.

Click a stage to see what the harness is doing. A step is one model request plus its tools; a turn can contain multiple steps.

Turn starts. The harness claims the next input, opens a turn, and prepares to run one or more steps.
Source: turn flow and session log

06 · Use cases

Pick the job. Pick the surface.

Local coding cockpit

Launch the Web UI, choose a project directory, and ask the agent to inspect, edit, test or explain the workspace. Approval prompts sit in the workflow when an operation needs permission.

dsh web
→ Settings → Models
→ Choose workspace → send a task
Sources: Web UI · MCP memory · GitHub review

07 · The extension model

Plugins stay small because the harness supplies the seams.

A plugin declares what it needs, then contributes one focused capability. Here, the plugin asks for the tools service and registers a model-callable greeting tool.

inject keeps the plugin pending until the required service exists.
defineTool gives the model a schema, validates arguments, and separates the returned value from rendered result content.
Unload is reversible. The registration disposer is attached to the plugin lifecycle.
greet-tool.ts
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'greet-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'greet',
    description: 'Greet the named person.',
    parameters: {
      name: { type: 'string', required: true }
    },
    output: { schema: { type: 'string' } },
    async execute(args) {
      return \`Hello, ${args.name}!\`
    }
  }))
}
Source: Cordis tutorial · Into the harness

08 · Read this before running it

Experimental means experimental.

The repository says DeepSeek Harness is a developer preview, has not undergone a security audit, and must not be treated as production-ready.

What it can touch

Model-generated code and commands, third-party plugins, network access, processes, credentials and files made available to it.

What can go wrong

Incorrect output, defects, misconfiguration, malicious input or an untrusted plugin may modify files or disclose data.

Responsible baseline

Use least privilege, a disposable VM/container or dedicated environment, backups, and reviewed plugins and commands.

Practical read: treat the harness as powerful developer tooling with a clear blast radius, not as a security boundary for untrusted workloads.
Source: SAFETY.md

09 · How-to guide · 1 of 3

Get to your first useful session.

STEP 01 / 05

Install and launch

For a quick trial, use Node.js and run the published launcher. The default Web UI listens on loopback.

npx @deepseek-ai/dsh web
Sources: README · Run · Web UI guide

10 · How-to guide · 2 of 3

Add one capability through a patch.

Start from the repository’s Cordis tutorial. It demonstrates the smallest useful path: a TypeScript plugin, a composition file, and the real harness tool pipeline.

cordis.yml
# Compose the dependencies first
- name: '@deepseek-ai/dsh-system-prompt'
- name: '@deepseek-ai/dsh-tools'
- name: './tool-logger.ts'
- name: './greet-tool.ts'
1. Create greet-tool.ts and register greet.
2. Compose the system-prompt and tools providers plus your plugin.
3. Run the Cordis tutorial launcher, then observe the tool result event.
4. Graduate the plugin into a dsh patch overlay once the behaviour is useful.
Source: Cordis tutorial · Into the harness

11 · How-to guide · 3 of 3

Move from trial to a repeatable local setup.

From a repository checkout

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

The development guide currently calls for Node.js 22.19+ or 24+, Corepack-enabled pnpm, and Git 2.26+.

Then customise deliberately

01

Inspect the boot tree.
dsh --profile web --dump-config

02

Keep credentials out of code.
Use the settings flow or environment variables such as DEEPSEEK_API_KEY.

03

Add an overlay.
Try a shipped example with --patch, or install an external bundle with dsh plugin.

04

Verify the boundary.
Use a disposable workspace and read the safety notice before granting access.

Sources: development guide · model providers

12 · Takeaway

Use it when you want the agent to be a system, not a chat box.

DeepSeek Harness gives you a composable runtime: choose a surface, keep a durable session stream, and extend the system through explicit seams.

Good fit

Developer tools, local coding workflows, CI agents, product integrations, event-triggered reviews, and experiments where you want to swap parts without rewriting the whole harness.

Be cautious

Untrusted workloads, sensitive credentials, production-critical automation, or any environment where the current developer-preview status and sandbox limits are unacceptable.

Continue reading

GitHub repository →Official documentation →Cordis tutorial →Safety notice →
Built from repository documentation · links open in a new tab
Copied