Introduction

In DSH’s agent workflow, dsh web is often the entry point for local development, testing, and agent collaboration. Manually starting dsh web in the foreground has a significant drawback: the service may become unavailable after the terminal closes, the process exits abnormally, or the machine wakes from sleep. If you need to consistently access the local web service across multiple sessions, you have to repeatedly check the port, process, and log status.

dsh-daemon solves this problem: it registers dsh web as an auto-starting, self-healing background service. Below, we introduce its capabilities, installation methods, typical commands, and considerations regarding permissions and upgrades during deployment.

What is it

dsh-daemon is a DSH plugin used to register the DeepSeek Harness network service dsh web as a background service. It does not directly replace dsh web; instead, it generates a watchdog script around it and registers a system-level service according to the platform to keep the watchdog running.

The package information verifiable in this documentation is as follows:

  • Repository path: chenkai2/dsh-daemon
  • NPM package name: @chenkai114/dsh-daemon
  • Version: 0.1.20
  • License: MIT
  • Node requirement: >=18

peerDependencies requirements:

@deepseek-ai/cordis >=3
@deepseek-ai/dsh-tools >=0.1.0-rc.6

Its main value lies in: after installation, dsh web can be started as a user-level service. In scenarios such as abnormal exits, wake-from-sleep, or process unavailability, the watchdog will recover the service according to the strategy.

Core Capabilities

Platform Service Registration

dsh-daemon supports different platform service registration methods:

  • macOS: LaunchAgent, using RunAtLoad and KeepAlive
  • Linux: systemd user service; falls back to cron @reboot if systemd is unavailable
  • Windows: VBS + Task Scheduler; documentation notes that this has not yet been verified on real Windows machines

Among these, the Windows behavior can currently only be understood as “implemented but not verified on real machines,” and it is not recommended to treat it as a production-ready capability in an unverified environment.

Watchdog Self-Healing

After installation, the plugin generates an independent watchdog script. This script does not depend on the current DSH session and runs under user-level service management.

Verified watchdog behaviors include:

  • Performs a health check every 30 seconds
  • Restarts the service after 3 consecutive health check failures
  • Automatically restarts the service after waking from sleep
  • The watchdog is an independently generated script and does not depend on the current session
  • Maintains state files and logs under $DSH_HOME/daemon/

The default health check address is:

http://127.0.0.1:<port>/health

The port resolution order is: the webServer port currently listening (usually 3080), followed by DSH_WEB_PORT, and then the explicit port parameter provided by the tool.

Tools and CLI

The plugin registers 7 dsh_daemon_* tools for agent invocation:

  • dsh_daemon_install
  • dsh_daemon_uninstall
  • dsh_daemon_reinstall
  • dsh_daemon_status
  • dsh_daemon_start
  • dsh_daemon_stop
  • dsh_daemon_update

At the same time, the installation process generates a lightweight CLI: dsh-daemon. The following commands can be used in the terminal:

dsh-daemon status
dsh-daemon restart
dsh-daemon start
dsh-daemon stop
dsh-daemon update
dsh-daemon install
dsh-daemon uninstall
dsh-daemon reinstall
dsh-daemon help

Among them, dsh-daemon restart and dsh-daemon stop will interrupt all open sessions; if the direct start fails, the watchdog will restart the dsh web service in subsequent health cycles.

Automatic Updates

The watchdog checks the npm registry according to the configuration and attempts to update to the same major version.

Verified update strategies:

  • Same major version can be updated automatically
  • Major version changes will not update automatically; manual execution of dsh_daemon_update is required
  • The automatic update mode supports restart and download

In restart mode, the watchdog waits for a quiet window after the download is complete before restarting dsh web.
In download mode, the new package is installed to the profile and a pending marker is written; it takes effect when dsh web naturally restarts next time.

Installation and Enabling

Before installation, ensure that pnpm is already in the PATH. If not, you can enable it first:

corepack enable

The formal installation steps are introduced below.

1. Install Plugin to Web Profile

Use the official plugin installation command to install the package to the web profile:

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

This step installs the package to the dependency directory of the web profile. A global installation alone may not be resolved by the loader, because dependencies within the profile represent a more direct resolution path.

2. Restart dsh web

After installation, restart dsh web to make the plugin bundle effective.

3. Run dsh_daemon_install with Agent

In the session after restarting, ask the agent to execute:

dsh_daemon_install

This tool generates the watchdog script, state files, and writes the service registration according to the platform, and then starts the watchdog.

4. Check Installation Status

After installation, you can check the status using the agent tools:

dsh_daemon_status

You can also check using the CLI:

dsh-daemon status

Status information includes installation status, port, local/latest version, update status, watchdog PID, service health, recent logs, and more.

Typical Usage

Common Agent Tools After Installation

In an agent session, you can use the following tools:

dsh_daemon_status
dsh_daemon_start
dsh_daemon_stop
dsh_daemon_reinstall
dsh_daemon_update

If you change the port, use:

dsh_daemon_reinstall

If you upgrade to a version that includes new watchdog update logic, it is also recommended to run:

dsh_daemon_reinstall

This allows you to regenerate the watchdog script according to the current configuration.

Terminal CLI Usage

You can directly use the following commands in the terminal:

dsh-daemon status

To view the current daemon status.

To immediately restart dsh web:

dsh-daemon restart

To start or resume the service:

dsh-daemon start

To stop the managed service:

dsh-daemon stop

To check or apply updates:

dsh-daemon update

Commands for registration, uninstallation, and reinstallation:

dsh-daemon install
dsh-daemon uninstall
dsh-daemon reinstall
dsh-daemon help

Plugin Upgrade

Use the following command during upgrade:

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

Restart dsh web after upgrading.

Notes on Upgrading from Old Versions

If upgrading from v0.1.8 or earlier versions, you may have previously manually added similar content to ~/.dsh/profiles/web/cordis.patch.yml:

- insert: dsh-daemon

After upgrading, you must delete this line but keep the other content in the file. Otherwise, the bundle layer and the manual layer will insert the same loader entry, causing dsh web to report an error at startup:

duplicate loader entry id: dsh-daemon

After deleting it, restart dsh web.

Automatic Update Configuration

The following environment variables participate in watchdog behavior. Their specific values can be included in the generation script during installation or reinstallation.

DSH_DAEMON_AUTO_UPDATE
DSH_DAEMON_UPDATE_INTERVAL
DSH_DAEMON_UPDATE_MODE
DSH_DAEMON_QUIET_WINDOW
DSH_DAEMON_DEFER_MAX
DSH_DAEMON_NPM_REGISTRY
DSH_DAEMON_PROFILE
DSH_DAEMON_HEALTH_INTERVAL
DSH_DAEMON_OPEN_BROWSER
DSH_DAEMON_CLI_DIR
DSH_DAEMON_NO_SYSTEM
DSH_DAEMON_TRUSTED_HOST

Some key items among them:

  • DSH_DAEMON_AUTO_UPDATE: Whether to enable automatic update checks
  • DSH_DAEMON_UPDATE_MODE: Automatic update mode, can be restart or download
  • DSH_DAEMON_HEALTH_INTERVAL: Watchdog health check interval
  • DSH_DAEMON_NPM_REGISTRY: NPM registry used for checking and updating
  • DSH_DAEMON_PROFILE: Profile directory where the plugin is located

Applicable Scenarios and Notes

This plugin is suitable for DSH users who need to run dsh web for a long time, especially:

  • Want to automatically launch dsh web after logging in or system startup
  • Want to automatically recover after process abnormal exit
  • Need to uniformly view status, logs, and update status
  • Need to manage the daemon directly in agent sessions
  • Need to control the service in the terminal without opening a GUI

The following points need attention before deployment.

Permissions

This plugin requests danger-full-access for file and command operations. It handles user-level system services, state files under $DSH_HOME/daemon/, and generates the watchdog script.

If the deployment environment denies elevation, related tools will fail with sandbox rejection. Therefore, before installation, you should check the source code and license, and confirm that this permission scope meets team requirements.

Session Interruption

restart and stop will interrupt all open sessions. Before executing these operations, you should first confirm that there are no important ongoing conversations or tasks.

Windows Support Status

The Windows support documentation clearly states that it has not yet been verified on real Windows machines. If your environment primarily uses Windows, it is recommended to verify the behavior of starting on login, task scheduling, VBS launcher, and logging in a test environment first.

Major Version Updates

Major version changes will not update automatically. Manual execution is required:

dsh_daemon_update

Dependencies

The plugin requires Node >=18 and depends on:

@deepseek-ai/cordis >=3
@deepseek-ai/dsh-tools >=0.1.0-rc.6

When installing to the web profile, pnpm must also be in the PATH, which can be enabled via corepack enable.

Conclusion

The value of dsh-daemon lies in transforming dsh web from a “manual foreground service” to a “user-level background service”: it can be automatically launched after login or system startup, can recover after abnormal exits according to the watchdog strategy, and provides two sets of management interfaces: agent tools and terminal CLI.

For DSH developers who need to use dsh web stably, it can reduce repetitive operations such as manual start/stop, port checking, log confirmation, and exception recovery.

Repository address:

https://github.com/chenkai2/dsh-daemon