mcp server

deepseek-harness-handbook

Agent-first DeepSeek Harness handbook: 173 source-backed runtime, plugin, MCP, sandbox, evaluation, troubleshooting, multilingual, and 74-resource Awesome ecosystem guides.

sandbaseai/deepseek-harness-handbookcommunitylistedunreviewednot running here yet

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

This project does not publish an install method we can turn into a config. Follow the README instead.

README

synced Oct 14, 2026

DeepSeek Harness Handbook

English · 简体中文 · 日本語 · 한국어 · Español

Listed in Awesome DeepSeek Harness, the community-maintained DSH ecosystem directory. Also mapped in SandBase's Awesome Agent Runtime, alongside runtime, sandbox, and tool-protocol infrastructure.

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.

If this handbook saves you a debugging cycle, star the repository. That signal helps more Agent builders find source-backed DeepSeek Harness guidance.

Cite or link the handbook

If you publish a DeepSeek Harness tutorial, benchmark, plugin, or integration, link to the canonical handbook URL so readers can follow the source-backed runbooks and current release notes:

SandBase. DeepSeek Harness Handbook: source-backed Agent runtime guides.
https://github.com/sandbaseai/deepseek-harness-handbook

The handbook is community-maintained and independent of DeepSeek AI. Please link to the exact guide or release when you make a version-sensitive claim.

173 canonical guides · 202 localized documents · 79 curated Awesome resources · rc.2 + alpha.1 source-pinned analysis

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	Evaluate	Debug or build
Five-minute quickstart	Agent Harness Scorecard	Interactive Failure Router
CLI and headless map	Agent runtime map	Profile repair and reset
API cost boundary	Current field status	MCP guide

Explore the Agent ecosystem

The curated Awesome resource map now covers 79 source-linked starting points, including checkpoint/rewind, side Sessions, child-Agent visibility, browser and Office surfaces, plugin discovery and health checks, database analysis, adversarial workflow review, Agent evolution, mobile access, and provider fallback controls. Each entry is an Agent-oriented discovery lead, not a compatibility or security endorsement; inspect permissions, credentials, and rollback paths before installation.

For scale context, the pinned upstream catalog snapshot contains 271 hub repositories, 1,000 public dsh-plugin topic repositories, and 471 manual additions. This handbook deliberately curates a smaller, source-linked subset so every entry has an explicit Agent boundary to inspect.

For Chinese-language peer discussion, see the upstream community’s Feishu group discussion for the current invite and context. It is community-run and not official DeepSeek support; do not share credentials, private Session logs, or sensitive workspace data.

Newly source-verified

Problem	What the guide proves
Understand Harness versus framework	Separate model, provider, framework, and runtime responsibilities so tool, context, and long-running Agent claims are tested at the right boundary.
A continuable child exposes only `report`	Separate parent/child tool views, preset composition order, `toolFilter`, and cold-resume evidence before treating model prose as a tool result.
Read-only Windows PowerShell succeeds with noisy stderr	Separate command output from ConstrainedLanguage preamble diagnostics and preserve the ACL sandbox while validating a narrow fix.
Firefox shows a blank Web client while Chrome works	Separate browser bootstrap, cached assets, origin/WebSocket, and extension boundaries before touching provider credentials or durable Sessions.
An alpha.1 auth token cannot be obtained or entered	Keep acquisition, UI entry, credential storage, token scope, and outbound authorization as separate contracts with redacted evidence.
A settings section recurses on `removeChild`	Route `NotFoundError` through DOM ownership and render-generation evidence instead of misclassifying it as a proven MutationObserver CPU loop.
Long ChatView sessions grow WebContent memory	Separate renderer DOM retention from Host memory, preserve Sessions, and measure a virtualization boundary before using reload as containment.
Choose from the DSH ecosystem by capability	Use four bounded Agent starter paths and multilingual maps to choose skills, memory, routing, UI, file, research, and governance resources from the public Awesome catalog.
Custom providers can hide multi-protocol models	Separate live model discovery from provider-default filtering, then pin each model's protocol and verify the actual request endpoint.
Recover a client Cordis inspect query stuck Pending	Separate a page refusal from Host settlement, preserve first-valid-page routing, and make every inspect wait bounded.
Evaluate cross-Session memory without leaking scope or losing the store	A local JSON file is not a local-only data path once recall becomes a model-visible tool result; require scoped identity, atomic writes, corruption quarantine, retrieval budgets, and explicit privacy copy.
Edit model capabilities without mistaking declarations for proof	Image, reasoning, capacity, and gateway fields declare a route contract; verify the real endpoint and keep headers out of whole-namespace presets.
Diagnose a terminal command still shown after 40 minutes	Standard alpha.1 foreground Bash cannot explain that timer by default; route background jobs, persistent terminals, live processes, and stale presentation before retrying.
Repair count-balanced but ID-invalid tool history	Equal call/result counts do not prove valid pairing; use an ordered identity ledger and keep request stripping observable as containment.
Stop empty continuation chunks from erasing a valid tool ID and name	rc.2 and tagged alpha.1 both accept explicit empty identity updates; retain the first valid identity, reject never-identified calls before policy, and keep invalid records out of Session replay.
Recover when one corrupt Session prevents Web startup	A Windows `plugin tree failed to load` can wrap one bad Zstandard header; isolate the artifact before changing the launcher, profile, or every healthy Session.
Classify macOS `sandbox-exec ENOENT`	Host executable lookup can succeed while the Harness sandbox provider cannot start; preserve fail-closed behavior and prove the provider boundary before changing authority.
Keep a single `~` literal in Markdown	alpha.1 calls both GFM parsers without disabling single-tilde strikethrough; verify source and served bundle across streaming, finalized, and plain-text projections.
Evaluate a bounded Ralph failure successor	Discussion #109's recovery proposal can remain fail-closed: default off, fresh child only, shared budgets, observable failure state, no-change circuit breaking, and no retry for infrastructure failures.
Keep HTTP(S) URLs out of filesystem tools	Discussion #4862's Windows reproduction is a capability-boundary failure: reject URI-like input before local path resolution, preserve the original value, and route network retrieval to a web/fetch tool.
Fold compaction and retry usage without losing cost evidence	Discussion #1886 separates duplicate chunk/message observations from independent retry attempts and makes `compaction/summary.usage` visible in cumulative accounting.

Each entry above names its pinned official source revision—currently rc.2 b150a551… or alpha.1 cd5ef814…—records what is observed, source-verified, inferred, or proposed, and includes acceptance gates rather than a copy-paste-only happy path.

If the handbook resolves a real question, star it on GitHub. That signal helps the next Agent builder find a source-backed answer instead of another unverified command list. If a claim differs from the runtime you operate, open an evidence report with the exact DSH version and first failing boundary.

Browse the visual field guides · Explore the Awesome resource map · Download its JSON index · Read the Show & Tell · Help validate the index · 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.

This repository is documentation, not a DeepSeek Harness plugin. Do not run dsh plugin add github:sandbaseai/deepseek-harness-handbook; the handbook has no dsh.bundle activation contract. Read the guides from GitHub or the visual field site instead.

Start with your goal

Choose the smallest path that matches the job. The full task index remains available below without occupying the repository's first screen.

Goal	Fastest useful path
Install or run DeepSeek Harness for the first time	Five-minute quickstart
UI looks reset after changing launch commands	Install identity and `DSH_HOME` guide
`npx` installs but `dsh web` burns CPU without a port	Post-install Web startup boundary
ACP inline images fail in the Python SDK	ACP inline-image contract
Web renderer drops dollar signs from prose	Literal dollar rendering
Every request fails during plugin inventory preparation	Request extension boundary
A follow-up accepted during a running turn never starts	Queued follow-up wake-latch recovery
A renamed workspace breaks tools and sandbox roots	Recover a stale session cwd
Evaluate a Codex-style Web client without replacing the Host	Client extension boundary
OpenRouter rejects concurrent requests with an in-flight budget cap	Retry the provider-attested cooldown
A resumed Agent intermittently loses a registered tool	Resumed tool-view boundary
Evaluate nested follow-up Sessions safely	Nested follow-up evaluation
Sessions corrupt under concurrent writers or recovery	Session write-integrity invariants
Session cold-open is dominated by zstd frames	Session framing performance
Diagnose a failing install	Interactive Install Doctor
Route an Agent, model, tool, Session, or UI failure	Interactive Failure Router
Check what is shipped, inferred, or proposed	Current field status
Configure a model, gateway, image route, or reasoning level	Model provider guide
Build and package a plugin	First plugin lab
Connect MCP tools	MCP integration guide
Connect SandBase Harness as a real MCP runtime	SandBase Harness bridge guide
Understand Sessions, Skills, and long-term memory	Memory architecture
Audit permissions, credentials, or a community plugin	Security guides

Every current task route

I want to…	Start here
Explain why `ask_user_question` aborted before I answered	`ask_user_question` abort and deadline guide
Stop an Agent alternating between unknown `edit` and `str_replace_editor` calls	Unknown edit-tool assembly diagnosis
Reach Settings sections clipped below a long plugin navigation	Settings navigation overflow repair
Organize Sessions without turning a sidebar label into a filesystem root	Session Collections and no-Workspace design
Design two real Session panes without crossing data or interaction identity	Multi-Session presentation contract
Customize the Web UI without patching files inside an npx installation	Persistent Client plugin guide
Generate strict Typert artifacts for a plugin developed outside the monorepo	Out-of-tree Typert generation guide
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 or recover `messageTokens` underflow after compaction	Token accounting and projection recovery
Recover preset collisions in Host providers or scoped tools	Preset generation and registry-ownership 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
Fix spawn delegations that lose reasoning effort	Spawn subagent route-fidelity runbook
Configure Bailian Token Plan without losing reasoning or model metadata	Bailian catalog-route runbook
Fix a custom OpenAI-compatible provider that silently sends `/messages`	Custom provider catalog-collision 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
Fix or render an ACP permission request without hanging the turn	ACP permission client 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
Diagnose why AGENTS.md loaded but did not constrain an action	AGENTS.md scope, visibility, and enforcement map
Build, test, package, and install my first plugin	First DeepSeek Harness plugin lab
Let a third-party execution tool render the correct code language	Tool-owned code-card language design
Keep a plugin subprocess from freezing the Agent Host	Async subprocess tool guide
Archive or delete old Sessions without corrupting durable history	Session archive, trash, and delete guide
Fix native `read_image` failing with a missing `fs` injection	`read_image` service-scope guide
Fix valid WebP images rejected by a pi-ai backend	Image media-type compatibility guide
Let an SDK embedding answer Agent questions and approvals	SDK human-interaction wire 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 rc.7 baseline and alpha.1 migration context	DeepSeek Harness 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, a custom provider, or an image-capable model missing its UI modality control	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
`allowBuilds` blocks an rc.8 registry plugin install	Review pnpm's approval gate
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, unreadable Session, or false “no more history” state without destroying evidence	Route storage, sequence, identity, projection, and read-state failures
Stop repeated narration, tool calls, or Agent turns before they exhaust a budget	Event-shaped runaway Agent runbook
Stop a compacted long Session from exhausting or blocking the Web Host during cold restore	Session heap and restore operator guide
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 empty streamed tool identity before it causes `UNKNOWN_TOOL`, replay 400s, or a corrupt Session resume	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
Keep one incompatible custom-event Session from blocking global search	Custom Session event compatibility
Connect external MCP tools	MCP integration guide
Design multi-tenant MCP across ACP	Session-scoped MCP architecture
Add reusable Agent instructions	Skills guide
Evaluate an optional bounded recovery round in Ralph	Ralph failure-successor design guide
Delegate work to child Agents	Subagents guide
Inspect or cancel one stale pending continuable-subagent follow-up	Subagent inbox control map
Let a subagent request human clarification safely	Parent-owned question relay
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 and ACL boundary guide
Recover partial multi-agent work after `unknown job`	Subagent ID routing and recovery
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 remote Settings unavailable, `crypto.randomUUID`, or Host/Origin 403 safely	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	173 pages
简体中文	Draft refresh	Reviewed core guides plus a machine-assisted current navigation awaiting fluent review
日本語	Draft	Navigation plus ecosystem resource map
한국어	Draft	Navigation plus ecosystem resource map
Español	Draft	Navigation plus ecosystem resource map

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.

Contributing

Corrections, reproducible examples, diagrams, troubleshooting cases, upstream change notes, and fluent translation reviews are welcome. Read CONTRIBUTING.md, follow the Code of Conduct, and run npm run check before submitting a pull request.

New here? Choose a scoped task from the public roadmap, open a documentation request, or use the support router to find the correct project. Reproducible evidence is more valuable than a large patch.

Two current evidence units are intentionally small: review five Simplified Chinese navigation summaries, or validate one cold-restart Session recovery row. Both issues define the privacy boundary and observable acceptance evidence.

Primary sources

License

Apache-2.0. See LICENSE.