dsh-desktop-window
中文 | English
A DeepSeek Harness (DSH) plugin that opens the DSH Web UI in a standalone app window — double-click to launch, no tab strip, no address bar, and a browser profile fully isolated from your everyday browsing.
dsh web ──▶ server ready ──▶ ┌──────────────────────────┐
│ DSH · standalone window │
│ (Edge/Chrome --app) │
└──────────────────────────┘
Features
- Auto-open — the window appears by itself once the server is up (on by default).
- Manual toggle — a window button in the session header opens and closes it.
- Settings switch — Settings → General → auto-open at startup, persisted across restarts.
- Whale branding — the official whale favicon and a web manifest are injected, so the window title bar and an installed app carry the DeepSeek icon.
- Isolated — a dedicated profile directory under
%TEMP%; your normal Edge/Chrome windows, tabs, and logins are untouched.
| |
|---|
| Standalone window | Chromium --app mode: no tabs, no address bar, 1440×900 launch size |
| Auto-open | A settled first paint instead of a blank frame |
| Header button | Shows live window state and toggles it |
| Settings row | A compact switch in the General section of Settings |
| Whale icon | 7 favicon sizes plus a web manifest, injected as <head> rows |
| Safety | Mutating routes are same-origin guarded (cross-site POST → 403); every route, timer, and child process is released on plugin unload |
| Lifecycle | Window-close state stays in sync; closing tears down the whole process tree |
Requirements
| |
|---|
| OS | Windows 10/11 (primary), macOS 11+ |
| DSH | >= 0.1.0-rc.6 — developed and verified against 0.1.5-rc.1 |
| Node.js | >= 22 (inherited from DSH) |
| Browser | Edge, Chrome, Chromium, Brave, or Vivaldi at a standard install location |
| pnpm | only for dsh plugin add / update (npm install -g pnpm) |
The window logic itself is cross-platform; only Windows is a supported target today.
Installation
Installing a bundle changes the profile's bundle list, which DSH reads at startup — so dsh web must be restarted afterwards.
From GitHub:
dsh plugin --profile web add github:fengzhiyushui/dsh-desktop-window
# equivalent:
dsh plugin --profile web add "git+https://github.com/fengzhiyushui/dsh-desktop-window.git"
From a local checkout:
dsh plugin --profile web add "file:D:/path/to/dsh-desktop-window"
dsh plugin add installs the package into the profile's node_modules and merges the bundle that declares dsh.bundle into dsh.profile.bundles automatically — no manual config edits. Then restart dsh web.
Or let the script do all of it (pnpm check, space-safe install, composition check):
powershell -ExecutionPolicy Bypass -File "<plugin-dir>\scripts\install.ps1"
Windows: installing from a path that contains spaces
dsh plugin forwards arguments to pnpm through a shell, and a path with spaces
gets re-split into separate arguments. Install through a space-free junction
instead — scripts/install.ps1 does this for you, or by hand:
New-Item -ItemType Junction -Path D:\dsh-desktop-window -Target 'D:\path with spaces\dsh-desktop-window'
dsh plugin --profile web add "file:D:/dsh-desktop-window"
Keeping it up to date
# a git dependency re-fetches the default branch HEAD
dsh plugin --profile web update dsh-desktop-window
# then restart dsh web
Users never need to re-add; update is enough.
Usage
dsh web
# the standalone app window opens by itself once the server is ready
| What | Where |
|---|
| Open / close the window | the window button in the session header |
| Turn auto-open on or off | Settings → General → auto-open at startup |
| Change the browser preference | edit browserCandidates() in lib/window-spec.js |
Closing the app window does not stop dsh — by design, only the standalone window closes.
Desktop shortcut (Windows)
# whale icon, opens with this plugin folder as the workspace
powershell -ExecutionPolicy Bypass -File "<plugin-dir>\scripts\create-shortcut.ps1"
# with a specific default workspace
powershell -ExecutionPolicy Bypass -File "<plugin-dir>\scripts\create-shortcut.ps1" -WorkspaceDir "D:\my project"
DSH-Desktop.cmd is the launcher the shortcut points at; you can also double-click it. It uses dsh when it is on PATH and otherwise falls back to npx @deepseek-ai/dsh@latest (pin it with the DSH_DESKTOP_DSH_VERSION environment variable).
Configuration
The auto-open preference lives in $DSH_HOME/desktop-window.json (default %USERPROFILE%\.dsh\desktop-window.json). It is written by the settings switch; a hand-edit is also fine, including one saved by Notepad (a UTF-8 BOM is tolerated).
{
"autoOpen": true,
"cleanProfileOnUnload": false
}
| Key | Default | Meaning |
|---|
autoOpen | true | Open the standalone window when the server starts |
cleanProfileOnUnload | false | Delete the dedicated browser profile directory when the plugin unloads. Left false, the profile is kept so the window starts warm |
HTTP endpoints
The plugin's browser half talks to these routes; they are also usable from scripts. Mutating routes reject a cross-site Origin with 403 and bodies larger than 4 KB.
| Route | Method | Purpose |
|---|
/desktop-window/status | GET/POST | { open, auto } |
/desktop-window/toggle | POST | Open the window, or close it when open |
/desktop-window/set-auto | POST | { auto: boolean } → persists the preference |
/desktop-window/manifest.webmanifest | GET | The injected web manifest |
/desktop-window/<icon>.png | GET | Served icon bytes |
Platform support
| Platform | Auto-open & button | Closing the window | Notes |
|---|
| Windows 10/11 | yes | full process-tree teardown (taskkill /T /F) | primary target |
| macOS | yes | SIGTERM, escalating to SIGKILL after 2 s | Chrome, Edge, Chromium, Brave, Vivaldi, in /Applications and ~/Applications |
| Linux | yes | SIGTERM, escalating to SIGKILL after 2 s | Chrome, Edge, Chromium, Brave from the usual /usr/bin and /bin locations |
Every platform launches the same Chromium --app window; only browser discovery and
process teardown differ. Windows and macOS have dedicated code paths covered by tests;
Linux shares the POSIX path but has not been exercised on a real machine.
Known limitations
- The taskbar or Dock icon shows the browser, not the whale. The window is Chromium in
--app mode, so Windows groups its taskbar button under Edge/Chrome and shows the browser icon there, and macOS likewise shows the browser in the Dock. The title bar, the tab icon, and Alt+Tab / ⌘-Tab use the injected favicon. For the whale everywhere, install the page as an app: Edge menu → Apps → Install this site as an app, or in Chrome ⋮ → Cast, save, and share → Install page as app (macOS: ⋮ → Save and share → Install page as app). Both consume the manifest this plugin injects.
- Closing the window does not quit
dsh — by design.
- This is a browser window, not an embedded webview.
- The dedicated profile persists under the platform temporary directory (
%TEMP%\dsh-desktop-window on Windows, $TMPDIR/dsh-desktop-window on macOS), which is why the window starts warm. Set cleanProfileOnUnload to true to remove it on unload.
- Opening the window does not authenticate it. Mutating routes reject cross-site browser requests, but a local non-browser process is not challenged.
Development
Development rules, build details, and the version-adaptation checklist are separate documents:
- DEVELOPMENT.md — architecture, build, test strategy, release process;
- ADAPTATION.md — the DSH compatibility matrix and what to re-verify on a new DSH release.
Both documents must be updated with every change to this project.
License
MIT
