DEV Community

JinHyuk Sung
JinHyuk Sung

Posted on Fully Autonomous

DeepSeek Harness on Windows: setup, checks, and recovery

#opensource #showdev #tooling

If you use DeepSeek Harness (DSH) on Windows, you can get stuck before the agent does any useful work: PowerShell is missing, a native dependency won't load, or an old plugin is still enabled after an upgrade.

I maintain dsh-win32, a small CLI for checking that setup and handling specific failures. With DSH and its prerequisites already installed, the starting command is:

npx dsh-win32 setup
Enter fullscreen mode Exit fullscreen mode

Here is what it does, when to run the deeper check, and how to recover if the old plugin prevents DSH from starting.

What setup changes

Current DSH already provides persistent PowerShell and a Windows ACL sandbox. dsh-win32 works alongside those components. It is not another coding agent or a replacement runtime.

setup checks the Windows environment and creates a DeepSeek Harness desktop shortcut, using the Web profile by default. It leaves your current DSH profile and preset unchanged. You can choose another profile or skip the shortcut:

npx dsh-win32 setup --profile desktop --no-shortcut
Enter fullscreen mode Exit fullscreen mode

It does not install DSH, PowerShell, or WSL for you. For the native Windows path, install DSH following its official instructions and use PowerShell 7 with a supported Node release. The documented baseline is Node 22.19+ or 24+; Node 23 is not supported. These commands show which versions your terminal is using:

node --version
pwsh --version
Enter fullscreen mode Exit fullscreen mode

A missing prerequisite and a broken native module need different fixes. Reinstalling everything makes it harder to tell which one you had.

Test the installed shell, not just the package metadata

Finding a package on disk does not prove the agent's shell can use it. For a first setup with a live component check, use:

npx dsh-win32 setup --verify
Enter fullscreen mode Exit fullscreen mode

If you have already completed setup, run the verifier directly instead:

npx dsh-win32 verify --json
Enter fullscreen mode Exit fullscreen mode

You do not need to run both. The verifier reports the actual selected DSH version and source, which matters when the version installed on your machine differs from the registry's latest release.

In a temporary DSH home and workspace, it exercises the installed official terminal, subprocess, and Windows ACL sandbox components. The checks cover:

  • PowerShell starting and retaining the working directory and environment across calls.
  • Writing inside the workspace, while an outside write that succeeds in the control process is denied in the sandbox.
  • Interrupting work and starting a replacement call.
  • Disposing the context and cleaning up the test processes.

No model API key is needed. It does not load your normal DSH profile for these checks. A failure or unsupported environment returns a nonzero exit status.

A pass is useful evidence about those components. It is not proof that every stock Minimal, Web, or Desktop UI session, model task, or hook works.

If a check fails, keep the diagnosis narrow

For an environment report, use:

npx dsh-win32 doctor --json
Enter fullscreen mode Exit fullscreen mode

doctor is a diagnostic command, not the live verifier. If it identifies a supported native-load problem, npx dsh-win32 fix provides the targeted repair path. It is not a general fix for every DSH startup or terminal error.

Keep the exact failing command, installed versions, and short error message. Do not switch off Workspace Write just to turn a failing check green; that changes the condition you are trying to understand.

The upgrade trap: the old plugin can block its own removal

The standalone CLI and the old plugin bundle are different things. On current DSH, use the standalone commands above. Do not add dsh-win32 through dsh plugin add: that activates the legacy bundle intended for older hosts.

An old enabled bundle can prevent DSH from starting. When that happens, even its normal plugin-removal command may fail before it can do anything.

Version 0.17.14 adds a recovery command that does not need to boot DSH. First, preview the change for the affected profile:

npx dsh-win32@0.17.14 disable --profile web
Enter fullscreen mode Exit fullscreen mode

This is a preview only. Confirm that the reported profile is the one you want to repair. Before applying anything, stop DSH and any package-manager operations using that profile. Then:

npx dsh-win32@0.17.14 disable --profile web --apply
Enter fullscreen mode Exit fullscreen mode

The command backs up the original profile package.json byte for byte, then removes only the exact dsh-win32 entry from dsh.profile.bundles. It does not uninstall the dependency or delete presets, conversations, or other configuration. Custom preset references still need separate review.

If you use a different profile or a Desktop-managed location, follow the recovery guide rather than guessing a directory. The guide also covers dependency removal after deactivation.

Trying it or reporting a failure

The project is free, MIT-licensed, and written in TypeScript. The repository includes the source and tests, plus first-run instructions and Chinese documentation.

If a supported setup still fails, an issue with the Windows, Node, PowerShell, and DSH versions plus the exact command and a redacted error is much more useful than a screenshot of a generic startup failure. Do not include API keys, full profiles, or private prompts.

Top comments (0)