hanwuji1/dsh-web-launcher

English · 中文

Stop typing. Stop navigating. Double-click the whale and you're in.

DeepSeek Harness (dsh) is DeepSeek's open-source agent harness. Its Web UI is one command and one URL away from your work — this plugin removes both.

---

🐋 Overview

Good tools disappear.

Every time you open the DSH Web UI the old way, you perform the same ritual:

open terminal  →  type "dsh web"  →  wait for boot  →  open browser  →  type the URL  →  Enter

Six steps. Ten seconds. Every single time. Ten times a day, that's a hundred minutes a month spent just arriving at your tools — not doing the work. Friction like this doesn't sound like much per click, but it taxes you every time, forever. The tax is invisible, so it never gets questioned.

Who is this for? Anyone who uses the DSH Web UI more than once a day on Windows and wants the entry point to be a single double-click instead of a six-step ritual — end users, agent power users, and anyone tired of typing http://127.0.0.1:3080 from memory.

This plugin exists to delete that ritual:

• 🖱️ One click to be there. Double-click the whale. The server boots, the browser opens, you're in. There is no step two.
• 🔁 Idempotent by design. Already running? It just opens the browser. Double-click it ten times — nothing breaks, no port conflicts, no duplicate servers.
• 🕳️ Invisible complexity. The launcher script lives in %LOCALAPPDATA%, off your desktop. All you see is one clean app icon.
• 🌍 Works anywhere. The launcher is pure ASCII — it parses correctly under GBK, UTF-8, or any Windows codepage, on any machine.
• 🤖 Agent-native. A web_launcher model tool lets the agent itself install, open, or check the UI — the entry point becomes part of the workflow, not a detour from it.

"The best interface is no interface — the second best is one click."

✅ Compatibility

dsh	Verified on 0.1.0-rc.6 (web profile); installs via the standard dsh plugin add flow (dsh.bundle manifest)
Node	^22.19 || >=24 (as declared in engines)
Platforms	Windows 10/11 for the desktop shortcut; the web_launcher tool's status / open actions work on any platform
Last verified	2026-08-15 (dsh 0.1.0-rc.6, plugin install + unit tests)

📦 Install / Upgrade / Uninstall

Requires a dsh profile (e.g. the web profile).

Install

# from npm
dsh plugin --profile web add dsh-web-launcher

# or straight from GitHub
dsh plugin --profile web add github:hanwuji1/dsh-web-launcher

Upgrade

dsh plugin --profile web update dsh-web-launcher

Uninstall

dsh plugin --profile web remove dsh-web-launcher

Then delete the leftovers: the DeepSeek Harness Web.lnk shortcut on your desktop and the %LOCALAPPDATA%\dsh-web-launcher folder.

No dsh yet? Standalone PowerShell install:

powershell -ExecutionPolicy Bypass -File install.ps1        # default port 3080
powershell -ExecutionPolicy Bypass -File install.ps1 -Port 8080

🚀 Quick start

1. Install the plugin (see above).
2. (Re)start dsh web once — the plugin activates on boot and places the DeepSeek Harness Web app on your desktop.
3. Double-click the app → the server starts, polls until ready, and the browser opens.
4. Reproducible check: ask any agent in a session to call web_launcher with action status — expect running: true and the URL http://127.0.0.1:3080.

Minimal configuration (optional) — see Configuration for the full table.

🤖 web_launcher tool

Action	Effect
install	(Re)create the launcher and the whale-icon app shortcut (Windows)
open	Open the Web UI in the default browser
status	Report whether the DSH Web server is running

⚙️ Configuration

Override the plugin row in your profile's cordis.patch.yml (e.g. ~/.dsh/profiles/web/cordis.patch.yml). A patch replaces the whole row config, so restate the keys you keep:

- id: dsh-web-launcher
  config:
    autoInstall: true          # create/refresh the launcher on activation (default true)
    createShortcut: true       # also create/refresh the app shortcut (default true)
    port: 3080                 # Web UI port (default 3080)
    shortcutName: Start-DSH-Web.cmd              # launcher file name (default)
    linkName: DeepSeek Harness Web.lnk           # app shortcut name (default)
    launcherDir: ""            # launcher folder; empty = %LOCALAPPDATA%\dsh-web-launcher
    desktopDir: ""             # desktop folder; empty = auto-detect

No environment variables and no secrets are involved.

🔐 Permissions & data

Area	What the plugin does
Files written	Start-DSH-Web.cmd under %LOCALAPPDATA%\dsh-web-launcher; DeepSeek Harness Web.lnk on the desktop
Files read	None of your data — only its own template and icon inside the package
Processes	Spawns powershell.exe (WScript.Shell) to create the shortcut; the launcher spawns dsh web under your user account
Network	Loopback only: probes http://127.0.0.1:<port> for status; open delegates to the OS default browser
Credentials	None — never reads, stores, or sends credentials

🔧 How it works

┌───────────────────────────┐   ┌───────────────────────────────┐
│  DeepSeek Harness Web     │──▶│  cmd /c Start-DSH-Web.cmd     │
│  (desktop .lnk, whale ico)│   │  (hidden in %LOCALAPPDATA%)   │
└───────────────────────────┘   └───────────────┬───────────────┘
                                                │
                        ┌───────────────────────┼───────────────────────┐
                        ▼                       ▼                       ▼
                 where dsh?             port listening?          start dsh web
                 (friendly error)      (open browser)           (poll → open browser)

• cordis.patch.yml — declares the dsh.bundle manifest; dsh plugin add auto-reconciles it into the profile's bundle stack.
• lib/launcher.js — template rendering (pure ASCII), desktop/launcher directory resolution, port probing (fetch + timeout), .lnk creation via WScript.Shell.
• lib/index.js — Cordis plugin (name / inject: ['tools'] / Config schema) + the defineTool-based web_launcher tool.
• tools/make-icon.mjs — regenerates the multi-size whale.ico (SVG → PNG → PNG-in-ICO) from the official Harness favicon silhouette.
• tools/make-banner.mjs — regenerates this README's hero banner.

🩺 Troubleshooting

Symptom	Cause & fix
transport failure for /api/...: HTTP 403	The browser-trust fence rejected a cross-origin call. Open DevTools → Network → the failed request → copy its Origin header. If it is not http://127.0.0.1:3080, something else is calling the local API — a browser extension (e.g. local-model/translate tools), a leftover tab, or an embedded iframe. Disable it or close that page. --trusted-host does not relax the Origin check.
EADDRINUSE / port already bound	Another instance is running — the launcher detects the listening port and just opens the browser. To use a different port, set port in cordis.patch.yml.
dsh not found when double-clicking	Install the CLI first: npm install -g @deepseek-ai/dsh
Desktop icon missing or generic	Run web_launcher with action install to recreate the shortcut and icon
Where are the logs?	The launcher console shows dsh web output; profile state lives under ~/.dsh

Rollback: dsh plugin --profile web remove dsh-web-launcher and delete the two files listed under Uninstall — the plugin leaves nothing else behind.

🛠️ Development

• No build step — plain ESM JavaScript in lib/; zero runtime dependencies beyond the dsh peer packages.
• Tests: npm test (node:test — no third-party dependencies needed).
• Regenerate assets: node tools/make-icon.mjs and node tools/make-banner.mjs (need sharp; set SHARP_PATH to its node_modules when not installed locally).
• Release: bump version in package.json → npm publish → git push. The dsh.bundle manifest means dsh plugin update picks up new versions.
• Contributing: PRs welcome — open an issue first for larger changes.

❓ FAQ

Q: Will this run my commands as admin? No. The launcher runs dsh web with your normal user permissions.

Q: Does it interfere with the running server? No. It detects the listening port and skips straight to the browser.

Q: Why is the launcher a .cmd and not an exe? Zero dependencies, no build chain, trivially auditable — 60 lines you can read before running.

Q: Non-Windows? The tool stays registered (status/open work anywhere); the desktop shortcut is Windows-only by design.

⭐ Support

If this plugin saves you even a few seconds a day, star the repo — it helps other people find it, and it tells the maintainer the friction tax was worth deleting.

Found a bug or want a feature? Open an issue — PRs welcome.

🗂️ Project layout

dsh-web-launcher/
├── lib/                  # plugin code (ESM, zero runtime deps)
│   ├── index.js          # Cordis plugin + web_launcher tool
│   ├── launcher.js       # template, shortcut, status, browser helpers
│   └── template.cmd.txt  # the ASCII launcher template
├── icons/                # whale.ico + multi-size PNGs (generated)
├── assets/               # banner.svg, favicon.whale.svg (icon source)
├── tools/                # icon/banner generators (sharp)
├── tests/                # node:test unit tests
└── install.ps1           # standalone install (no dsh required)

📜 License & security

MIT — see LICENSE.

To report a security issue privately, use the repository's Security tab (GitHub Security Advisory) instead of a public issue.