deepseek-harness

1. Project Overview

DeepSeek Harness (dsh) is an open-source, plugin-based agent framework from DeepSeek AI that lets developers build, run, and fully trace AI agents — from every model call and tool invocation down to sandboxed code execution — with any part of the system swapped or recomposed as a plugin.

2. Background & Positioning

DeepSeek Harness was created to give the community open, reusable, and composable infrastructure for exploring what AI agents can (and can't) do in real-world environments, rather than leaving every team to rebuild the same agent scaffolding — model routing, tool execution, sandboxing, session storage, scheduling — from scratch.

Its core mission is stated plainly in the project's own words: "everything is a plugin." The framework is built on Cordis, a plugin runtime designed for what its authors call "spatiotemporal composability" — the ability to add, remove, or hot-swap capabilities (models, tools, skills, sandboxes, storage) without redesigning the surrounding system.

What sets it apart from many other agent frameworks is this uniform plugin model applied end to end: models, tools, skills, sessions, sandboxes, storage, scheduling loops, and even the Web UI are all first-class plugins built on the same substrate, rather than a fixed core with a few extension points bolted on. Combined with append-only session logging for full traceability, it targets teams that need agents whose behavior can be inspected, replayed, and audited — not just agents that produce an answer.

3. Feature Categories

• 🧩 Plugin System — the foundational layer; every capability (models, tools, skills, sessions, sandboxes, storage, loops, scheduling, UI) is implemented as a Cordis plugin that can be swapped independently, letting teams mix and match components without forking the core.
• 🤖 Model & Tool Orchestration — pluggable model backends and a complete toolset for coding agents, including file editing, shell access, and web search, so agents can operate on real codebases and real environments.
• 📝 Session Recording & Replay — append-only session logs capture every model interaction, enabling inspection, resumption, forking, and replay of past agent runs for debugging and auditing.
• 🖥️ Multiple Runtime Modes — Standard (full coding-agent toolset), Code (TypeScript-based tool orchestration), Minimal (a lean benchmarking environment), and Creator (custom preset development with live runtime inspection), covering use cases from production agents to controlled benchmarks.
• 🌐 Web UI — a built-in browser interface (served locally, e.g. at http://127.0.0.1:3080) for interacting with and observing running agents without extra tooling.
• 🔌 Community Plugin Ecosystem — hundreds of third-party plugins tagged dsh-plugin on GitHub, spanning vision/multimodal extensions, sandboxes, MCP integrations, terminal UIs, and workflow tools.

4. Key Highlights

• Everything is a plugin — models, tools, skills, sessions, sandboxes, storage, loops, scheduling, and the UI are all implemented and swapped the same way, so there's one mental model for extending the system instead of several.
• Full traceability by design — session state is append-only, so any agent run can be inspected, resumed, forked, or replayed, which is essential for debugging non-deterministic agent behavior.
• Built on Cordis — a dedicated plugin runtime (documented in the paper A Programming Paradigm for Spatiotemporal Composability) rather than an ad hoc extension mechanism, giving the plugin system formal underpinnings.
• Host/Client aggregate architecture — the codebase cleanly separates Host packages (tsconfig.host.json) from Client packages (tsconfig.client.json) so both sides can safely extend the same Cordis Context interface with different services without type collisions.
• Multiple runtime presets out of the box — Standard, Code, Minimal, and Creator modes cover coding agents, TypeScript-orchestrated tool use, lightweight benchmarking, and custom preset authoring without extra setup.
• Zero-install quick start — npx @deepseek-ai/dsh web launches a working Web UI immediately, lowering the barrier to first use.

5. Use Cases by Role

• General developers: use the Standard runtime mode to spin up a coding agent with file editing, shell, and web search tools, and drive it through the Web UI for day-to-day development tasks.
• DevOps/SRE: leverage sandboxed execution and append-only session logs to run and audit automated operational agents, replaying past runs when diagnosing incidents.
• Data/research scientists: use Minimal mode as a controlled benchmarking environment to evaluate agent or model behavior under a reduced, reproducible toolset, and use session replay for analysis.
• Project managers / platform teams: adopt Creator mode to assemble and inspect custom agent presets tailored to a team's workflow, then distribute them as reusable plugins.

6. Getting Started

Find what you need — browse the official docs, the development guide, and community plugins tagged dsh-plugin on GitHub.

Install / integrate — the fastest path is npm, no clone required:

npx @deepseek-ai/dsh web

This starts the Web UI at http://127.0.0.1:3080. To build from source instead:

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

Contribute — read CONTRIBUTING.md and AGENTS.md in the repository, then run the relevant checks before submitting a change:

pnpm run typecheck
pnpm run lint
pnpm run check:all

7. Project Structure

deepseek-harness/
├── tsconfig.json          # solution root / tsserver discovery entry
├── tsconfig.base.json      # shared compiler options and path resolution
├── tsconfig.host.json      # Host aggregate: host packages, examples, tests, scripts, website
├── tsconfig.client.json    # Client aggregate: packages/client/* and browser apps
├── api/remotes/            # the only package split across Host and Client configs
├── docs/                   # development, architecture, and user guides
└── AGENTS.md                # conventions for agent-facing contributions

Packages register in exactly one aggregate — Host or Client — never both, which keeps the two sides' declaration-merged Cordis Context interfaces from colliding when both are compiled together.

8. Related Ecosystem

• Cordis — the underlying plugin runtime framework that DeepSeek Harness is built on, providing the "spatiotemporal composability" model for plugins.
• Model Context Protocol (MCP) — supported as an integration layer, allowing external tools (e.g., statistical or data analysis tools) to be exposed to agents through MCP servers.
• Community plugins — a growing ecosystem of 800+ repositories under the dsh-plugin GitHub topic, including vision/multimodal plugins, sandbox providers, terminal UIs, and Web UI skins.

9. License

• ✅ Use, modify, and distribute the code, including for commercial purposes, under the permissive MIT License.
• ✅ Integrate DeepSeek Harness into proprietary products, provided the license and copyright notice are retained.
• ❌ No warranty is provided — the software is offered "as is."
• ℹ️ Third-party dependencies carry their own licenses, documented separately in THIRD_PARTY_NOTICES.md.

10. FAQ

Q: Is DeepSeek Harness ready for production use?
A: It is currently in developer preview and iterating rapidly, with the maintainers explicitly warning of compatibility-breaking changes — evaluate carefully before depending on it in production.

Q: What is Cordis and why does the project depend on it?
A: Cordis is the plugin runtime framework underlying DeepSeek Harness's "everything is a plugin" architecture; see the paper A Programming Paradigm for Spatiotemporal Composability referenced in the repo for the design rationale.

Q: How do I try it without building from source?
A: Run npx @deepseek-ai/dsh web to launch the Web UI locally at http://127.0.0.1:3080.

Q: Can I write my own plugins?
A: Yes — plugins are declared on Host services using @Remote or @RemoteScope decorators, consumed on the Client side via ctx.remote; see the development guide for details.

Q: Where can I find community-built plugins?
A: Browse the dsh-plugin topic on GitHub, which lists third-party plugins for vision, sandboxes, terminal UIs, and more.

11. Quick Links

• Repository: https://github.com/deepseek-ai/deepseek-harness
• Development guide: https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/development.md
• Contributing guide: https://github.com/deepseek-ai/deepseek-harness/blob/master/CONTRIBUTING.md
• Community discussions: GitHub Discussions on the repository, plus a dedicated Discord community

12. Summary

DeepSeek Harness offers a uniform, fully traceable plugin architecture for building AI agents, letting teams swap models, tools, sandboxes, and storage without re-architecting their stack. It is best suited for developers and teams who need auditable, replayable agent runs and are comfortable working with a fast-moving developer preview rather than a stable, long-term-support release.