TL;DR

DeepSeek Harness (dsh) is an open-source agent harness from DeepSeek AI, not a model or a fixed coding agent. It uses the Cordis plugin system so model adapters, tools, sessions, sandboxes, loops, scheduling, and UI can be composed from configuration. Its important engineering lesson is not “everything should be a plugin”; it is that every replaceable capability needs an explicit interface, lifecycle, policy boundary, and test contract.

Table of Contents

What DeepSeek Harness is

DeepSeek Harness is a runtime for tool-using agents. Its official project describes the product as an open-source agent harness powered by Cordis, where capabilities are plugins and an agent is composed from a model plus its harness. A model adapter generates proposals; the harness supplies the environment in which those proposals can access context, request tools, receive results, and continue work.

That boundary matters. A model provider, a tool schema, and a chat UI do not independently provide durable execution, permission enforcement, or recovery. Those concerns belong to the surrounding Agent Harness, even when a framework supplies extension points for them.

DeepSeek currently labels dsh a developer preview and explicitly warns about compatibility-breaking changes. Treat its public documentation and pinned source revision as the compatibility contract; do not infer a stable API from a demonstration or an internal package name.

The Cordis composition model

Cordis is the framework below DeepSeek Harness. A Cordis plugin contributes services, typed events, and reversible effects to a shared context. The key consequence is that a consumer depends on a capability such as ctx.tools or ctx.sessions, rather than importing a specific tool registry or persistence backend.

flowchart LR P["Profile"] --> B["Bundles"] B --> C["Cordis plugin tree"] C --> M["Model adapter"] C --> T["Tool registry"] C --> S["Session log"] C --> X["Sandbox and approvals"] C --> U["Web or protocol UI"]

The architecture uses three related extension mechanisms:

Mechanism Job Design question
Service Provides a named capability on ctx What interface and ownership boundary does this capability need?
Typed event Lets plugins observe or intercept a lifecycle seam Is this an observation, a policy decision, or a durable fact?
Reversible effect Registers a listener, tool, provider, or resource with cleanup What must be removed or closed when the plugin unloads?

This is more than dependency injection. A tool plugin can register a schema, a policy plugin can intercept execution, and an observability plugin can consume the resulting event stream without editing the agent loop. But composability does not make every plugin trustworthy. A plugin that can read files, alter a prompt, or authorize a tool is part of the agent's supply chain and needs review, version pinning, and scoped privileges.

Profiles bundles and patches

A running dsh is assembled as an ordered plugin tree. The official architecture distinguishes:

  • A profile: a named composition in the Harness home that lists bundles, installed plugins, and user patch configuration.
  • A bundle: a distributable set of Cordis configuration rows and the code those rows mount.
  • A patch: an overlay that replaces or inserts configuration rows.

The boot order is significant: profile bundles are applied in order, followed by profile and home patches, then an optional command-line patch. Later layers can replace a row inserted earlier. Inspect the effective configuration instead of guessing which provider is active:

sh 
dsh --profile web --dump-config

The output is useful for review, but it is not a production approval record by itself. A deployment should also pin the deepseek-harness revision, installed plugin versions, model routes, credential source, workspace mount, sandbox backend, egress policy, and approval policy.

How an agent turn moves through the runtime

In the default loop, a turn may contain zero or more steps. A step is one model request and the tool executions it requested. The runtime assembles prompt sections and tool schemas, streams the model response, runs requested tools through the tool pipeline, then decides whether another step is owed.

sequenceDiagram participant U as User or event source participant A as Agent loop participant L as Model adapter participant T as Tool pipeline participant S as Session log U->>A: enqueue message A->>S: append turn and user events A->>L: assembled prompt and schemas L->>S: append assistant stream and message L->>T: requested tool call T->>S: append tool result T-->>A: result or policy decision

The architecture documentation identifies agent/pre-step, agent/request, model streaming, and tool execution events as extension seams. Use those seams deliberately:

  • A policy that can deny or ask for approval belongs before execution.
  • A timeout or retry wrapper belongs around the actual dispatch lifetime.
  • Metrics and audit records should observe the immutable final result.
  • A new model-visible input must be represented in the durable session event model.

This aligns with the broader distinction between an Agent Runtime and an application control plane. The runtime can make a policy hook possible; the application still owns tenant identity, resource authorization, business invariants, and incident response.

What is configurable and what remains your responsibility

DeepSeek Harness can compose a model route, tool set, sandbox backend, session store, and UI. It does not turn a permissive configuration into a secure system. The following table separates framework capability from application responsibility.

Area Harness can provide Application must still own
Tool access Registry, schemas, execution hooks User and tenant authorization, object-level policy, spend limits
Sandbox Backend seam and process wrapping Workspace scope, secret brokering, network egress, image provenance
Sessions Event model, replayable history seam Retention, redaction, encryption, deletion, access audit
Model routing Adapter registration and route settings Provider contract, cost limits, fallback policy, quality evaluation
Plugins Mounting, dependencies, cleanup Review, version pinning, compatibility tests, rollback

For example, a valid tool argument is not permission to modify a repository or a cloud resource. Keep the model proposal, authorization decision, external side effect, and reconciled outcome as separate records. The general implementation patterns are covered in Agent Harness Engineering and the Tool Use glossary entry.

How to evaluate an adoption

Evaluate DeepSeek Harness as a runtime integration, not as a benchmark score. Start with a bounded workspace and a minimal task suite, then expand only after the evidence is sufficient.

  1. Pin an artifact. Record the Git commit or released package version, Node.js version, profile, bundles, patches, and provider settings.
  2. Test capability boundaries. Verify that prohibited paths, network destinations, secrets, and write operations are denied even if a model proposes them.
  3. Test lifecycle behavior. Mount and unload a custom plugin; confirm listeners, timers, and resources are disposed.
  4. Test recovery semantics. Interrupt a task during a read-only tool and during a side effect. A replayable session is not proof that the external system did not commit.
  5. Test upgrades separately. Re-run the suite on every DSH or plugin revision because the project is in developer preview.

The Agent Harness Evaluation Guide explains how to turn these checks into replay, fault-injection, and release gates. Do not use a successful demo as evidence that a plugin tree is ready for privileged production work.

FAQ

Is DeepSeek Harness only for DeepSeek models?

No. The project documentation describes model adapters as a plugin seam and its Web UI documentation includes custom OpenAI-compatible endpoints. Provider compatibility, streaming behavior, tool-call behavior, token accounting, and error semantics still need testing for the exact adapter and model route.

Does “everything is a plugin” mean any plugin can replace the agent loop safely?

No. Plugins can extend a documented seam, but replacement changes the runtime contract. A loop, policy, or persistence replacement must preserve required lifecycle, logging, cancellation, authorization, and recovery semantics before it is considered compatible.

Can a DSH patch safely change a production deployment?

Only after review and testing. A patch can replace configuration rows, so it can change providers, tools, or policies. Treat patches as deployable code: review the diff, pin referenced plugins, test in an isolated environment, and retain a rollback path.

Does DeepSeek Harness provide security by default?

No framework can provide application security by itself. DSH exposes sandbox and approval seams, but deployment security also requires least privilege, scoped credentials, egress policy, tenant isolation, input defense, audit, and business-specific approvals.

Where should a team start?

Start with the official Web UI quickstart, then inspect the active profile with --dump-config. Build one small plugin in a throwaway workspace before connecting a real repository, credentials, or production tools.