Start with the official entry point
DeepSeek Harness, usually shortened to dsh, runs an AI agent with a workspace, tools and a model connection. Installing it gives you the runtime. You still need to configure a model before asking it to do useful work.
The official DeepSeek Harness page links to desktop downloads for macOS on Apple silicon and 64-bit Windows, plus the DeepSeek GitHub repository. Use those links to choose the correct package. The Web UI is a separate Node.js launch path; you do not need to compile the repository to use its published npm package.
This guide follows npm version 0.2.1-rc.2, checked October 22, 2026. The project is still a developer preview. Keep your first workspace small and disposable, and review the upstream safety notice before giving the agent access to files. Choosing a folder organizes the work; it is not an operating-system sandbox.
Choose desktop or the Web UI
| Your starting point | Use this route | First check |
|---|---|---|
| You want an app window on a supported Mac or Windows computer | Desktop download on DeepSeek's official page | Match the advertised operating system and processor before installing |
| You want a local browser interface and already use Node.js | Published @deepseek-ai/dsh package |
Check Node and npm, then start the Web profile |
| You intend to modify Harness itself | Official repository and its source-build instructions | Install dependencies and build before launching the source checkout |
Desktop downloads and npm packages can change on different schedules. Record the version you actually launch. Instructions for one client do not establish that every button or credential setting looks identical in another.
Launch a separate Web UI trial
Use a current Node.js release supported by the package dependencies. Check node --version and npm --version in the terminal you will use. The commands below use macOS or Linux shell syntax; PowerShell uses a different syntax for environment variables.
Create an empty working directory, then keep the Harness state in a separate sibling directory. This prevents the state directory from becoming part of the example workspace.
mkdir -p "$PWD/harness-trial/workspace"
export DSH_HOME="$PWD/harness-trial/state"
cd "$PWD/harness-trial/workspace"
npx @deepseek-ai/dsh@0.2.1-rc.2 web --no-open
Review npm's package confirmation before accepting it. The first launch can need network access to download dependencies. The official README uses the unpinned package name; this guide pins the version to make the example repeatable.
The normal local address is http://127.0.0.1:3080. Read the address printed by your process and open it in your browser. --no-open prevents Harness from automatically opening a browser window. Leave that terminal running while you use the interface.
The CLI reference describes DSH_HOME and profiles. Reuse the same state path when restarting this trial. Changing it creates a different set of settings; an empty session list after switching paths is not proof that the original sessions were deleted.
Configure a model and select the workspace
The official Web UI guide starts with Settings, then Models. For the DeepSeek API route, enter your own DeepSeek API key and save. Check the provider account's current usage and billing terms before sending a task. Installing open-source Harness does not grant unlimited model usage.
For another provider or a custom compatible endpoint, follow the model configuration guide. Match the endpoint's API protocol and model ID. A saved field or detected environment variable is not a successful authentication test. Keep credentials in the provider settings, outside prompts, screenshots and shared configuration samples.
Next, choose Choose workspace, add your trial workspace and select it. The official guide says a fresh Web UI has no selected workspace, even though you launched the process from a directory. The composer remains unavailable until you select one. Select a configured model before starting the session.
Give the first task an answer you can check
Create a plain text file called sample.txt in the workspace yourself:
Project: Cedar
Modules: reader, formatter
Output: summary.txt
Then ask:
Read sample.txt and report the project name and the two modules. Do not change any files or run shell commands.
A useful result names Cedar, reader and formatter, with no extra modules. Inspect the tool activity to confirm the agent read the file. A plausible answer without that read is not evidence that workspace access works. Check that sample.txt remains unchanged.
This is a small verification task, not a benchmark. If it succeeds, try a reversible edit in a copied project and review the diff before accepting it. A browser page loading, a model answering, and an agent correctly editing files are separate checks.
Find the failing step before reinstalling
| What you see | Check next |
|---|---|
| The local page will not open | Confirm the terminal is still running and use its printed address. Check a startup failure or port conflict before changing model settings. |
| The page opens but the composer is unavailable | Select a workspace, then a configured model. |
| A model request is rejected | Check the provider key, account access, model ID and protocol against the provider's documentation. |
| The reply describes the wrong project | Confirm the selected workspace and inspect which file the agent actually read. |
| A source checkout cannot launch | Follow the repository's build step; the source launcher does not replace that build. |
Stop the trial with Ctrl+C in its terminal. Keep the trial state if you want to resume it. Avoid deleting an established Harness directory merely to clear an error.
For a separate MCP server configuration problem, the browser-local MCP checker can inspect a sanitized JSON example. It does not validate Harness's model settings or test a live model connection.