DeepSeek Harness (dsh):
The Complete Guide

What is DeepSeek Harness?

DeepSeek Harness (dsh) is an open-source agent harness: the runtime that sits between a language model and your machine, deciding how the model calls tools, edits files, runs shell commands, and keeps a long session coherent. DeepSeek released it on August 13, 2026 under the MIT license, and it crossed 66,000 GitHub stars within a day (66,343 on Aug 14, via the GitHub API).

The mental model that matters: dsh is not a finished assistant like Claude Code or Codex. It is the chassis you assemble one from. Out of the box it ships a full coding agent — file editing, shell, search, plans, skills, subagents, approval policies, a local Web UI — but every one of those parts is designed to be replaced.

That design has a name in the architecture docs: “everything is a plugin.” The model adapter is a plugin. The tool registry is a plugin. The session log is a plugin. Even the agent loop itself is a plugin. In the docs’ own words, “there is no privileged core to patch.”

The project is led by Cui Tianyi, a former Jane Street engineer who joined DeepSeek in March 2026 — meaning the team went from formation to public preview in roughly five months. Note the contribution model is unusual: the repo does not accept external pull requests and has GitHub Issues disabled. Feedback goes through Discussions and Discord; the intended way to extend dsh is to publish your own plugin (tag your repo with the dsh-plugin GitHub topic).

Quick start

There are three ways to run dsh: the local Web UI, headless mode for one-shot jobs, and a Python SDK. The first two need Node.js 22.19+ (or any 24.x).

copy# Web UI — served at http://127.0.0.1:3080
$ npx @deepseek-ai/dsh web

# one-shot headless run (prints the final answer, then exits)
$ dsh --profile headless "fix the failing test"

# Python SDK — bundled runtime, no system Node.js needed
$ pip install deepseek-harness-sdk

To connect a model, open Settings → Models in the Web UI and paste a DeepSeek API key — no restart needed. Keys are stored write-only in $DSH_HOME/.credentials.yaml; the UI only ever shows a masked descriptor (providers guide). Or use environment variables: DEEPSEEK_API_KEY, DSH_MODEL, and DEEPSEEK_BASE_URL.

Platform notes worth knowing before you start:

• The Python SDK supports Linux x64/arm64 and macOS 14+ (Apple Silicon) only — the persistent PTY requires POSIX, so there is no Windows agent in the SDK.
• There is no desktop app and no hosted version — the Web UI runs on your machine. If you expected a Claude Code-style CLI, this is the biggest surprise at first contact (Discussion #601).
• Source builds use pnpm: git clone → pnpm install → pnpm run build → pnpm dsh web.

Troubleshooting

Every fix below traces to a real, linked GitHub Discussion — this table is the part of the guide we update most aggressively as the rc versions churn.

Architecture, in plain English

Under the hood, a running dsh instance is a tree of plugins composed at boot, powered by Cordis — a framework whose design is laid out in an 88-page paper, A Programming Paradigm for Spatiotemporal Composability (DeepSeek + Peking University). The paper’s two guarantees, translated from academese:

• Unload cleanly (temporal): every side effect a plugin creates is tracked and reversible, so removing a plugin fully undoes it — no restart, no leftover state.
• Depend declaratively (spatial): plugins declare which services they need, and the runtime resolves and hot-swaps them reactively.

In practice you pick a profile (named plugin composition — web and headless ship built-in) and override anything with patch files. dsh --profile web --dump-config prints the exact tree that booted, and any line of it can be replaced.

The four presets

The official page ships four run modes: Standard (the full coding agent), Minimal (just bash + a file editor — closest to a raw model), Code mode, and a fourth the official page calls “Creator” — though in the rc.5 source the fourth preset directory is actually cordis, which lets the model edit the live plugin composition (details in our architecture deep dive). Code mode is the interesting one: instead of classic tool-calling, dsh generates a TypeScript SDK and lets the model write a program that calls the tools — collapsing what would be five round-trips into one (The New Stack).

Event-sourced sessions

Everything the model sees is reconstructed from an append-only event log — the docs state the invariant as “model-visible means logged.” Resume, fork, replay, transcripts, and the Web UI’s trajectory view are all projections of that one stream. This is the feature HN engineers praised most in the launch thread.

Sandboxing

Tool execution can be confined with OS-level sandboxes: Landlock on Linux (via a custom Node addon), Seatbelt on macOS, and a restricted-token ACL approach on Windows, plus bwrap support. Whether the defaults are strict enough is a separate question — see section 9.

Using other models (Claude, GPT, local)

The single most-asked question, and the answer is yes — model adapters are plugins like everything else. Three routes, per the providers guide:

• Catalog providers: in the Web UI, “Add provider” lists Anthropic, OpenAI, and others; Bedrock / Vertex / Azure use their native auth flows.
• Custom OpenAI-compatible endpoints: point a custom provider at any gateway or self-hosted server — provider ID, base URL, protocol, credentials, and it can auto-populate models from GET /models.
• Local models: set DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1 (vLLM, Ollama’s OpenAI endpoint, LM Studio, etc.) and dsh treats it like any other backend.

Default DeepSeek models are deepseek-v4-flash (284B params, ~13B active) and deepseek-v4-pro (1.6T params, ~49B active), both with a 1M-token context window (VentureBeat) and a reasoningEffort dial (off / high / max). One real limitation: DeepSeek’s own chat route is text-only — no image input — so vision-dependent workflows need a third-party multimodal model plugged in.

For Claude Code users

dsh was clearly built by people who use Claude Code — the repo itself contains a CLAUDE.md and .claude/ directory. Interop is real, not aspirational (The New Stack, repo):

• dsh reads your existing CLAUDE.md and AGENTS.md project instructions.
• A hooks package speaks the Claude Code / Codex hook wire-protocol, so existing hook integrations can bridge over.
• Claude Code and Codex ship as subagent providers (disabled by default) — dsh can find the binaries on your PATH and delegate work to them, meaning you can drive Claude Code from inside dsh.
• What’s missing: a settings importer (requested in #838), slash-command parity, hosted background agents, and native GitHub PR workflows.

The honest framing: if Claude Code is working for you, dsh today is a lab, not a replacement— the place to experiment with owning your harness (swap models mid-workflow, inspect every event, write custom tools) while keeping your daily driver.

Pricing & the Aug 16 increase

dsh itself is free and works with any provider. The story is the DeepSeek API behind it: alongside the Harness launch, DeepSeek announced peak/off-peak pricing effective Aug 16, 2026, 16:00 UTC — a substantial increase (TNW):

Reference points from before the increase: early users reported a 27-minute 3D project for ~$0.12 in API spend, and one HN user ran a full security audit for ~$0.15 (HN thread). Scale those by the multipliers above for a post-Aug-16 estimate — and remember dsh reports cache hits (prompt_cache_hit_tokens) in its usage view, so you can measure your own ratio before the new prices land. Third-party hosts on OpenRouter may undercut the official API; official cache pricing has historically been the counterargument.

dsh vs Claude Code vs Codex

Feature axes adapted from VentureBeat’s launch comparison plus the official docs; we’ll replace vendor claims with our own benchmarked numbers as we run them.

Security & maturity caveats

Read this section before running dsh anywhere near production credentials.

• The local RPC surface has no auth. A public disclosure (Discussion #853) shows dsh web exposes 60+ RPC methods on 127.0.0.1:3080 guarded only by a Host-header check — which the docs themselves say is “not an auth layer.” Any local process could open sessions or flip permission modes. No maintainer response and no SECURITY.md as of Aug 14.
• Plugins are unsigned code with no permission manifest. Installing one means letting it run arbitrary code in the harness process. Vet plugins the way you’d vet a dependency, not an app-store install.
• Full-access mode does what it says. One early user reported an agent in danger-full-access mode deleting their home directory while testing a plugin (#461). Keep approvals on; use the sandbox.
• Preview software, moving fast: breaking changes are promised, external PRs aren’t accepted, and several crash/runaway bugs (subagent spawn loops, unbounded memory) are still open in Discussions.

FAQ

Sources & changelog

Everything above is sourced from the official repo/docs, linked GitHub Discussions, or named press coverage — numbers carry the date we captured them. If you spot something stale, the project moves fast and we want to know.

Changelog: 2026-08-14 — first published, verified against dsh 0.1.0-rc.6.