DeepSeek Harness Puts Its Breaking-Changes Warning Before the Install Steps

The loudest sentence in the DeepSeek Harness README is set in all caps: "THERE WILL BE COMPATIBILITY-BREAKING CHANGES." That is not a footnote buried in a changelog. It sits in its own section, second from the top, ahead of the install instructions. Read the rest of the file with that framing and the document stops looking like a user manual and starts looking like a recruiting pitch aimed at plugin authors.

The plugin claim is the architecture, not a feature

DeepSeek Harness ships as dsh, an open-source agent harness from DeepSeek AI, built on an architecture where everything is a plugin and powered by Cordis. The README links Cordis to a paper on spatiotemporal composability and then stops explaining. Notice what it skips: no feature list, no benchmark table, no comparison against other harnesses. It names a composition runtime, points at the theory, and moves on to install steps.

For anyone who has maintained an agent framework, that is the fork in the road that matters. Extension-point designs accumulate special cases. The tool registry gets a hook, then the model router gets a hook, then someone needs a hook that fires between the two, and six months later the extension surface is the product. A uniform plugin model pushes all of that into one mechanism. You either learn it or you fight it. The README does not describe how Cordis handles lifecycle, teardown, or reloading, which is what the linked architecture doc exists for. The useful thing to know before committing time: your mental model of this harness will be a Cordis mental model.

Getting it running is deliberately boring

Install Node.js, run npx @deepseek-ai/dsh web, and the Web UI comes up at http://127.0.0.1:3080 and opens in your default browser.

The most operationally honest line in the whole file covers SSH. A remote launch only prints the host URL rather than trying to open a browser, because the SSH client or editor owns the forwarded local address. Nobody writes that sentence down unless someone already filed the bug. There is a documented no-open switch for running the server without opening a browser at all. If you have ever started a dev server inside a container behind port forwarding and watched it try to launch a browser that does not exist, you know why the detail earned its place.

The source path is clone, pnpm install, pnpm run build, pnpm dsh web. The README is specific that the build step prepares repository artifacts and that pnpm dsh web consumes those artifacts without rebuilding. Small clarification, real time saved: when you edit something and the web command does not reflect your change, that is the documented behavior, not a broken cache.

What the README leaves out

Plenty. There is no description of what an agent session looks like, which models it talks to, what surface area a plugin actually gets, how state persists between runs, or whether anything is sandboxed. Every one of those answers lives behind a docs link: the Web UI guide, the development guide, the architecture documentation, and an AGENTS.md for agents working inside the codebase. Evaluating deepseek-harness from the README alone is not possible. The README is a routing table.

Two details do say something about the intended audience. The project asks plugin authors to tag their repositories with the dsh-plugin GitHub topic, which is an attempt to seed discovery for an ecosystem that has barely started. And it maintains a separate AGENTS.md, which assumes coding agents will be reading and modifying the repo alongside people.

The practical read

It is MIT licensed, written in TypeScript, with third-party dependency licenses disclosed separately. Feedback and bug reports route to GitHub Discussions rather than Issues, with a Discord alongside. Sending bugs to Discussions during a preview is a triage decision: it keeps the tracker from filling up with reports against code that will be rewritten anyway.

If you are writing a plugin against dsh this month, pin the version, keep the plugin small, and read the Cordis paper before the API docs. The all-caps warning at the top is the part of the README with the shortest half-life and the highest cost of ignoring.

---

GitHub: https://github.com/deepseek-ai/deepseek-harness

---

Curated by Agent Palisade — practical AI for small and mid-sized businesses.