Preface¶

When using the dsh web profile, the common workflow is to open a terminal running dsh --profile web, then visit the local port in a browser. Once the terminal is closed, the service exits with it, requiring a repeat next time. dsh-desktop-shell condenses this sequence into a desktop icon: after double-clicking, it automatically checks if the local dsh web server is running; if not, it starts it for you, then opens the web UI in a native window, and closing the window merely minimizes it to the system tray. Below is an introduction to how it works, installation steps, and a few usage notes.

What is this¶

dsh-desktop-shell is a desktop launcher shell for DeepSeek Harness (dsh): a tray-resident Electron thin wrapper responsible for launching or reusing the local dsh web server and opening the web UI in a native window. The author is ikashana, licensed under MIT, version 0.1.0 in package.json, and electron ^43.4.0 in devDependencies.

It consists of two parts: the dsh side is a profile bundle that, after being installed into the web profile, applies a patch and mounts a glue plugin; the desktop side is the Electron application itself, responsible for window, tray, and web server lifecycle.

Core Features¶

After double-clicking the app, it first checks if the dsh web server is already listening (default http://127.0.0.1:3080), and starts it automatically if not, then opens the web UI in a native window. On this basis:

1. Tray Resident: Closing the window only hides it to the system tray instead of exiting; the tray menu provides options to open the main window and exit.
2. Single Instance: Restarting focuses on the existing window rather than opening a second instance.
3. Ownership Awareness: The web server started by the shell stops when the shell exits; servers you started manually in the terminal or with other tools are not affected.
4. Configurable: dsh command, working directory, extra environment variables, port, and window title are all set in config.json.
5. Logging: Writes shell.log and web.log to Electron’s userData directory (on Windows, this is %APPDATA%\dsh-desktop-shell\).

Step 1: Install the dsh-side bundle¶

This repository is simultaneously a dsh profile bundle: package.json declares dsh.bundle.patch, which, after being installed into the web profile, activates a patch layer to pin the web server to loopback 127.0.0.1:3080 and mounts a glue plugin — to print a “ready” line and warn if the server binds outside loopback.

Install via git checkout:

dsh plugin --profile web add github:ikashana/dsh-desktop-shell

Install via npm (marked as “once published” in the README; this command may not be available before the npm package is published):

dsh plugin --profile web add dsh-desktop-shell

After installation, you can start the dsh web as usual (dsh --profile web), or do nothing and let the desktop shell below start it for you.

Step 2: Install the desktop application¶

Requires Node.js ≥ 18 (Electron is downloaded during npm install):

git clone https://github.com/ikashana/dsh-desktop-shell.git
cd dsh-desktop-shell
npm install
cp config.json.example config.json
npm start

The only required change is dshCommand (and cwd if dsh is not in the current directory). Point it to your dsh CLI, or to source-installed node + entry file, for example:

{
  "dshCommand": ["C:/path/to/node.exe", "--import", "tsx/esm", "apps/cli/src/bin.ts", "--profile", "web"],
  "cwd": "C:/path/to/deepseek-harness"
}

config.json Configuration Options¶

Windows: Using node.exe absolute path¶

Simply writing dsh goes through .cmd shim parsing, and child_process refuses to spawn without a shell (hardened against CVE-2024-27980). The shell can handle this situation itself, but writing an explicit executable file is the most reliable, such as C:/path/to/node.exe in the example above.

Windows: Create Desktop Shortcut¶

Use WScript.Shell to create a .lnk pointing to node_modules\electron\dist\electron.exe with the project directory as arguments:

$WshShell = New-Object -ComObject WScript.Shell
$lnk = $WshShell.CreateShortcut("$HOME\Desktop\dsh Desktop.lnk")
$lnk.TargetPath = "C:\path\to\dsh-desktop-shell\node_modules\electron\dist\electron.exe"
$lnk.Arguments = "`"C:\path\to\dsh-desktop-shell`""
$lnk.WorkingDirectory = "C:\path\to\dsh-desktop-shell"
$lnk.IconLocation = "C:\path\to\dsh-desktop-shell\assets\icon.ico"
$lnk.Description = "dsh Desktop · DeepSeek Harness launcher shell"
$lnk.Save()

Logging and Troubleshooting¶

If the web server fails to start, check the logs first. The shell writes shell.log and web.log to Electron’s userData directory, which is %APPDATA%\dsh-desktop-shell\ on Windows.

Use Cases and Notes¶

Suitable for: People using the dsh web profile on Windows who want to double-click to launch like a normal desktop app, minimize to tray on close, and don’t want to manually manage the server process. Tray behavior is cross-platform, but the author developed and tested it on Windows; process tree termination uses taskkill on Windows, and falls back to kill() on other platforms.

Three notes:

1. Plugins run with the permissions of the current dsh process; it is recommended to read the source code and confirm the license before installing. This project is MIT; assets/favicon.svg is copied from the MIT-licensed deepseek-harness repository.
2. The npm install command is marked as “once published” in the README; please use the git checkout method to install before the npm package is published.
3. When modifying port, remember to sync webserver.port in the bundle patch layer, otherwise they won’t match.

Conclusion¶

dsh-desktop-shell does something small but specific: condensing “start terminal, run command, open browser” into a single double-click, and using ownership awareness to ensure it doesn’t accidentally kill servers you started manually. The project homepage is on GitHub: https://github.com/ikashana/dsh-desktop-shell; the community directory listing page is at https://www.skillhub.cn/plugins/ikashana/dsh-desktop-shell (community site, no official affiliation with DeepSeek / Fangfang).