Skip to main content
AI Choice Engine
← 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 October 2, 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 VM, container or dedicated environment with a sanitized clone. The publisher says the preview has not undergone a security audit, and permissions/sandboxing do not guarantee isolation.

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

Saved keys appear as redacted descriptors in the UI and live in $DSH_HOME/.credentials.yaml. Profile configuration is $DSH_HOME/profiles/<name>/cordis.patch.yml, with web as the ordinary profile. The model form does not support OAuth providers such as Codex. Redaction in the UI does not establish encrypted storage; keep DSH_HOME outside the repository.

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 satisfying ^22.19.0 (the 22.x line from 22.19 onward) or >=24.0.0; Node 23 does not satisfy these published engines.

    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 and save the DeepSeek key, or use Add model provider for installed catalog providers and Custom model API for gateways. Choose the actual protocol: OpenAI Chat Completions, OpenAI Responses or Anthropic Messages. A catalog provider's discovery uses its installed catalog; discover a gateway through a custom provider. New requests pick up configuration without a restart; already-used sessions retain their recorded model.

    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: A repository-summary prompt limits requested work, but it does not enforce a read-only boundary. The UI asks only for operations requiring approval under the active policy; use a disposable environment and explicit permissions, then inspect the actual diff.

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. Current DeepSeek Vision docs support text and images for deepseek-flash, and Harness v0.2.0-rc.2 release notes add text/image support to its DeepSeek adapter; older installed versions may differ. Confirm both model and adapter capabilities before attaching images (official docs/releases checked 2026-10-01).

Sensitive repos: Use a sanitized clone in a disposable environment, keep $DSH_HOME outside the repo, and do not commit .credentials.yaml or profiles/<name>/cordis.patch.yml. Review third-party plugins and pin a reviewed published preview before a shared rollout.

Pricing

The harness client is free (MIT). Hosted inference is billed by the provider API key you save. No separate Harness seat-price SKU was established in the current developer-preview documentation; hosted model billing remains separate.

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.

    Check your installed preview version and selected model: v0.2.0-rc.2 adds text/image support to the DeepSeek adapter, and deepseek-flash accepts images. For custom endpoints, configure only the input types that the endpoint and adapter actually support; consult the current provider guide.

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

    The official Node launcher is @deepseek-ai/dsh. Do not run an unrelated similarly named package; inspect what was installed before removing anything you need. The October 2 release list starts with dsh-v0.2.0-rc.2, published September 29 and marked prerelease; no stable release is established. Verify npm distribution separately before pinning.

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 October 2, 2026; use the official source below before installing in a managed or production environment.

DeepSeek Harness READMECompare all harnesses