Source Install \u00b7 git clone

Git Clone DeepSeek Harness — git clone https://github.com/deepseek-ai/deepseek-harness and Build from Source

Start with git clone https://github.com/deepseek-ai/deepseek-harness.git, then install with pnpm, build, and run the local Web UI. This guide covers the full chain from prerequisites to verification, plus 7 common build errors and a one-click GUI alternative.

If you searched for git clone https github com deepseek ai deepseek harness without slashes, you are in the right place \u2014 the canonical command is git clone https://github.com/deepseek-ai/deepseek-harness.git followed by cd deepseek-harness.

Before you start

You will need a terminal, internet access, and three pinned tools. Versions below are taken from downloads/manifest.json:build.requires and are the exact versions the project expects:

• Node.js ^22.19.0 || >=24 \u2014 check with node -v. Node 22.19+ or 24+ is required; older Node 18/20 will fail the build.
• pnpm 11.7.0 \u2014 check with pnpm -v. Install via npm i -g pnpm@11.7.0 or corepack enable then corepack prepare pnpm@11.7.0 --activate.
• git >=2.40 \u2014 check with git --version.
• Terminal \u2014 macOS Terminal/iTerm, Windows PowerShell, or any Linux shell. Disk: ~1 GB for the clone plus dependencies.

Optional but recommended: a code editor, and a browser that can open http://127.0.0.1:3080. No cloud account is required until you add a model key.

When to use git clone vs npx

If you just want to run the harness once, npx @deepseek-ai/dsh web (covered in Install Guide) is the fastest path \u2014 no clone, no build. Choose git clone when you need to:

• Edit source, prototype a preset, or patch a plugin.
• Pin a specific tag or commit, e.g. dsh-v0.1.2-alpha.1.
• Build offline or work from a fork.
• Customize build steps before running pnpm dsh web.

Step 1 \u2014 Clone the repository

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

Choosing a branch or tag (optional): By default you get master. To pin the tested tag from the manifest, run git checkout dsh-v0.1.2-alpha.1 or git clone --branch dsh-v0.1.2-alpha.1 https://github.com/deepseek-ai/deepseek-harness.git. Verify the commit with git rev-parse HEAD \u2014 the pinned commit is cd5ef8148158c3a752a658978873241fdf8e2bbc.

For users who copy queries without slashes, searching git clone https github com deepseek ai deepseek harness or git clone https://github.com/deepseek-ai/deepseek-harness lands on the same step \u2014 the repository is always https://github.com/deepseek-ai/deepseek-harness.

Step 2 \u2014 Install dependencies

pnpm install

If you see pnpm: command not found: install pnpm first. The project pins pnpm@11.7.0:

npm i -g pnpm@11.7.0
pnpm -v

Alternative via Corepack (ships with Node 22+):

corepack enable
corepack prepare pnpm@11.7.0 --activate
pnpm -v

On Windows, restart PowerShell after installation so pnpm is on your PATH. Verify again with pnpm -v and ensure it prints 11.7.0.

Step 3 \u2014 Build from source

pnpm run build

Directory and environment: stay in deepseek-harness for all steps. The harness will create a home folder at $DSH_HOME (defaults to ~/.dsh on macOS/Linux, %USERPROFILE%\.dsh on Windows). You do not need to edit it by hand before the first run, but API keys will later be stored there as $DSH_HOME/.credentials.yaml.

If pnpm run build exits non-zero, see Troubleshooting #2 and #3 below (Node version and build failed). For increasing Node heap on low-memory machines, you can run NODE_OPTIONS=--max-old-space-size=4096 pnpm run build as a workaround, though most modern machines do not need it.

Step 4 \u2014 Run the Web UI

pnpm dsh web

The source-based entry point pnpm dsh web is equivalent to npx @deepseek-ai/dsh web once the Web UI is up \u2014 same UI, same session log, same trajectory ruler. The difference is that the pnpm path runs your local build, so source edits take effect after you rebuild.

Verification: In the browser you should see the harness shell: a prompt to configure a model and choose a workspace. If nothing loads, try curl -I http://127.0.0.1:3080 in a second terminal; you should get HTTP/1.1 200. Keep the server running for the next section.

Configure your API key and workspace

With the Web UI open at http://127.0.0.1:3080, complete setup inside the UI:

1. Add a provider. Open Settings \u2192 Models. For DeepSeek, enter your API key in the DeepSeek card and save. For Anthropic or OpenAI, choose Add provider and select the catalog entry. For a company gateway or self-hosted server, choose Add a custom provider and supply provider ID, base URL, API protocol, credential, and at least one model (must be OpenAI-compatible).
2. Security note. Keys are write-only \u2014 the UI shows a redacted descriptor after saving and never displays the raw key again. They are stored locally at $DSH_HOME/.credentials.yaml (read-only after write, 0600 permissions on Unix). The key stays on your machine; the engine never uploads it.
3. Choose a workspace. Click Choose workspace, add the project directory where you started pnpm dsh web, and select it. The session composer stays disabled until a workspace is chosen, because the agent needs a filesystem scope.

Run your first task and verify

Start a session and send a low-risk prompt:

Summarize this repository and identify its main packages.

The agent can read workspace files, run commands, delegate work, and maintain a plan, asking for approval when the permission policy flags an operation. A good run shows:

• The session log appends turns, tool calls, and results with source attribution.
• The trajectory view records every step for inspection or replay.
• Permission gates appear as \u25b3 prompts when a tool call needs your click.

Stop the harness with Ctrl+C in the terminal when finished. To restart later, run pnpm dsh web again from the same checkout.

Troubleshooting \u2014 7 common errors and fixes

Each entry shows the symptom, the cause, and the copy-paste fix plus how to confirm it.

1. Repository or branch not found

Symptom: fatal: repository \u0027https://github.com/deepseek-ai/deepseek-harness\u0027 not found or warning: Could not find remote branch feature-x.

Cause: Typo in the remote URL, missing .git suffix on some git versions, or a non-existent branch/tag.

Fix: Copy the canonical command exactly and check the remote:

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
git remote -v
git ls-remote --heads origin | head

Verify: git remote -v shows https://github.com/deepseek-ai/deepseek-harness.git and git status prints On branch master or the tag you checked out.

2. Node version mismatch (build fails)

Symptom: error: engine Unsupported engine or TypeError: Unknown file extension during pnpm run build.

Cause: The project requires Node ^22.19.0 || >=24 and pnpm@11.7.0 per downloads/manifest.json. Older Node (18/20) cannot build.

Fix:

node -v
# expect v22.19.x or v24.x; if older, install from https://nodejs.org/
npm i -g pnpm@11.7.0
pnpm -v
pnpm run build

Verify: node -v shows v22.19+ or v24+ and pnpm run build exits 0.

3. pnpm: command not found

Symptom: zsh: command not found: pnpm or \u0027pnpm\u0027 is not recognized on Windows.

Cause: pnpm is not installed or not on PATH. This is common on fresh Node installs.

Fix:

npm i -g pnpm@11.7.0
# or
corepack enable
corepack prepare pnpm@11.7.0 --activate
pnpm -v

Verify: pnpm -v prints 11.7.0. On Windows, reopen PowerShell as a normal user and re-run pnpm install.

4. Port 3080 already in use

Symptom: EADDRINUSE: address already in use 127.0.0.1:3080 or a blank URL printed.

Cause: Another process occupies port 3080, or a previous pnpm dsh web instance is still running.

Fix:

lsof -i :3080
# or on Windows: netstat -ano | findstr 3080
kill <PID>  # or Task Manager \u2192 End task
pnpm dsh web

Verify: curl -I http://127.0.0.1:3080 returns 200 after restart.

5. API key invalid or model mismatch (401/404)

Symptom: Model calls return 401 Unauthorized, invalid_api_key, or model not found / 404.

Cause: The key does not match the provider, the model name is wrong, or the custom base URL/protocol is mismatched.

Fix: Open Settings \u2192 Models, re-enter the key for the correct provider card, and confirm the model ID exists for that provider. For custom providers, ensure base URL ends without a trailing slash and protocol is openai or catalog-supported.

Verify: Save and start a tiny test session; the model should stream a response. Check cat $DSH_HOME/.credentials.yaml shows a redacted entry (never the raw key).

6. Network or fetch failed

Symptom: pnpm install hangs, ERR_PNPM_FETCH_404, or fetch failed / ENOTFOUND registry.npmjs.org.

Cause: Offline, corporate proxy, or registry outage. Very common on restricted networks.

Fix:

ping registry.npmjs.org
npm config get proxy
npm config get https-proxy
# if behind proxy, set:
npm config set proxy http://proxy.company.com:8080
pnpm install --registry https://registry.npmmirror.com  # mirror example

Verify: pnpm install completes and ls node_modules is non-empty.

7. Permission denied or workspace not writable

Symptom: EACCES: permission denied, EROFS: read-only file system, or workspace not selected blocking the composer.

Cause: The terminal lacks write permission on the workspace, $DSH_HOME/.credentials.yaml is read-only and locked after save, or no workspace is selected in the UI.

Fix:

ls -ld .
chmod -R u+w .
ls -l $DSH_HOME/.credentials.yaml
# if credentials are corrupted, remove and re-add via UI (do not hand-edit with wrong perms)
# In the Web UI: Choose workspace \u2192 Add your project folder \u2192 Select

Verify: pnpm dsh web starts without EACCES, and the UI composer is enabled after workspace selection.

8. Windows PowerShell execution policy

Symptom: cannot be loaded because running scripts is disabled on this system when running pnpm.

Cause: Windows PowerShell default execution policy blocks scripts.

Fix: Run PowerShell as Administrator and allow remote-signed scripts, then reopen as normal user:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
pnpm -v
pnpm install

Verify: pnpm -v and pnpm run build succeed in a fresh PowerShell window.

Prefer a one-click Desktop GUI?

If the terminal steps above feel heavy, the same engine is available as a live experimental one-click Desktop GUI — a local wrapper that bundles the pnpm + build + pnpm dsh web chain behind an app window. It handles installation, guided provider setup, and updates so you do not need to manage Node or pnpm versions by hand.

Prefer a GUI? The same engine is available as a live experimental Desktop GUI — available now for macOS Apple Silicon (arm64) via the homepage Download and GitHub Release: dsh-desktop-v0.1.0 (asset dsh-desktop-0.1.0-mac-arm64.zip, SHA256 118168931c3e3064b0a785e35011f08f0c4100c7c923ab1671933266f8886439). That desktop download is Unsigned / Not notarized — Experimental · macOS Apple Silicon (arm64) only · Requires macOS 13+; Gatekeeper will block it until you right-click → Open or run xattr -cr "DeepSeek Harness Desktop.app" at your own risk. The desktop app is a third-party community wrapper and service is free during validation, with no promise of permanent free access — and it is not affiliated with DeepSeek.

Prefer to stay on the command line? Continue with npx @deepseek-ai/dsh web for the quickest start, or keep this git clone checkout for source edits. Both paths lead to the same Web UI at http://127.0.0.1:3080.

FAQ

Do I need to install Node globally if I use the Desktop GUI?

No. The Desktop GUI bundles its own runtime; you only need Node and pnpm for the terminal flow described here. The GUI alternative described above needs no terminal.

Can I update the harness after cloning?

Yes. Inside deepseek-harness run git pull --ff-only, then pnpm install and pnpm run build again, and restart pnpm dsh web. To pin a release, use git checkout dsh-v0.1.2-alpha.1.

Where do I report issues?

Report engine bugs to the upstream repo deepseek-ai/deepseek-harness and wrapper questions to deepseek-harness-desktop. Both are MIT-licensed and community-maintained.