DeepSeek Harness development setup and contributor workflow

DeepSeek Harness development starts with a supported Node.js release, Corepack, pnpm, and Git. The upstream project currently targets Node.js 22.19 or newer and also supports the 24.x line; its continuous integration matrix covers Node 22.19, 24, and 26. This guide turns the official contributor notes into a practical path for installing dependencies, validating the workspace, understanding the build order, and preparing a change for review.

This is an independent, search-oriented explanation of the upstream development guide, not a replacement for it. Check the official Chinese development document before contributing because requirements can change during the developer preview.

DeepSeek Harness development requirements

Prepare the following tools before cloning the repository:

• Node.js 22.19 or newer; Node.js 24 is a sensible default for local development;
• Corepack, used to activate the package manager version pinned by the project;
• Git 2.26 or newer; and
• a model provider API key only if you plan to run an agent demo.

Confirm the local versions:

node --version
corepack --version
git --version

The repository pins pnpm@11.7.0. Let Corepack honor that declaration instead of installing an unrelated global pnpm version. This reduces lockfile churn and makes local behavior closer to CI.

Clone and install the source tree

Clone the official repository, enter it, and install the workspace dependencies:

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
corepack enable
pnpm install

The postinstall step configures Lefthook and the repository’s translation merge driver. These are part of the contributor workflow, so a successful package download is not the only installation signal. Run the TypeScript check immediately afterward:

pnpm run typecheck

If this command fails in a fresh checkout, first compare your Node and pnpm versions with the upstream requirements. Avoid editing generated files or the lockfile merely to hide a tooling mismatch.

Understand the build order

DeepSeek Harness contains Host, Client, and Web layers. Their builds are ordered because later layers consume output or generated contracts from earlier ones. The official sequence is conceptually:

1. compile Host TypeScript;
2. bundle the Host packages;
3. compile Client TypeScript;
4. bundle the Client packages; and
5. build the Web application.

This ordering matters most when you change an API surface shared between Host and Client. A Client error may originate from a Host descriptor or generated type, not from the UI file that reports it. Read the API Gateway guide before editing remote methods, and use the architecture guide to identify the correct package boundary.

Configure model credentials safely

Agent demos can read a provider key from the environment:

export DEEPSEEK_API_KEY="your-key"

An alternative endpoint can be supplied through DEEPSEEK_BASE_URL when your environment requires it. Keep credentials out of source files, examples, terminal transcripts intended for publication, and commits. A local shell environment or an ignored secrets mechanism is safer than a repository-level file that may be staged accidentally.

Run checks before opening a pull request

The project uses Git hooks for pre-commit, pre-merge, and pre-push checks. You can run the broad validation path yourself before pushing:

pnpm run check:all

During development, run the narrowest relevant check after each change, then run the full suite before review. If a hook fails, treat it as evidence that the proposed change is incomplete rather than bypassing it by default.

The upstream codebase also distinguishes comment markers: FIXME records a known defect, TODO records planned follow-up work, and XXX calls attention to surprising or risky behavior. Preserve those meanings so searches remain useful to maintainers.

Run a focused development demo

After checks pass and credentials are available, choose a demo that exercises the layer you changed. The official guide includes these examples:

pnpm dsh --profile headless "summarize this workspace"
pnpm run demo:cordis
pnpm run demo:acp

Use a disposable workspace for agent runs. A successful TypeScript build does not prove that tool permissions, event order, or streamed responses behave correctly at runtime. Keep the test task small, inspect tool calls, and review the resulting diff.

A practical contributor checklist

Before submitting a DeepSeek Harness change, verify that:

• the pinned package manager is active and the lockfile only changed intentionally;
• pnpm run typecheck and the relevant package checks pass;
• Host changes were validated before Client and Web changes;
• no API key, local path, or private transcript appears in the diff;
• the change belongs in the selected plugin, capability seam, or application layer; and
• a focused runtime demo covers the behavior you changed.

For the design vocabulary behind plugins and capability seams, continue with DeepSeek Harness architecture. For the execution path behind a demo task, see the Agent lifecycle guide.

Official source

This tutorial was independently written from the official DeepSeek Harness development guide, reviewed on 2026-08-20. The upstream file remains authoritative for supported versions, commands, hooks, and contributor policy.