DeepSeek released DeepSeek Harness on 13 August 2026, at the same time as the DeepSeek-V4-Pro model. The harness, invoked as dsh, is a TypeScript agent runtime published under the MIT license and described by its authors as a developer preview. Its organising idea is that every part of the runtime is a plugin, composed through a system called Cordis: the model adapter, the shell executor, the filesystem provider, session persistence, compaction, subagents, and the transport layer are all entries in a composition file rather than fixed internals. Releasing a coding harness beside a model line is a deliberate pairing. The model is tuned for agentic work, and the harness is the loop that work runs in.
SuperQode 0.2.94 adds DeepSeek Harness as an optional harness backend. DeepSeek keeps ownership of its agent loop, tools, system prompts, compaction, and sandbox. SuperQode launches the runtime, hosts its stream, and translates progress into harness events so a DeepSeek run appears in the same terminal, session store, and evidence trail as every other harness.
Choosing a route into a TypeScript runtime
SuperQode is a Python application, so a TypeScript harness raises an obvious question about the seam. Three routes existed on release day, and they are not equivalent. The first is the published dsh command from npm, driven in headless mode. It works, and it returns a final answer, but a single answer per invocation discards the tool calls, reasoning, and usage that a terminal wants to display.
The second is Agent Client Protocol. SuperQode already speaks ACP and connects to Codex, Claude Agent, OpenCode, Grok Build, and Prime Agent through it, and the DeepSeek repository contains an ACP server. That route looked most attractive, because ACP carries session/request_permission, which would let SuperQode's own permission screen take part in approvals. We tested it and it does not install:
npm error Could not resolve dependency:
npm error peer @deepseek-ai/dsh-bash-env@"^0.0.1-rc.1"
npm error from @deepseek-ai/dsh-tool-bash@0.0.1-rc.1The published @deepseek-ai/dsh-acp-demo package declares a peer dependency on @deepseek-ai/dsh-bash-env, which is absent from the npm registry at the current release candidate, so the plugin graph cannot resolve outside DeepSeek's own workspace. This is an incomplete publish rather than a design decision, and the route is worth revisiting when it resolves cleanly.
The third route is the one we shipped. DeepSeek publishes deepseek-harness-sdk on PyPI, and installing it pulls a matching platform wheel that carries their compiled TypeScript runtime as a single-file executable. No Node.js, no npm, no pnpm workspace. The SDK drives that executable over newline-delimited JSON-RPC on stdio, which is the same shape as the RPC host we built for Prime Agent Python Client. DeepSeek solved the language boundary themselves, and the SuperQode side became a translation layer rather than a reimplementation. That distinction is worth stating plainly. We did not rebuild DeepSeek Harness in Python. Rebuilding it would have meant reproducing fifty-three packages and a plugin system, and drifting from upstream on the day it was finished.
What the backend does
The backend resolves settings from the HarnessSpec, starts the runtime subprocess, subscribes to its session notifications, and sends the prompt. The SDK is synchronous, built on reader threads feeding queues, so every blocking call is dispatched to a worker thread and awaited, and a deadline turns an unresponsive runtime into a reported error instead of a stalled terminal. Translation is the substance of the work. DeepSeek emits a rich stream, and each of its event shapes maps onto the SuperQode vocabulary:
assistant/chunk text delta -> model_delta
assistant/chunk reasoning delta -> thinking_delta
assistant/chunk usage -> usage
assistant/message -> message
tool/call -> tool_call
tool/result -> tool_result
turn/start -> turn_start
turn/end -> turn_complete
subagent.started, subagent.finished-> subagent
any other notification -> dsh_eventEvery translated event retains the complete original payload, so a future DeepSeek release stays readable before the mapping is extended. Two behaviours needed care and were only visible against the real runtime. A failed turn reports its cause on turn/end rather than as a separate error notification, so a run that ends without a credential, or without a reachable endpoint, would otherwise surface as a failure with no explanation. And DeepSeek treats a session identifier as owning its persisted log: a second prompt sent from a fresh process under an existing identifier is rejected as a collision. SuperQode therefore keeps one runtime alive per session and scopes the wire identifier to the process, so both a second message and a restarted terminal continue to work.
Model routes, local models, and BYOK
DeepSeek resolves provider route names from its own Cordis composition rather than from SuperQode's model catalogue. The bundled composition registers exactly one name, so forwarding a route called ollama fails the handshake. The endpoint behind that route, however, is configurable. SuperQode uses that seam. When you connect to a local or OpenAI-compatible provider and select this harness, the route is bridged automatically: the DeepSeek route name is preserved while the endpoint and model identifier are repointed at your provider. Connecting to ollama/qwen3.5:9b runs on Ollama:
route : deepseek-official / qwen3.5:9b
endpoint : http://localhost:11434/v1
bridged : ollama/qwen3.5:9bBridging is limited to providers that speak the OpenAI wire format, which covers local servers and dynamic catalogue entries. Providers with their own wire format, such as Anthropic and Google, are left untouched rather than pointed at an adapter that cannot address them.
Watch the demo
Installing the extra, switching to the preset from the SuperQode terminal, and running a turn through DeepSeek's own runtime against a local model, with the tool call and its result arriving as normalized harness events rather than as a block of final text.
The permission boundary
DeepSeek executes its own tools inside its own process. SuperQode approval profiles, permission rules, and sandbox backends therefore do not gate a DeepSeek tool call before it runs. The backend advertises this, harness doctor warns about it, and the preset carries a selection warning. This has a consequence for reading a harness file. The tool list and permission flags describe the specification, and the built-in backend enforces them, but this backend delegates execution. Treat allow_write and allow_shell in a DeepSeek harness as a statement of intent for reviewers, and use DSH_PERMISSION_MODE for the control the runtime applies. The preset defaults it to workspace-write, the narrower of the two modes DeepSeek offers:
runtime:
backend: deepseek-harness
config:
deepseek_harness:
env:
DSH_PERMISSION_MODE: workspace-writeWhat the route gives you, and what it does not
The advantages follow from running DeepSeek's own binary. Behaviour matches upstream exactly, because it is upstream. Tool calls, reasoning, token counts, subagent lifecycle, and session persistence all arrive as structured events rather than as a block of final text. Installation is a single Python command with no JavaScript toolchain. Upgrades are a version pin. The costs follow from the same fact:
approvals DeepSeek executes its own tools; SuperQode cannot gate a call
workflow children DeepSeek runs its own subagents
structured output output schemas are not honoured
cost tokens are reported, cost is not
composition MCP and plugins belong in cordis.yml, not the HarnessSpec
platforms macOS arm64, Linux x86_64 and aarch64
continuity DeepSeek-side history does not survive a terminal restartThe extra installs on unsupported platforms and contributes nothing there, so Windows and Intel macOS report the backend as missing rather than breaking the install. Each live session holds a runtime subprocess until it is cancelled. The upstream project is a developer preview that expects compatibility-breaking changes, and the SDK pin should move deliberately.
Using it
Install the extra, then open a repository, start the terminal interface, and select the preset. It needs no harness file and no Cordis composition, because the SDK injects DeepSeek's own bundled composition when none is supplied:
uv tool install "superqode[deepseek-harness]":connect
:harness switch deepseek-harnessdsh and deepseek resolve to the same preset. Set DEEPSEEK_API_KEY for the DeepSeek route, or connect a local model and let the bridge handle it. To tune the defaults, generate an editable copy and inspect what the runtime will actually do before granting broader access:
superqode harness init my-deepseek -t deepseek-harness
superqode harness doctor --spec my-deepseek.yaml
superqode harness explain --spec my-deepseek.yamlChoosing between harnesses
SuperQode now carries several external coding runtimes beside its own. Prime Agent suits recursive work through a persistent IPython environment. Hugging Face Tau remains a read-only preview. The native RLM harness serves programmable context selection and recursive sessions inside the Python stack. DeepSeek Harness suits work where the DeepSeek model line and its own plugin composition are the point, and where its sandbox and permission mode are an acceptable boundary. All of them run in the same terminal, and the choice is per task rather than per repository.
Source and documentation
SuperQode is available from the Superagentic AI website, GitHub, and PyPI. The backend, event mapping, runtime configuration, permission boundary, and current limits are documented in the DeepSeek Harness guide. If you need more information, read the docs or get in touch with any questions. DeepSeek Harness is maintained by DeepSeek as a separate project under the MIT license. SuperQode hosts its published Python SDK and does not imply endorsement by DeepSeek.