DeepSeek Harness v0.1: Plugin Architecture and Agent Workflow Guide

DeepSeek opened DeepSeek Harness to agent-harness developers on August 13, 2026, with source code under the MIT-licensed GitHub repository. The project calls itself dsh, is powered by the Cordis meta-framework, and is explicitly in developer preview. The README warns that compatibility-breaking changes will occur.

The launch post is useful as a product-level summary, but the repository and documentation are the sources to use for implementation details. At collection time, the official post had more than 19,000 likes and 3.8 million views; those engagement values are discovery context, not evidence that the preview is mature or production-ready.

This guide turns the release into a developer decision. It explains the architecture, runtime modes, session traces, installation path, plugin and tool workflow, and a security checklist. It does not claim that the preview is production-ready, and it does not treat public GitHub security discussions as a formal audit or a proven exploit.

The practical verdict

DeepSeek Harness is worth evaluating when you want to study the layer between a model and a real working environment: tool execution, context injection, session persistence, sandboxing, subagents, and replayable trajectories. It is especially interesting for teams building their own harness rather than merely calling a model API.

Use it now for:

• comparing agent modes under a controlled repository and tool budget;
• prototyping Cordis plugins and custom presets;
• inspecting how tool calls, results, reasoning and context are recorded;
• testing code-mode orchestration against a small, disposable workspace;
• learning from an open implementation of a coding-agent runtime.

Wait or isolate it when you need:

• a stable plugin ABI;
• signed third-party extensions;
• a mature enterprise approval and credential boundary;
• guaranteed backward compatibility;
• production access to source repositories, cloud accounts or customer data.

The right first deployment is a sandboxed evaluation host with synthetic credentials, a disposable repository, outbound network restrictions, and a rollback path.

What DeepSeek released

The release has three evidence surfaces that should not be conflated:

The current source package identifies the project as 0.1.0-rc.5, uses [email protected], and requires Node ^22.19.0 || >=24.0.0. The website's shortest path is:

npx @deepseek-ai/dsh web

The repository README says the Web UI is served on the local loopback interface at port 3080 by default. If you run it on a VPS, bind and expose it deliberately; do not assume that a local development listener is safe to publish through a firewall or reverse proxy.

The public repository history shows the 0.1.0-rc.5 release commit on August 13, followed by the public npm packaging merge. Pin that release or a reviewed commit for experiments; do not use a floating preview dependency when comparing trajectories or plugin behavior.

DeepSeek's API documentation separately documents model APIs and links to the Harness guide. A Harness installation is not the same thing as a hosted DeepSeek API account: you must supply and scope any model credentials used by the selected adapter. If you are evaluating the model layer separately, compare the DeepSeek V4 Flash API guide; for broader security controls, see the Agent Baseline implementation guide.

How the plugin architecture works

The important architectural choice is that capabilities are not hard-coded into one monolithic agent loop. DeepSeek describes the Cordis kernel as managing plugin mounting, unmounting and dependencies. Plugins expose services and events, and configuration selects which capabilities participate in a runtime.

The website lists these as plugin-provided capabilities:

• model adapters;
• tools and skills;
• sessions and storage;
• sandboxes;
• loops and scheduling;
• user interface components.

That composition changes what “the agent” means. A model is one part of the system; the harness determines what the model can see, which tools it can invoke, how results enter context, where files persist, and how a run is resumed.

The practical benefit is controlled substitution. You can compare two tool sets or storage strategies without rewriting the whole harness. The practical cost is a larger configuration and dependency surface. A plugin can change behavior even when the model identifier stays constant.

The repository's architecture guide is the right source before changing packages. Treat it as an implementation reference, not a promise that the preview's internal interfaces will remain stable.

Compare the runtime modes

DeepSeek documents four modes with different evaluation and authoring jobs:

A useful experiment keeps the model, task set, repository snapshot, reasoning setting and evaluator fixed while changing one mode. Record tool count, successful task completion, repair loops, token use, elapsed time and unauthorized-action attempts.

Do not compare a Standard run with a Minimal run and call the difference a model benchmark. You changed the harness, not only the model.

Trace sessions and trajectories

DeepSeek's strongest operational idea is traceability. The Harness website says that the model-visible record is kept in an append-only session log. The record includes system prompts, reasoning, tool calls and results, subagent scheduling, and context injections.

The Trajectory view is described as supporting:

• inspection by source;
• resume;
• fork;
• search;
• replay.

This gives an evaluator more than a final answer. A failed coding task can be classified as a bad plan, missing context, tool error, incorrect tool result, unsafe action, or evaluator defect. A fork can test a changed instruction or tool without discarding the original trajectory.

There are still questions to answer before using traces as an audit record:

1. Which events are persisted locally and for how long?
2. Are secrets redacted before entering prompts, tool results or logs?
3. Can a plugin modify or delete the event stream?
4. Can a fork be distinguished from an authoritative production run?
5. Which logs are exported, and who can read them?

The append-only description is useful evidence of design intent. It is not by itself proof of tamper resistance or compliance retention.

Install and start the preview

The simplest documented path is:

node --version
npx @deepseek-ai/dsh web

For a source checkout, the README documents:

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

Pin the repository commit or package version for repeatable evaluation. The project is moving quickly, and the README explicitly warns about compatibility-breaking changes. Record at least:

Harness package version
Git commit
Node version
Package-manager version
Selected model adapter and model ID
Runtime mode
Tool/plugin configuration
Sandbox and approval policy
Task-set revision

Start with a disposable repository containing no credentials. Verify that the UI listens only where intended, that the workspace root is correct, and that the agent cannot reach production networks before adding any real integration.

Add tools and plugins safely

The repository includes a tool-authoring guide. A safe tool-development loop is:

1. Define one narrow operation and its input schema.
2. Return structured, bounded results.
3. Add timeout, size and retry limits outside the model prompt.
4. Test invalid input and partial failure.
5. Run the tool against synthetic data.
6. Record the tool call and result in the trajectory.
7. Add an explicit approval gate before any mutation.
8. Only then make the tool discoverable to a broader mode.

For a file-editing tool, test path traversal, symlink handling, binary-file behavior, repository-root enforcement, diff size, and rollback. For a network tool, test destination allowlists, DNS rebinding assumptions, response size, redirects and secret leakage. For a cloud tool, use a separate low-privilege identity and deny destructive operations by policy.

Code Mode deserves a separate budget. It can combine multiple operations in one model-generated TypeScript program, which may reduce round trips but can also make the side-effect boundary less obvious. Log every underlying operation, not only the generated program's final output.

Security and data boundaries

DeepSeek's data-processing statement describes the Harness as local-first and explains what the installed product processes and stores. Read it alongside your own filesystem, model-provider and plugin configuration; “local-first” does not mean that prompts never leave the machine when a remote model adapter is configured.

The preview's plugin model creates a trust boundary that deserves explicit treatment. Public maintainer discussions include reports that third-party plugins run inside the core process and that plugin installation does not yet provide the signing and source-verification guarantees an enterprise supply chain may require. Another public discussion describes configuration-tree write risks during boot. These are public issue/discussion reports, not a formal DeepSeek security audit and not proof that every installation is exploitable. They are nevertheless sufficient reason to isolate untrusted plugins and review the source before installation.

Use this threat model:

Do not let a preview plugin decide its own approval policy, expand its own credential scope, or rewrite the configuration that governs its sandbox without an external control.

Build an evaluation harness

A useful DeepSeek Harness evaluation tests the harness and the model separately. Use a fixed repository snapshot and run each task in Standard, Code and Minimal mode where applicable.

Record:

• accepted-task rate, not just completion text;
• number and type of tool calls;
• repair attempts and retries;
• files changed and diff size;
• tests passed and tests skipped;
• token and wall-clock cost;
• approval requests and denied actions;
• network destinations;
• trace completeness;
• failure classification.

The result should be a matrix rather than a single score. A mode that completes more tasks by making broader edits may be less suitable than a slower mode with smaller, reviewable diffs.

DeepSeek's V4 release used the Harness Minimal mode in its own public code-agent benchmark setup, but that fact does not make the preview harness an independent benchmark standard. Reproduce the task set and configuration yourself before comparing model claims.

Adopt, test or wait

Choose evaluate now if you want an open implementation to study and can isolate it. Choose wait if you need stable APIs, signed extensions, mature enterprise controls or a supported production SLA.

A bounded adoption checklist:

• [ ] Pin a package version or commit.
• [ ] Run on a disposable host and repository.
• [ ] Use synthetic secrets and data.
• [ ] Start with Minimal mode.
• [ ] Deny outbound network access by default.
• [ ] Review every plugin source before installation.
• [ ] Add external approval for mutations.
• [ ] Capture and inspect trajectories.
• [ ] Compare modes with a fixed task set.
• [ ] Maintain a rollback path and delete preview data after evaluation.

The project is compelling because its architecture is inspectable. Its preview status is equally important: composability is an opportunity for engineering, not a substitute for supply-chain, sandbox and credential controls.

FAQ

The short answers are in the page metadata for search and agent extraction; the operational details above are the authoritative guide.

Official sources

• DeepSeek Harness developer preview
• DeepSeek official X announcement
• DeepSeek Harness data-processing statement
• DeepSeek Harness GitHub repository
• Architecture guide
• Tool-authoring guide
• DeepSeek Harness API documentation
• DeepSeek tool-calling documentation
• Public plugin security discussion
• Public defensive-research discussion