deepseek-harness-desktop

中文 | English

A Windows desktop shell for the web edition of DeepSeek Harness (dsh web): a thin Electron launcher that starts/stops the dsh web server and displays its UI in a native window. It never forks or patches any dsh code, so the daily preview releases of dsh stay naturally compatible.

⚠️ This is an unofficial community wrapper. It is not affiliated with or endorsed by DeepSeek.

How it works

┌──────────────────────────── DSH Desktop (Electron main process) ───────────────────────────┐
│  engine-manager  ──verify/install/atomic-swap/rollback──►  <engine closure directory>       │
│        │                                                    engine/node_modules/@deepseek-ai/dsh │
│        ▼                                                      + all deps (dsh-base / dsh-web-app / …) │
│  spawn  node.exe …/dsh/lib/bin.js web --port N                                                │
│        │ stdout: "dsh web: http://127.0.0.1:PORT"   ← url-detector parses the ready line      │
│        ▼                                                                                      │
│  BrowserWindow.loadURL(http://127.0.0.1:PORT)  ← the exact same GUI as the web edition       │
└──────────────────────────────────────────────────────────────────────────────────────────────┘

Key facts (verified in the @deepseek-ai/dsh-app-boot source):

• The upgrade unit is the whole npm closure directory: dsh profile bundles (dsh-base, dsh-web-app) resolve installation-first (resolveBundleDir anchors on the launcher package); $DSH_HOME/profiles/node_modules only holds junction links into that closure, re-pointed automatically on every boot (healProfilesModuleFallback). Swapping the whole engine directory IS the upgrade, and user data is never touched.
• User data is isolated: $DSH_HOME (default %USERPROFILE%\.dsh: profiles / sessions / storages / settings / credentials) is fully separate from the engine directory and is shared with the web edition.
• No user-installed pnpm needed: a missing profiles/web is auto-initialized from the built-in template (a few files) with no network access; the desktop shell bundles pnpm only for engine installation.

Upgrades & rollback (semi-automatic)

• 12 seconds after startup an asynchronous background check runs npm view @deepseek-ai/dsh dist-tags (respecting your .npmrc registry/mirror), so a slow mirror never freezes the window. The default next channel follows upstream developer-preview releases; set engineUpdateChannel: "latest" in config.json for the conservative npm channel.
• Upgrade flow: bundled pnpm add into a staging directory → smoke-verify (--version + --profile web --dump-default-config, with DSH_HOME pointed at a throwaway directory, never touching real data) → stop the server → atomic rename engine ↔ engine.prev-<old-version> → restart. The current server and UI remain available throughout download and verification; only the seconds-long swap shows a status page.
• Registry checks, install, and verification are asynchronous. During download or verification, use “取消引擎更新” from the menu or tray to stop the entire package-manager process tree; the current engine remains intact.
• For already-installed older engines, the shell passes --no-open only to dsh >= 0.1.0-rc.8; earlier engines start normally and can update first.
• The tray menu item "回滚引擎到上一版本" (roll back to the previous engine) works at any time (the last 2 old versions are kept).
• Updating restarts the service: running background jobs are interrupted, but persisted session data is never lost.

Directories & configuration

Common config.json keys: port (default 3080), host, closeToTray, autoUpdateEngine, engineUpdateChannel (next or latest), maxAutoRestarts, startupTimeoutMs. Environment variables: DSH_DESKTOP_CONFIG_DIR, DSH_DESKTOP_ENGINE_BASE, DSH_DESKTOP_NODE (testing/custom use).

Development

npm install --include=dev     # add --include=dev if your global .npmrc sets omit=dev / NODE_ENV=production
npm start                     # dev mode: auto-detects an existing dsh closure in the npm cache (e.g. npx), starts offline

Dev mode uses port 3080 by default; if 3080 is taken by the web edition, you can pick "random port" or "attach to the existing instance".

Building the installer (Windows x64)

npm run prepare:resources     # downloads portable Node 24, bundles pnpm 11.7.0 (NODE_DIST_MIRROR), and creates the offline engine snapshot
npm run dist                  # electron-builder → build/DeepSeek Harness Desktop-<ver>-setup.exe

• The installer is a per-user NSIS package (no admin required), bundled with a Node runtime and an offline engine snapshot: the target machine does not need Node installed, and first launch works offline; updates work once online.
• Mirrors for build-time downloads: Electron → ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/; Node → NODE_DIST_MIRROR=https://npmmirror.com/mirrors/node/; pnpm/npm follow your registry configuration.
• The unsigned installer triggers a SmartScreen prompt on first run ("More info → Run anyway"); code signing is recommended for distribution.

Compatibility contract (the shell's only dependencies, all with fallbacks)

1. dsh web flag family --port / --host (commander parsing in dsh-web-app).
2. The stdout ready line dsh web: http://127.0.0.1:<port> (dsh-web-app printUrl).
3. dsh --version prints a semver; fatal errors exit non-zero.
4. Fallback chain: no URL line → probe the configured port (ready only when the response carries __DSH_BOOT__) → if all fail, show a compatibility dialog with the engine version + log tail. Never silently hangs.

Security

• Renderer: nodeIntegration:false, contextIsolation:true, sandbox:true, only loopback URLs are loaded; will-navigate / setWindowOpenHandler block external navigation and hand it to the system browser.
• User environment variables such as DSH_HOME and DSH_TELEMETRY_DISABLED are never overridden.

Troubleshooting

• Port busy: detected at startup; choose a random port or attach to the existing instance.
• Engine corrupt/missing: reinstalled from the registry automatically; offline first run uses the bundled snapshot.
• Upgrade failure or cancellation: the current engine remains intact; manual rollback is available after a successful switch.
• Child crash: auto-restarted (max 3 by default), then a dialog with the log tail is shown.
• Logs: %APPDATA%\DSH Desktop\logs\ ("查看日志目录" in the tray).

License & acknowledgements

• This project is an unofficial desktop wrapper for DeepSeek Harness and does not contain upstream source: the engine (@deepseek-ai/dsh and other npm packages) is installed from the npm registry at build/runtime. Upstream is MIT licensed (Copyright © 2026 DeepSeek); see THIRD_PARTY_NOTICES.md.
• The app icon is rasterized from the DeepSeek whale mark shipped in the upstream dsh-web-frontend package (MIT). The whale is a trademark of DeepSeek; this project is not affiliated with or endorsed by DeepSeek.
• This project's own code is released under MIT (see LICENSE).