Tutorial

DeepSeek Harness Tutorial

DeepSeek Harness is an open-source agent harness from DeepSeek AI where everything is a plugin. This tutorial answers what it is, why it matters, and how to run your first task right here: one command, local Web UI at http://127.0.0.1:3080, your API key stays local. No GitHub README click-through required.

1. What an agent harness actually is

A coding harness is the runtime around a language model that makes it a working agent. A raw chat model can only answer questions; a harness gives it real capabilities: tools such as file editing, shell commands and search, sessions that keep context across turns, permission policies that decide which operations need approval, and a log that records every step so a run can be inspected, resumed or replayed.

DeepSeek Harness is exactly that runtime, and its design motto is short: everything is a plugin. Models, tools, skills, sessions, sandboxes, storage, loops, scheduling and even the UI are replaceable plugins on the Cordis framework. That architecture is what makes the project interesting: you adapt it without forking it. For reference, the upstream source is github.com/deepseek-ai/deepseek-harness and the official docs are deepseek-harness.github.io — both optional reading, not required to finish this guide.

2. The four presets

The project ships four agent presets, each tuned for a different way of working:

You do not have to pick once and forget it — presets are configuration, so you can switch per project or per session. The default preset is Standard.

3. Every run is a record

Each session writes an append-only session log. That log powers a trajectory view where you can inspect exactly what the agent saw and did — prompts, reasoning, tool calls, file changes and results, attributed by source. For long-running agent work, this turns a black box into something you can audit, resume or replay.

Permission policies gate risky operations. When the active policy flags a command or an edit as sensitive, the Web UI asks for approval before the agent proceeds, and sandboxing options let you constrain what the agent can reach.

4. A quick tour of the Web UI

The official command starts a local Web UI. You will run it in the Commands section below, but here is what to expect once it is running:

Once the Web UI is running and prints Local: http://127.0.0.1:3080, you will see a small set of steps in the UI: configure a model, choose a workspace, run a task.

1. Configure a model. Open Settings → Models, enter a DeepSeek API key (or pick another provider), and save. The model route becomes usable immediately — no server restart. Keys are stored in $DSH_HOME/.credentials.yaml and shown as redacted afterwards.
2. Choose a workspace. Add the project directory you started dsh in and select it. The session composer stays disabled until a workspace is selected.
3. Run a task. Start a session and send a prompt. The agent can read and edit workspace files, run commands, delegate work and maintain a plan — asking you before anything the permission policy flags.

A good first prompt from the official guide, which you will run in the verification section: "Summarize this repository and identify its main packages." It exercises reading, search and structured summarization without touching anything dangerous.

5. Models are a plugin too

You bring your own key. The model adapter is itself a plugin, so switching providers does not require changing the framework source:

• DeepSeek API — one API-key field under Settings → Models.
• Catalog providers such as Anthropic or OpenAI — pick the provider, enter its key; the installed catalog supplies endpoint, protocol and model list.
• Custom OpenAI-compatible endpoints — for company gateways, self-hosted servers or providers absent from the catalog, with a provider ID, base URL, API protocol, credential and at least one model.

Keys are write-only in the UI and stored in $DSH_HOME/.credentials.yaml, never displayed back to you. Your key stays local — calls go directly from your machine to the provider, never through deepseek-harness.io.

Prerequisites

Scope: this tutorial covers the open-source harness concepts. The Desktop GUI is a separate live experimental desktop app — see homepage and GitHub Release dsh-desktop-v0.1.0 for that path. This page stays focused on the local Web UI at http://127.0.0.1:3080.

Three things help you prepare for a local run. Check them now — the commands below are copy-paste (see the installation guide for the launch command):

• Node.js — required node ^22.19.0 || >=24 and npm 10.x. If you later build from source, also pnpm@11.7.0 and git >=2.40 (from downloads/manifest.json:build.requires). Check with node -v and npm -v.
• Terminal — macOS Terminal or iTerm, Windows PowerShell, or any Linux shell.
• API key — a DeepSeek API key works out of the box; Anthropic, OpenAI, or any OpenAI-compatible key is also supported. The harness is MIT-licensed; you only pay the provider for tokens.

Network: first run downloads the package, so allow registry.npmjs.org and your model provider endpoints. If you are behind a proxy, fix it before running (see Troubleshooting #5).

Check and install Node.js

node -v
npm -v
# expected: v22.19.x or v24.x, npm 10.x

• macOS: brew install node@22 or via nvm: curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash then nvm install 22 and nvm use 22.
• Windows: winget install OpenJS.NodeJS.LTS then restart PowerShell and verify node -v is on your PATH. If node : command not found, reopen the shell.
• Linux: use nvm or your distro package, then node -v.
• pnpm: only needed for source builds. Install when needed with npm i -g pnpm@11.7.0 or corepack enable then corepack prepare pnpm@11.7.0 --activate.

Verify git if you plan to use source: git --version should be >=2.40.

Where is DSH_HOME? By default $DSH_HOME is ~/.dsh on macOS/Linux and %USERPROFILE%\.dsh on Windows. The file $DSH_HOME/.credentials.yaml is created on first save. Back it up with 0600 permissions and never commit it.

echo $DSH_HOME
# macOS/Linux default: /Users/you/.dsh
ls -la $DSH_HOME
# should show .credentials.yaml with -rw-------

If you use a custom home, export it before running: export DSH_HOME=/path/to/.dsh then the harness will read $DSH_HOME/.credentials.yaml from that path. Verify with ls -l $DSH_HOME/.credentials.yaml.

Quick self-check you can run right now:

node -v && npm -v && git --version
# all three should print versions: node v22+, npm 10+, git 2.40+

How the Web UI fits the workflow

Once the harness is running, the Web UI guides you through three steps: configure a model, choose a workspace, and run a task. The exact launch command is on the installation guide.

Configure your API key and keep it local

With the Web UI at http://127.0.0.1:3080 open, configuration lives in the UI:

1. Open Settings → Models.
2. For DeepSeek: paste your API key in the DeepSeek card and Save. For another provider: click Add provider and choose Anthropic or OpenAI.
3. For a company gateway or self-hosted server: click Add a custom provider and supply a provider ID, base URL, API protocol, credential and at least one model. It must be OpenAI-compatible or use a supported protocol.

Your key stays local: keys are write-only — after saving the UI shows only a redacted descriptor. The raw value lives in $DSH_HOME/.credentials.yaml on your machine with 0600 permissions. Inspect it with:

ls -l $DSH_HOME/.credentials.yaml
cat $DSH_HOME/.credentials.yaml | head -n 20
# should exist and be redacted in UI; never commit this file

It is never sent to deepseek-harness.io; your key stays local and calls go directly from your harness to the provider. The route becomes usable immediately without restarting the server at http://127.0.0.1:3080. If you rotate a key, just overwrite it in Settings → Models; check $DSH_HOME/.credentials.yaml updated time with ls -l.

Security model: permission policies gate risky operations — when the active policy flags a command or edit as sensitive, the Web UI asks for approval before the agent proceeds. Sandboxing options let you constrain what the agent can reach. This site is a third-party wrapper, not affiliated with DeepSeek, and we never handle your key.

Run the Web UI and verify

With the Web UI running, verify it end-to-end on this page without needing another guide.

curl -I http://127.0.0.1:3080
# expected: HTTP/1.1 200 OK
# or: HTTP/1.1 200

Summarize this repository and identify its main packages.

Keep the terminal open while you work — closing it stops the server at http://127.0.0.1:3080.

Troubleshooting — 8 fixes for real errors

Each entry is symptom → cause → command or path → verify. All fixes run locally; no re-install from GitHub is required.

1. Node version too old (EBADENGINE / engine mismatch)

Symptom: EBADENGINE or required: node ^22.19.0 || >=24 when starting the harness.

Cause: Node 18/20 is too old for the harness.

Fix: nvm install 22 && nvm use 22 or brew upgrade node@22 or winget upgrade OpenJS.NodeJS.LTS. Verify with node -v prints v22.19.x or v24.x and retry the launch.

2. command not found: npx / node: command not found

Symptom: zsh: command not found: npx or node: command not found.

Cause: Node not on PATH.

Fix: Reopen terminal, or add Node to PATH. Windows: restart PowerShell after install, run where node. macOS/Linux: echo $PATH and which node, then export PATH="/opt/homebrew/bin:$PATH" if using Homebrew. Retry the launch.

3. Port 3080 already in use (EADDRINUSE)

Symptom: Error: listen EADDRINUSE: address already in use 127.0.0.1:3080 or blank page at http://127.0.0.1:3080.

Cause: Another process occupies 3080, or a previous harness session is still running.

Fix: lsof -i :3080 (macOS/Linux) or netstat -ano | findstr :3080 (Windows), then kill PID or close the old terminal. Verify curl -I http://127.0.0.1:3080 fails before and succeeds after the fix, then retry the launch.

4. API key missing or invalid (401 / Invalid API key)

Symptom: Model requests fail with 401, Invalid API key, or authentication failed.

Cause: Key not saved, pasted with whitespace, or for the wrong provider.

Fix: Open Settings → Models, re-paste the key (trim spaces), Save, and check the redacted descriptor appears. Confirm the provider card matches the key (DeepSeek key in DeepSeek card). Inspect $DSH_HOME/.credentials.yaml exists: ls -l $DSH_HOME/.credentials.yaml and cat $DSH_HOME/.credentials.yaml shows a non-empty file.

5. Network / proxy / fetch failed (ETIMEDOUT, fetch failed)

Symptom: fetch failed, ETIMEDOUT, or first-run npx download hangs.

Cause: No internet, firewall, or corporate proxy blocking registry.npmjs.org or provider endpoints.

Fix: Check curl -I https://registry.npmjs.org and ping api.deepseek.com. If behind proxy: npm config set proxy http://proxy:port and https-proxy, or set HTTP_PROXY/HTTPS_PROXY env vars. Retry the launch and verify curl -I http://127.0.0.1:3080 eventually prints 200.

6. Permission denied (EACCES, permission)

Symptom: EACCES: permission denied on cache or ~/.npm.

Cause: npm cache owned by root after a sudo install.

Fix: sudo chown -R $(whoami) ~/.npm (macOS/Linux) or run PowerShell as normal user (not elevated) on Windows. Avoid sudo npx. Check npm config get cache points to a writable path, then retry the launch.

7. Model or provider mismatch (404 / model not found)

Symptom: 404 model not found or provider mismatch even with a valid key in $DSH_HOME/.credentials.yaml.

Cause: Selected model does not exist for the provider, or custom base URL/protocol is wrong.

Fix: In Settings → Models, verify the model name spelling and provider pairing (e.g., DeepSeek-V3 for DeepSeek, not OpenAI). For custom gateways, ensure base URL ends correctly and protocol is OpenAI-compatible. Save and check the redacted descriptor updates.

8. Workspace not selected (composer disabled)

Symptom: Session composer is greyed out, hint says choose workspace.

Cause: No workspace selected at http://127.0.0.1:3080.

Fix: Click Choose workspace → Add your project folder → Select it. Verify composer becomes active. On Windows, use an absolute path like C:\projects\my-app.

Bonus — Nothing prints a URL: if the harness exits silent, check exit code with echo $? (should be 0) and try http://127.0.0.1:3080 directly. Verify curl -I http://127.0.0.1:3080 still checks liveness.

Quick verification FAQ

Two checks users ask for most:

• Is http://127.0.0.1:3080 reachable? Run curl -I http://127.0.0.1:3080 — look for 200. If not, check Troubleshooting #3.
• Is my key saved? Check ls -l $DSH_HOME/.credentials.yaml exists and cat $DSH_HOME/.credentials.yaml is non-empty; the UI shows only redacted.
• Can I stop the server? Press Ctrl+C in the terminal where the harness runs, then curl -I http://127.0.0.1:3080 should fail.

# full liveness sequence
curl -I http://127.0.0.1:3080
ls -l $DSH_HOME/.credentials.yaml
cat $DSH_HOME/.credentials.yaml | head -n 5
the harness --help 2>&1 | head -n 5

Prefer a one-click desktop app?

If the terminal steps above feel heavy, the Desktop GUI wraps the same open-source engine with a one-click install, guided API key setup, and your key stays local — no terminal needed. It is a third-party community wrapper, not affiliated with DeepSeek, and every run remains fully traceable.

Live experimental build: GitHub Release dsh-desktop-v0.1.0 (dsh-desktop-0.1.0-mac-arm64.zip, SHA 118168931c3e3064b0a785e35011f08f0c4100c7c923ab1671933266f8886439 prefix 11816893) is available now as an unsigned, not notarized experimental asset for macOS Apple Silicon (arm64) only, requires macOS 13+. Gatekeeper will block it — right-click → Open or xattr -cr "DeepSeek Harness Desktop.app" at your own risk. Also see the homepage overview and download — the live experimental build is available now via that page, and the waitlist / update list there is for community updates only and does not affect your ability to download.

This site is an independent community page. We are not affiliated with or endorsed by DeepSeek. The GUI is not the official DeepSeek app and is not notarized or signed.

FAQ

Quick answers to questions that come up while running this tutorial. These are also encoded as FAQPage JSON-LD above.

Why does dsh web use 127.0.0.1:3080?

3080 is the default local port for the Web UI. Open http://127.0.0.1:3080 in your browser. If it is busy, free it with lsof -i :3080 then kill PID, or change the port via configuration. Verify with curl -I http://127.0.0.1:3080.

Where is my API key stored?

In $DSH_HOME/.credentials.yaml as write-only with 0600. The UI shows only a redacted descriptor after saving. Your key stays local and is never sent to deepseek-harness.io; calls go directly to the provider. Inspect with ls -l $DSH_HOME/.credentials.yaml.

Do I need git clone?

No for this page. This tutorial is self-contained for concepts. Only use git clone https://github.com/deepseek-ai/deepseek-harness then pnpm install and build from source if you are editing the harness source. That path is covered in the Source Clone guide.