DeepSeek Harness Handbook

August 22, 2026 · View on GitHub

Listed in Awesome DeepSeek Harness, the community-maintained DSH ecosystem directory.

The agent-first, English-canonical field guide to understanding, running, debugging, and extending DeepSeek Harness, with reviewed Simplified Chinese coverage and multilingual foundations. — Community-maintained and open-source.

115 canonical guides · rc.8 and rc.2 source coverage · primary-source links · runnable recovery paths

Unlike a command catalog, this handbook follows the complete Agent boundary: model routing, tools, approval, sandboxing, durable Sessions, plugins, MCP, ACP, and operator-visible failure recovery. Version-sensitive pages identify the source revision they were checked against.

Choose one path and get to evidence quickly:

Run	Debug	Build
Five-minute quickstart	Install Doctor	First plugin lab
CLI map	Failure Router	MCP guide
API cost boundary	Current field status	Agent runtime map

If one of these guides saves an incident or an afternoon, star the repository. Stars help the next Agent builder find a source-backed answer instead of another unverified command list.

Browse the visual field guides · Request a source-backed runbook · Subscribe to new guides · Read the changelog

DeepSeek Harness is more than a model wrapper. It is a composable agent runtime that connects model providers, tools, approval, sandboxing, durable sessions, subagents, and user interfaces through a plugin graph. This independent handbook explains those systems from the perspective of people building and operating agents.

The project is maintained by SandBase. It is not an official DeepSeek AI project.

Important

DeepSeek Harness is in developer preview and may introduce compatibility-breaking changes. Pages in this handbook name their verification date and link to primary sources. Pin the revision you deploy.

Start with your goal

I want to…	Start here
Diagnose manual `/compact` ending with `DeepSeek request aborted by caller`	Manual compaction cancellation runbook
Fix `ERR_PNPM_UNEXPECTED_STORE` during a plugin update	pnpm store-identity recovery
Fix `AbortSignal.any is not a function` even though Node looks current	Runtime identity and offline recovery runbook
Recover Web stuck on Loading plugins in a pnpm source checkout	pnpm symlink boot guide
Separate Responses API full-history traffic, retry attempts, and SSE leaks	Responses overload runbook
Run supported Codex hooks without assuming policy parity	Codex hooks bridge guide
Install the Claude Code hooks bridge without duplicating the runtime	Hooks bridge installation guide
Recover when a second core package copy breaks every tool call	Duplicate core runtime recovery
Design session, model, JSON, and exit semantics for headless embedding	Programmatic headless contract
Build rc.8 in an air-gapped environment without losing provenance	Air-gapped source-build guide
Interpret token estimates, provider usage, UI occupancy, and compaction pressure	Token accounting map
Recover Session creation after editing a live Agent preset	Preset generation recovery
Recover raw pinyin, kana, or jamo in the Web composer	Web IME composition runbook
Protect API keys from backups, same-UID tools, or an untrusted Agent	Credential storage threat model
Recover a Session whose committed event sequence repeats	Duplicate committed seq runbook
Recover a Web composer stuck read-only after sending an image	Image-send admission runbook
Set and verify reasoning effort for a headless one-shot run	Headless reasoning-effort guide
Configure Bailian Token Plan without losing reasoning or model metadata	Bailian catalog-route runbook
Recover tools that repeatedly return `Unknown or expired MCP session`	Expired MCP session loop runbook
Understand the shipped CLI, automate one task, or evaluate a community TUI	DeepSeek Harness CLI map
Recover when the Windows folder picker crashes or truncates a Unicode path	Windows folder-picker crash and truncation guide
Connect to DeepSeek through an authorized proxy or enterprise CA	Provider egress and TLS guide
Fix Web Search authentication when chat uses a custom gateway	Custom-gateway Web Search runbook
Add an MCP server or diagnose missing MCP tools	MCP preset and connection guide
Evaluate DeepSeek Harness as an ACP External Agent in an editor	ACP editor-integration boundary
Render an ACP permission request in a custom Web client	ACP permission UI contract
Move Codex or Claude Code memory without losing provenance or isolation	Sessions, Skills, and long-term memory
Run Web, headless, ACP, or SDK processes concurrently without sharing a writable Session root	Single-writer Session topology
Fix `spawn bash ENOENT` after moving or renaming a workspace	Moved-workspace recovery runbook
Upgrade an exact runtime and preserve a proven rollback	Upgrade and rollback guide
Detect when a community plugin replaces core Agent providers	Composition-diff plugin audit
Choose an exact, reproducible installation topology	Install DeepSeek Harness safely
Diagnose `npx` waiting at the DeepSeek Harness install prompt	npx install-boundary runbook
Create, invoke, and debug a reusable Skill	DeepSeek Harness Skills lab
Decide whether an instruction belongs in global, project, nested, local, or Skill scope	AGENTS.md scope and precedence map
Build, test, package, and install my first plugin	First DeepSeek Harness plugin lab
Keep a plugin subprocess from freezing the Agent Host	Async subprocess tool guide
Discover and manage community plugins from the DSH Web UI	DSH Plugin Store (GitHub)
Fix a plugin boot crash for missing `@deepseek-ai/dsh-client-schema-form`	Plugin distribution-closure runbook
Fix `additionalProperties`, type-array, or `oneOf` tool schema errors	Tool schema subset guide
Distinguish the official Agent runtime from same-name API wrappers	Official DeepSeek Harness identity guide
Check current rc.7 boundaries and safer next actions	DeepSeek Harness rc.7 Field Status
Capture the package and source revision that actually ran	DeepSeek Harness Version Evidence
Find the first broken runtime boundary	Interactive Failure Router
Keep the essential commands and checks in one tab	DeepSeek Harness cheat sheet
Choose the right official runnable example	Official examples map
Understand what DeepSeek Harness actually is	DeepSeek Harness explained
Choose between DeepSeek Harness, Claude Code, and Codex	Source-backed control-plane comparison
Read a Session log without dropping packed assistant output	Session log storage-format map
Recover when an invalid overlay prevents the profile from booting	Invalid-overlay recovery runbook
Run the Web UI safely	Five-minute quickstart
Use it from Python	Python SDK quickstart
Run one task in automation or CI	CLI and Headless Agent guide
Configure DeepSeek or another provider	Model provider guide
Track the rc.2 Files-backed image-input release	Release and migration note
Prove DeepSeek chat and Web search cannot create unexpected charges	DeepSeek API cost-boundary runbook
Fix a context-window or token-budget error	Classify and recover context overflow
Understand why one model switch affects future Agents	Map session and deployment model state
Fix a plugin script corrupted around a dollar sign	Repair tapIndex replacement-string insertion
Fix an OpenAI-compatible gateway that rejects `developer`	Diagnose system-message role compatibility
Fix CJK commands that stall persistent Bash for 300 seconds	Separate the locale/readline trap from PTY corruption
Fix plugin installation blocked by `ERR_PNPM_ADDING_TO_ROOT`	Make the profile workspace target explicit
Fix rc.8 source builds when Node parses an ELF, shell, or Windows pnpm entrypoint	Cross-platform pnpm entrypoint runbook
Stop black console windows flashing during Windows tool calls	Two-path Windows process-creation runbook
Find the corrupt `package.json` behind a pathless boot SyntaxError	Package-closure recovery runbook
Fix an OpenAI-compatible `server_error` that never retries	pi-ai classification and retry evidence
Recover an old Session that throws `received an update before its start Match`	Conversation projection recovery
Recover when pnpm leaves a plugin package behind but DSH skips reconciliation	Partial plugin install recovery
Recover when a Node 24 + tsx build exits 0 but creates no artifacts	Silent source-build recovery
Fix unknown or malformed prompt variables such as `{{hexagon}}` or `{{dotted.state.path}}` in `tools:sdk`	Code Mode literal-section boundary
Fix npm `ETARGET` for `dsh-agent-loop@^0.1.0-rc.8`	Registry and cache recovery
Session title stays on the first-prompt fallback with a reasoning model	Auxiliary title budget diagnosis
Generate exact installation evidence commands for my OS and install path	Interactive Install Doctor
Recover an empty sidebar or unreadable Session without destroying evidence	Route frame, sequence, and tool-call identity failures
Stop a repeating Agent turn before it exhausts a budget	Runaway Agent loop emergency runbook
Detect repeated model text inside one streaming attempt	Degenerate-output guard guide
Stop a foreground tool after `session.cancel` is accepted but work remains live	Stuck-tool cancellation runbook
Recover when every turn in one Session returns invalid JSON	Poisoned Session recovery guide
Recover when every retry reports insufficient tool messages	Missing tool-result recovery guide
Fix a todo that stays in progress after the final answer	Todo state and projection guide
Fix a Code Mode Skill that appears in UI but not model context	Code Mode Skill context guide
Fix `terminal inspection is unsupported on platform win32` in Minimal	Windows Minimal preset Bash guide
Diagnose a frozen first `workspace-write` call on Windows	Windows first ACL grant guide
Run DeepSeek Harness from source on a Synology NAS	Synology NAS deployment guide
Recover when the Agent waits but no question or approval card appears	Missing interaction card guide
Diagnose `Output token limit reached` without confusing it with context overflow	Output token ceiling guide
Recover when a Git plugin installs without its declared `dist/` or `lib/` export	Missing plugin artifact guide
Fix `/compact` when its summary reaches the token cap	Compaction summary truncation guide
Decide which plugin `missing peer` and ignored-build warnings require action	Plugin peer-warning guide
Keep answers in Chinese or another language and diagnose an English Think row	Response and reasoning language guide
Recover a long prompt after Web clears it but the turn fails	Accepted-before-durable prompt recovery
Fix Bailian/DashScope `UNKNOWN_TOOL` or `tool "" is disabled` after a streamed call loses its ID and name	Streamed tool-call identity guide
Explain slow first-token latency before blaming the provider	Mature Session TTFT guide
Fix `ReplaceFileW EACCES` while editing a Windows profile	Windows HMR-watched config recovery
Decide whether worker-thread Code Mode fits the security boundary	Code Mode trust-boundary guide
Fix Web, headless, or custom-profile startup reporting `--expose-internals` is required	HMR loader-capability diagnosis
Fix a pnpm global install that reports an installed plugin as missing	Global native-binding resolution guide
Fix macOS workspace selection when the path ends in `:/`	macOS native picker path guide
Persist downstream plugin events without breaking Session resume	Custom Session event compatibility
Connect external MCP tools	MCP integration guide
Add reusable Agent instructions	Skills guide
Delegate work to child Agents	Subagents guide
Understand the runtime	The agent-runtime mental model
Understand one complete turn	Agent Loop and Session Events
Choose between Session persistence and long-term memory	Sessions are not long-term memory
Understand approval, guards, and tool effects	Tool execution pipeline
Build an Agent rather than a loose collection of tools	Agent design map
Research a repository without publishing changes	Repository Research Agent recipe
Run or debug DeepSeek Harness on Windows	Windows compatibility guide
Recover a profile after a plugin change	Plugin install and recovery guide
Diagnose an `ERR_HTTP2_INVALID_SESSION` crash	HTTP/2 provider-transport troubleshooting
Fix `crypto.randomUUID` or `host.pickDirectory` HTTP 403 without weakening the Agent shell	Remote Web control-plane guide
Fix persistent Bash on NixOS or minimal Linux	PTY shell-path guide
Protect or recover a session log	Live session log durability
Fix first Session flush when the filesystem rejects hard links	Session hard-link compatibility runbook
Fix a failing installation or run	Troubleshooting index
Track upstream changes	Updates and breaking changes

The agent-first mental model

flowchart LR
  U[User goal] --> A[Agent contract]
  A --> C[Profile + Bundles + Patches]
  C --> G[Cordis plugin graph]
  G --> L[Agent Loop]
  L --> M[Model provider]
  L --> T[Tools + policy + approval + sandbox]
  L --> S[Durable Session events]
  S --> L
  S --> H[Web, headless, SDK, clients]

An agent is not just a prompt. A useful Agent has a task boundary, allowed effects, completion condition, model route, tool surface, permission policy, session strategy, failure behavior, and an operator-visible result. DeepSeek Harness supplies the runtime vocabulary for assembling those responsibilities without forcing every product into one fixed loop or interface.

What makes this handbook different

Agent-first: concepts are organized around building, running, and debugging Agents.
Source-backed: version-sensitive claims link to official documentation or source.
Operational: every tutorial includes success evidence, failure branches, and safety boundaries.
Visual: architecture pages prioritize diagrams over walls of text.
Living: updates, breaking changes, and troubleshooting pages follow upstream development.
Multilingual by design: English is canonical; translations declare their source revision and review status. Current depth is reported explicitly.

Language coverage

Locale	Current status	Published coverage
English	Canonical	115 pages
简体中文	Reviewed	Navigation plus three core guides
日本語	Draft	Navigation only
한국어	Draft	Navigation only
Español	Draft	Navigation only

The locale links at the top do not imply feature parity. English remains the source of truth until a translation points to the current canonical revision and has been reviewed by a fluent contributor.

Published guide map

Every item below is available now. Planned coverage lives in the public roadmap.

Getting started

Architecture

Agent patterns

Recipes

Repository Research Agent

Operations

Keep concurrent Session roots single-writer

Official examples

Choose the right upstream example
Headless CLI task runner
Python SDK and JSON-RPC runtime
ACP automation server
MCP memory overlays
Self-modifying Cordis composition
Session-local schedules

Integrations

Plugin development

Security

Searchable operations

Repository structure

docs/<locale>/
  getting-started/     installation and first runs
  architecture/        runtime and lifecycle explanations
  agent-patterns/      design decisions for real agents
  recipes/             reproducible agent builds
  troubleshooting/     symptom-driven diagnostic pages
  ecosystem/           plugins, tools, skills, and comparisons
  updates/             upstream change coverage
scripts/               content and translation verification
content-manifest.json  canonical revision and locale status

Editorial and commercial boundary

DeepSeek Harness remains the subject of every technical page. SandBase maintains the handbook and may provide a restrained link to related Agent, model, Skill, or MCP discovery resources. A mention is never presented as an official DeepSeek recommendation, a compatibility guarantee, or a security endorsement.