DSH adopts the “everything is a plugin” philosophy. In Windows environments, directly starting dsh web often faces issues such as complex dependencies, process residue, or window flicker. dsh-launcher, as a lightweight launcher, aims to solve these problems by providing a startup solution that requires no additional runtime and automatically cleans up when the browser is closed.

What Is This

dsh-launcher is a single-file Windows OS launcher written in Rust, specifically designed to start the Web UI of dsh (DeepSeek Harness). It does not depend on WebView2, carries no extra runtime dependencies, and is only a few hundred KB in size.

Installation and Activation

The plugin is distributed as a dsh plugin, with no extra blocking during installation.

dsh plugin --profile web add github:alvinpro/dsh-launcher

After installation, the executable is included in the package at node_modules\dsh-launcher\dist\dsh-launcher.exe.

Basic Usage

1. Default Startup

Simply double-click dsh-launcher.exe to run it. No configuration file is required; by default, it starts with dsh web and listens on port 3080.

2. Command-Line Startup

If you need to customize the port or parameters, you can override them via the command line.

dsh-launcher.exe --port 8899 --args "web --port 8899"

3. Configuration File (Optional)

config.json is optional. The priority order is: command-line arguments > config.json > built-in defaults.

If you want to fix the port or parameters, you can copy config.example.json and modify it.

{
  "dsh_path": "",
  "url": "http://127.0.0.1:8899",
  "port": 8899,
  "timeout_secs": 40,
  "package": "dsh",
  "args": ["web", "--port", "8899"]
}

4. Verify the Resolution Chain

Without actually starting the service, verify only the dsh command resolution chain.

.\dsh-launcher.exe --check

How It Works

The launcher manages the dsh lifecycle through six steps:

  1. Detection: Check whether the port is already ready. If it is ready, open the browser directly and exit, avoiding duplicate startup.
  2. Resolution: Try to obtain dsh in the following order: configured path, local offline package (vendor\dsh\), system PATH, and npx; then verify availability with dsh --version.
  3. Launch: Use CREATE_NO_WINDOW to launch cmd.exe with the window hidden, and immediately bind a JobObject to ensure proper process tree management.
  4. Readiness: Perform dual validation using TCP connectivity and HTTP response (port reachable ≠ service ready). After validation passes, use ShellExecuteExW to launch the browser in the foreground.
  5. Coordination: Closing the browser launched by the launcher automatically stops dsh; if the browser was already running, the launcher enters resident mode and can be exited via the tray icon.
  6. Cleanup: Regardless of the exit method (normal, tray, or forced termination), the JobObject terminates the entire process tree, achieving zero residue.

Core Features

  • Automatic Discovery: Supports automatic discovery from the configured path, local offline package, system PATH, and npx, without requiring global installation.
  • Real Readiness Detection: Uses TCP + HTTP dual validation, with adaptive backoff and timeout protection mechanisms.
  • Zero Residue: Uses the JobObject KILL_ON_JOB_CLOSE attribute to ensure the process tree is fully cleaned up under any exit path.
  • Browser Coordination: Closing the browser automatically stops the service; for shared instances, it enters resident mode and will not accidentally terminate browser windows in use.
  • Invokes the System Default Browser: Does not bundle a browser; directly uses the system default browser to open the service address.
  • Windowless Experience: Runs with the GUI subsystem, with no console window and no black-screen flicker. Logs are written to dsh-launcher.log, and error popups are shown when errors occur.
  • Exception Handling: Includes explicit error handling for dsh exiting early or timing out during detection.
  • Single File: About a 360KB executable, with an embedded icon and zero runtime dependencies.
  • No WebView2 Dependency: Uses native Win32 tray and popups, with no need to install the Edge/WebView2 runtime; compatible with Windows 7+.

Exit Code Description

Exit Code Meaning
0 Normal exit
1 Configuration error or dsh startup failure
2 Port already ready but service response abnormal
3 Waiting for the service timed out
4 dsh process exited early or abnormally
5 dsh command resolution or automatic installation failed (including npm not existing)

Applicable Scenarios and Precautions

  • System Requirements: Supports Windows 7 and later only.
  • Permissions: The plugin runs with the permissions of the current dsh process. It is recommended to review the source code and license (MIT) before installation.
  • Shortcut: After first running dsh plugin add, a desktop shortcut is automatically created once, pointing to the executable included in the package, and will not be recreated afterward.

Summary

DSH-Launcher solves core pain points when starting the DSH Web UI on Windows: complex dependencies, process residue, and window flicker. Through a single-file, zero-dependency design implemented in Rust, it provides a minimalist and reliable startup solution.