[Show & Tell] DeepSeek Harness Handbook — architecture maps, operator guides, and recipes

[denial123789]

I have been reading the DeepSeek Harness source and official docs from an Agent-builder perspective. The runtime becomes easier to reason about once the model, profile composition, Agent Loop, tool policy, and durable session events are treated as separate layers.

I turned those notes into an independent, open-source handbook:

https://github.com/sandbaseai/deepseek-harness-handbook

It is not an official DeepSeek AI project. The handbook complements the upstream reference with task-oriented explanations, diagrams, and failure checklists while linking version-sensitive claims to primary sources.

Live operator tools

• Field Status — current rc.6 boundaries, first evidence, and safer next actions.
• Interactive Failure Router — choose the first broken surface and collect the right evidence.
• Version Evidence — distinguish moving npm tags, the installed artifact, and the inspected source revision.
• Subagent Scale and OOM — separate concurrency from total-agent limits and batch large fan-out workloads.
• Plugin Recovery Runbook — preserve a known-good profile, inspect reconciliation, and route the first boot error.
• Session Log Durability — stop a live writer safely and separate crash tails from committed corruption.
• Non-FHS PTY Shell Paths — point persistent Bash at the executable available on NixOS and other non-FHS hosts.
• Visual site — quickstart, runtime map, incident notes, and downloadable field guide.

What is available now

• a five-minute Web UI quickstart with explicit success evidence;
• headless Agent, CI, and Python SDK guidance;
• model-provider and custom endpoint configuration;
• visual maps of the plugin-composed runtime, Agent lifecycle, and tool execution pipeline;
• guides for Skills, subagents, MCP, bounded subagent capacity, and plugin recovery;
• a reproducible repository-research Agent recipe;
• symptom-driven troubleshooting for provider, session, MCP, sandbox, permission, composition, and host compatibility failures;
• a compact operator cheat sheet and offline PDF.

The mental model used throughout

Profile
  → Bundles + patches
    → Cordis plugin graph
      → Agent Loop
        ↔ Model provider
        ↔ Tools + approval + sandbox
        ↔ Durable session events
          → Web, headless, SDK, and other clients

The practical distinction that saved me the most debugging time is this:

• a prompt describes intent;
• approval decides whether a requested effect may proceed;
• the sandbox limits what the process can actually reach;
• session events provide evidence of what happened.

Those are related, but they are not interchangeable security boundaries.

Example bounded first task

Inspect this repository without changing files.

Deliver:
1. its purpose;
2. its main packages and entry points;
3. the commands used to test it;
4. unresolved risks or unknowns.

Cite file paths for every conclusion. Stop before any write,
network request, credential use, or external publication.

Feedback wanted

The most useful contributions are source corrections, reproducible platform failures, real Agent recipes with explicit effect boundaries, and fluent reviews of the translated navigation pages.

The project is Apache-2.0 and technical pages record verification context. If a page becomes stale against upstream, please open an issue with the relevant source path, package version, or commit.

[denial123789]

The two source-backed review drafts are now published on main:

• Official examples map — choose between headless, Python/JSON-RPC, ACP, MCP memory, Cordis, and Schedule by interface and effect boundary.
• Windows compatibility guide — separates native CLI/Web support from PowerShell, partial ACL sandbox enforcement, language-mode, nested-process, and Python wheel limitations.
• Subagent route inheritance incident note — explains why a child can use a stale provider route and unexpected credential, with a two-provider regression checklist.

The handbook is now machine-detectable Apache-2.0 and its published guide map contains only shipped pages. Windows users: review of ACL, PowerShell, and large-workspace first-run behavior is especially useful. If a claim differs from the current runtime, please cite the upstream path or a minimal reproduction so the correction can be tracked precisely.

[denial123789]

New visual entry point: DeepSeek Harness Handbook.

It gives Agent builders a five-minute first run, a runtime composition map, task-oriented learning paths, and direct links into the source-backed handbook.

The v0.1.1 documentation release adds the published official-examples map, Windows compatibility guide, a cleaner shipped-guide index, machine-detectable Apache-2.0 metadata, and a live subagent route-inheritance incident note.

A downloadable companion remains available: DeepSeek Harness Field Guide v0.1.0 (PDF).

The source repository remains canonical: sandbaseai/deepseek-harness-handbook. Corrections with upstream paths or minimal reproductions are welcome.

[denial123789]

Project update: interactive Failure Router

The handbook now includes a free, no-login DeepSeek Harness Failure Router.

Instead of starting with reinstall advice, it asks for the first broken boundary and routes seven common symptom families:

1. the Host never prints a Web URL;
2. a remote Web UI loads empty;
3. a workspace or folder picker fails;
4. the model-provider turn fails;
5. a tool does not execute;
6. a shell operation is denied or isolation is unavailable;
7. session history, continuation, queueing, or child-agent routing is wrong.

Each route returns the first evidence to collect, a bounded command, a success signal, three next steps, and the relevant source-backed guide. It is static HTML/JS, works locally without transmitting diagnostic data, has no account requirement, and includes explicit credential/session-log redaction guidance.

Desktop and 390 px mobile layouts were checked for overflow; all seven state transitions and target links were exercised with no console errors. The page is indexed in sitemap.xml and llms.txt.

Feedback and reproducible missing routes are welcome in the handbook repository.

[denial123789]

Project update: the handbook now includes a source-linked DeepSeek Harness rc.6 Field Status.

It currently tracks six operator-facing boundaries—Linux CLI installation, tool-call/session continuity, privileged bwrap risk, remote Web secure contexts, Windows workspace paths, and MCP configuration. Each card separates observed evidence from inference, names the first signal to collect, and links to the primary discussion or incident note.

The page deliberately avoids calling an issue “fixed” until a published build and the original failure path have both been retested. Corrections and additional reproducible evidence are welcome in the handbook repository.