dsh-daemon

August 29, 2026 · View on GitHub

中文 | English

Register the DeepSeek Harness web server (dsh web) as an auto-start, self-healing background service.

After install, dsh web:

  • starts automatically on login (LaunchAgent RunAtLoad / systemd WantedBy=default.target / cron @reboot),
  • restarts automatically after sleep/wake,
  • self-heals: a watchdog health-checks http://127.0.0.1:<port>/health every 3 s (configurable) and restarts the server after 3 consecutive failures,
  • survives this session: the watchdog is a standalone generated script, not an in-memory plugin.

The currently running session is never touched by install/uninstall.

For the account map (npm scope / GitHub account) see CONTEXT.md.

Usage

Option A — install with dsh plugin, mount as a composition row

  1. Install the package into the web profile with the official plugin manager (runs pnpm in the profile directory, so the loader can resolve it; a plain global install is not enough — see below):

    dsh plugin --profile web add @chenkai114/dsh-daemon

    (needs pnpm on PATH — enable it once with corepack enable.)

    Why not just npm install -g? The loader imports name: rows with Node's ESM resolution anchored at the profile directory (~/.dsh/profiles/web/); the global node_modules is not on that resolution chain (and NODE_PATH does not apply to ESM). The profile's own node_modules — managed here by pnpm — is what makes the package reachable.

  2. Restart dsh web. The package declares a dsh.bundle manifest, so dsh plugin add automatically appends it to dsh.profile.bundles and it mounts as a bundle layer at boot — you do not need (and must not) also insert the same row manually into ~/.dsh/profiles/web/cordis.patch.yml, or boot fails with duplicate loader entry id: dsh-daemon.

    The seven dsh_daemon_* tools then become available to every agent — just ask the agent to run dsh_daemon_install.

To upgrade later: dsh plugin --profile web update @chenkai114/dsh-daemon (plus a restart).

⚠️ Upgrading from v0.1.8 or earlier: if you previously followed the old docs and added a manual - insert: dsh-daemon row to ~/.dsh/profiles/web/cordis.patch.yml, you must delete that row (keep anything else in the file) after upgrading — otherwise the bundle layer and the manual layer insert the same id: dsh-daemon twice and dsh web fails to boot with duplicate loader entry id. Restart after deleting it.

Permissions: the daemon manages per-user system services (LaunchAgent plists, state files under $DSH_HOME), so the plugin requests danger-full-access for its file and command operations. On a deployment that denies escalation the tools fail with sandbox denials.

Option B — dynamic Cordis plugin (no install)

Paste the content of lib/index.js into the code.host field of cordis_define and run it. This is how the plugin is developed and verified in a live session: the sandbox supplies the harness global, and the file ends with return plugin;.

Port

Default port is the currently listening webServer port (usually 3080), then DSH_WEB_PORT, then the explicit port tool argument. After changing the port, run dsh_daemon_reinstall.

Architecture

The daemon is a watchdog supervisor made of three parts.

1. Platform registration

A per-user service that starts the watchdog at login and keeps it alive:

PlatformMechanism
macOSLaunchAgent ~/Library/LaunchAgents/com.deepseek-ai.dsh-watchdog.plist — ProgramArguments=[node, watchdog.js], RunAtLoad, KeepAlive{SuccessfulExit:false}, ThrottleInterval=10, environment carries DSH_WEB_PORT and DSH_HOME. Loaded with launchctl load -w.
Linuxsystemd user unit ~/.config/systemd/user/dsh-watchdog.service — Type=simple, Restart=always, RestartSec=10, StartLimitIntervalSec=0; enabled with systemctl --user enable --now. Falls back to a cron @reboot entry when systemd is unavailable.
WindowsVBS launcher + Task Scheduler — task DshWatchdog (XML in $DSH_HOME/daemon/dsh-watchdog-task.xml, UTF-16LE) runs wscript.exe //B dsh-watchdog.vbs at logon; the VBS sets DSH_WEB_PORT/DSH_HOME and starts node watchdog.js hidden. RestartOnFailure PT1M/999, MultipleInstancesPolicy=IgnoreNew. Registered with schtasks /Create.

Windows support is implemented mirroring the macOS/Linux behavior (the plugin's shell layer switches to PowerShell, which is the DSH shell executor on win32) but has not yet been verified on a real Windows machine.

2. The watchdog loop

The generated standalone script $DSH_HOME/daemon/watchdog.js (dependency-free, runs on any Node ≥ 18, no session required):

  • writes its PID to .dsh-watchdog.pid; SIGINT / SIGTERM / SIGHUP clean up and exit; a single-instance lock refuses duplicate watchers;
  • at startup, launches the web server (node <dsh> web --port <port>, detached, output to logs/dsh-web.log) if http://127.0.0.1:<port>/health is not OK;
  • then every 30 s (configurable via DSH_DAEMON_HEALTH_INTERVAL):
    • skips when .daemon-stopped exists (user paused monitoring) or .daemon-restart.lock is fresh (< 120 s, a restart is in progress);
    • restarts the server when a tick gap exceeds 90 s (sleep/wake);
    • restarts the server after 3 consecutive failed health checks;
    • exits when the .daemon-installed marker disappears (uninstalled);
  • logs to logs/watchdog.log (5 MB × 3 rotation).

3. Daemon-aware start / stop

  • dsh_daemon_stop writes .daemon-stopped (the watchdog will not restart the server) and stops the daemon-managed server if one is running.
  • dsh_daemon_start clears the flag, makes sure the watchdog runs, and launches the server if it is unhealthy.

Tools

The plugin is Host-only and registers seven model-callable tools:

ToolWhat it does
dsh_daemon_installGenerates watchdog.js + state files, writes the LaunchAgent plist (or systemd unit / cron entry, VBS + Task Scheduler on Windows), starts the watchdog now. Optional port argument.
dsh_daemon_uninstallStops the watchdog, unloads and deletes the platform registration, removes all state files.
dsh_daemon_reinstalluninstall + install (use after upgrading dsh or changing the port; also regenerates the watchdog with the current auto-update configuration).
dsh_daemon_statusInstalled since, port, local/latest versions, update state, watchdog PID/liveness, manual-stop flag, server health, last log lines.
dsh_daemon_startClears the stopped flag, ensures the watchdog runs, launches the server if unhealthy.
dsh_daemon_stopWrites the stopped flag (watchdog will not restart), stops the daemon-managed server if one is running. Never touches the current session.
dsh_daemon_updateCheck for a newer version (apply: false, default) or download and apply it (apply: true). Also the manual entry point for major version changes.

Command line (dsh-daemon)

dsh_daemon_install also writes a thin dsh-daemon command into the node bin directory (PATH), so the daemon is controllable from a terminal without opening the GUI:

CommandWhat it does
dsh-daemon statusSame status as the GUI tool.
dsh-daemon restartImmediately restarts dsh web (kills the process on the port and launches a new one; no waiting for the health loop), verified healthy before returning.
dsh-daemon startClears the stopped flag, starts the watchdog if missing, launches the web server if unhealthy.
dsh-daemon stopWrites the stopped flag and kills the web server (including a manually started one).
dsh-daemon updateCheck the registry (--apply to download and apply).
dsh-daemon install / uninstall / reinstallRegistration operations, executed by the plugin through its /dsh-daemon/command route — these need dsh web to be up (the supervision commands above work standalone via the watchdog script).
dsh-daemon helpUsage.

restart/stop interrupt all open sessions, exactly like a manual pkill — the watchdog relaunches the web server on the next health cycle if the direct launch fails.

State files ($DSH_HOME/daemon/, $DSH_HOME defaults to ~/.dsh)

daemon/
├── watchdog.js            # generated watchdog script (standalone, no deps)
├── .daemon-installed      # install timestamp marker
├── .daemon-port           # supervised port
├── .daemon-stopped        # pause flag: watchdog will not restart the server
├── .daemon-restart.lock   # restart-in-progress marker (TTL 120 s)
├── .dsh-watchdog.pid      # watchdog PID
├── .dsh-web.pid           # daemon-managed web server PID
├── .daemon-update.lock    # update-in-progress lock (concurrency guard)
├── .daemon-update-pending # downloaded update awaiting a restart to activate
├── .daemon-update-check.json  # last update check result (status display)
├── dsh-watchdog.vbs       # Windows: hidden wscript launcher
├── dsh-watchdog-task.xml  # Windows: Task Scheduler XML (UTF-16LE)
└── logs/
    ├── watchdog.log       # watchdog log (5 MB × 3 rotation)
    └── dsh-web.log        # web server stdout/stderr when launched by the watchdog

Auto-update

The watchdog checks the npm registry at startup and every 6 h and updates @chenkai114/dsh-daemon in the profile directory with pnpm:

  • Version policy: same-major versions (0.1.3 → 0.1.4, 0.2.x → 0.2.y) update automatically; a major change (0.x → 1.x, 1.x → 2.x, …) is only reported and requires the manual dsh_daemon_update tool.
  • Update modes (DSH_DAEMON_UPDATE_MODE):
    • restart (default): after downloading, the watchdog polls the plugin's /dsh-daemon/activity endpoint (agent turns + background jobs) every 30 s and restarts dsh web only after it has been idle for the quiet window — an in-progress conversation or job defers the restart until it finishes. If the endpoint is unreachable (plugin not mounted), the restart still happens after DSH_DAEMON_DEFER_MAX. Fully unattended.
    • download: the new package is installed in the profile and a pending marker is written; the update activates on the next natural dsh web restart. No session is ever interrupted — the user decides when the update takes effect.
  • Failure safety: registry unreachable, pnpm failure, or a version mismatch after update only writes a log line and the check state; the old package stays installed (pnpm's store keeps it, so dsh plugin --profile web add @chenkai114/dsh-daemon@<old> rolls back).

Configuration is captured at dsh_daemon_install/reinstall time and embedded into the generated watchdog script:

Env varDefaultMeaning
DSH_DAEMON_AUTO_UPDATE10 disables the checks
DSH_DAEMON_UPDATE_INTERVAL6hcheck interval (ms/s/m/h/d)
DSH_DAEMON_UPDATE_MODErestartrestart or download
DSH_DAEMON_QUIET_WINDOW5midle time required before a restart-mode restart
DSH_DAEMON_DEFER_MAX15mmax wait for the activity endpoint before restarting anyway
DSH_DAEMON_NPM_REGISTRYhttps://registry.npmjs.orgregistry used for checks and pnpm update
DSH_DAEMON_PROFILEwebprofile directory holding the plugin
DSH_DAEMON_HEALTH_INTERVAL30shealth-check interval of the watchdog loop (ms/s/m; 3 failures trigger a restart)
DSH_DAEMON_OPEN_BROWSER1when 0, never auto-open the browser even when a new-dsh launch token is detected (the URL is still written to ~/.dsh/daemon/.web-auth-url and the watchdog log for manual access)
DSH_DAEMON_CLI_DIRnode bin dirdirectory for the generated dsh-daemon CLI (tests/sandboxed installs point it at a temp dir to avoid polluting the real PATH)
DSH_DAEMON_NO_SYSTEMunsetwhen 1, skips system-level registration (launchd/schtasks/systemd) — test/sandboxed installs never touch the host's services; the watchdog is still started directly
DSH_DAEMON_TRUSTED_HOSTunsetcomma-separated --trusted-host list (e.g. dsh.example.com,192.168.5.5:8080). When dsh web is reached through a reverse proxy (nginx) the Host header is the public hostname and the /api browser-trust fence would reject it with 403 — set this to make dsh web trust those Hosts

The auto-update logic lives in the generated watchdog.js; after upgrading to a version with new update logic, run dsh_daemon_reinstall once to regenerate it.

Verification

All of the following were verified end-to-end against the real plugin code:

  • install → plutil -lint OK, launchctl list shows the agent, watchdog logs watchdog started (PID …, port 3080) / web server already healthy on port 3080;
  • on an empty port the watchdog launches a real dsh web --port <port> at startup (health OK on the new port);
  • self-heal: after SIGKILL of the managed server → health check failed (1/3 → 2/3 → 3/3) → failure threshold reached, restarting web server → new process serves 200;
  • launchd KeepAlive: SIGKILL of the watchdog → launchd restarts it within ~11 s;
  • single-instance guard: running watchdog.js a second time exits immediately;
  • stop writes the pause flag and kills only the daemon-managed server; start clears it; uninstall removes launchd registration, plist, state files and frees the port; status reflects every state.

Local test

node test/harness.js dsh_daemon_status          # static package mode
DYNAMIC=1 node test/harness.js dsh_daemon_status # dynamic sandbox mode

The harness runs the real plugin code with real bash/fs and invokes the tool for real.

v0.1.19 — dsh web token-auth adaptation (seeding the ?token= launch token)

Since dsh ≥ 0.1.2-alpha.1 (harness commit 3e24087bfa) dsh web generates an in-process random token at startup and prints dsh web: http://127.0.0.1:<port>/?token=...: the browser must visit that URL once to seed a 30-day host-only Cookie (the signing key persists across restarts; a bare 3080 visit with no Cookie → 401). The watchdog used to launch with --no-open, so the user's browser never got a Cookie and the daemon-managed web was 401.

Adaptation: after launching, the watchdog extracts the current run's token URL from dsh-web.log (the web process stdout), then:

  • ?token= detected (new dsh) → open the default browser once to seed the Cookie (same as manual dsh web); if opening fails (headless), the URL is already on disk for manual access;
  • not detected (old dsh) → status quo (--no-open, never touch the browser);
  • the URL is always written to ~/.dsh/daemon/.web-auth-url (0600, overwritten each launch) and shown by dsh-daemon status;
  • DSH_DAEMON_OPEN_BROWSER=0 disables the auto-popup (disk + log only);
  • the scan is anchored to the pre-launch file offset: the append-only POSIX log never reuses an old run's dead token (the LAST dsh web: line of the current run's segment wins; win32 Start-Process overwrite semantics fall back to reading the whole file, and dsh-web.log.1 — the previous process — is never read);
  • the probe is cross-version stable: dsh web: http://... has been printed by every dsh version, old and new differ only in whether the URL carries ?token= — so ?token= presence is the judge, robust to future versions;
  • reverse insurance: if a new dsh's token line is slow to appear the watchdog KEEPS WAITING (fast poll 15s@250ms then a slow retry phase 75s@5s) instead of dismissing it as "no token" (treating a probe failure as old dsh would miss the auth); on total timeout it only logs and the next launch retries;
  • popup throttle: the token changes on every start but the 30-day cookie outlives any single token (persistent signing key), so the browser is not re-opened when the URL equals the last recorded one (.web-auth-url is still refreshed for manual access); SSH_CONNECTION/SSH_TTY non-empty suppresses the popup entirely (never open a browser on a remote host's desktop);
  • the version gate mirrors the --no-open pattern (DSH_TOKEN_AUTH_MIN = 0.1.2-alpha.1, module-scope functions inlined into the watchdog via toString(), re-decided at every launch) and only skips the poll when the installed dsh is known to predate token auth; the URL-line probe is the authoritative detector.

v0.1.18 — Windows black-box fix: hidden console, not no console; start waits for health

On Windows the watchdog spawns dsh web, pnpm, netstat, etc. with CP.spawn(..., { detached: true }), and Node gives detached children their own console window by default (the watchdog itself runs hidden — VBS / Task Scheduler — and has no console), so every launch/restart flashed black boxes. Once v0.1.17 fixed the --no-open restart loop, the black boxes became the visible problem.

Mechanism choice (deepseek-harness discussion #1564 / #810): dsh web must NOT be launched with windowsHide (CREATE_NO_WINDOW) — a console-less host forces every child it spawns to allocate a new visible console, and CREATE_NO_WINDOW kills the Windows ACL sandbox's restricted-token children with 0xC0000142 (DLL initialization failed). The correct approach is to give dsh web a hidden console (STARTF_USESHOWWINDOW + SW_HIDE, keeping dwCreationFlags=0 — on Windows implemented via Start-Process -WindowStyle Hidden, matching the dsh-daemon start direct-launch path): dsh web has no visible window itself, and its console children inherit that hidden console, so nothing flashes at any level.

  • on win32 the watchdog now launches dsh web through powershell.exe -Command "Start-Process -FilePath <node> -ArgumentList ... -WindowStyle Hidden -RedirectStandardOutput <web.log> -PassThru" (the powershell wrapper itself uses windowsHide — short-lived, normal token, safe); the wrapper writes the PID file and the watchdog polls for it; ⚠️ the wrapper must NOT use detached: true — Node maps it to DETACHED_PROCESS on Windows, which hangs the Start-Process command (no PID file, child never starts; reproduced empirically). Start-Process children are independent processes anyway, so the short-lived wrapper needs no detachment; Start-Process redirects with OVERWRITE semantics, so before each launch the old dsh-web.log is rotated to dsh-web.log.1 (the previous run's crash output survives; the log stays bounded — current + one previous run, never unbounded);
  • the watchdog's other short-lived children (self-spawn, pnpm, idle-restart waiter, netstat/lsof probes) keep windowsHide: true — safe under a normal token, consistent with the discussion's subprocess-local treatment;
  • dsh-daemon start now polls for health after launching (like restart does, up to ~13 s) before returning — previously start returned while dsh web was still booting, the next status looked unhealthy, and users ran start again, which killed the still-booting first instance via the PID file;
  • template assertions: every spawn site carries windowsHide, and the win32 web launch must go through Start-Process -WindowStyle Hidden (regression guard).

Note: the DSH-internal layer from #1564 (two spawns in dsh-sandbox-windows-acl dwFlags:256→257 + wShowWindow:0; windowsHide:true in dsh-subprocess-local) is a patch to dsh itself, not this repo; re-apply it after upgrading dsh (the community script Culeot/dsh-no-console-flash is idempotent).

v0.1.17 — pass --no-open only when the dsh version supports it

Since v0.1.16 the watchdog launched dsh web --port <port> --no-open, but --no-open only exists in @deepseek-ai/dsh 0.1.0-rc.8 (dsh-web-app 0.1.0-rc.8, which also introduced default browser opening). Older CLIs reject the flag with unknown option '--no-open' and exit immediately, so the watchdog fell into a restart loop: launch → instant death → failed health check → relaunch, and web never came up.

  • The watchdog reads the dsh package package.json version at every launch and appends --no-open only when it is ≥ 0.1.0-rc.8 (semver, including prerelease ordering); an unknown/unreadable version conservatively skips the flag — the server still starts, and pre-rc.8 dsh never opened a browser anyway, so nothing is lost;
  • the dsh-daemon start direct-launch commands (Windows Start-Process / Unix nohup) make the same version-based decision;
  • the gate is a single module-scope implementation; the watchdog inlines the exact same code via Function.prototype.toString(), so dsh upgrades or downgrades take effect at the next launch without reinstalling the daemon;
  • new test/version-gate.test.js unit tests (run by npm test).

v0.1.16 — health check, browser pop-ups, and env forwarding

  • /health route: the watchdog health-checks http://127.0.0.1:<port>/health every 30 s, but deepseek-harness's web server has no such route (unknown paths 404), so a running web was reported unhealthy forever. The plugin now registers /health itself, returning 200 {"ok":true} — plugin up means web up, and the check is reliable.
  • --no-open: daemon-managed web restarts (auto-update, self-heal) no longer pop a browser tab; manual dsh web still opens by default.
  • Env forwarding: dsh-daemon install/uninstall/reinstall execute in the web process via the /dsh-daemon/command route, so DSH_DAEMON_* variables from the invoking shell never reached the plugin. The CLI wrapper now collects all DSH_DAEMON_* from the current shell and forwards them with the request, so DSH_DAEMON_UPDATE_INTERVAL=1m dsh-daemon reinstall configures the watchdog correctly.

v0.1.15 — test/sandboxed installs no longer touch the host

Test harness installs with a temp HOME used to pollute the real environment; two switches close that gap:

  • DSH_DAEMON_CLI_DIR: overrides where the generated dsh-daemon CLI is written (default: node bin) — tests point it at a temp dir so the real wrapper on PATH is never overwritten;
  • DSH_DAEMON_NO_SYSTEM: when 1, skips system-level registration (launchd/schtasks/systemd) so a test install cannot steal the system service label and leave the real daemon dead. The harness sets both by default.

v0.1.14 — restart is now the default auto-update mode

The default of DSH_DAEMON_UPDATE_MODE changed from download to restart: when unset, after an update is downloaded the watchdog restarts dsh web on its own once it is idle (fully unattended, never interrupting an in-progress session). Set it explicitly to download when you want to control when the update takes effect.

v0.1.13 — watchdog regenerated automatically after auto-update

Previously auto-update only refreshed the npm package; the already-generated watchdog.js (a one-time artifact from install time) never picked up the new generator logic — a manual dsh_daemon_reinstall was required. Since v0.1.13:

  • the plugin version is embedded into the generated watchdog (GEN_VERSION);
  • on every plugin boot the script's GEN_VERSION is compared with the installed package version; when they differ (after an auto-update, or a manual package upgrade) the plugin regenerates watchdog.js and the CLI wrapper and restarts the watchdog process;
  • so after an auto-update (user restarts web in download mode, or the idle-aware restart does it in restart mode) or a manual upgrade + web restart, the watchdog catches up with the new version on its own — no manual dsh_daemon_reinstall;
  • test/development loads can skip the sync with DSH_DAEMON_AUTOREGEN=0.

v0.1.12 — Windows console-flash regression fix

v0.1.11 added windowsHide: true (Windows CREATE_NO_WINDOW) to the watchdog's launch() and other spawns. The side effect: the dsh web process lost its console handle, so any child it spawns afterwards (git, tool executions, …) gets a visible console window on Windows — frequent console flashes while the server runs (issue #1).

v0.1.12 removes all four windowsHide flags and restores the v0.1.10 model: the watchdog is started by VBS shell.Run ..., 0 (SW_HIDE) with its own hidden console, the web process inherits it, and web's children inherit in turn — the whole chain stays windowless (verified on v0.1.10).

Note: if console windows still flash during plugin install/command execution (the DSH sandbox/subprocess path, not this plugin's watchdog), that is a deepseek-harness Windows console-handling issue, not this plugin — see discussion #1564 and the Culeot/dsh-no-console-flash patch.

License

MIT