dsh-win-quick-launcher

DSH Win Quick Launcher

A handy Windows launcher for DeepSeek Harness: no terminal window, automatic auth token, service stops when the window closes
Supports both source-built and npm-installed DSH · Agent-installable · Zero npm dependencies

中文 · English

Using DeepSeek Harness (DSH) means opening a terminal, running pnpm dsh web (or dsh web), and copying the tokenized URL from its output — every single time. This launcher compresses that routine into one double-click: desktop icon → server starts in the background → app window pops up → closing the window stops the service.

Features

⚠️ Pick one of this launcher and the sister plugin dsh-web-window-companion: both share the same dedicated browser profile, and enabling both makes the windows kick each other off (flash-close) and stops the server by mistake. If you use the desktop icon, do not install the plugin.

Quick Start

Delegate to your AI agent (recommended)

Paste this prompt into the AI agent you use (Codex, Claude Code, Kimi, etc.):

Install DSH Win Quick Launcher for me. The repository is https://github.com/big0lives/dsh-win-quick-launcher. First read AGENTS.md and the README, confirm my machine meets the prerequisites (Windows, Node.js, DSH install mode), then follow the AGENTS.md steps to install and verify. Before acting, tell me exactly what you will change; stop and ask me first for antivirus exclusions, killing processes, credentials, or overwriting existing files.

The agent only reads and writes this repository's directory and creates one desktop shortcut; it does not touch your DSH checkout or your antivirus settings.

Manual install

Prerequisites: Windows 10 / 11, Node.js, and one of the following — a DSH source checkout with pnpm run build completed, or an npm install (npm install -g @deepseek-ai/dsh, with the dsh command on PATH).

git clone https://github.com/big0lives/dsh-win-quick-launcher.git
cd dsh-win-quick-launcher

# Source-built DSH: point at the source checkout
powershell -ExecutionPolicy Bypass -File install.ps1 -DshRoot D:\path\to\deepseek-harness

# npm-installed DSH:
powershell -ExecutionPolicy Bypass -File install.ps1 -Npm

Double-click the DSH Web icon on your desktop to start.

Usage

Daily use after installation is zero-touch: double-click the desktop icon, wait a few seconds, and the app window opens already authenticated. Close the window and the service stops with it. The only signals you will ever perceive are the app window itself and log lines in %TEMP%\dsh-web-launcher.log.

Troubleshooting & maintenance

Rollback: delete the desktop shortcut and launcher.config.json to uninstall completely; the launcher writes no registry keys and never modifies DSH itself.

Architecture & Principles

When each component triggers: start-web.vbs runs only on a shortcut double-click and merely attaches launcher.cjs to a hidden host; launcher.cjs spawns the DSH server and then watches exactly two things — the authenticated URL on stdout and the browser process lifetime. Window close is the sole stop signal, carried out by a synchronous taskkill /T /F from the launcher.

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#64748B'}}}%%
flowchart TD
    A[Desktop shortcut<br/>DSH Web.lnk] --> B[start-web.vbs<br/>hidden WScript host]
    B --> C[launcher.cjs<br/>Node.js]
    C -->|spawn --no-open| D[dsh web server process<br/>pnpm in source mode / dsh in npm mode]
    D --> E{stdout captured<br/>dsh web: URL?}
    E -->|yes| F[app-mode browser window<br/>Edge / Chrome]
    E -->|240s timeout| G[taskkill /T /F<br/>kill process tree]
    F --> H{window closed?}
    H -->|yes| G

    classDef start fill:#3B82F6,stroke:#2563EB,color:#fff,stroke-width:2px
    classDef process fill:#10B981,stroke:#059669,color:#fff,stroke-width:2px
    classDef decision fill:#F59E0B,stroke:#D97706,color:#fff,stroke-width:2px
    classDef stop fill:#8B5CF6,stroke:#7C3AED,color:#fff,stroke-width:2px

    class A start
    class B,C,D,F process
    class E,H decision
    class G stop

Token mechanism: the DSH server generates a random in-memory token on every launch and prints http://127.0.0.1:3080/?token=... to stdout. The launcher passes --no-open to stop the server from opening a browser itself, captures that address, and opens it in app mode instead — yielding a monitorable browser process handle whose window-close event becomes the server stop signal.

Agent protocol (automated — not for humans)

The machine-readable contract for installation and troubleshooting lives in AGENTS.md: environment checks, per-mode install steps, verification (poll port 3080 and check the log's final browser spawned line), and boundaries (never modify DSH itself, list processes before killing any, Defender exclusions require user approval). This part is executed by the agent; users do not need to read it.

Configuration

launcher.config.json is generated by install.ps1 next to launcher.cjs (gitignored):

Project Structure

dsh-win-quick-launcher/
├── launcher.cjs          # Core launcher: spawn server, capture auth URL, watch window, stop server
├── start-web.vbs         # Windowless entry point invoked by the desktop shortcut
├── install.ps1           # Installer: config and desktop shortcut
├── AGENTS.md             # Install/troubleshoot playbook for AI agents
├── assets/
│   └── dsh-whale.ico     # Shortcut icon (DeepSeek whale)
├── .gitignore
├── LICENSE               # MIT
├── README.md             # 中文文档
└── README-en.md          # English documentation

Tech Stack

No npm dependencies. The icon is a DeepSeek brand asset taken from the deepseek.com site icon, used only to identify the desktop shortcut.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

License

MIT

Maintained by @big0lives