This site does not allow itself to be embedded. You can still read it on the original site — the toolbar below keeps your place in the directory.
DeepSeek open-sourced its agent harness today. We cloned it and read the code: a 453K-line plugin runtime on a vendored Cordis fork, three patterns worth stealing, V4 line signals hiding in the model adapter, and a 3-line BENCHMARK.md from a lab that published zero eval claims.
Two weeks ago, the DeepSeek Harness was a footnote in the V4-Flash benchmark config: "to be released soon." As of 2026-08-13 it is public. [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) landed on GitHub under MIT, and [`@deepseek-ai/dsh`](https://www.npmjs.com/package/@deepseek-ai/dsh) is live on npm at `0.1.0-rc.6` - one `npx @deepseek-ai/dsh web` gets you a local web UI on port 3080.
Launch posts will tell you what DeepSeek says it is. We cloned the repo and read the code. This is what it actually is, the three patterns worth stealing for your own agent stack, and the gaps the announcement will not mention.
## What dsh actually is
`dsh` is not a CLI wrapper around a chat API. It is a full agent runtime - session log, agent loop, tool scheduler, sandbox, web UI, SDK - built as roughly 453,000 lines of TypeScript across about 219 workspace packages (measured on our clone, as of 2026-08-13). The architectural bet, stated in the README, is that **everything is a plugin**: the model adapter, the tools, the persistence layer, the agent loop itself, and even the web UI are all mountable plugins on [Cordis](https://github.com/cordiverse/cordis), a plugin/event-bus framework whose design paper the README cites.
DeepSeek did not just depend on Cordis - they source-vendored a fork of it. The `vendor/` directory pins `cordis 4.0.0-rc.7` (a pre-release upstream version) with 18 logged local patches, renamed into the `@deepseek-ai` scope so the harness "fully owns its framework layer," in the words of `vendor/README.md`. That makes DeepSeek the flagship production consumer of the Cordis paradigm, and it also means every future upstream release is a merge exercise against a patched fork.
Composition works in layers, per [docs/architecture.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/architecture.md): a profile lists bundles, each bundle is an npm package carrying a config patch, and layers apply in order to an empty root - bundle patches, then the profile's patch, then the home-level patch, then `--patch` overlays. There is no privileged core to configure around; you replace any row the boot prints with a patch of your own.
## Three patterns worth stealing
### 1. "Model-visible equals logged" as a runtime invariant
Most agent frameworks treat their session log as a best-effort record. dsh makes it load-bearing. Every message the model can see must be reconstructable from the append-only session log, and this is enforced at runtime, not by convention: at every LLM dispatch, an invariant in `packages/core/agent-loop/src/invariant.ts` asserts that the outgoing request's messages byte-match `session.deriveMessages()`, the projection derived from the log. One layer down, `packages/core/session/src/surface.ts` throws at append time if a message-producing event arrives without a surface marker saying how it projects into model history.
The payoff is that replay, forking, resume, debugging, and the UI all derive from one artifact, and "what did the model actually see" is never a reconstruction exercise. The cost is real too: the check serializes the full message history twice on every production dispatch. DeepSeek decided auditability was worth that hot-loop tax, and we think they are right.
### 2. Keyless transcript replay, where the fixture is input and expected output
The testing story is the part we would port tomorrow. dsh commits real recorded session logs as fixtures, then derives a deterministic mock model from them: the replay harness in `packages/test-support/llm-replay` splits recorded assistant chunks into per-stream scripts and fails the test if a fixture is underrun. The clever half is in `examples/headless-agent/tests/headless.snapshot.ts`: the same committed `.jsonl` log is both the replay input and the expected output. The test boots the real agent subprocess against the mock, lets the full loop-tools-persistence chain run, then diffs the freshly persisted log against the fixture after normalization.
One artifact, two roles - no API keys in CI, no flaky LLM-as-judge for regression coverage, and any drift in the loop's behavior shows up as a log diff. Three modes (`replay`, `record`, `refresh`) make re-baselining a one-flag operation. This composes naturally with pattern 1: the replay trick only works because the log provably contains everything the model saw.
### 3. A fail-closed sandbox ladder
Tool execution resolves a sandbox policy per call (`read-only`, `workspace-write`, `danger-full-access`) and confines commands by argv wrapping: Linux probes [bubblewrap](https://github.com/containers/bubblewrap) then falls back to a native [Landlock](https://docs.kernel.org/userspace-api/landlock.html) launcher, macOS uses seatbelt, Windows uses a write-restricted token. The detail that matters is the failure mode: if a confined mode is requested and no backend is usable, `packages/sandbox/sandbox/src/index.ts` throws `SANDBOX_UNAVAILABLE` and refuses to run the command unconfined. A missing approval service likewise means denial, never a hang.
Escalation is designed as model UX, not just enforcement: the bash tool's description teaches the model that a denial is a policy outcome, and that the sanctioned response is one same-turn retry with a wider `sandbox_permissions` plus a one-sentence `justification`, which raises the approval prompt that is the user's actual consent. The code is also honest where the sandbox is weak: the Windows backend documents that reads, network, and process visibility stay unrestricted. Confinement there is "token-limited," not sandboxed, and the source says so.
## What it signals about the V4 line
The harness is the first-party consumer of DeepSeek's models, so its DeepSeek adapter is worth reading as a statement of intent. The default catalog in `packages/llm/llm-deepseek/src/index.ts` ships exactly two models, `deepseek-v4-flash` and `deepseek-v4-pro`, and the defaults in `packages/llm/llm-deepseek/src/adapter.ts` set `DEFAULT_CONTEXT_WINDOW = 1_000_000` and `DEFAULT_MAX_TOKENS = 256_000` - a 1M-token context window with a 256K output cap, with reasoning effort levels `off`, `high`, and `max`. Those numbers are what DeepSeek's own tooling assumes about V4, as of 2026-08-13.
The interoperability posture is also legible from the package tree: hook bridges for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [Codex](https://developers.openai.com/codex) ship in `packages/hooks/`, and [MCP](https://modelcontextprotocol.io) support is client-only - dsh consumes MCP servers, it does not present itself as one.
## The honest gaps
**BENCHMARK.md is a 3-line stub.** A heading, and a pointer to the Python SDK guide for running your own tasks. No methodology, no scores, no SWE-bench, no eval harness anywhere in the tree. An AI lab shipped an agent runtime with zero evaluation claims - read that as restraint or as a gap, but either way you are benchmarking this yourself. Given that V4-Flash's launch numbers were produced with this harness's minimal mode, we expected the eval tooling to be the headline. It is absent.
**The history is one commit.** `git rev-list --count HEAD` returns 1: the entire estimated two months of internal development arrived as one squashed merge of PR #2519, "feat/npm-public," opened and landed on release day. No review trail, no blame, no archaeology for contributors. The 1,372 bilingual decision records in `.agents/notes/` - an RFC corpus written by and for the agents that built this - partially compensate, but a squash this size is a contributor-hostile way to open a project.
**It is a preview, and it behaves like one.** The README warns in bold that there will be compatibility-breaking changes. The repo sits at `0.1.0-rc.5` while npm serves `rc.6`, the license flipped from BSD-3-Clause to MIT mid-release-candidate, and the Python SDK on PyPI is versioned `0.0.0.dev0` - a stdio driver around a bundled Node executable, not a runtime port. Nothing here is stable enough to build a product on this quarter.
## The takeaway
The harness core - the logging doctrine, the replay-driven testing, the fail-closed sandbox - is some of the most disciplined agent-runtime engineering we have read, and all three patterns port to any stack without adopting dsh itself. What DeepSeek did not ship is everything above the loop: no eval tooling, no artifacts surface, no session sharing, no metering. The runtime layer is now open-source table stakes. The competition moved up a floor.
## Continue Reading
- [DeepSeek V4 Flash 0731: The Budget Tier Just Overtook Pro Preview on Agent Benchmarks](/blog/deepseek-v4-flash-0731-agent-update) - the release where this harness was still "to be released soon," and the benchmark config it ran
- [Agent Sandbox Architecture: How to Choose the Right Runtime Boundary](/blog/agent-sandbox-architecture-guide) - how other runtimes draw the same confinement ladder dsh implements
- [Agent Replays with TraceTrail: Loom for Agent Runs](/blog/agent-replays-with-tracetrail) - the replay-and-observability problem dsh solves with its session log
- [DeepSeek V4: The Developer's Guide to Flash and Pro](/blog/deepseek-v4-developer-guide) - the models this harness is built to drive
- [Loop Engineering: How to Design Agent Loops That Actually Converge](/blog/loop-engineering-designing-agent-loops) - the turn/step loop design space dsh's agent-loop package sits in
## Sources
- [deepseek-ai/deepseek-harness - GitHub](https://github.com/deepseek-ai/deepseek-harness) (cloned and read 2026-08-13, HEAD `47f9438`)
- [docs/architecture.md - profile/bundle/patch composition](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/architecture.md)
- [BENCHMARK.md - the 3-line stub](https://github.com/deepseek-ai/deepseek-harness/blob/main/BENCHMARK.md)
- [@deepseek-ai/dsh - npm](https://www.npmjs.com/package/@deepseek-ai/dsh) (version `0.1.0-rc.6` as of 2026-08-13)
- [Cordis - cordiverse](https://github.com/cordiverse/cordis) (the vendored framework, pinned at `4.0.0-rc.7`)Read on developersdigest.tech ↗
Comments
Nothing yet. Say the first thing.
Sign in to join the conversation.