Web Launcher

> **Stop typing. Stop navigating. Double-click the whale and you're in.** > > [DeepSeek Harness](https://github.com/deepseek-ai/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** ```sh # 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** ```sh dsh plugin --profile web update dsh-web-launcher ``` **Uninstall** ```sh 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 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](#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: ```yaml - 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:` 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](#-install--upgrade--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. [](https://github.com/hanwuji1/dsh-web-launcher/stargazers) Found a bug or want a feature? [Open an issue](https://github.com/hanwuji1/dsh-web-launcher/issues) — 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](LICENSE). To report a security issue **privately**, use the repository's **Security** tab (GitHub Security Advisory) instead of a public issue.