DeepSeek Harness Handbook

The agent-first, multilingual field guide to understanding, running, debugging, and extending DeepSeek Harness.

If this handbook saves you time, star the repository and watch releases. That signal helps more Agent builders find source-backed DeepSeek Harness guidance.

Open the cheat sheet · Get started in five minutes · Build a repository research Agent · Contribute

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
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
Run the Web UI safely	Five-minute quickstart
Use it from Python	Python SDK quickstart
Run one task in automation or CI	Headless Agent guide
Configure DeepSeek or another provider	Model provider guide
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
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
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: translations declare their canonical source revision and review status.

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

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

Connect MCP servers

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 and run npm run check before submitting a pull request.

New here? Choose a scoped task from the public roadmap, or open a documentation request. Reproducible evidence is more valuable than a large patch.

Primary sources

License

Apache-2.0. See LICENSE.

deepseek-harness-handbook