Prerequisites and compatibility
| Component | Version / notes | Required? |
|---|---|---|
| Node.js | ^22.19.0 or >= 24.0.0 | Yes |
| pnpm | 11.28.5 (source installs only) | For source builds |
| Git | Latest release | To clone the repository |
| Python | 3.10 or newer | Only for the Python SDK |
| Operating system | Linux x64/arm64, macOS 14+ (arm64), Windows x64 | Yes |
| Model API key | From the DeepSeek platform or another provider | To call a model |
Run node -v. If the result is below 22.19, upgrade Node.js first (the latest LTS is a good choice). Node.js also ships npx, which the first route needs.
Fastest: run it with npx
Open a terminal in your project folder
On Windows use PowerShell; on macOS/Linux use Terminal. The folder where you run the command becomes the agent's default workspace.
Start the DeepSeek Harness web interface
This command fetches the official package, starts the local server and opens your browser automatically.
Choose the workspace and model
In the web interface click Choose workspace if you want a different folder, then enter your API key in Settings → Models.
# jalankan antarmuka web (browser terbuka otomatis)
npx @deepseek-ai/dsh web
# tanpa membuka browser (mis. di server)
npx @deepseek-ai/dsh web --no-open
# ganti port bila 3080 sudah dipakai
npx @deepseek-ai/dsh web --port 8080The default web interface address is http://127.0.0.1:3080.
Install from source (plugin developers)
Clone the official repository
The DeepSeek Harness repository lives on GitHub under the
deepseek-aiorganisation.Install dependencies and build
Use the supported pnpm version so dependency locks stay consistent.
Run the built app
The
pnpm dshcommand runs the local build, so your plugin changes are tested immediately.
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh webRequires pnpm 11.28.5 and Node.js matching the prerequisites above.
To install a plugin package into a profile, use the plugin command with pnpm arguments. This keeps the profile consistent without disturbing global dependencies.
dsh plugin --profile web add @nama/plugin-andaFormat example; adjust the profile and package name to your needs.
Choosing the right profile
A profile is a bundle of plugins and settings loaded together. Profiles let one DeepSeek Harness installation serve several purposes without interference: the web interface for daily work, headless mode for automation, and SDK mode for calling it from code.
| Profile | Purpose | Example |
|---|---|---|
web | Local web interface for daily use. | dsh web |
headless | Run jobs with no interface — good for scripts and CI. | dsh --profile headless "job" |
sdk / sdk-minimal | To be called from your own app (including the Python SDK). | dsh --profile sdk |
acp | Editor/agent integration speaking the ACP protocol. | dsh --profile acp |
desktop | Profile name reserved for the desktop app. | Used automatically by the desktop app. |
dsh --version # cek versi
dsh --help # daftar perintah
dsh --dump-config # lihat konfigurasi aktif
dsh --dump-default-config # lihat konfigurasi bawaan
dsh --dump-config-schema # skema konfigurasi
dsh --patch berkas.yml # tambahkan penambalan konfigurasiArguments after the launcher flags are forwarded to the app, for example --port.
Setting up API keys and models
Open model settings
In the web interface or desktop app, open Settings → Models.
Paste your API key
The key is stored in a local credentials file inside
$DSH_HOME(default~/.dsh) and is write-only, not readable back by other tools. No restart is needed to activate it.Add other providers if needed
Use Add model provider for third-party providers or your own gateway. Three supported protocols:
openai-completions,openai-responsesandanthropic-messages.
| Location | Contents |
|---|---|
$DSH_HOME (default ~/.dsh) | Central user settings. |
settings.yaml | General application preferences. |
.credentials.yaml | API keys (write-only). |
profiles/<name>/cordis.patch.yml | Configuration patches for that profile. |
skills/ | Skills that apply to every project. |
sessions/ | Session history. |
Never paste an API key into project files, example scripts or screenshots. If a key leaks, revoke and recreate it in the provider dashboard.
Running local models with Ollama
When data must not leave your machine or network, DeepSeek Harness can run against a local model through the Ollama integration. Suitable for exploration, workflow testing or internal-data work.
# jalankan DeepSeek Harness melalui Ollama
ollama launch dsh
# pilih model tertentu
ollama launch dsh -- --model nama-model-andaThis integration keeps its own configuration and does not modify your DeepSeek Harness settings.
Keep in mind: a local model on an ordinary computer usually follows long instructions less reliably than a cloud model. For layered work (workflows, subagents), cloud models remain more dependable.
Confirming the installation works
node -vprints 22.19 or later (or 24+).dsh --versionprints the DeepSeek Harness version.- The web interface opens at
http://127.0.0.1:3080. - The workspace shows your project files.
- Settings → Models shows an active model, and a test task completes.
Sebutkan lima berkas terbesar di folder ini beserta ukurannya, dan jangan ubah apa pun.A read-only task like this is safe even under the strictest sandbox mode.
Common installation problems
| Symptom | Cause | Fix |
|---|---|---|
npx is not recognised. | Node.js is missing or the terminal was not restarted. | Install the Node.js LTS release, then open a new terminal. |
| Node version too old error. | Version below 22.19. | Upgrade Node.js to 22.19+ or 24+. |
| Port 3080 already in use. | Another app uses the same port. | Run with --port 8080 or another free port. |
| The browser did not open. | Server mode or a desktop-less environment. | Open the address printed in the terminal manually. |
| Model calls are rejected. | API key missing or incorrect. | Re-enter it in Settings → Models and confirm your quota. |
| pnpm install fails. | pnpm version mismatch or a broken cache. | Use pnpm 11.28.5 and clear the pnpm cache if needed. |
Need help rolling out DeepSeek Harness?
Free consultation with Andi to choose the right setup, prepare a workflow, or review safety before your team adopts it.