# DeepSeek Harness

> Source: https://aiwiki.ai/wiki/deepseek_harness
> Updated: 2026-08-15
> Categories: AI Agents, AI Code Generation, Developer Tools, Open Source AI, Software Development
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/) - attribute to "AI Wiki (aiwiki.ai)"
> Cite as: AI Wiki. "DeepSeek Harness." aiwiki.ai, 15 Aug 2026. https://aiwiki.ai/wiki/deepseek_harness
> From AI Wiki (https://aiwiki.ai), the free encyclopedia of artificial intelligence. Reuse freely with attribution.

**DeepSeek Harness** is an open-source [AI agent](https://aiwiki.ai/wiki/ai_agents) harness developed by [DeepSeek](https://aiwiki.ai/wiki/deepseek). Also called **dsh**, it supplies the software around a language model: the agent loop, tools, sessions, filesystems, permission controls, orchestration, and user interfaces. DeepSeek announced version 0.1 as a developer preview on August 13, 2026.[1][2]

Harness is not a language model and does not include downloadable DeepSeek model weights. A working agent still needs access to a configured model endpoint. The project ships a DeepSeek adapter, but its Web configuration also supports other catalog providers and custom OpenAI-compatible endpoints.[5] The Harness source is licensed under the [MIT License](https://aiwiki.ai/wiki/mit_license); separately accessed models and services retain their own terms.[16]

The developer-preview label is a material limitation. The repository warns that compatibility-breaking changes will occur. As of August 14, the current npm package was a release candidate rather than a stable 1.0 release, and the corresponding [Python](https://aiwiki.ai/wiki/python) package was explicitly marked as a pre-release.[2][3][8]

## Release and distribution

DeepSeek's launch post described Harness v0.1 as an opening of the codebase to agent-harness developers and summarized its design as making every major capability a replaceable plugin.[1] The official repository provides source code, documentation, Web and headless profile templates, examples, and development tooling. It does not publish model weights as part of the Harness release.[2]

Registry metadata provides more precise package versions than the product-level v0.1 name. On August 14, 2026, npm's latest tag for **@deepseek-ai/dsh** pointed to **0.1.0-rc.6**, published on August 13. That package installs the **dsh** executable.[3] PyPI listed **deepseek-harness-sdk 0.1.0rc6**, also released on August 13, and warned that the pre-release might not be stable for production use.[8] The GitHub repository had no formal entry on its Releases page at that time.[19]

| Installation path | Documented command or package | Runtime requirements |
|---|---|---|
| Published Web launcher | npx @deepseek-ai/dsh web | Node.js; the public quickstart does not state an exact minimum |
| Source checkout | pnpm install, pnpm run build, pnpm dsh web | Node.js 22.19+ or 24+, Corepack pnpm 11.7.0, Git 2.26+ |
| Python SDK | python -m pip install deepseek-harness-sdk | Python 3.10+ and a supported bundled runtime platform |

The exact Node.js floor in the table belongs to the source-contributor workflow. The published npm metadata did not declare an **engines** field when checked, so the contributor floor should not be presented as a verified npm package constraint.[3][4] Continuous integration covers Node.js 22.19, 24, and 26. A real DeepSeek-backed run also needs an API credential, while framework tests and some tutorials can run without one.[4]

The Python quickstart lists Linux on x64 or arm64 and macOS 14 or newer on arm64. Installing the SDK also installs a matching bundled runtime, so ordinary SDK use does not require a system Node.js installation. Its example still requires a compatible model endpoint, a credential, and a workspace the agent is allowed to modify.[7][8]

## Interfaces

The default user-facing path is a local Web application. Running **dsh web** serves it at **127.0.0.1:3080** unless configured otherwise. The invoking directory is the default filesystem location, but a fresh Web UI has no active workspace until the user adds and selects one. Once configured, the agent can inspect and edit files, run commands, delegate work, and maintain a plan. The interface asks for approval when an operation exceeds the active permission policy.[2][5]

Model setup is separate from starting the server. The Models settings page accepts a DeepSeek API key and stores it in a credentials file while retaining only a reference in ordinary settings. Users can also add catalog providers, native cloud routes, or a custom endpoint. A manually entered model is treated as text-only unless its modalities are explicitly declared. The official DeepSeek chat route is documented as text-only.[6]

The **headless** profile is a one-task alternative. The command **dsh --profile headless "job"** creates a persisted session, runs until the agent becomes idle, prints the final non-empty assistant response, and exits. It opens no HTTP server and has no interactive follow-up channel. Both Web and headless profiles initialize from shipped templates on first use.[4][9]

For programmatic use, the Python SDK starts a bundled Harness runtime and communicates with it over JSON-RPC through standard input and output. The **DeepSeekHarness** class can reuse that subprocess across calls, and a repeated session identifier continues the same durable session and persistent shell state. A source checkout also includes ACP and JSON-RPC demonstrations, but those are development or automation examples rather than additional default interactive profiles.[4][7]

## Plugin architecture

Harness is built on Cordis, a [TypeScript](https://aiwiki.ai/wiki/typescript) meta-framework vendored into the repository. Cordis provides a shared context of named services. A [plugin](https://aiwiki.ai/wiki/plugins) requests services such as tools, model access, or sessions by context key instead of importing a fixed implementation. Required services are declared through injection, typed events carry communication, and registrations are tracked so they can be reversed when a plugin unloads.[9][10]

This design applies to product components, not just third-party extensions. The model adapter, tool registry, session log, agent loop, persistence, filesystem, sandbox policy, approvals, settings, credentials, telemetry, and Web surface are mounted as plugins. The architecture documentation says there is no privileged core that an extension must patch. Replacing a component is instead a configuration operation within the Cordis tree.[9]

A running Harness is assembled from profiles and bundles:

- A **bundle** is an npm package that contributes a Cordis configuration patch.
- A **profile** is a runnable composition that lists bundles in order and stores user overrides.
- **dsh-base** is the first layer of every profile and provides the common agent, tool, persistence, model, permission, and settings components.
- The Web and headless bundles add their respective interfaces.
- Profile, home-level, and command-line patch layers can replace earlier configuration rows by identifier.[9][12]

The smallest extension is a TypeScript module exporting an **apply** function that receives the Cordis context. Object and service-class forms are also supported. Plugins can register tools, listeners, prompt sections, model adapters, providers, and other services. Context-managed registrations are cleaned up on unload, while arbitrary resources can supply an explicit disposer.[10][12]

Packaged plugins declare a **dsh.bundle** manifest in package.json and point it at a patch file. The launcher manages out-of-tree dependencies through **dsh plugin --profile**, which forwards package operations to pnpm inside the selected profile. The official documentation suggests the **dsh-plugin** GitHub topic for discovery, but it does not describe a curated or security-reviewed marketplace.[2][12]

## Cordis design basis

Cordis is accompanied by the draft paper *A Programming Paradigm for Spatiotemporal Composability*. It defines temporal composability as the ability to reverse a component's effects when it is removed, and spatial composability as declaratively managing dependencies as the surrounding context changes. Cordis implements those ideas through tracked effects, dependency resolution, a declarative loader, configuration reconciliation, and hot module replacement.[11]

The paper was dated August 13, 2026 and labeled a preprint under active revision. It is the design rationale for Cordis, not an independent or peer-reviewed evaluation of DeepSeek Harness. The separate Cordis repository also says its API is not yet stable and may change without notice.[11][20]

## Agent loop and session state

The default loop distinguishes a **step** from a **turn**. A step consists of one model request and the tool calls that follow it. A turn can contain several steps when a tool result or queued input requires another request. Plugins can observe or intercept model requests, tool execution, and turn transitions through typed events.[9]

Durable session events record user messages, assistant output, tool calls and results, and turn boundaries. The model-visible history is derived from that log, as are resume, fork, transcript, telemetry, and persistence features. This event-stream design reduces the need for each interface to maintain a separate copy of agent state, but it does not guarantee that every optional persistence plugin has identical durability properties.[9]

The checked-in Python minimal example is intentionally narrower than the main Web composition. It exposes persistent Bash and a string-replacement editor, stores sessions as JSONL, and disables context compaction. Its purpose is to provide a reproducible SDK starting point, not to define every Harness deployment.[7]

## Permissions and sandboxing

The shipped base profile configures new sessions for **workspace-write** with an **ask** approval policy unless an operator overrides the permission mode through the environment. It also defines **read-only** with approvals and **danger-full-access** without approvals as selectable presets.[14]

| Mode | Documented filesystem effect |
|---|---|
| read-only | Denies writes apart from required system sinks |
| workspace-write | Allows writes inside the canonical workspace and designated temporary areas |
| danger-full-access | Bypasses filesystem confinement |

These modes describe filesystem effects only. The official sandbox specification explicitly excludes network access and process visibility from the policy vocabulary. A workspace-write session therefore should not be interpreted as a complete network or process-isolation boundary.[13]

For confined shell commands, the local provider prefers Bubblewrap and then Landlock on Linux, uses Seatbelt on macOS, and uses an ACL restricted-token runner on Windows. If no intended backend is usable, the provider is designed to fail closed rather than silently execute without confinement. It reports enforcement as either full or partial. Older Landlock application binary interfaces and documented Windows ACL gaps are examples of partial enforcement, which callers needing an absolute boundary must not treat as full.[13]

Filesystem editing tools use a separate trusted-code containment check. Their documentation calls it a policy fence rather than a kernel boundary and acknowledges a narrowed but accepted race involving changes to ancestor symbolic links between checking and writing. Untrusted shell code is intended to pass through the process sandbox instead.[15]

The Python tutorial's minimal composition is a notable exception to the Web default. It uses danger-full-access, and absolute editor paths can reach any file visible to the runtime process. The tutorial tells users to run that example only in a disposable checkout or container. Its persistent terminal backend also makes that particular composition unsuitable for Windows agents.[7]

Installing plugins creates another boundary. A plugin fetched from a Git host may run a **prepare** build script on the host if the user allowlists it in pnpm. That code executes at install time, outside the sandbox used for later agent commands. The official guide recommends reviewing the source and pinning a commit hash; publishing prebuilt artifacts avoids the build step but does not make an untrusted plugin safe.[12]

## Development status and limitations

DeepSeek Harness had extensive architecture and subsystem documentation at launch, but several production questions remained open. The repository promised breaking changes, Cordis declared its API unstable, and both public packages used release-candidate versions.[2][3][8][20]

The repository's benchmark file only explains how to run the Python minimal variant. It publishes no comparative Harness scores, so it does not support claims that dsh is faster, safer, or more capable than another agent system.[17] Community reports and discussion comments may motivate tests, but they are not a substitute for controlled evaluations.

As of August 14, GitHub detected no SECURITY.md policy and listed no published security advisories for the repository.[18] The absence of an advisory is not evidence that the code has no vulnerabilities. The project documents its sandbox design and limitations, but it does not publish an independent security audit, a production service-level commitment, or a stable compatibility policy.

These constraints make the developer preview most suitable for evaluation in controlled workspaces, with versions pinned, permission modes reviewed, and plugins treated as executable host code. They do not prevent production experimentation, but the official evidence does not justify describing the release as production stable.

## References

1. DeepSeek. *DeepSeek Harness v0.1 developer preview announcement*. August 13, 2026. https://x.com/deepseek_ai/status/2087887408440164663
2. DeepSeek. *DeepSeek Harness repository and README*. https://github.com/deepseek-ai/deepseek-harness
3. npm Registry. *@deepseek-ai/dsh package metadata*. Accessed August 14, 2026. https://registry.npmjs.org/%40deepseek-ai%2Fdsh
4. DeepSeek. *Development guide*. https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/development.md
5. DeepSeek. *Use the Web UI*. https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/index.md
6. DeepSeek. *Configure models*. https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/providers.md
7. DeepSeek. *Get started with the Python SDK*. https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/python-sdk.md
8. Python Package Index. *DeepSeek Harness Python SDK*. Accessed August 14, 2026. https://pypi.org/project/deepseek-harness-sdk/
9. DeepSeek. *DeepSeek Harness Architecture*. https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md
10. DeepSeek. *Cordis Primer*. https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md
11. Cordiverse. *A Programming Paradigm for Spatiotemporal Composability*. Draft of August 13, 2026. https://github.com/cordiverse/paper
12. DeepSeek. *Package and install a plugin*. https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md
13. DeepSeek. *Process Sandbox*. https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/sandbox.md
14. DeepSeek. *dsh-base profile configuration*. https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/base/cordis.patch.yml
15. DeepSeek. *The sandbox-enforcing filesystem backend*. https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/fs/fs-sandbox/README.md
16. DeepSeek. *MIT License*. https://github.com/deepseek-ai/deepseek-harness/blob/master/LICENSE
17. DeepSeek. *Running benchmarks*. https://github.com/deepseek-ai/deepseek-harness/blob/master/BENCHMARK.md
18. GitHub. *Security overview for deepseek-ai/deepseek-harness*. Accessed August 14, 2026. https://github.com/deepseek-ai/deepseek-harness/security
19. GitHub. *Releases for deepseek-ai/deepseek-harness*. Accessed August 14, 2026. https://github.com/deepseek-ai/deepseek-harness/releases
20. Cordiverse. *Cordis repository*. Accessed August 14, 2026. https://github.com/cordiverse/cordis