DeepSeek Harness: An Open‑Source Agent Runtime Built on a Full‑Plugin Architecture

Project Overview

DeepSeek Harness ( deepseek-harness, short name dsh) is an open‑source agent harness released by DeepSeek on 2026‑08‑13. It is built on the Cordis plugin system, whose design originates from the paper A Programming Paradigm for Spatiotemporal Composability . The framework treats every capability—model adapters, tool registries, session logs, and the agent loop—as a plugin that can be added, removed, or replaced without touching a privileged core.

Core Capabilities

All‑as‑Plugin : Model adapters ( ctx.llm), tool registries ( ctx.tools), and session logs ( ctx.sessions) are all plugins that are automatically rolled back when the plugin is unloaded.

No Privileged Core : The runtime has no hard‑coded core; extensions are applied via cordis.patch.yml which can replace any configuration line by ID.

Event‑Sourced Session Log : Every interaction with the model is recorded as an append‑only SessionEvent. The log is the single source of truth for model history, enabling replay, branching, usage statistics, and strict enforcement that nothing can be sent to the model without being logged.

Four Runtime Modes : Standard (full tool set), Code (TypeScript‑based orchestration), Minimal (bash + file editor for benchmarks), and Creator (runtime checks + plugin experiments).

Replaceable Capabilities : Filesystem, shell, sandbox, subprocess, sub‑agent, web, LSP, and skill services are defined via a Provider/Consumer model, allowing a whole capability to be swapped by changing the provider definition.

Cross‑Platform Sandbox : Implements sandboxing on Linux ( bwrap + Landlock), macOS ( Seatbelt), and Windows (restricted‑token ACL) behind a unified ctx.sandbox interface.

CLI Design

The dsh CLI parses only the profile to launch and forwards all other arguments to the underlying application. Key commands include: dsh web – start the Web UI (alias for --profile web). dsh --profile <name> – launch a specific profile, passing remaining arguments through. dsh --profile headless "<task>" – run a one‑off task and exit. dsh plugin --profile <name> add <pkg> – install a plugin (delegates to pnpm). dsh --dump-config – print the merged plugin tree (including user overrides).

Runtime Architecture

The runtime consists of five layers:

Access Layer (Web/CLI/Python SDK/ACP/JSON‑RPC)
  ↓
Composition Layer (Profile × Bundle stacking)
  ↓
Cordis Core (plugin loading, service registration, event dispatch)
  ↓
Core Services (session / agent‑loop / tools / system‑prompt / llm)
  ↓
Replaceable Capabilities (fs / shell / sandbox / sub‑agent / web / LSP / skill)
  ↓
External Back‑ends (LLM Provider / sandbox / persistence / credentials)

Session Log and Model Visibility

Each model interaction is logged as a distinct event (e.g., turn/*, step/*, user/message, assistant/*, tool/*). The log is append‑only and stored in memory with optional JSONL persistence. Because the log is the only data source, any UI can reconstruct the exact context by replaying events, eliminating mismatches between front‑end and back‑end state.

Turn/Step Lifecycle

A step equals one model request plus any tool calls; a turn consists of zero or more steps. The full turn flow (from turn/start to turn/end) includes claim, prompt assembly, pre‑step validation, model streaming, tool execution pipelines, and post‑step handling. Notable details:

If agent/pre-step rejects or claims nothing, the turn still closes but records zero steps.

The decision returned by agent/pre-step becomes the final result, and listeners can rewrite or reject the message.

Partial messages can wake the driver immediately, queuing injected context for the next turn.

Extension Mechanism – Writing a Tool Plugin

Creating a new tool requires three steps:

import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'greet-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'greet',
    description: 'Greet someone by name.',
    parameters: { name: { type: 'string', required: true, description: 'The name to greet' } },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }]
    },
    async execute(args) {
      return `Hello, ${args.name}!`
    }
  }))
}

Then the plugin is attached via a patch layer:

pnpm dsh web --patch ./scratch-plugin/cordis.yml

Finally, the model can invoke the tool in the Web UI with a prompt such as “Use the greet tool to greet Ada.” The response will be “Hello, Ada!”. This demonstrates how defineTool defines schema, validation, execution, and rendering, and how the plugin is automatically incorporated into the system prompt.

Quick‑Start Guide

Environment: Node.js ^22.19.0 || >=24.0.0, pnpm, and a DeepSeek (or compatible OpenAI) API key.

Run without installation: npx @deepseek-ai/dsh web (access at http://127.0.0.1:3080).

Build from source:

git clone https://github.com/deepseek-ai/deepseek-harness.git && cd deepseek-harness && pnpm install && pnpm run build && pnpm dsh web

.

Python SDK: pip install deepseek-harness-sdk and use DeepSeekHarness as shown in the documentation.

Inspect the merged plugin tree: dsh --profile web --dump-config.

Run a headless task:

dsh --profile headless "Inspect the repository and fix the failing tests."

.

Comparison with Similar Projects

Compared to other agent runtimes, DeepSeek Harness distinguishes itself by being fully open‑source (MIT), using the Cordis plugin system, offering three wire protocols plus a pi‑ai provider directory, and providing cross‑platform sandboxing and an event‑sourced session log. Other projects such as Claude Code (closed source) and Codex CLI (Apache‑2.0) lack the same level of composability and replayability.

Conclusion

DeepSeek Harness is currently the most advanced open‑source agent runtime, built on a truly modular plugin architecture that eliminates privileged cores, records every model interaction in an append‑only log, and makes all capabilities replaceable. It is ideal for developers who want to understand agent internals, teams that need to build custom agent services, or anyone looking for a fully replayable, extensible AI‑agent platform.