Skip to main content
AI Choice EngineAI Choice Engine
Browse decision tools
← All setup guides

DeepSeek · Setup guide

How to set up DeepSeek Harness

Install Node.js, launch DeepSeek Harness with the official npx command, open the local web UI, add a workspace, paste a provider API key in Settings → Models, and start with a read-only repository summary before approving edits.

DeepSeek Harness

browser · checked August 14, 2026

~15 minIntermediate
Start installOpen DeepSeek HarnessCompare itBuyer guide

The “Open DeepSeek Harness” link goes to the vendor site. It is not an affiliate-tracked link on this page — no commission is claimed for that click. Affiliate disclosure.

Critical: finish install before closing the window

Keep the installer terminal open until you see a success message. If you used an admin window, do not close it until verification works. Then open a new Terminal or PowerShell window and run the verify step — PATH updates rarely apply to shells that were already open, especially on Windows.

Before you begin

  • macOS, Linux, or Windows.
  • Node.js ^22.19.0 or >=24.0.0 (engines from the DeepSeek Harness repo).
  • A DeepSeek API key, or another catalog provider key (Anthropic, OpenAI, and custom OpenAI-compatible endpoints are documented).
  • A disposable git clone with secrets removed — the process uses the invoking directory as the default filesystem location.

Authentication

Settings → Models in the local web UI (API key stored under $DSH_HOME/.credentials.yaml)

Account: A DeepSeek API key, or a catalog/custom provider key

Keys are write-only in the UI; after save you see a redacted descriptor. Native auth for Bedrock, Vertex, Azure, and Codex needs those platforms’ credentials — an API-key field alone does not configure them. Never commit $DSH_HOME/.credentials.yaml or settings.yaml.

Install or open it

1. Get the harness ready

These steps are written for beginners. On Mac, Terminal is the black/white text window where you type commands. On Windows, use PowerShell or Terminal. Use the OS tabs to hide steps that are not for your computer, then copy one command at a time.

  1. 01

    Open Terminal on a Mac

    Mac

    Click the Spotlight search icon (magnifying glass) at the top-right of the menu bar, or press Command (⌘) + Space. Type Terminal and press Return. A text window opens — that is where you paste the install commands below. Leave it open.

  2. 02

    Open Terminal or PowerShell on Windows

    Windows

    Press the Windows key, type Terminal or PowerShell, then press Enter. Use that window for the commands below. If Windows asks for permission to run a script or install software, read the prompt before approving.

  3. 03

    How to paste a command

    Copy one command at a time from this page. Click inside the terminal window, paste (Mac: ⌘+V, Windows: Ctrl+V or right-click → Paste), then press Return / Enter. Wait until the prompt comes back before running the next command. You do not need to type the leading $ if you see one in other docs.

  4. 04

    Do not close the installer until verified

    Keep the installer terminal (or admin PowerShell) open until the install finishes without errors. Closing early can leave a half-written binary or an incomplete PATH update — especially on Windows.

  5. 05

    Open a new terminal after installers

    PATH updates often only apply to new shells — especially on Windows. Do not close the install session until the installer finishes, then open a fresh Terminal/PowerShell before running --version checks.

  6. 06

    Inspect before you pipe an installer

    Commands like curl … | bash download and run a script immediately. Prefer the official package manager when offered. If you use a curl installer, you can download the script first, open it in a text editor, then run it — never paste installers from random blogs.

  7. 07

    Confirm a supported Node.js version

    DeepSeek Harness requires Node.js 22.19+ or 24+. If node is missing or too old, install a current LTS from nodejs.org, then open a new terminal.

    bash
    node --version

    You should see: A version string starting with v22.19 or v24 or newer.

    If this fails
    • “command not found”, “not recognized”, or no window opens. Open a new terminal after install, confirm PATH, then re-run the verify command from the official docs.
    DeepSeek Harness package engines
  8. 08

    Show the dsh launcher help

    This downloads the published CLI via npx without cloning the monorepo. You should see the launcher grammar (web, --profile, plugin). Developer preview — expect breaking changes.

    bash
    npx @deepseek-ai/dsh --help

    You should see: Launcher help for @deepseek-ai/dsh, including the web profile alias.

    If this fails
    • npx cannot find @deepseek-ai/dsh or Node refuses to run it. Confirm node --version is ^22.19 or >=24, then retry. Do not install random npm packages named dsh. The official package is @deepseek-ai/dsh.
    DeepSeek Harness README
  9. 09

    Start the local web UI

    Run this from the project folder you want as the default filesystem root. The command prints the URL; the default is http://127.0.0.1:3080. Leave the process running.

    bash
    npx @deepseek-ai/dsh web

    You should see: A local URL, typically http://127.0.0.1:3080.

    If this fails
    • The install command errors, or the next verify step says “command not found”. Re-run the official install command with network access, then open a brand-new terminal window before verifying.
    DeepSeek Harness README

Repository or project

2. Start in the right place

Keep the first repository small, clean, and easy to roll back while you learn the harness’s permissions and context model.

  1. 01

    Choose a workspace in the web UI

    A fresh UI has no selected workspace. Click Choose workspace, add the directory you launched dsh from, and select it. The session composer stays unavailable until a workspace is selected.

    Use the Web UI
  2. 02

    Paste a model key

    Open Settings → Models. For DeepSeek, enter the API key on the DeepSeek card and save. Add provider covers Anthropic/OpenAI catalog routes; Add a custom provider is for gateways. Model changes apply on the next request without restarting.

    Configure models

First run

Summarise the repo without approving edits

Use this task to test the workflow before handing over a larger repository or production responsibility.

  1. 01Start a session and send: Summarize this repository and identify its main packages. Do not edit files.
  2. 02Read the permission prompts. Deny anything that writes files, runs mutating shell, or leaves the workspace.
  3. 03Stop the session, check git status, and confirm $DSH_HOME/.credentials.yaml was not copied into the repo.

Why this is safe: The official first prompt is a repository summary. The web UI asks before operations that require approval under the active permission policy, so the first run can stay read-only.

Stop and review if

  • The UI asks to approve a write, install, or network call you did not expect.
  • You cannot tell which provider will receive the prompt after saving a key.
  • The process was started in a directory that contains production secrets or .env files.

The operating boundary

Privacy, data, and cost

The setup is incomplete until you know what the harness can see, what account pays for it, and who approves a risky action.

Privacy

DeepSeek Harness is MIT open source and runs locally. Prompts, files, and tool output go to whichever model provider you configured. Credentials live in $DSH_HOME/.credentials.yaml, not in the repository.

Training on code: tier dependent

Retention and training follow the selected provider. DeepSeek’s own chat-completions route is documented as text-only; image input on that route cannot be enabled in settings.

Sensitive repos: Start with a sanitized clone, keep $DSH_HOME outside the repo, and do not commit credentials.yaml or settings.yaml. Developer preview — pin the npx version before any shared rollout.

Pricing

The harness client is free (MIT). Hosted inference is billed by the provider API key you save. There is no DeepSeek Harness seat price in the v0.1 developer preview.

Model: usage based

Watch out: A free npx launch is not free inference. Long agent loops, large context, and retries bill the configured provider. Pin @deepseek-ai/dsh if you need a stable preview.

Estimate a seat stack

When setup goes wrong

  • npx cannot find @deepseek-ai/dsh or Node refuses to run it.

    Confirm node --version is ^22.19 or >=24, then retry. Do not install random npm packages named dsh. The official package is @deepseek-ai/dsh.

  • MISSING_CREDENTIAL when sending a message.

    Open Settings → Models and save the provider key, or set the environment variable referenced in settings. Keys are stored under $DSH_HOME/.credentials.yaml.

  • The composer is unavailable or no workspace is selected.

    Click Choose workspace and add the directory you started dsh from. The UI has no selected workspace on a fresh launch.

  • An image attachment is refused before sending.

    DeepSeek’s own chat-completions route is text-only. For a custom vision endpoint, set input: [text, image] on that model in $DSH_HOME/settings.yaml as documented.

  • pip or PyPI installs a package named deepseek-harness.

    Uninstall it. That name is not the official client. Use `npx @deepseek-ai/dsh web` (pin 0.1.0-rc.6 if you need a stable preview).

Next steps

After the first successful run

Keep the pilot small, then compare surfaces and budget before a team rollout.

Compare harnessesBuyer guideOpen-source agents hubAI stack cost calculatorGPU inference (rent)Local GPU sizingBuyer guidesLocal open-source AI guide

Setup details change quickly. The page was checked August 14, 2026; use the official source below before installing in a managed or production environment.

DeepSeek Harness READMECompare all harnesses