Home›Advanced Guides

Run DeepSeek Harness from Source

Use this path when you want to inspect, modify or contribute to DSH itself. If you only want to use DSH, the npm quick-start is simpler and has fewer moving parts.

On this page

Most users should stay on the npm quick-start

If your goal is simply to run DeepSeek Harness, use npx @deepseek-ai/dsh web. Source execution is for development, debugging upstream behavior, testing a patch or contributing code.

Use a source checkout when you need to change DSH itself

Inspect implementation

You want to trace a CLI, provider, plugin or Web UI behavior into the current source.

Test a patch

You need to modify DSH and run that exact local checkout before opening a pull request.

Contribute upstream

You need the repository's build, type-check, test and documentation workflow rather than the packaged npm runtime.

Requirements from the current upstream repository

Node.js^22.19.0 || >=24.0.0

pnpmUpstream currently declares pnpm@11.7.0

GitNeeded to clone and update the repository

Build timeThe first complete build produces host and frontend artifacts

Check your local tools before debugging DSH:

node --version
pnpm --version
git --version

STEP 1

Clone the official repository

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

If you plan to contribute, work in your own branch and keep unrelated local changes out of the checkout you use for debugging.

STEP 2

Install workspace dependencies

pnpm install

The repository is a pnpm workspace. Do not substitute a random npm install workflow and then diagnose the resulting dependency tree as a DSH bug.

If the lockfile or workspace packages changed

Run pnpm install again after pulling upstream changes before assuming an import failure comes from your code.

STEP 3

Build the required artifacts

pnpm run build

The current CLI source runner can execute apps/cli/src/bin.ts directly, but it still depends on built Typert host artifacts plus frontend/client bundles. A fresh checkout therefore needs the build before the Web profile can start correctly.

Existing build output can be stale

The launcher does not check whether already-built frontend bundles match your latest source edits. If the browser behaves like old code after a pull or local change, rebuild before chasing a runtime bug.

STEP 4

Run the Web profile from the checkout

pnpm dsh web

The root dsh script launches the source CLI with node --import tsx/esm and forwards the remaining arguments. The Web UI still uses the normal local port behavior and can be moved with --port when needed.

Inspect before booting

Use the CLI's config-dump modes when debugging composition. A dump shows the layered configuration without activating the app rows.

pnpm dsh --profile web --dump-default-config
pnpm dsh --profile web --dump-config

Update an existing checkout without mixing old artifacts with new source

01
Update the branch
Fetch/pull the upstream changes you actually intend to test.
02
Refresh dependencies
Run pnpm install when the lockfile, workspace packages or package metadata changed.
03
Rebuild
Run pnpm run build after a fresh checkout and whenever host/frontend artifacts need updating.
04
Start from the same checkout
Run pnpm dsh web and record the exact commit when reporting a regression.

Common source-execution failures

Module-resolution error immediately after a fresh clone

Run the full build. The source runner still needs generated/built host artifacts.

Startup explicitly tells you frontend/client bundles are missing

Run pnpm run build from the repository root and retry.

The Web UI looks like an older version of your code

Rebuild. Existing stale browser bundles can continue to run because the launcher does not perform a freshness check.

pnpm install behaves differently from upstream documentation

Check the repository's current packageManager field and your local pnpm version before changing workspace files.

Port 3080 fails

Treat EADDRINUSE and Windows reserved-port EACCES as normal startup/port problems, not source-build failures. Try another port after diagnosing the error.

API calls fail only on a restricted proxy network

Use a supporting Node release and the proxy guide; the source process inherits the environment from the shell that launches it.

NEXTChanging the plugin composition?

Open plugin installation guide →

Sources

DeepSeek Harness official README · current Node/pnpm requirements · CLI source-execution behavior.