dsh-dock

_{🌐 中文 · English}

---

_{After the window opens the whale settles into the notification area: hover for server status, left-click to reopen, right-click for restart / autostart / exit — "restart the server", several times a day, shrinks from a process-list hunt to one click.}

---

What problem does it solve

If you use DeepSeek Harness daily, this probably repeats every day: open a terminal → npx dsh web --no-open → copy the token URL → paste it into a browser → press F11. Want a restart? Get-NetTCPConnection -LocalPort 3080 to find the PID, Stop-Process, then do the whole thing again.

The problem isn't that any single step is hard — it's that every step needs your hands. "Restart" happens several times a day, yet it's buried in the process list.

DSH Dock collapses the ritual into three entry points plus one resident status seat:

• One black whale icon on the desktop: server running → opens full-screen directly; server down → starts it silently and opens the window once ready; after opening, the whale settles into the system tray (can be turned off in the settings page).
• The tray whale (status entry, v0.4.0): hover shows "running / starting / stopped"; left-click reopens instantly; right-click menu = Open DSH · Restart Server · ☑ Start on boot · Full Exit.
• One "Whale Bay" menu in the sidebar: Surface (reload the UI, server untouched) / Migrate (restart the server — it always returns) / To the Bay (full exit, two-step confirm) — three actions borrowed from the whale's behavior repertoire, with the functional legend on hover. Settings is not in the menu — it stays at the native sidebar-footer entry, where the dsh-dock settings page (tray residency / start on boot) lives inside the Settings dialog.
• Exit cleans up after itself: Full Exit → the page closes itself → the server stops gracefully (whole-tree dispose) → sessions persist in real time; double-click the whale next time and pick up where you left off.

All plugin chrome (menu, settings page, exit overlay) follows the harness display language and re-renders live on a language switch (中文 menu shown in menu.png).

---

Results and live tests

Every image and number in this section is a real run artifact; the re-capture recipes live in the repo: docs/screenshots/CAPTURE.md.

Desktop app (double-click to launch)

After install, a "DSH Harness.exe" app appears on the desktop — double-clicking it is the whole entry (not a shortcut): server running → silent full-screen window; server down → the whale card takes over. The icon is the black whale (compiled into the exe; the shot above is the embedded 512×512 frame of assets/dsh-dock.ico, transparent background).

Sidebar "Whale Bay" menu (pops upward on click)

As of v0.5 the sidebar footer gains a three-wave icon button, "Whale Bay" (鲸湾) — the whale's rest-and-reset bay. It opens three actions borrowed from the whale's behavior repertoire: Surface (reload the UI — same effect as Ctrl+Shift+R, server untouched), Migrate (restart the server; it always returns), and To the Bay (full exit; two-step accidental-click guard, auto-disarms after 4 seconds). The menu keeps the metaphor pure — the functional legend rides the native hover tooltip and aria-label — and its icons (wind / migratory loop / moon) compose one small seascape with the wave trigger. The menu renders as a plain neighbor entry in the sidebar footer slot — no native DOM is moved or hidden — so it coexists with every other sidebar plugin (including dynamic Cordis plugins); its labels follow the harness display language live (中文: 换气 / 洄游 / 归湾).

Both are real v0.5 captures: the open Whale Bay menu (Surface / Migrate / To the Bay) and the armed two-step state (确认归湾?) after one click on "To the Bay". 中文 menu shown in menu.png. Re-capture in one command: node scripts/capture-whale-menu.mjs --en.

Tray whale (resident status entry, v0.4.0)

After opening the window the whale stays in the notification area: hover tooltip shows the server state; left-click reopens instantly; Restart Server / ☑ Start on boot live on the right-click menu; the tray's "Full Exit" is a single click (the right-click itself is the intent; the sidebar keeps its two-step guard). A named mutex guarantees at most one icon at any time — whichever of double-click / boot autostart / tray arrives first stays.

Tray right-click menu (top to bottom): Open DSH · Restart Server · ☑ Start on boot · Full Exit (single click).

Settings page ("DSH Dock（启动器）" section in the Settings dialog, v0.4.0)

All plugin settings in one place: the native "Settings" entry at the sidebar bottom → the "DSH Dock（启动器）" section in the left list → two toggles (Tray residency / Start on boot, each with a description). Their state stays in sync with the tray's right-click checkmark in real time.

Cold-start card (double-click the whale while the server is down)

A dark translucent rounded glass card; the centered black whale is a breathing light (brightness pulsing 35%↔100% on a cosine curve — no progress bar, no caption). On failure the whale stops breathing, the text turns red, and the log path plus a close button appear.

Screenshot provenance: the card is a real render of the prebuilt launcher (assets/dsh-dock-launcher.exe) under a demo config (temporary launcher.ini pointing at the real server on 3080 + a dead token line, read-only probing, no real log writes), captured in the "connecting" state. Re-capturable via pwsh -File scripts/capture-demo-card.ps1.

Several DSH installs? Pick on the cold card (since v0.3.3)

With several dsh installs (global / npx cache / source checkouts), the cold-start card draws its own candidate list (version · source · path) and starts the one you pick; no click for 10 seconds auto-uses the last successful choice (or the highest version); switching never rewrites a single file; with zero candidates it offers a one-click npx fetch. Re-capturable via pwsh -File scripts/capture-multidsh.ps1.

Measured numbers (this machine)

This machine = Windows 11 + 360 AV; method in Verification and testing. Engine-related timings will differ on other machines; the plugin's own overhead stays ~0.75s.

---

Quick start

Prerequisites: Windows 10/11 + the DSH web profile + Edge (falls back to the default browser if missing). No Node setup needed — the installer auto-detects a usable Node (≥ 22.19).

dsh plugin --profile web add github:UnknowCao/dsh-dock#v0.8.0

After restarting the server there is nothing to do: on activation the plugin extracts its parameters from the environment (its own listening port, Node path, start command); within ~2s the desktop gets "DSH Harness.exe" (black whale icon) and the sidebar gets the "Whale Bay" menu. Daily routine: double-click the whale to open, exit from the menu. "Full Exit" asks the host to dispose the whole Cordis tree and treats the process.exitCode the host assigns as the "disposal finished" signal, then finishes itself (cost = real dispose time + 0.25s, see stop.log); a host that never signals falls back to a 6s ceiling, and only hosts without ctx.appExit fall back to the legacy hard kill.

Upgrading from v0.4? v0.5 touches only the sidebar menu: renamed to "Whale Bay", narrowed to Surface (reload) / Migrate (restart the server) / To the Bay (full exit), each with a hover legend (Settings returns to the native sidebar-footer entry; the settings page itself is unchanged); fixes the page freeze when another plugin (e.g. the Cordis panel badge) also occupies the sidebar footer slot; menu labels now follow the harness language live. Tray, restart, autostart and the settings page are unchanged.

For customization (rename / different port), tell the agent:

Rename the DSH desktop app to XX / install it on port 3081

Uninstall: delete the desktop DSH Harness.exe and ~\.dsh\launcher\; remove the dependency and bundle entries from the profile. Uninstalling never deletes files automatically.

---

What it can do

---

Compared to doing it by hand

How it differs from other launcher approaches

The dsh-plugin ecosystem already has several desktop clients and launchers (see the indexes at the bottom). dsh-dock's bet: not another program — a plugin inside the dsh you already have.

In one line: if you already use dsh's Web UI and want "desktop double-click + tray residency + a clean exit" rather than yet another client — this is it.

More plugins in the ecosystem indexes: dsh-plugin topic · Oh-My-DSH · awesome-deepseek-harness.

---

Security boundaries

• Loopback only: the exit endpoint /launcher/api/stop accepts local/trusted-origin + same-origin requests only; cross-site requests get a flat 403 — nothing exposed externally
• Never touches session data: exit relies on DSH's real-time persistence; the plugin does not read or write sessions in $DSH_HOME
• No credentials read or sent: the token only flows between the local log and the local Edge launch arguments
• No wrong kills: exit uses "own-PID kill + netstat fallback"; if the manifest points at some other process, it never acts
• Zero lifecycle scripts on install: package.json has no preinstall/install hooks — installing runs no arbitrary code; if a same-named desktop file exists that is not this plugin's, it refuses to overwrite and reports loudly
• Full Exit has a two-step confirmation; startup failures surface the reason plus the log path
• No resident background service (as of v0.4.0): the double-click chain remains a single native exe; the tray residency is a visible, user-toggleable whale process (on by default) with loopback-only traffic and no credential access. Turning "tray residency" off means a double-click no longer leaves a resident tray (back to the v0.3.x short-lived process model) — with two caveats: start-on-boot IS exe --boot (silent residency + server preheat), and turning the toggle off does not evict a tray that is already resident (it disappears at the next full exit + relaunch)
• Autostart writes only the per-user registry: boot autostart is one dsh-dock value under HKCU\Software\Microsoft\Windows\CurrentVersion\Run (pointing at the suite exe with --boot) — no admin rights needed, removing it deletes the entry
• Settings routes share the same fence: /launcher/api/settings/{get,set} goes through the same loopback/same-origin trust check as the exit and restart endpoints; cross-site gets a 403

Known limitations (stated up front, not defects)

• Windows only (macOS/Linux planned)
• Manually started server + a fresh Edge profile: no token in the log to grab — log in once with a token URL (login state lasts 30 days)
• "Full Exit" from an ordinary browser tab may be blocked from auto-closing → an overlay explains it; close manually once. Windows opened by the desktop app close automatically
• The web chrome (menu / settings page / exit overlay) follows the harness display language live; the native tray exe is not localized yet (Chinese labels; OS-driven context menu styling)
• Sidebar "Migrate" (restart server) needs the resident tray to execute (the host cannot restart its own death); when no tray is present it prompts you to double-click the whale first
• Tray "Restart Server" deliberately closes every dsh-dock window before booting — their tokens died with the old process, so a refresh cannot resurrect them

---

File structure

dsh-dock/
├── index.js                 # Host: launcher_install tool + exit/settings/restart routes + baked launcher.ini/start-server.cmd + desktop exe placement
├── client.js                # Client: sidebar "Whale Bay" menu (plain neighbor entry + React portals) + "DSH Dock（启动器）" settings page in the Settings dialog + exit auto-close
├── cordis.patch.yml         # bundle patch: inserts the plugin row into the composition
├── package.json             # package manifest (name: dsh-dock)
├── regen-launcher.mjs       # maintenance: regenerate the launcher suite outside the harness
├── candidates.mjs           # shared: multi-DSH detection + suite materialization (activation + T2 refresh)
├── dsh-dock-refresh.mjs     # cold-start refresh script (T2, run by the exe via node; deployed next to candidates.json)
├── dsh-dock-v0.8.0-release-notes.md  # v0.8.0 release notes (adaptive tray pacing / exactly-once restart / publish-gate fixes)
├── dsh-dock-v0.7.0-release-notes.md  # v0.7.0 release notes (user-pointed extra install paths)
├── dsh-dock-v0.6.0-release-notes.md  # v0.6.0 release notes (adaptive candidate discovery)
├── dsh-dock-v0.5.0-release-notes.md  # v0.5.0 release notes (Whale Bay redesign / coexistence / live locale)
├── dsh-dock-v0.4.0-release-notes.md  # v0.4.0 release notes (the tray/restart/autostart/settings story)
├── src/
│   └── DshDockLauncher.cs   # the launcher's single implementation: fast-path silent window + cold card + health gate + exit races + single-instance lock + tray
├── assets/
│   ├── dsh-dock-launcher.exe # prebuilt launcher (output of scripts/build-launcher.ps1, committed — installs need no compiler)
│   ├── dsh-dock.ico         # desktop app whale icon (compiled into the exe)
│   └── whale.png            # card whale source bitmap (whiteness remap)
├── docs/
│   └── screenshots/
│       ├── desktop-shortcut.png    # desktop app icon close-up (black whale 512×512, transparent)
│       ├── menu.png / menu-en.png  # Whale Bay menu captures (v0.5, scripted)
│       ├── menu-exit-armed.png     # "Full Exit" two-step confirmation state
│       ├── tray-menu.png           # tray right-click menu, real capture
│       ├── settings-section.png    # the "DSH Dock（启动器）" section inside the Settings dialog
│       ├── cold-card.png           # cold-start card, real capture (re-recorded under the demo config)
│       ├── cold-card-multidsh.png  # the multi-DSH candidate picker, real capture
│       └── CAPTURE.md              # re-capture recipes (manual menu shots + scripted runs)
├── scripts/
│   ├── build-launcher.ps1        # compile src/DshDockLauncher.cs → assets/dsh-dock-launcher.exe (dev-time)
│   ├── capture-demo-card.ps1     # cold-card re-capture: demo ini + dead token → burst-shoot, pick the brightest whale phase
│   ├── capture-multidsh.ps1      # multi-DSH picker re-capture
│   ├── capture-whale-menu.mjs    # Whale Bay menu + settings page one-command re-capture (CDP-driven Edge, incl. language switch + restore)
│   └── verify-health-gate.ps1    # regression: a dead token (401) must never open a window
├── test/
│   ├── candidates.smoke.mjs      # offline unit tests: candidate scanning (M1 adaptive + M2 extra roots)
│   └── exit-path.smoke.mjs       # offline unit tests: exit orchestration (signal / ceiling / throw / exactly-once)
├── LICENSE
├── README.md                # Chinese README (primary)
└── README.en.md             # this file

On install, generated under ~\.dsh\launcher\ (runtime artifacts, not committed):