DeepSeek Harness: install, profiles, and first run

Published 16 August 2026

This is the practical half of our DeepSeek Harness coverage: how to get dsh running, what the composition model expects of you, and which demos are worth ten minutes.

Fastest path

npx @deepseek-ai/dsh web

That starts the web UI at http://127.0.0.1:3080. From there, two things must happen before the session composer becomes usable:

1. Settings → Models, and enter your DeepSeek API key. The route enables immediately; no restart.
2. Choose workspace, to add and activate the project directory. Until a workspace is active, the composer stays unavailable.

Once running, the agent can read and edit files, run commands, delegate tasks to subagents, and plan. It prompts for confirmation according to the active permission policy.

From source

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

Floors to be aware of: Node 22.19 or newer (CI covers 22.19, 24, and 26), Git 2.26 or newer, and Corepack with pnpm pinned to pnpm@11.7.0. A DEEPSEEK_API_KEY is optional, read from the environment or a gitignored repo-root .env; alongside it, DEEPSEEK_BASE_URL can point at a different endpoint. The real-API end-to-end suites self-skip when the key is absent, so a keyless checkout still builds and tests cleanly.

Profiles and bundles: the composition model

Because every part of the harness is a plugin, something has to say which plugins are loaded. That is a profile: a named composition storing an ordered list of bundles plus user patches. A bundle distributes Cordis config rows and code.

Three template profiles ship:

The four-layer override order

Configuration resolves in a fixed order, later layers winning:

1. Profile bundles
2. Profile patches
3. Home-level patches
4. CLI overlays

The subsystems you will meet

Six registry keys carry most of the behaviour: ctx.sessions (the append-only event log), ctx.systemPrompt, ctx.tools (a scoped registry with guarded execution), ctx.agents, ctx.agentLoop, and ctx.llm. If you are extending the harness, these are the names to search for first.

Three demos worth running

• Headless one-shot: pnpm dsh --profile headless "summarize this workspace". The shape you would wire into CI or a cron job.
• Cordis introspection: pnpm run demo:cordis. Self-referential — it inspects and modifies its own live plugin runtime. This is the clearest demonstration that the plugin claim is structural rather than marketing.
• ACP automation: pnpm run demo:acp. An automation server speaking JSON-RPC over stdio, which is the integration surface for driving the harness from another system.

If you plan to contribute

A few conventions save time. TODO markers are graded by urgency: FIXME is a release blocker, TODO is soon, XXX is someday. Lefthook runs pre-commit (staged pairing records, .oxlintrc.staged.json, third-party notices regeneration, whitespace, vendor manifest guard), pre-merge-commit, and pre-push (pnpm run typecheck). The hooks deliberately skip tests and builds — CI owns exhaustive coverage, and pnpm run check:all is the opt-in comprehensive local gate.

Two quirks explain otherwise-confusing structure. The build splits into Host and Client tsconfig aggregates because both sides declaration-merge the Cordis Context interface under the same keys, and one TypeScript program seeing both merges reports a collision. And documentation code samples are kept honest by ts type-equiv fences plus pnpm run verify-type-equiv, so pasted declarations cannot silently drift from source.

Set expectations

The README says it plainly: this is a developer preview, and there will be compatibility-breaking changes. Plugin discovery runs through the dsh-plugin GitHub topic, and the project is MIT-licensed with third-party dependencies listed in THIRD_PARTY_NOTICES.md. Evaluate it now; standardise on it later.

Related

• DeepSeek Harness: what "everything is a plugin" buys you — the architecture.
• Where to put spend guardrails in DeepSeek Harness — the control points.
• The DeepSeek Harness session log as a cost record — the accounting.
• The true cost of coding agents — budgeting for the result.

Want this applied to your own LLM spend? FinOps LLM runs a free audit of your AI costs and shows where the savings are. Book free audit →

Back to research