DeepSeek Harness Documentation
by DeepSeek AI
The only agent harness that documents its own loop, session log and tool pipeline as replaceable plugins.
Overview
DeepSeek Harness (dsh) is DeepSeek AI's open-source agent harness, published 13 August 2026 and still labelled developer preview with breaking changes expected. The documentation splits into a user guide (quickstart, Web UI, model providers, scheduling, MCP memory, network proxy, GitHub review, Python SDK), a development track divided into basic plugin authoring, framework internals and production practice, plus a Cordis primer and API reference, a cookbook, subsystem docs and a postmortem section — every page mirrored in English and Chinese. The architecture chapter is the substantive part: a running dsh is described as a plugin tree composed at boot from ordered layers, where a bundle packages Cordis config and code, a profile (web, headless, sdk) names a composition, and patches override rows at bundle, profile, home and CLI-overlay level. There is deliberately no privileged core — the model adapter, tool registry, session log and the agent loop itself are all plugins. A turn is defined as a group of steps, each step one model request plus its tool calls, and the docs enumerate the hooks a plugin can attach to: agent/pre-step, agent/request, llm/stream, tools/pre-execute, tools/execute, tools/post-execute and agent/turn-stopping. Sessions are append-only JSONL event logs with Zstandard compression, and the stated invariant is that anything reaching the model must be reconstructible from logged events via deriveMessages(). The Cordis primer covers contexts as service repositories, inject-declared load ordering, five event dispatch modes (emit, waterfall, parallel, serial, bail) and reversible effects that unwind cleanly on reload. Stack: Node.js CLI, TypeScript and Python SDKs, an Electron desktop app, pnpm, MIT licence.
At a Glance
- Topic
- Frameworks
- Level
- Advanced
- Format
- Documentation
- Cost
- Free
- Duration
- ~5-8 hours to work through the user guide, Cordis primer and architecture chapter; self-paced reference thereafter
- Provider
- DeepSeek AI
- Hands-on
- Yes — code/exercises
- Certificate
- None
What You’ll Learn
- ✓How a plugin tree is composed at boot from ordered bundle, profile, home and CLI layers
- ✓How to author a Cordis plugin that registers services, typed events and reversible effects
- ✓Where to hook an agent loop: agent/pre-step, agent/request, llm/stream and agent/turn-stopping
- ✓How a tool pipeline sequences pre-execute, execute and post-execute around durable tool events
- ✓How append-only JSONL session logs project model history through deriveMessages() and survive migrations
- ✓How to configure model providers, wire MCP memory, schedule runs and sit behind a network proxy
- ✓How the sandbox backend confines spawned processes so filesystem and subprocess share one execution world
- ✓How to drive the harness headlessly from the Python SDK instead of the bundled Web UI
Highlights
- •Documents the parts most harnesses hide — the agent loop, session log, tool registry and model adapter are all swappable plugins with published extension points
- •One of the fastest adoption curves GitHub has recorded: ~218k stars and ~26k forks within weeks of the August 2026 release
- •The 747-point Hacker News launch thread had a maintainer answering in-thread; commenters singled out the append-only session log as replay/inspection capability closed harnesses do not offer
- •Honest caveats are easy to find: it is still a developer preview, and HN critics called out plugin-ecosystem rot risk and a bare batteries-not-included core
- •Security history is public — CVE-2026-82533 (CVSS 9.4) let a sandboxed agent flip its own session to danger-full-access via a spoofed Host header; fixed in 0.1.2-alpha.1 on 27 August 2026
- •Fully bilingual English/Chinese, including a postmortem section that publishes real incident write-ups
Who It’s For
Best For
- ✓Engineers building or forking an agent runtime rather than consuming one
- ✓Teams that need replayable, auditable agent execution traces for debugging or compliance
- ✓TypeScript and Node developers writing tool, model-adapter or sandbox plugins
- ✓Anyone evaluating self-hosted coding agents against Claude Code or Codex CLI
Prerequisites
- •Solid TypeScript/Node.js and a working pnpm toolchain
- •Prior experience with an agent loop, tool calling and MCP concepts
- •Comfort reading architecture docs and source — the developer preview moves faster than tutorials do
FAQ
What is DeepSeek Harness Documentation?
Official documentation for DeepSeek Harness (dsh), the agent runtime DeepSeek AI open-sourced on 13 August 2026 under an everything-is-a-plugin design. It is written for engineers who want to rebuild parts of an agent loop rather than call one, and it covers the plugin tree, the append-only session event log, the tool execution pipeline and the sandbox in enough detail to write your own harness plugin afterwards.
Is DeepSeek Harness Documentation free?
DeepSeek Harness Documentation is free to access.
What level is DeepSeek Harness Documentation for?
DeepSeek Harness Documentation is aimed at a advanced audience. Recommended background: Solid TypeScript/Node.js and a working pnpm toolchain, Prior experience with an agent loop, tool calling and MCP concepts, Comfort reading architecture docs and source — the developer preview moves faster than tutorials do.
How long does DeepSeek Harness Documentation take?
Expect roughly ~5-8 hours to work through the user guide, Cordis primer and architecture chapter; self-paced reference thereafter. Most learners work through it at their own pace.
What will I learn from DeepSeek Harness Documentation?
You'll learn: How a plugin tree is composed at boot from ordered bundle, profile, home and CLI layers; How to author a Cordis plugin that registers services, typed events and reversible effects; Where to hook an agent loop: agent/pre-step, agent/request, llm/stream and agent/turn-stopping; How a tool pipeline sequences pre-execute, execute and post-execute around durable tool events; How append-only JSONL session logs project model history through deriveMessages() and survive migrations; How to configure model providers, wire MCP memory, schedule runs and sit behind a network proxy; How the sandbox backend confines spawned processes so filesystem and subprocess share one execution world; How to drive the harness headlessly from the Python SDK instead of the bundled Web UI.
Topics
Sources
This page was written from 6 sources, 5 on domains other than deepseek-harness.github.io.