The mission

DeepSeek Harness (dsh) is, in the repo's own words:

an open-source agent harness developed by DeepSeek AI.

An agent harness is the runtime shell around an LLM agent: it manages sessions, feeds context and tool schemas to the model, executes the tools the model calls, enforces sandbox and approval policy, and persists the transcript. dsh is DeepSeek AI's take on that shell, and it is structured so that everything inside the shell is a replaceable plugin — there is no privileged core.

That one-liner comes directly from the root README.md:

It uses an architecture where everything is a plugin, and is powered by Cordis, whose design is described in A Programming Paradigm for Spatiotemporal Composability.

Two ideas in that sentence carry the whole design. First, the substrate is a plugin framework: the harness is built on Cordis, a vendored framework where plugins register services, typed events, and reversible effects on a shared context. Second, everything is a plugin: the model adapter, the tool registry, the session log, and even the agent loop are all plugins mounted on that context. The philosophy chapter unpacks what this buys you.

Running it: the Web UI

The primary interface is a browser application. From npm:

npx @deepseek-ai/dsh web

--profile web, which boots the web profile — one of the named, user-editable plugin compositions the launcher knows how to stack (see Boot & CLI). The profile is the @deepseek-ai/dsh-web-app bundle riding on top of the shared @deepseek-ai/dsh-base bundle, so the browser surface is itself just another set of plugin rows.

Inside the Web UI you pick a workspace, configure a model in Settings → Models, and run tasks. The agent can read/edit workspace files, run commands, delegate work, and maintain a plan, asking for approval before operations the permission policy requires (see the [user guidedocs/user/guide/index.md).

Headless mode

Alongside the Web UI, dsh ships a headless one-shot mode — a runner with no server, no Host, and no browser:

dsh --profile headless "summarize this workspace"

The @deepseek-ai/dsh-headless bundle supplies the coding persona and tool mode, and its headless-runner plugin reads the task from the injected headlessStartup provider, creates one fresh persisted session through ctx.agents, submits the task as an ordinary user message, waits for quiescence, prints the last non-empty assistant text, and exits (0 on a settled turn/end, 1 otherwise). It opens no listening port. In the Web profile the same base stack is used but overlaid with the browser rows; headless is a genuinely different surface over the same dsh-base — see packages/bundle/headless/README.md.

SDK & JSON-RPC

For programmatic use there is a real client/server story, not just a CLI:

• @deepseek-ai/dsh-sdk-client, @deepseek-ai/dsh-sdk-jsonrpc-server, @deepseek-ai/dsh-sdk-protocol under packages/sdk/ define an SDK built on a JSON-RPC protocol, so an external process can drive a harness.
• The repo ships a Python SDK (deepseek-harness-sdk) whose tutorial lives at docs/user/guide/python-sdk.md; it drives a remote harness over the JSON-RPC surface.
• A ready-made example is [jsonrpc-agentexamples/jsonrpc-agent/README.md, an unattended coding agent driven through the Python SDK and JSON-RPC.

So beyond the interactive GUI, dsh exposes its agent capabilities as a wire protocol for automation.

What ships in the box

The three published launcher packages make the surfaces concrete:

Package	Surface	Role
@deepseek-ai/dsh-base	shared core	first bundle layer of every profile: adapters, tools, persistence, policy, settings, credentials, telemetry
@deepseek-ai/dsh-web-app	browser	adds webserver, API gateway, browser plugin roster, client-HMR reload chain
@deepseek-ai/dsh-headless	one-shot	adds a headless runner; no Host, HTTP server, or browser
@deepseek-ai/dsh (CLI)	launcher	the dsh bin; boots a profile by stacking these bundle layers

Together these packages are how npx @deepseek-ai/dsh web and --profile headless both work: the launcher composes the same shared core with a surface-specific bundle.

Examples & community

The repository keeps a runnable examples/ directory: headless-agent, jsonrpc-agent, mcp-memory, web-cordis (a self-referential agent that inspects and edits its own live plugin tree), web-schedule, and acp-agent (an Agent Client Protocol automation server). Each owns its config and prerequisites; see Examples & Demos.

The community surface is documented in README.md:

• Feedback and bug reports via GitHub Discussions.
• Publishing a plugin under the dsh-plugin GitHub topic for discoverability.
• A DeepSeek Harness Discord server (https://discord.gg/Ycq5dCaS4). The Chinese README.zh.md additionally advertises a WeCom (企微) group and a WeChat official account.

License & relation to Cordis

dsh is MIT-licensed (LICENSE); third-party licenses are disclosed in THIRD_PARTY_NOTICES.md. Despite the "AI" in the name, the harness is not model-specific at the core: it registers model adapters as plugins (ctx.llm), and the DeepSeek adapter is one of several. Its dependency on Cordis is notable: rather than pulling Cordis from npm like a normal dependency, the harness vendors the framework into the monorepo under vendor/ (renamed into the @deepseek-ai scope, e.g. @deepseek-ai/cordis), so it fully owns and can patch its framework layer. See Vendored Libraries.

Further reading

• “Everything Is a Plugin” Philosophy — the architectural core idea.
• Getting Started — install and run dsh today.
• Anatomy of the Monorepo — the 49 group, ~219-package layout behind one dsh command.
• README.md — the upstream one-liner and run instructions.
• docs/architecture.md — the upstream architecture deep-dive.
• packages/bundle/web-app/README.md — the web bundle's role and limitations.