DeepSeek Harness Desktop

English | 简体中文

A desktop shell for DeepSeek Harness — the pluggable AI agent harness from DeepSeek. Wrap the official dsh web UI into a native-feeling, always-on desktop app, reusing the dsh CLI you already have.

Features

Recovery Center — when an update breaks the backend

dsh moves fast and occasionally ships breaking changes, and plugins often lag behind — so a dsh update can leave the backend unable to boot, and a plugin that used to work can suddenly take the whole harness down with it. Until now, all the shell told you was a dead-end "backend exited unexpectedly" dialog: no plugin name, no error detail, no way to fix anything in place.

The Recovery Center is the shell's answer — a native page that turns a broken backend into a few clicks:

• Automatic on failure — when dsh crashes or fails to boot, the shell switches to the Recovery Center by itself: a rolling output snapshot (token-redacted) plus an automatic diagnosis that pinpoints the failing plugin when dsh names one, falling back to a plain "here's the log" when it can't
• Plugin rescue — disable/enable writes the profile patch layer with whole-file validation and atomic replacement (it will never corrupt your hand-edited lines or leave the backend unbootable); uninstall/update runs the dsh plugin CLI with live logs. Host-critical modules are protected and refuse to be touched
• Version switching, unified — upgrade and rollback share one list (npm global and git source, channel badges, current version pinned on top), with live progress and an automatic restart back to the normal page when done
• Single entry — version maintenance lives here even when everything is fine: Settings → Desktop checks for updates, and confirming an update hands off to the Recovery Center (no scary diagnostics, just progress) — no terminal needed, ever

Backend (dsh) integration

• Dual backend sources — run the dsh from your npm global install (stable channel) or from a local git checkout (any version, including pre-releases), switchable in Settings. Auto mode prefers npm and falls back to the source directory; if the chosen source breaks, the shell falls back to the other one and tells you why
• Zero-intrusion wrapper — spawns the chosen dsh as a child process (dsh web), loads its localhost UI; the harness source is never modified. One dsh shared by terminal and desktop — plugins, settings, credentials, sessions and versions always match (DSH_HOME, default ~/.dsh)
• Source mode without terminals — pick a folder and the shell drives everything: clone the official repo, run pnpm install + pnpm build with live logs, validate the result, then boot. The only prerequisites are git and pnpm on PATH
• Source-mode updates without terminals either — the shell checks the upstream tags, then one click checks out the chosen version, reinstalls, rebuilds and restarts the backend — the same pipeline the Recovery Center drives, just reached from Settings. Dirty worktrees are refused with a clear message
• One proxy for every update channel — a single proxy setting covers git (clone/fetch), pnpm (install/build) and npm (check/upgrade); git uses per-invocation config, never touching your global gitconfig
• First-run setup page — no dsh detected? The app offers a copyable install command, a one-click in-app install, or the source-mode path (clone + prepare), then boots automatically

Desktop experience

• Frameless immersive window — no native title bar; the custom window controls (minimize / maximize / close) blend into the page with DeepSeek brand-blue hover and follow the light/dark theme
• Always-on tray — closing the window hides to the system tray instead of quitting; the backend keeps running for instant resume
• Auto-start at login — toggle in the tray menu (Windows/macOS native; Linux via XDG autostart)
• Configurable port policy — fixed 3080 by default (same as dsh web, giving a stable page origin so browser-side preferences survive restarts), switchable to a custom port or random in Settings; falls back to a random port with a notice when the fixed port is taken. Note: while the shell lives in the tray it holds the port — run dsh web --port <other> in a terminal to coexist
• Single instance — launching again focuses the existing window
• Full plugin freedom — dynamic plugins (cordis_define/cordis_run), $DSH_HOME/cordis.patch.yml, and the npm plugin ecosystem all work exactly as in the web edition
• Desktop settings section — the app's Settings page gains a "Desktop" tab (styled to match the harness UI): backend source card (mode, directory validation, clone/prepare, proxy), dsh version card (source-aware check → hands updates to the Recovery Center), shell self-update check, auto-start toggle, launch-minimized toggle, port policy, About card
• Conversation width, natively — the upstream drag handles do the job on supported dsh versions; the shell injects nothing
• Shell self-update (two-step) — checks silently 15s after launch (detection only, never auto-downloads): a "Download update" button appears in Settings, switching to "Install update" once downloaded — every step is triggered by you. Windows installs by quitting and running the installer (unsigned builds can't install silently); Linux AppImage replaces itself automatically; macOS excluded (needs signing)

Screenshots

General desktop options	Backend source, proxy and updates

dsh version support

dsh version	use
≥ 0.1.5-rc.1 (verified through 0.1.6-alpha.1)	this shell release
anything older (0.1.0 through 0.1.5-alpha.2)	an older shell release — download it from the Releases page

This shell no longer adapts to dsh versions before 0.1.5-rc.1. Check your backend with dsh --version; if it is too old, either update dsh (npm i -g @deepseek-ai/dsh — 0.1.5-rc.1 is the latest npm channel — or press "Check for updates" in Settings → Desktop from a supported shell) or download the matching older shell release.

Relationship with the official Desktop app

Since dsh 0.1.5, upstream ships its own official Electron app alongside the CLI. This project is an independent, lightweight alternative that wraps the dsh web UI you already have — the two differ in three places:

	This shell	Official Desktop app
Profile	always web; never touches the official exclusive desktop profile (the CLI rejects --profile desktop, and the Recovery Center refuses to list or modify it)	exclusively owns $DSH_HOME/profiles/desktop
Transport	listens on localhost (fixed 3080 by default, configurable, random fallback) — terminal and desktop share one backend	opens no port (dsh-app:// + private pipes)
Versions	tracks a dsh version range (≥ 0.1.5-rc.1): npm latest or any source tag, switched from Settings / Recovery Center	pins one exact Electron+dsh combination per release

Coexistence: both can live under one DSH_HOME (sessions, settings and credentials are shared product data), but never drive the same profile at the same time — and this shell will always refuse to touch profiles/desktop.

Install

Prerequisites

• npm channel (default): Node.js ≥ 22 and the dsh CLI (npm i -g @deepseek-ai/dsh) — if missing, the app shows a setup page with a copyable command or a one-click in-app install
• Source channel (optional): additionally requires git and pnpm on PATH; the shell clones the repo and runs pnpm install + pnpm build for you — supported dsh versions (≥ 0.1.5-rc.1) use the prebuilt node-addon-system, so no C++ build toolchain is needed (historical 0.1.3.x compiled fs-ext and is outside the supported range)

Download

Download the installer for your platform from the Releases page:

Platform	Package	Notes
Windows	deepseek-harness-desktop-<ver>-setup.exe	NSIS installer, x64
macOS	.dmg (Apple Silicon / Intel)	unsigned — first run: right-click → Open
Linux	.AppImage + .deb	x64

First launch

1. Start the app — it resolves your backend (npm by default), boots dsh web in the background and opens the UI at its ready state (no dsh? you'll see the setup page first)
2. Dismiss the 预览版 / preview notice
3. Open Settings → Models and configure your LLM provider (API key, model, base URL) — same as the web edition
4. Pick a workspace and start chatting

Everyday use

• Close window → app hides to the tray, backend keeps running (a DeepSeek whale icon appears near the system clock)
• Tray menu (right-click the icon): reopen the window, toggle auto-start at login, or quit — quitting fully stops the backend
• Quit via tray is the only way to exit the app; closing the window never does

Development

npm install        # installs electron 43 + toolchain
npm run dev        # dev mode: system Node + your chosen backend (npm or source dir)

electron binary download stuck? (you see Downloading Electron binary... forever) GitHub-hosted binaries can be slow from some networks. Manually fetch https://npmmirror.com/mirrors/electron/<version>/electron-v<version>-win32-x64.zip into %LOCALAPPDATA%\electron\Cache\electron-v<version>-win32-x64\, then:

printf "electron.exe" > node_modules/electron/path.txt
# and unzip the archive into node_modules/electron/dist/

Packaging

npm run build:runtime     # generates resources/icon.png (+ build/icon.png) from the upstream favicon
npm run dist:win          # Windows NSIS installer → release/
# npm run dist:mac        # macOS dmg (requires macOS; CI builds it)
# npm run dist:linux      # Linux AppImage + deb

The CI workflow (.github/workflows/release.yml) builds all three platforms on every v* tag and publishes the artifacts to a GitHub Release.

Data & logs

• Data (DSH_HOME): defaults to ~/.dsh (honors the $DSH_HOME environment variable) — profiles, sessions, storage; shared by both backend sources
• Logs: <userData>/logs/main.log
• dsh: the shell runs the backend from your chosen source — npm global (located via PATH + npm root -g, upgradable from Settings → Desktop) or a local checkout (validated before launch: manifest, node_modules/tsx, built web dist, plus an fs-ext hint for pre-floor 0.1.3.x directories)

Project layout

src/
  main.ts               app lifecycle: single-instance lock, window, tray, backend resolution, recovery IPC, setup page
  paths.ts              dev/prod resource resolution (icon, preload, desktop plugin patch, recovery page)
  dsh-locator.ts        locate the npm-global dsh CLI (PATH check + npm root -g) + semver compare
  dsh-versions.ts       backend version listing (npm versions × dist-tags → sorted, channel-tagged)
  dsh-update-target.ts  npm dist-tags → update target (semver whitelist, prerelease-aware)
  dsh-source.ts         git-checkout source: validation (manifest/tsx/web dist, incl. the 0.1.3.x fs-ext gate), tag parsing, entry args
  dsh-source-updater.ts source-channel updates: fetch tags → clean tree → checkout → pnpm install/build → restart
  dsh-updater.ts        npm-channel backend: check latest / install any version (upgrade or rollback)
  dsh/spawn.ts          spawn dsh web --port <policy port> --patch; parse stdout URL line; output ring buffer; graceful stop
  dsh/ready.ts          HTTP readiness probe (any status — the URL may carry a process token since 0.1.2-alpha.1)
  recovery/             Recovery Center core: crash diagnosis, profile patch layer, plugin inventory & toggles, recovery state, theme matching, IPC origin guard
  kill-tree.ts          subprocess-tree termination for timed-out maintenance commands
  settings.ts           shell settings (userData/settings.json — backend source, source dir, proxy, port policy)
  updater.ts            electron-updater (Windows guided / Linux AppImage auto)
  tray.ts               tray menu (open / auto-start / quit) + autostart sync
  autostart.ts          auto-start (native on win/mac; XDG file on linux)
  preload.ts            contextBridge bridge (window controls + desktop IPC; compiled to CJS)
scripts/
  recovery-*.test.mjs   recovery test suite (8 suites, node --test on dist)
  install-runtime.mjs   generates resources/icon.png at build time (from upstream favicon)
  smoke.mjs             headless smoke test: spawn dsh, assert URL line + HTTP response
resources/
  recovery.html         Recovery Center page (vanilla, dual theme)
  desktop-integration/  settings "Desktop" section plugin (dsh browser half)
  desktop-patch.yml     shell-injected patch mounting the plugin
assets/
  wordmark.svg          project wordmark

Known limitations (v1.x)

• Requires Node.js ≥ 22 and dsh ≥ 0.1.5-rc.1; the npm channel needs a globally-installed dsh CLI (the setup page offers one-click install), the source channel needs git + pnpm — the shell bundles no runtime either way, so the installer stays small. Older dsh versions need an older shell release (see the dsh version support table above)
• macOS builds are unsigned — Gatekeeper requires right-click → Open on first run; macOS has no auto-update (needs a signing certificate)
• Windows auto-update is guided (downloads then runs the installer) rather than silent, due to the unsigned build
• The source channel checks out release tags in detached HEAD — switch your branch back manually if you develop in the same clone

Feedback

Found a bug? Have a feature idea? Issues are very welcome — bug reports, usage questions, and suggestions all help.

• Open an issue (English or 中文, either is fine)
• For harness-level problems, also check upstream deepseek-harness discussions

Activity

License

MIT. The DeepSeek Harness itself is MIT © DeepSeek AI.