dsh-launcher

中文 | English

A launch & management tool for DeepSeek Harness Web on Windows: type deepseek in cmd / PowerShell to start it (foreground / background modes), auto-open the browser, check status, and stop the service. One-click registration of the deepseek command is also supported.

Features

• Command-line launch: type deepseek in cmd / PowerShell to start — no need to hunt for icons or remember paths
• Foreground / background modes: foreground shows logs in a window (closing the window stops it); deepseek -b submits background startup and returns immediately
• Auto-open browser: opens the authenticated local Web UI automatically when the service is ready
• Cross-browser reopen: deepseek --open [default|edge|chrome|firefox|brave] opens the authenticated URL in a selected browser
• Visible shortcut feedback: shows startup progress, closes after opening the browser, and stays open with log details on failure
• Status & stop: deepseek --status shows the run state; deepseek --stop stops the service and reminds you how to restart it
• Works on both Windows 10 and Windows 11

Installation

Prerequisite: Install Node.js

dsh-launcher is a launcher for DeepSeek Harness; dsh-launcher only requires Node.js. On the first deepseek run, it prepares and starts DeepSeek Harness through npm in %USERPROFILE%\dsh-launch\runtime.

1. Install Node.js LTS (requires ^22.19.0 || >=24.0.0, same as upstream DSH; Node 22 LTS or 24+ both work. The launcher checks this before install, start and upgrade and reports the current version and how to upgrade)

The first launch requires an internet connection. Node.js normally includes npm; if the environment check cannot find npm, reinstall Node.js LTS.

Option 1: One-line install via PowerShell (recommended)

irm https://raw.githubusercontent.com/RYun601/dsh-launcher/main/install.ps1 | iex

Downloads the latest Release, verifies the release package SHA-256 and manifest, extracts it to %USERPROFILE%\dsh-launcher, and registers the deepseek command automatically.

Before extraction the installer verifies the package SHA-256 (the GitHub release asset digest first, the published .sha256 sidecar as fallback) and the shipped release-files.txt manifest. The install refuses without writing anything when the digest is missing or mismatched, or when the package files do not match the manifest.

A desktop shortcut is not created by default. To create one, run these two steps in the same PowerShell window:

1. Download the installer script to the current directory:

   irm https://raw.githubusercontent.com/RYun601/dsh-launcher/main/install.ps1 -OutFile .\install.ps1
   

2. Run the script with the -Shortcut parameter:

   .\install.ps1 -Shortcut
   

-Shortcut: creates a "DeepSeek Harness" desktop shortcut. It starts in background mode, shows startup progress, and closes automatically after a successful start. Running the installer with this parameter again updates the shortcut; without it, the installer does not create a shortcut.

Option 2: Manual install

1. Download dsh-launcher.zip from Releases and extract it
2. Run install-command.cmd (registers the deepseek command)
3. Open a new terminal and type deepseek

Option 3: Run from source

git clone https://github.com/RYun601/dsh-launcher.git
cd dsh-launcher

Quick Start

After completing the installation above (any option) and opening a new terminal window (so the new PATH takes effect):

1. Type deepseek -b to submit background startup and return immediately (or deepseek for foreground mode)
2. On first run, npm prepares the DeepSeek Harness runtime and required dependencies automatically (needs internet, ~1-2 minutes)
3. The browser opens the local Web UI automatically when the service is ready
4. On first use, sign in / enter an API Key in the DeepSeek Harness UI

See "CLI Usage" below for every subcommand and flag.

CLI Usage

Only one action is allowed per invocation; unknown arguments or conflicting combinations fail with an error and never fall back to a foreground launch. Real exit codes from the PowerShell layer are propagated unchanged to the deepseek command. --full is only valid together with --uninstall; a number is valid only immediately after --logs as its line count or after --upgrade as the version-list display count, --json only after --status, --follow only after --logs, a version token (e.g. 0.1.1-rc.2) only after --upgrade, and a browser alias only after --open.

Start & Stop

Status & Logs

Authentication & browsers

--open only attaches to an instance already in READY; retry after startup completes. It reuses the DSH process's authenticated entrypoint without disabling authentication or printing the token URL. Explicit browsers use their default profile; private windows and named profiles are not supported.

Version & Upgrades

• Normal startup prefers the prepared and validated local DSH version and does not contact npm when a usable runtime exists; dependencies are prepared only for a first launch or repair without a usable runtime. Use deepseek --update to discover releases from npm and deepseek --upgrade to install and switch versions.
• deepseek --update / deepseek --upgrade query the npm public registry directly (dist-tags or the published version list, both faster than npm view). To use a mirror or a private registry, set the DSH_REGISTRY environment variable (e.g. https://registry.npmmirror.com); it only affects remote release discovery, never local runtime startup.
• deepseek --upgrade without a version in detail: it resolves and validates the target version first; if the current runtime is healthy and already at least the target version, it reports "already latest" and exits without stopping the service or running npm; otherwise it stops the service, clears old DSH npx workspaces, syncs the global dsh command, and restarts in background. If the candidate fails because a plugin imports an export removed from DSH or its plugin manifest is incompatible with the target DSH (plugin tree failed to load), it lists the incompatible plugins and asks whether to remove them from the web profile; after confirmation it runs the target version's dsh plugin --profile web remove command and retries the candidate; declining or failing the repair falls back through current, previous, or legacy usable runtimes (only runtimes that pass readiness validation are used for rollback).
• deepseek --upgrade also syncs the global dsh command: it syncs it to the target version when installed or installs it when missing, so the dsh command stays in line with the launcher; a failure here only prints a warning and never blocks the launcher runtime upgrade. If the target version cannot be resolved or is invalid, the upgrade aborts before stopping anything and leaves the current install untouched.
• deepseek --upgrade <version> constraints and flow: the target must be an exact published npm version, in either direction (upgrade to a newer version or roll back to an older one); an unpublished target or a malformed version aborts before the service is stopped and leaves the current install untouched. The switch reuses the --upgrade transaction (stop the service → clear old DSH npx workspaces → sync the global dsh command → restart in background and validate) and also moves the global dsh command to the target version; the plugin handling and runtime fallback chain on a failed candidate match --upgrade. A target equal to the active version is a no-op that never stops the service. The version list shows the newest 20 by default and prints how to obtain the full list when truncated; targets are always validated against the complete version list, so the display count only affects printing.
• deepseek --upgrade-launcher in detail: verify the release package's SHA-256 and manifest → take the maintenance mutex → back up the old install directory → place the new version → run an offline smoke check → commit; it refuses while a service is running, a DSH upgrade is in progress, in a source worktree, or for unmanaged installs; failures restore the old version automatically (an incomplete restore keeps the backup plus a recovery script and exits with code 2).

Diagnosis & Uninstall

• deepseek --uninstall --full transaction details: with confirmation — cancelling changes nothing; it stops the service first, moves directories to a backup before deletion; PATH is removed only after every directory is safely backed up; the install dir is validated against its ownership marker, and a failed cleanup keeps the backup with its location.

Other Ways to Start

The paths below bypass the deepseek command; pick whichever fits.

Built-in scripts

• start-deepseek-harness.bat: foreground mode (starts the service + auto-opens the browser)
• start-background.cmd: background startup progress window (closes automatically after a successful start, stays open with log details on failure)

Optional: the official DSH CLI

Install the DSH CLI globally only if you want to use the official dsh command directly from any terminal (dsh-launcher uses its own versioned runtime, so this step is not required):

npm install -g @deepseek-ai/dsh

Open a new terminal, then run:

dsh web

Opening the authenticated URL printed at startup confirms that it started successfully (press Ctrl+C to exit).

npm install -g @deepseek-ai/dsh registers dsh in npm's global executable directory (as dsh.cmd on Windows). A standard Node.js installation adds that directory to PATH; if dsh is still not found in a new terminal, check that the npm global directory is on PATH.

npx @deepseek-ai/dsh web can start DSH directly, but does not register the dsh command for use in any terminal.

FAQ

• deepseek is not recognized as a command: run install-command.cmd first, then open a new terminal window
• Stuck on download / network errors: switch to a mirror and retry: npm config set registry https://registry.npmmirror.com
• deepseek --status shows STARTING: DSH is downloading or starting. Use deepseek --logs 50 to inspect progress; another deepseek -b will not submit a duplicate startup job.
• deepseek --status shows FAILED: DSH exited before it listened on the port. Run deepseek --logs 50 for the error, then retry with deepseek -b.
• deepseek --status shows UNHEALTHY: a DSH process listens on port 3080 but HTTP is not answering (it may have hung). Run deepseek --stop and start again.
• deepseek --status shows FOREIGN_PORT: port 3080 is owned by a process that is not DeepSeek Harness. Free the port before starting; neither the launcher nor the stop logic will kill an unknown process.
• Port 3080 is already in use (EADDRINUSE): an instance is already running — check with deepseek --status, or run deepseek --stop first
• Another browser says dsh web authentication required: do not open the bare address; in a new terminal run deepseek --open edge (or use chrome, firefox, or brave)
• Service stops when the foreground window closes: by design (the process lives in the console window); use deepseek -b for a persistent service
• Migrate existing DSH settings (including API Key): copy the whole %USERPROFILE%\.dsh folder to C:\Users\<username>\.dsh on the new machine (contains sensitive credentials — do not share publicly)

Appendix: Files

For readers who want to understand each script's role or contribute; daily use only needs the commands above.

License

MIT