DeepSeek Harness: Detailed Introduction

[ikaijua]

DeepSeek Harness: Detailed Introduction

DeepSeek AI's open-source agent harness (dsh) on an "everything is a plugin" architecture (Cordis) — a full agent runtime with CLI + local Web UI. Open-sourced August 13, 2026 (MIT, 70K+ stars in 24h); the October 3 release added an experimental Claude Code Mods compatibility layer. Still developer preview.

Positioning. DeepSeek's answer to Claude Code / Codex — but open-source, model-agnostic, and fully plugin-based; even the agent loop is a replaceable plugin.
Signature capability. Four runtime modes; can absorb Claude Code / Codex as subagents; every run fully traceable via append-only session logs.
Reception. Called "the Linux moment of agents" by the community for its architectural originality; maturity still trails Claude Code / Codex.
Pricing. Free — MIT-licensed; pay per token only if you use DeepSeek's API (any vendor's model is supported).
Caveats. Developer preview with breaking changes; the Mods compatibility layer is experimental and does not run all Mods seamlessly.

Floors below follow: Product Overview → Getting Started → Resources.

Table of Contents

Product Overview

1. What is DeepSeek Harness?
2. Highlights
3. Core Concepts
4. Subsystems at a Glance
5. When to Pick DeepSeek Harness
6. Caveats

Getting Started

7. Install & Run
8. Typical Use Cases

Resources

9. Related Resources
10. License

Click a TOC entry to jump to the corresponding comment; if in-page clicking does not work, open the link in a new tab.

[ikaijua]

What is DeepSeek Harness?

DeepSeek Harness (dsh) is DeepSeek AI's open-source agent harness built on Cordis's "everything is a plugin" architecture, shipping as CLI + local Web UI.

It is a full agent runtime covering LLM, MCP, LSP, ACP, sandbox, skills, subagents, sessions, tools, plans, scheduling, shell, and the web layer.

⚠️ Developer preview. Released August 13, 2026 as v0.1 (MIT); hit 70K+ GitHub stars within 24 hours. Iterating weekly ever since (RC.8 → 0.1.2-rc.1 → 0.1.7-rc line). Breaking changes are expected; treat the CLI/API as unstable.

New in the October 3, 2026 release:

• Experimental Claude Code Mods compatibility layer: some extensions built for Anthropic's Claude Code can, after adaptation, run inside DeepSeek Harness
• Pluginization and cross-platform capabilities strengthened
• Lead maintainer Cui Tianyi said the layer's purpose is to test whether "Claude Code Mods' extension surface is a subset of DSH's plugin capabilities"; not all Mods run seamlessly yet, but it is technically feasible in the future

[ikaijua]

Highlights

• Everything is a plugin. The runtime is built on Cordis, a well-known IoC-style plugin framework. Every subsystem — LLM, MCP, LSP, sessions, tools, plans, sandbox, scheduling, web, etc. — is a Cordis plugin using the same event / service / effect model. Even the agent loop itself is a replaceable plugin.
• CLI + Web UI out of the box. Run npx @deepseek-ai/dsh web and the Web UI is served at http://127.0.0.1:3080. No separate "headless" vs "GUI" build.
• Four runtime modes (presets). Standard (full toolset); Code/PTC mode (the model writes one TypeScript program that orchestrates multiple tool calls, cutting token usage); Minimal (only a shell tool + file editor — used by DeepSeek for official model benchmarks); Creator (runtime inspection + in-memory plugin experiments to compose new modes).
• Native image input. Model adapters can send images directly; for models without vision, the harness falls back to OCR / color statistics / pixel scanning tools to turn images into structured info — a "poor man's vision" for text-only models.
• Absorbs competitors as subagents. Claude Code and Codex can be installed as Profile Bundles and dispatched as task executors inside DSH workflows (Codex supports non-interactive permission modes and multiple named instances).
• Every run is traceable. Everything the model sees is recorded in an append-only session log (system prompts, reasoning, tool calls and results, subagent scheduling, context injections); the Trajectory view lets you inspect by source, and resume / fork / search / replay all operate on the same event stream.
• Bilingual architecture docs. The docs/ tree ships in English and Chinese: architecture, agent lifecycle, tool execution pipeline, capability seams, the Cordis primer, defensive patterns, and more.
• 40+ first-party packages. core, llm, mcp, lsp, acp, sandbox, skill, subagent, session, tools, plan, goal, schedule, web, shell, terminal, workflow, jobs, hooks, guard, feedback, compaction, context, attachment, identity, credentials, e2b, runtime-diagnostics, typert, client, host, sdk, extensions, bundle, boot, storage, preset, etc.
• Ecosystem growing fast. ~300 community plugins during beta, 1000+ after open-sourcing; 100+ built-in official plugins; a Plugin Store is planned.
• MIT licensed. Full source, docs, and tooling are MIT.

[ikaijua]

Core Concepts

• Plugin (Cordis) — the fundamental unit. A plugin declares events, services, and effects, and can await services from other plugins.
• Service — an injectable capability. Plugins obtain services via this.someService and await them.
• Event — a typed lifecycle hook, used for inter-plugin messaging and for the harness's own diagnostic surfaces.
• Effect — long-running side effect (e.g. a tool call, a sandboxed subprocess) registered with the lifecycle system.
• Capability seams — the explicit places where new capabilities (LLM provider, tool, transport, storage) plug in. See docs/capability-seams.md upstream.

The combination of these primitives is what makes the architecture "everything is a plugin" rather than a hard-coded pipeline of features.

[ikaijua]

Subsystems at a Glance

Subsystem	Package(s)	What it does
Core runtime	core, runtime-diagnostics, compaction	Plugin lifecycle, error/trace, context window compaction
LLM & tools	llm, tool-catalog, tool-execution-pipeline	Provider abstraction, tool registry, sandboxed tool execution
Agent orchestration	agent, subagent, plan, goal	Agent lifecycle, sub-agents, planning, goal tracking
Skills & memory	skill, feedback, context	Reusable skills, feedback loop, working context
Sessions & jobs	session, session-query, jobs	Long-running sessions, queries, scheduled jobs
External integrations	mcp, lsp, acp, client	MCP servers, language servers, ACP, client-side integrations
Sandbox & execution	sandbox, e2b, subprocess, shell, terminal	Sandboxed code/tool execution, subprocess management, shell/terminal
UI & web	web, host, interaction	Web UI, host runtime, user interaction
Storage & identity	storage, credentials, identity, attachment	Persistence, secrets, identity, file attachments
Extension surface	extensions, sdk, hooks, guard	Custom plugins, SDK, hook points, guardrails
Workflow	workflow, schedule, boot, bundle	Workflow definitions, scheduled runs, bootstrap, packaging
Diagnostics	runtime-diagnostics, compaction, typert	Tracing, compaction policies, schema types

See docs/architecture.md in the upstream repo for the canonical subsystem diagram.

[ikaijua]

When to Pick DeepSeek Harness

Pick it if…	Maybe skip if…
You want a DeepSeek-maintained, MIT-licensed agent runtime that is genuinely plugin-based (not a hard-coded pipeline).	You just want a polished CLI coding agent today — Claude Code / Codex / Kimi Code / Antigravity are more battle-tested right now.
You need to embed or extend an agent runtime and prefer its surface area to be Cordis plugins.	You depend on a stable, documented CLI API — the upstream dsh CLI is still labelled "developer preview".
You want a runtime that natively speaks MCP, LSP, and ACP.	You only need a chat UI with no runtime customization.

Since October 3, it is also the pick if you want to run Claude Code Mods inside an open, plugin-based runtime — but the compatibility layer is experimental.

[ikaijua]

Caveats

• Still a developer preview. From v0.1 (Aug 13) to the 0.1.7-rc line, docs, CLI and APIs keep changing; breaking changes can land any time — not yet a daily-production-workflow tool.
• The Claude Code Mods layer is experimental. Not all Mods run seamlessly; the official positioning is to test the plugin capability boundary.
• Documentation lags code in places. Most docs are bilingual and high quality, but some newer packages may not yet be fully covered.
• npm distribution is accelerating but the API is not stable. @deepseek-ai/dsh is now on the 0.1.7-rc line; check migration notes before upgrading (e.g. Session log v4 upgrade, settings & preset migration).
• No public cloud tier. Self-hosted, local-first runtime; no hosted offering from DeepSeek for the harness itself (as of this writing).
• Plugin supply chain is a double-edged sword. A tool plugin can touch files and the network; a storage plugin holds full sessions — vet plugin provenance, permission boundaries and dependency conflicts before production use.

[ikaijua]

Install & Run

Web UI (recommended for first try)

# Requires Node.js
npx @deepseek-ai/dsh web

The command starts the Web UI, served at http://127.0.0.1:3080 by default. See the Web UI guide in the upstream docs for the --host / --port flags.

Run from source

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

[ikaijua]

Typical Use Cases

• Standalone agent runner. Run dsh from the terminal or open the Web UI and use it as a coding/research agent — similar to Claude Code or Codex, with the difference that every capability is a plugin.
• Switch modes per job. Standard mode for daily coding; Code/PTC mode for batch operations / complex orchestrations (token-efficient); Minimal mode for model benchmarks; Creator mode for plugin development and custom presets.
• Dispatch Claude Code / Codex as subagents. Install them as Profile Bundles and use them as task executors inside DSH workflows; reportDelivery returns results and wakes the waiting parent task, so multi-agent collaboration does not sit idle.
• Embed in your own product. Because the runtime is a set of Cordis plugins, you can import only the packages you need and skip the rest (e.g. drop the Web UI and run headless).
• Extend with your own LLM / tools. Add a new provider or tool by writing a small Cordis plugin that registers a service and an effect. The harness handles the lifecycle, the event bus, and the rest of the wiring.
• Spec-driven or workflow-driven runs. Use the workflow, plan, goal, and schedule packages to run multi-step, time-based, or goal-oriented jobs that survive restarts.

[ikaijua]

Related Resources

• GitHub Repository
• Architecture documentation (upstream)
• Cordis primer (upstream)
• Agent lifecycle (upstream)
• Tool execution pipeline (upstream)
• Community Discord
• Chinese version

[ikaijua]

License

MIT — see LICENSE.