Home › Blog › DeepSeek Harness (dsh)
Harness Engineering · Product Case Study #3 · Snapshot: September 2026 🐋

DeepSeek Harness (dsh): an Open-Source, Plugin-Composed Agent Runtime

The first two product case studies were managed harnesses you rent. DeepSeek Harness is the opposite bet: an MIT-licensed harness you own, where the model adapter, tools, sessions, sandboxes, storage, the agent loop and even the UI are all swappable plugins on the Cordis framework, and every model-visible fact is written to an append-only session log. This visual deep dive takes it apart from its repository and documentation — with interactive diagrams and a runnable miniature of its two core ideas.

How to read this: the third product case study (after OpenAI Agents API and Claude Agent SDK & Managed Agents). Facts come from the deepseek-harness repository, its architecture document and launch coverage, checked in September 2026 (see References). dsh is a developer preview — its own README warns that there will be compatibility-breaking changes. Diagrams simplify; the Python miniature is a teaching model, not dsh's TypeScript code.

01 What Is DeepSeek Harness (dsh)?

DeepSeek Harness, dsh for short, is an open-source agent harness from DeepSeek AI: the software between a language model and the outside world that supplies tools, sessions, sandboxing and the loop that keeps a task moving. DeepSeek released v0.1 as a developer preview on 13 August 2026 under the MIT licence, built on Node.js/TypeScript. Its one core idea: everything is a plugin.

13 Aug 2026v0.1 developer preview
MITlicence; self-hosted, developer-owned
5shipped profiles: web, headless, sdk, sdk-minimal, acp
0MCP servers enabled by default
▶ The launch, in GitHub stars As reported in launch coverage (one tracker's counts).
Reported milestones: over 20,000 stars in about an hour, ~50,000 in 12 hours, over 92,000 in 28 hours and 141,532 stars (14,350 forks) on 17 August 2026 — widely described as the fastest-rising repository in GitHub history. Star counts measure attention, not adoption.
✓Modular, plugin-based architecture — no privileged core to patch; you extend dsh by mounting a plugin beside the others.
✓Event-sourced session log: "model-visible means logged".
✓MCP integration is optional — none enabled by default.
✓Multiple profile templates: web, headless, sdk, sdk-minimal, acp. Quick start: npx @deepseek-ai/dsh web.

02 The System Boundary: dsh vs External Systems

Unlike the managed harnesses, there is no vendor-operated side: you run dsh, and it talks to models and tools you choose.

Your application (developer-owned)
🌐 Web UI (dsh web)
⌨️ Headless / CLI (dsh headless)
🧩 SDK clients (TypeScript, Python, any JSON-RPC)
🏗️ Custom applications
DeepSeek Harness (self-hosted, open source)
Profiles / bundles
Cordis plugin runtime
Core agent loop
Session log (event-sourced)
Tool runtime
MCP client (optional)
Execution services
Plugins (models, storage, …)
External systems
🧠 Model providers (DeepSeek, OpenAI, Anthropic, …)
🔌 MCP servers (GitHub, databases, enterprise tools)
🧰 Other tools and APIs
🏢 Infrastructure (storage, credentials, network)

03 High-Level Architecture

Layers, top to bottom: user surfaces pick a profile; the profile composes bundles on the Cordis plugin runtime; core harness plugins (session log, system prompt, agent loop, tool registry) plus an LLM provider plugin form the harness; execution, MCP, storage and other plugins provide capabilities. Press play:

▶ Layers of dsh A request travels down the layers and back.

04 Profiles and Bundles

A running dsh instance is composed from a profile, which lists the bundles it stacks, any out-of-tree plugins it installs, and the user's own cordis.patch.yml. Most profiles stack an app bundle on dsh-base; sdk-minimal deliberately doesn't. Pick one:

▶ Shipped profiles Bundle stacks from the architecture document.

05 Cordis: "Everything Is a Plugin"

Cordis is the plugin framework beneath dsh: plugins contribute services, typed events and reversible effects to a shared context. It grew out of the Koishi chatbot framework, built by the developer known as Shigma (Yifan Shi), and describes itself as a "meta-framework of spatiotemporal composability" — formalized with DeepSeek and Peking University researchers in A Programming Paradigm for Spatiotemporal Composability (arXiv:2608.25512). Two properties make hot-swapping safe:

Temporal composability
Every effect a plugin registers — a service, a listener, a timer — comes with a disposer. Unloading a plugin runs its disposers in reverse order, fully reverting its effects.
Spatial composability
Plugins declare which services they depend on; when a dependency appears, disappears or is replaced, dependents are reactively reloaded.
▶ Load, unload and hot-swap plugins Click plugins to toggle them. Watch the context, and the dispose order.

A runnable miniature of both core ideas — reversible plugin effects and an event-sourced session:

"""A miniature of the two ideas at the heart of DeepSeek Harness (dsh), in plain Python.

1. Cordis-style plugins: every effect a plugin registers (a service, an event listener, a tool)
   comes with a disposer; unloading the plugin runs its disposers in reverse order, so the
   system returns exactly to its previous state. That is what makes hot-swapping safe.
2. An event-sourced session log: an append-only list of events is the source of truth; the
   messages sent to the model are *derived* from it, so a turn can be replayed or forked.
This is a teaching model, not dsh's TypeScript code. Standard library only.
"""
class Context:
    def __init__(self):
        self.services, self.listeners, self.tools = {}, {}, {}

    def load(self, plugin):
        disposers = []
        def effect(do, undo):                     # every change carries its inverse
            do(); disposers.append(undo)
        plugin(self, effect)
        return lambda: [undo() for undo in reversed(disposers)]   # unload = revert in reverse

    def state(self):
        return f"services={sorted(self.services)} tools={sorted(self.tools)} listeners={sorted(self.listeners)}"

def deepseek_adapter(ctx, effect):
    effect(lambda: ctx.services.__setitem__("llm", "deepseek-v4.1-flash"), lambda: ctx.services.pop("llm"))

def openai_adapter(ctx, effect):
    effect(lambda: ctx.services.__setitem__("llm", "gpt-6-astra"), lambda: ctx.services.pop("llm"))

def shell_tools(ctx, effect):
    effect(lambda: ctx.tools.__setitem__("shell", "run commands"), lambda: ctx.tools.pop("shell"))
    effect(lambda: ctx.listeners.__setitem__("tool/call", "audit"), lambda: ctx.listeners.pop("tool/call"))

ctx = Context()
print("start:            ", ctx.state())
unload_model = ctx.load(deepseek_adapter)
unload_shell = ctx.load(shell_tools)
print("after loading:    ", ctx.state(), "->", ctx.services["llm"])
unload_model(); ctx.load(openai_adapter)          # hot-swap the model adapter
print("model swapped:    ", ctx.state(), "->", ctx.services["llm"])
unload_shell()
print("shell unloaded:   ", ctx.state())

# ── event-sourced session ──
log = [
    {"type": "turn/start", "turn": 1},
    {"type": "user/message", "text": "Investigate the failing service"},
    {"type": "step/start", "step": 1},
    {"type": "assistant/message", "text": "Checking pods.", "tool_call": "shell: kubectl get pods"},
    {"type": "tool/result", "tool": "shell", "status": "ok", "output": "api-7f 0/1 CrashLoopBackOff"},
    {"type": "step/end", "step": 1},
    {"type": "assistant/message", "text": "The api pod is crash-looping; reading its logs next."},
    {"type": "turn/end", "turn": 1},
]

def project(events):
    """Derive the model-visible messages from the log (the log is the only source of truth)."""
    msgs = []
    for e in events:
        if e["type"] == "user/message": msgs.append(("user", e["text"]))
        elif e["type"] == "assistant/message": msgs.append(("assistant", e["text"] + (f" [{e['tool_call']}]" if "tool_call" in e else "")))
        elif e["type"] == "tool/result": msgs.append(("tool", e["output"]))
    return msgs

print(f"\nsession log: {len(log)} events -> {len(project(log))} model-visible messages")
for role, text in project(log): print(f"   {role:<10} {text}")
fork = log[:5] + [{"type": "user/message", "text": "Actually, check the database first"}]
print(f"\nfork at event 5: {len(fork)} events; last derived message -> {project(fork)[-1]}")
print("replaying the same log always yields the same messages:", project(log) == project(list(log)))

Output:

start:             services=[] tools=[] listeners=[]
after loading:     services=['llm'] tools=['shell'] listeners=['tool/call'] -> deepseek-v4.1-flash
model swapped:     services=['llm'] tools=['shell'] listeners=['tool/call'] -> gpt-6-astra
shell unloaded:    services=['llm'] tools=[] listeners=[]

session log: 8 events -> 4 model-visible messages
   user       Investigate the failing service
   assistant  Checking pods. [shell: kubectl get pods]
   tool       api-7f 0/1 CrashLoopBackOff
   assistant  The api pod is crash-looping; reading its logs next.

fork at event 5: 6 events; last derived message -> ('user', 'Actually, check the database first')
replaying the same log always yields the same messages: True

Swapping the model adapter leaves every other plugin untouched, and unloading the shell plugin removes both its tool and its audit listener — nothing leaks. The session half shows why dsh can resume, fork and replay: the model's messages are a pure function of the log.

06 Turns, Steps and Events: the Agent Loop

In dsh a step is one model request plus the tools it calls; a turn is zero or more steps — it opens before its first input is claimed and closes once nothing is owed. The default driver is the core/agent-loop plugin. Watch a turn emit its events:

▶ One turn, two steps Event names from the architecture document; payloads illustrative.
Durable session events (turn/*, step/*, system/message, user/message, assistant/message, tool/*) are written to the log; live events such as agent/pre-step, agent/request and agent/assistant-stream are extension points plugins can hook.

07 Durable, Event-Sourced Sessions

The session log is append-only and is the source of truth for all agent state; session history — including the messages sent to the model — is derived from it, not stored separately. Its guiding invariant is "model-visible means logged": a runtime check verifies that every model request can be reconstructed from the log. Failed, retried and cancelled attempts are kept too (assistant/attempt). Logs are JSONL files (session.vN.jsonl, optionally zstd-compressed) behind a pluggable SessionPersistence interface.

▶ Log → projection, replay and fork Click an event to fork there.

08 Capability Seams

Each swappable capability is a seam with three roles: a service definition (the interface), one or more service providers (implementations) and consumers. Pick a seam and swap its provider — the consumers never change:

▶ Swap a provider behind a seam Provider names are illustrative of the kinds dsh supports.
Core servicePackageContext key
Session logcore/sessionctx.sessions
Prompt assemblycore/system-promptctx.systemPrompt
Tool registrycore/toolsctx.tools
Agent registrycore/agentctx.agents
LLM adapterllm/llmctx.llm
Webhookswebhook/webhookctx.webhookRuntime

09 The Tool Runtime

Tools are plugins that register typed definitions with ctx.tools. Each call passes through validation, permission and policy checks, runs under an execution mode with timeouts, and returns a result that the loop can use — failures included. Pick a call:

▶ Through the tool runtime Simplified pipeline; policies are configurable per tool and agent.
📐 Typed definitions & validationSchema-based tool definitions; calls validated before execution.
🔐 Permissions & policyAllow / deny / ask per tool and agent; sandbox and approval policy ship in dsh-base.
⚡ Execution & parallel safetyCalls run through execution-service plugins (shell, filesystem, subprocess); independent, safe calls can run in parallel.
⏱️ Cooperative timeoutsPrevent hanging tools; failures return as results so the loop continues.

10 MCP Architecture (Optional)

dsh can connect to external MCP servers, whose tools are registered in the same tool runtime under server-qualified names such as mcp__github__create_issue. But no MCP server is enabled by default: the MCP client ships as a dependency, and you enable servers deliberately — because each server command is trusted executable code that runs outside the agent sandbox.

▶ Enable a server Toggle servers; watch tools appear in the registry.

11 SDK and Automation Entrypoints

The sdk profile serves SDK clients over newline-delimited JSON-RPC on stdio until shutdown or disconnect; clients exist for TypeScript and Python (deepseek-harness-sdk on PyPI) and any language that speaks JSON-RPC. The acp profile runs an automation-only Agent Client Protocol server that reserves stdout for ACP frames.

▶ JSON-RPC frames over stdio Illustrative method names; press play.
Developer-preview caveat: a public repository discussion (#1238) notes that there is not yet a session/cancel request on the SDK wire — killing the runtime process is currently the way to abandon a turn.

12 dsh vs the Managed Harnesses

AspectDeepSeek Harness (dsh)Claude Agent SDK / Managed AgentsOpenAI Agents API
Who runs itYou (self-hosted)You (SDK) or Anthropic (Managed)OpenAI (managed)
LicenceMIT, full sourceSDK distributed as a library; Managed Agents is a proprietary serviceProprietary service
ModelsAny, via model-adapter pluginsClaudeOpenAI models
ExtensibilityEvery capability is a swappable pluginTools, MCP, hooks, subagents, skillsTools, MCP, environments
Session modelAppend-only JSONL log; messages derivedAppend-only session log (Managed)Durable sessions, events/items
MaturityDeveloper preview (breaking changes)SDK GA; Managed Agents public betaPublic beta
You operateEverything: hosting, security, upgradesSDK: runtime; Managed: app onlyApp, tools, optional environment

13 End-to-End Example: Investigate a Failing Service and Prepare a Fix

▶ Eleven steps Press play. Illustrative.
Key takeaway: dsh is an open, self-hosted, plugin-composed agent runtime. Its differentiator is the replaceable plugin seams — model, tools, session, storage, loop and more — around an explicit event-sourced session spine. That buys maximum flexibility and composability, at the cost of higher engineering and operational ownership, in a developer preview whose APIs will change.
The product in one paragraph
Where OpenAI and Anthropic sell the harness as a service, DeepSeek open-sourced one and made it maximally decomposable. On the Cordis framework, every capability — model adapter, tool, session store, sandbox, loop, UI — is a plugin with reversible effects, composed into profiles (web, headless, sdk, sdk-minimal, acp) from bundles over a shared dsh-base. An append-only JSONL session log is the single source of truth, from which everything the model sees is derived and checked. Security defaults are conservative — no MCP servers until you enable them, sandbox and approval policy in the base bundle — but the operational burden is yours. It is the clearest reference implementation of the harness ideas in this series, and, as a developer preview, not yet a stable platform.

Next: Product case studies #4–#11 — Foundry, ADK, LangChain, CrewAI, Temporal, E2B, Browserbase and AgentCore compared.

⚠️ Notes

The source infographic matches the repository well; corrections and refinements: (1) its example session log uses dotted event names (session.start, model.response.delta, tool.result); dsh's documented durable events use slash names — turn/start, step/start, user/message, assistant/message, tool/call, turn/end — and files are named session.vN.jsonl (optionally zstd); (2) profiles — it treats sdk-minimal like the others, but it is the one profile that does not stack dsh-base; (3) MCP — "no MCP server enabled by default" is correct, and the reason matters: server commands are trusted code running outside the agent sandbox; (4) the package families panel is a reasonable summary of the repository's layout, but individual package names change quickly in the preview — rely on the repository. Launch-star figures are one tracker's reported counts; interactive diagrams are simplified and the Python miniature is a teaching model.

🔗 References