DeepSeek Harness
DeepSeek Harness (dsh): Official DeepSeek Agent Setup Guide
DeepSeek's own open-source agent harness. One command starts a local web UI, the model is swappable, every capability is a plugin, and the whole thing is MIT licensed.
Every other guide on this site shows you how to point a third-party agent at DeepSeek. DeepSeek Harness is a different category: it is DeepSeek's own agent runtime, open sourced on 13 August 2026 alongside V4-Pro, and it passed 100,000 GitHub stars within two days.
This guide is maintained by deepseekagent.io, verified against 0.1.0-rc.6, with figures current as of 15 August 2026.
Agent = Model + Harness
How DeepSeek describes the split:
The model is the soul of an agent. A harness lets it understand its environment, use tools, and keep working in real-world settings.
A model only emits text. On its own it cannot open a file, run a command, or remember the previous turn. The harness is the layer around it: workspace, tools, permissions, session memory, and the loop that keeps work moving.
Claude Code and Codex are harnesses too, but they are finished products. In dsh the model adapter, the tool registry, the session log, and the agent loop itself are all replaceable plugins. The docs call it "no privileged core to patch."
Who it is for
| Your situation | Recommendation |
|---|---|
| You want DeepSeek's first-party coding agent | Use dsh, it is DeepSeek-first by design |
| You want to own your agent runtime instead of using a closed product | Start here, that is its core design goal |
| You evaluate models and need a clean, stable tool surface | Use Minimal mode, which exposes only two tools |
| You are building an internal agent platform for a team | Workable, compose the shape you need from plugins and profiles |
| You only want Claude Code running on a cheaper model | dsh is not required, see CC Switch or the Claude Code guide |
| You need production API stability today | Hold off, this is a developer preview and DeepSeek states compatibility will break |
Prerequisites
1. Get the Node.js version right
dsh requires ^22.19 || >=24. Odd-numbered releases fall outside that range, so Node 23 fails to start. Check your current version:
node -v
If you need to upgrade (macOS, Homebrew):
brew install node@24
brew link --overwrite --force node@24
2. Get a DeepSeek API key
- Open the DeepSeek platform
- Sign in, create an API key, and copy it (shown only once)
- Make sure the account has balance or available credit
Step 1: Launch with one command
Run this from the project directory you want the agent to work in:
cd your-project
npx @deepseek-ai/dsh web
The terminal prints its address; open it in a browser:
dsh web: http://127.0.0.1:3080
The first run auto-initializes configuration under ~/.dsh, which holds your profiles, credentials, and settings.
It serves the local machine only. Passing --host 0.0.0.0 makes the CLI exit with a usage error. DeepSeek did not design it as a hosted service, so it cannot be shared with teammates that way.
Step 2: Configure a model
Open Settings → Models, enter your API key in the DeepSeek card, and save. The change applies to the next request without restarting the server.
Keys are write-only: after saving, the page receives a redacted descriptor, the real secret lands in ~/.dsh/.credentials.yaml, and settings retain only a reference to it.
Models available by default:
| Model | Notes |
|---|---|
deepseek-v4-pro | Flagship, tuned for agentic work |
deepseek-v4-flash | Faster and cheaper, fine for daily use |
Both default to a 1,000,000-token context, a 256k output cap per request, and high reasoning effort.
dsh is not tied to DeepSeek. Add provider offers a built-in catalog including Anthropic, OpenAI, Bedrock, Azure, and Vertex. Add a custom provider covers your own gateway or self-hosted endpoint: supply a lowercase provider ID, base URL, protocol, credential, and at least one model. Fetch available models queries the endpoint for its model list.
A model you type in by hand is treated as text-only, and attaching an image is refused before sending. A vision model needs one extra line in
~/.dsh/settings.yaml:input: [text, image].
Step 3: Pick a workspace and run a task
Click Choose workspace, add the project directory you launched dsh from, and select it. The composer stays unavailable until a workspace is selected.
Then start a session and try:
Summarize this repository and identify its main packages.
The agent can read and edit files, run commands, delegate to subagents, and maintain a plan. Operations that require approval under the active permission policy prompt you first.
Four runtime modes
Each mode boots a different plugin tree, which changes the tools available:
| Mode | Capabilities | When to use it |
|---|---|---|
| Standard | Full coding agent: file editing, shell, file and web search, skills, planning, goals, subagents, workflows | Everyday coding, the default |
| Code mode | Everything in Standard, but tools are exposed through the Code Mode SDK so the model writes one TypeScript program to orchestrate multiple steps | Multi-step work where round trips cost you |
| Minimal | Two tools only: persistent bash and str_replace_editor | Model benchmarking in a minimal environment |
| Creator | Standard plus runtime inspection, in-memory plugin experiments, and preset-authoring guidance | Building your own agent presets |
As an example of what Code mode does: a sequence that would take five tool round trips becomes one program that runs in a single call.
How it compares to Claude Code and Codex
| Claude Code / Codex | DeepSeek Harness | |
|---|---|---|
| Shape | Finished agent | Framework for building agents, with a usable UI included |
| Interface | Terminal-first | Local web UI first, plus a headless mode |
| Extension | hooks / MCP | Cordis plugins, down to the agent loop |
| Models | Mostly first-party | Multi-vendor, DeepSeek-first |
| Source | Closed or partly open | Fully open, MIT |
| Maturity | Production-ready | Developer preview, breaking changes expected |
Compatibility with competing tools goes fairly deep: it ships hook bridges for Claude Code and Codex that run your existing hooks.json, and it can delegate work to Claude Code or Codex binaries already installed on your machine (both off by default). It also reads AGENTS.md and CLAUDE.md, and supports MCP as a client.
What "everything is a plugin" means in practice
Two design decisions define how far you can take it.
1. Every capability is swappable in configuration
A running dsh is a plugin tree composed at boot from ordered layers: bundle patches, then the profile patch, then the machine-level patch, then command-line overlays. To see what your machine actually boots:
npx @deepseek-ai/dsh web --dump-config
Any row it prints can be replaced by a patch of your own.
2. Every run is traceable
Everything the model sees is written to an append-only session log: system prompts, reasoning, tool calls and results, subagent scheduling, and every context injection. The Trajectory view inspects those records by source. Resume, fork, search, and replay all operate on that same event stream.
DeepSeek enforces this as a hard rule: model-visible means logged. Anything reaching a model request must be reconstructable from the log.
Headless mode and SDKs
When you do not want a UI, run one task, print the result, and exit:
npx @deepseek-ai/dsh --profile headless "fix the failing tests"
There is also a Python SDK (pip install deepseek-harness-sdk, which bundles its own Node runtime so the target machine needs none), a JSON-RPC SDK, and an ACP server for embedding it in your own programs.
FAQ
Startup fails complaining about the Node version
dsh requires ^22.19 || >=24. Odd-numbered releases like Node 23 are outside the supported range and are end-of-life anyway. Install Node 24.
Port 3080 is already in use
Arguments after web go to the web app, so use npx @deepseek-ai/dsh web --port 8080.
Can teammates on my LAN reach it?
No. The CLI rejects --host 0.0.0.0 with a usage error; it is designed to serve the local machine only.
The composer is greyed out and I cannot type
No workspace is selected. Use Choose workspace to add and select a directory. If the model picker shows Select model, your saved default points at a deleted provider, so pick another.
I get MISSING_CREDENTIAL or UNKNOWN_MODEL
The first means no key is stored (add it on the Models page, or set the referenced environment variable). The second means the selected model is not configured, so add its ID to your custom provider.
Where do configuration and sessions live?
All under ~/.dsh: profiles/ for profiles, .credentials.yaml for secrets, settings.yaml for settings, and cordis.patch.yml for your own patch layer.
Does it work on Windows?
The web UI runs, but persistent terminals (PTY) need a POSIX substrate, and the officially bundled runtimes ship for Linux and macOS only. Some capabilities are limited on Windows.
Can I use it on real projects today?
Be cautious. It is a developer preview, the README warns about compatibility-breaking changes, and the session format carries no compatibility promise, so older session logs may become unreadable after an upgrade. Suitable for evaluation and internal experiments, not as your only production tool.
Can I send a pull request?
External PRs are not accepted for now. DeepSeek points contributors to GitHub Discussions, or to writing plugins and tagging the repository with dsh-plugin for discoverability. They also state that packages in the official repo are not inherently more important than community ones.
Related links
- Source: github.com/deepseek-ai/deepseek-harness
- Official page: deepseek.com/harness
- Cordis, the plugin framework: github.com/cordiverse/cordis
- DeepSeek API docs: platform.deepseek.com/api-docs
- All guides on this site: tool list