DiFlowrin

Posted on Aug 20 Originally published at diflowrin.com

DeepSeek Harness: Plugin-First Agent Runtime

#typescript #github #git #ai

Where DeepSeek Harness Stands Right Now

DeepSeek Harness (dsh) is an open-source agent harness from DeepSeek AI, built on one idea: everything is a plugin. It launched on August 13, 2026 under the MIT license, the same day DeepSeek raised V4 Pro API prices — a free harness paired with a monetization move. It is in developer preview, and the project says in capitals that there will be compatibility-breaking changes. You can run it from npm in one command or build it from source with pnpm. It ships with no model, no key, no provider — you bring those yourself.

What DeepSeek Harness Actually Is

DeepSeek Harness is an open-source agent harness developed by DeepSeek AI. Not a model. Not a coding assistant you talk to. A harness — the thing that wraps around a model and gives it hands: tools, sessions, sandboxes, scheduling, a UI.

And here is the part that matters. The architecture is plugin-based to the core. Models, tools, skills, sessions, sandboxes, storage, loops, scheduling, the UI itself — all of it is plugins. The kernel underneath is Cordis, a meta-framework whose design is laid out in the paper A Programming Paradigm for Spatiotemporal Composability. Cordis handles loading, unloading and dependency relationships between plugins. It does not carry any agent capability itself. The capabilities come from the plugins, and they cooperate through Cordis services and events.

So what does that buy you? You can select, replace or extend any capability at the configuration layer — without touching the source code. That is the claim, and it is the whole design philosophy: a thin kernel plus a bag of composable parts, not a monolithic agent tool.

Why It Matters Now

Because of the timing. VentureBeat reports that DeepSeek launched Harness v0.1 on August 13, 2026, alongside the official DeepSeek-V4-Pro model — and alongside a price increase. V4-Pro peak input moved to $1.32 per million tokens and peak output to $3.96; off-peak sits at $0.66 input and $1.98 output.

DeepSeek open-sourced its agent harness under MIT on the same day it raised V4 Pro API prices — free orchestration, paid inference.VentureBeat, August 13, 2026

Read that structure. The harness is free, permissively licensed, yours to modify. The model inference is not free — it is billed by whatever API provider you configure. The giveaway and the monetization are two halves of one move. And the positioning is explicit: an alternative to integrated coding-agent environments such as Anthropic's Claude Code.

What can it do already? Per VentureBeat's reporting: inspect repositories, edit files, execute shell commands, search files and the web, maintain plans, invoke skills, delegate work to subagents, and enforce approval policies. That is a full agentic coding loop, not a demo.

How the Plugin Architecture Works

The repository tells the story before you read a word of documentation. It is a TypeScript monorepo managed with pnpm, and the packages/ directory holds dozens of plugin packages — session, sandbox, mcp, llm, plan, schedule, skill, subagent, terminal, workflow, and many more. Each capability is its own package. There are also apps/cli and apps/web, a Python SDK under python/, vendored dependencies under vendor/ (including Cordis itself), and a VitePress site under website/.

Cordis kernel

The plugin framework underneath DeepSeek Harness. Responsible only for plugin loading, unloading and dependency relationships — no agent capabilities live in the kernel.

Capabilities as plugins

Models, tools, skills, sessions, sandboxes, storage, loops, scheduling and UI are all provided by plugins that cooperate through Cordis services and events.

Configuration-layer composition

Developers can select, replace or extend any capability in configuration, without modifying source code.

Append-only session log

According to Eigent's write-up, every agent run is recorded in an append-only log: system prompts, reasoning, tool calls and results, subagent scheduling, every context injection. Full traceability of what the model saw and did.

It can orchestrate its own competitors

One detail worth sitting with. MindStudio reports that the plugin composability extends to entire other agent harnesses — Claude Code or Codex can be called as sub-agents inside a DeepSeek-orchestrated workflow. Rival and wrapper at the same time. The line between the two gets blurry fast when everything is a plugin.

Running It: npm and Source

How to run DeepSeek Harness from npm

Install Node.js, then one command:

npx @deepseek-ai/dsh web

That starts the Web UI at http://127.0.0.1:3080 by default and opens it in your default browser on a local launch. Over SSH it only prints the host URL, because the SSH client or editor owns the forwarded address. Pass --no-open to run the server without opening a browser.

One caveat the README does not spell out but installers should know: AtlasCloud's setup guide states the repository requires Node.js ^22.19.0 or >=24.0.0 — nothing on the 23.x line qualifies at any patch level. An older Node may not satisfy the engine requirement even if npx itself runs.

DeepSeek Harness run from source with pnpm

From a repository checkout:

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

pnpm run build prepares the repository artifacts. pnpm dsh web then uses those built artifacts without rebuilding.

The Fine Print: Configuration, Credentials, Context

Here is where early adopters need to pay attention. The harness ships with no credentials, no default provider, and no bundled model, per AtlasCloud. It will not do a single useful thing until you give it an OpenAI-compatible base URL, an API key, and at least one model ID. Three routes work: DeepSeek's own API, an OpenAI-compatible gateway, or a local model via Ollama.

Two more details from the same guide deserve a table, because they will bite you if you miss them:

Setting	Default	Implication
Hand-declared model context window	262,144 tokens	V4's full 1,048,576-token window stays off until configured
Default max tokens	32,768	Output limits are far below the model's ceiling
Credential storage	Plain text at ~/.dsh/.credentials.yaml	Keys sit unencrypted on disk; no source documents mitigations
Settings	~/.dsh/settings.yaml	Plugins and models configured via YAML

And a warning about a comfortable assumption: a local Web UI is not local inference. Atoms.dev puts it plainly — the browser interface runs locally, but the configured model may still call a paid remote API. The same source notes the standard permission preset is workspace-write with approval prompts, and that a danger-full-access mode exists which deliberately bypasses filesystem confinement. Do not reach for that one casually.

What Real Usage Costs

Agentic coding at scale burns tokens. MindStudio's real-world test — building a real-time ISS tracker with a live API feed and a 3D globe visualization — consumed roughly 20 million tokens across two turns and about 35 minutes, with output alone near 240,000 tokens. Cache hit rates landed in the 95–100% range, unusually high for this category of tool.

One moderately complex task: ~20 million tokens, two turns, 35 minutes.MindStudio, August 2026

So budget accordingly. High cache hit rates soften the bill, but 20 million tokens is 20 million tokens.

On benchmarks, be careful. Composio tested DeepSeek v4 Flash across several harnesses — 240 runs, a 53.8% overall pass rate, DeepAgents at 53.3% with a 187.1-second median and $0.045 per successful task. But DeepSeek Harness itself was not in that test. Nobody has published a head-to-head benchmark of it against rival harnesses. Anyone claiming otherwise is guessing.

Where Reports Disagree

Because the project is days old and moving fast, third-party write-ups contradict each other. Two examples worth knowing:

Default port. The README states http://127.0.0.1:3080, and Atoms.dev agrees. MindStudio's two setup articles both say port 3018. Whether the default changed between versions or one report is simply wrong — no source settles it. Trust the README.
Whether a DeepSeek API key is mandatory. MindStudio says you need a DeepSeek API key before the harness will let you do anything. AtlasCloud says the opposite: no default provider, any OpenAI-compatible endpoint works, including local Ollama. The architecture — model provider as plugin — supports AtlasCloud's reading.
Preset modes. Atoms.dev lists Standard, PTC, Minimal, Creator. CometAPI lists Standard, Minimal, Code, Creator. MindStudio says full, code, minimal, creator. Four modes, three namings — check the current docs before scripting against them.

The Developer Preview Caveat

The project is unusually honest about its own status. The README states it is in developer preview, iterating rapidly, and — in capitals — THERE WILL BE COMPATIBILITY-BREAKING CHANGES. No source provides a roadmap or a date for a stable release. Pin a package version and verify current documentation before adopting it for anything serious, as Atoms.dev advises.

The licence, at least, is settled: MIT, copyright DeepSeek, with third-party dependencies and their licenses disclosed in THIRD_PARTY_NOTICES.md. Commercial use, modification, redistribution — all permitted.

Community and Contributing

Feedback and bug reports go through GitHub Discussions. Plugin authors are asked to add the dsh-plugin topic to their repositories for discoverability — a small signal that third-party plugin development is an expected part of the model, not an afterthought. There is also a Discord community. For contributors: CONTRIBUTING.md, a development guide, and architecture documentation. For agents working in the repo: AGENTS.md. Documentation ships in English and Chinese.

📊 What This Means for Teams Evaluating DeepSeek Harness

Architecture is the product: a thin Cordis kernel with every capability — models, tools, sessions, sandboxes, UI — as a swappable plugin, composable in configuration without source changes.
Free harness, paid inference: MIT-licensed code launched the same day V4 Pro API prices rose; the browser UI is local but the model bill is not.
Bring your own everything: no bundled model, no default provider, no credentials — you supply an OpenAI-compatible endpoint, key and model ID.
Watch the defaults: hand-declared models get a 262,144-token context window and 32,768 max tokens, and credentials sit in plain text under ~/.dsh.
Preview means preview: breaking changes are promised in writing, no stable-release roadmap exists, and third-party guides already contradict each other on ports, modes and requirements. Pin versions; verify docs.

The Bottom Line

DeepSeek Harness is a serious piece of infrastructure from a major lab, released with unusual openness and unusual candor about its own instability. The plugin-first design is not marketing decoration — the monorepo structure, the Cordis kernel, the dsh-plugin ecosystem push all point the same direction. What it is not yet is finished. Treat it as what it says it is: a developer preview worth building on carefully, with pinned versions, isolated workspaces, and eyes open about where the tokens — and the money — go.

Additional Resources

This article includes content created with AI.

DEV Community