deepseek-harness

DeepSeek Harness (dsh) is DeepSeek AI’s open-source agent harness, built on the Cordis plugin framework under an “everything is a plugin” philosophy: the model adapter, tool registry, session log, and even the agent loop itself are all replaceable plugins mounted into a shared context rather than privileged core code.

A running dsh instance is composed at boot from named profiles (web, headless, sdk, sdk-minimal, acp) that stack ordered bundles of Cordis config and code, patchable at every layer down to a user’s own local overrides. This lets the same underlying agent loop power a full browser-based web app, a one-shot headless CLI runner, a JSON-RPC SDK server for TypeScript and Python clients, or an automation-only ACP server, without forking the core.

The project ships a signed Electron desktop application, a web frontend, native system-integration packages, and TypeScript/Python SDKs, all built from one large pnpm/TypeScript monorepo. Its durable, append-only session log is the single source of truth for everything a model sees, with typed events (turn/*, step/*, tool/*) driving an explicit turn-and-step execution model that supports cancellation, streaming, forking, and session migration.

It is explicitly labeled experimental developer-preview software with breaking changes expected, and its own safety notice warns that it can execute model-generated code and commands and should be run with least privilege in a disposable environment.

What You Get

• A CLI, web app, signed Electron desktop app, and TypeScript/Python SDKs all driven by the same dsh core through named profiles
• An “everything is a plugin” architecture (Cordis) where model providers, tools, storage, sandboxing, and the agent loop itself are replaceable at config time
• A durable, append-only session log with typed turn/step/tool events that supports cancellation, streaming, session forking, and versioned migration
• A scoped tool registry (ctx.tools) with allow/deny/ask policy, parallel-safe execution, and both native function-calling and PTC presentation modes
• Capability seams for filesystem, subprocess, sandbox, and subagent providers, so swapping one provider (e.g. a remote sandbox) moves the whole execution surface with it
• An extension cookbook and generated config catalog documenting how to add packages, tools, LLM adapters, and settings cards

Common Use Cases

• Running an autonomous coding/automation agent locally via the web or headless profile without depending on a closed SaaS agent product
• Embedding a DeepSeek-model-driven agent into another application through the TypeScript or Python SDK’s JSON-RPC server
• Building custom agent tooling or model adapters as Cordis plugins without forking or patching the core agent loop
• Running fully automated, human-free agent workflows through the ACP profile for CI or scheduled automation
• Self-hosting an agent harness in a disposable VM/container for experimentation while retaining full control over data and execution

Under The Hood

Architecture DeepSeek Harness has no privileged core: it is a plugin tree assembled at boot from named profiles (web, headless, sdk, sdk-minimal, acp) that stack ordered bundles of Cordis configuration, each layer patchable by the ones above it. The default agent driver (dsh-agent-loop) implements an explicit turn/step lifecycle over a durable, append-only session log (core/session), reconstructing model-visible history purely from typed session events (turn/*, step/*, tool/*) rather than in-memory state, which is what makes cancellation, streaming, forking, and versioned session-format migration possible without ad hoc bookkeeping. Capability “seams” (service definition, provider, consumer) formalize how a subsystem like filesystem access, subprocess execution, or sandboxing gets swapped as a unit, so pointing the filesystem and subprocess providers at a remote sandbox moves tool execution, PTY, and LSP together with no per-tool forking.

Tech Stack The project is a large TypeScript-first pnpm workspace (over 96% TypeScript, with smaller Python, C++, and native-addon components), built with tsdown and TypeScript project references (tsc -b) across host and client compilation targets, linted with oxlint, and orchestrated through custom build/clean/release scripts (scripts/build.ts, scripts/verify-application-entrypoints.ts). It ships a signed Electron desktop app that runs the real production dsh runtime in an isolated Desktop Host process, a browser-based web frontend, native system-integration packages, and separate TypeScript and Python SDK distributions — the Python SDK’s runtime is packaged as a wheel wrapping the same Node-based dsh CLI.

Code Quality The repository contains well over a thousand .spec.ts test files run under Vitest, alongside an extensive GitHub Actions setup covering unit CI, a master CI gate, end-to-end tests, sandbox tests, weighted-approval review workflows, and dedicated release pipelines for the CLI, native system addon, and both SDKs. Git hooks are managed through lefthook, and a dedicated entrypoint-verification script enforces that every executable path in the monorepo is classified and launches through the sanctioned dsh profile mechanism rather than an ad hoc bypass. Architectural decisions are recorded as dated design notes under .agents/notes/implemented/architecture/, giving the codebase an unusually explicit paper trail for why specific invariants exist.

What Makes It Unique Rather than hard-coding an agent loop and bolting on extension points, DeepSeek Harness inverts the relationship: the agent loop, tool registry, and even the system prompt assembler are themselves ordinary plugins on the same Cordis context that any other plugin can observe or replace, with the composition described as reversible effects that unwind cleanly when a plugin unloads. The profile/bundle/patch layering lets four very different applications (web app, headless runner, JSON-RPC SDK server, automation-only ACP server) share one core without diverging forks, and the “capability seam” concept generalizes provider-swapping (sandboxes, subagents) into a documented, first-class extension pattern rather than a series of one-off abstractions.

Self-Hosting

Licensing Model MIT licensed — all features available in self-hosted deployments with no restrictions or license keys required.

Note DeepSeek Harness is explicitly labeled experimental developer-preview software with breaking changes expected, and its own safety documentation warns it has not undergone a security audit; it can execute model-generated code and commands, so the project recommends running it with least privilege in a disposable VM or container.