Mandarin715/dsh-autostart

English | 中文

A Windows-only DeepSeek Harness plugin: one-click boot autostart and one-click restart, where a failed restart leaves DSH running instead of taking it down — with no console window at any point.

⚠️ Disclaimer (read first)

Verify your environment before installing. The author is not liable for lost conversation history, interrupted tasks, or damaged data.

Restarting kills the DSH host process that runs your conversations and agent turns:

• Restarting while an agent is mid-turn → that turn is hard-interrupted and its result may never be written to disk
• A conversation not yet flushed to ~/.dsh/sessions/ → that history may be lost and is not recoverable
• Tasks running in parallel sessions are interrupted too

Before you use it: (1) verify the environment yourself (Windows version, Node, DSH version, whether security software blocks registry writes); (2) make sure no important task is running before you restart; (3) back up ~/.dsh/sessions/ for important conversations; (4) decide for yourself whether to enable boot autostart (it writes to HKCU\...\Run).

The software is provided "as is" (MIT License, no warranty of any kind).

Why you want it

Restarting a program is easy; coming back after the restart is the hard part. This plugin makes that a guarantee:

1. A failed restart leaves DSH running, not dead. Before letting DSH exit, the plugin (a) makes sure a supervisor — the process that will bring DSH back — is alive, and (b) writes the restart request to disk and reads it back to prove it landed. If either step fails, it refuses the restart, leaves DSH untouched, and says why. This is a real bug that used to happen: the port had not been released yet, one probe gave up, and DSH stayed down.

2. No console window, ever. DSH is launched attached to a hidden console owned by the supervisor, so every command DSH spawns shares it instead of creating a fresh Windows Terminal window — the old behaviour was one black window per tool call.

3. The supervisor is not a watchdog. It stays resident, but it only starts a replacement when the exit was a restart you asked for. Close DSH yourself and it quietly finishes — a process you cannot stop is worse than a service that occasionally does not come back.

4. Disabling or uninstalling never ambushes the DSH you are using. Disabling autostart only removes the next-login entry; DSH keeps running for the rest of this session, and the supervisor steps aside after DSH exits on its own.

5. Failures are diagnosable. Every step is written to service.log, and a failure states its cause instead of silently doing nothing.

Requirements

• Windows 10 / 11 (Win32_Process.Create must work through PowerShell — when you click restart and no supervisor is running yet, one is deliberately created by the WMI service, so that it is not killed together with the host)
• Node.js ≥ 20 (shipped with DSH)
• DeepSeek Harness ≥ 0.1.0-rc.6 (tested on 0.1.2-rc.1; the job-object behaviour the restart depends on was measured on 0.1.5-rc.1)
• A writable HKCU\...\Run for autostart — security software that blocks registry writes makes "enable" fail

Environment and restart

DSH is started by a resident supervisor — node service.js start --config <config.json>, launched by bootstrap.vbs at login (start is an alias of supervise, which is the real entry point; the generated bootstrap.vbs uses start). The supervisor is what outlives DSH: it learns of DSH's exit from its child handle, and starts the replacement when the exit was a restart you asked for.

When you click restart and no supervisor is running yet (for example you started DSH by hand), one has to be created from inside DSH first. That is the only moment the WMI service is involved: DSH runs its subprocesses inside a Windows Job Object created kill-on-close, so a merely "detached" process is killed the instant DSH exits — leaving DSH down. Having WMI create the supervisor is what lets it out of that job and lets it outlive the host. Once a supervisor exists (the normal case at login, and every restart after the first), WMI is not used.

One consequence: a process created that way does not inherit your environment. So:

• the supervisor is told where config.json lives explicitly (--config <absolute path>), instead of re-deriving the DSH home from DSH_HOME (which would be missing);
• the restarted instance re-asserts DSH_HOME from the dshHome captured in config.json.

Other environment variables (a custom PATH, extra variables DSH reads) are not carried over to the restarted instance. If your DSH setup depends on environment variables, keep that in mind, and prefer an absolute command.execPath.

Install

# Pinned release (recommended): the exact version verified on the author's machine
dsh plugin --profile web add "github:Mandarin715/dsh-autostart#v0.2.1"

Want the latest fixes from main (may be unverified)? dsh plugin --profile web add "github:Mandarin715/dsh-autostart"

Restart DSH, then open Settings → General and scroll to the bottom to find this plugin's card.

Usage

Control	What it does
Service status	Probes the port live; shows running / stopped
Boot autostart toggle	When enabled, writes ~/.dsh/dsh-autostart/config.json, generates bootstrap.vbs, and adds the DSH autostart entry under HKCU\...\Run
Current access URL	The newest token-bearing URL parsed out of the captured startup output; one-click copy
Restart service	Restarts after a confirmation; DSH is back within seconds. It first makes sure a supervisor is running to bring DSH back, and refuses the restart if none can be started
Hook script	Optional. Run once the service is up, to start your own dependent processes

Cannot open the page at all? This card only exists while DSH is running — see If the service will not start below.

Configuration

In the profile's cordis.patch.yml:

- id: dsh-autostart
  name: dsh-autostart
  config:
    hookScript: ''                 # optional, absolute path to a script run after the service starts
    dshPort: 3080
    exitDelayMs: 800               # delay before the old host exits on restart; clamped to 5000 max (see below)
    waitForExitMs: 30000           # UNUSED since the supervisor replaced the old restart path — kept only so an
                                   # existing config.json that sets it still loads
    startTimeoutMs: 30000
    openBrowserOnBoot: false       # true = open the browser on boot
    blockWhenAgentsRunning: false  # true = refuse to restart while an agent is running
    allowedHosts: []               # for reverse-proxy access, add your domain (must be opted in), e.g. ['derp.example.com']

exitDelayMs is clamped at 5000 ms. The delay only exists to let the restart response flush before the old host exits, and a freshly started supervisor waits only 30 s (DEFAULT_TAKEOVER_EXIT_MS) for that host to exit. A delay past that window would make the takeover give up, turning a restart into a shutdown — so values above 5000 are clamped to 5000 at the point of use, not rejected (index.js, MAX_EXIT_DELAY_MS).

allowedHosts is opt-in — you must add the entry yourself. The default is an empty array, meaning no non-loopback Host is trusted. If you reach DSH through a reverse proxy (for example frp + auth-proxy, which forwards the browser's original Host), the request's Host is your public domain rather than 127.0.0.1, so the write buttons (enable / disable autostart, restart service) are refused with 403. Add your domain to allowedHosts to make those buttons work; the same-origin check (Origin must equal Host exactly) still applies to those entries — see the accepted forms below.

Accepted allowedHosts forms: a bare host, or host:port — for example ['derp.example.com'] or ['derp.example.com:8443']. Do not include a scheme or a path (https://derp.example.com/ is wrong). Because a browser reaching https://derp.example.com sends no port at all, the local dshPort check is skipped for allow-listed authorities — the entry itself is the explicit opt-in, and the Origin/Host match still has to hold. Loopback keeps the strict port check.

Do config changes require re-enabling autostart? Yes — but not because of dispose. hookScript, dshPort and startTimeoutMs are snapshotted into config.json when you click Enable, and the supervisor reads config.json, not the plugin's live config. So after changing them you must open the settings card and enable autostart again (re-enabling is idempotent). Measured on a real install: changing hookScript and only restarting the service left the old value in config.json, so the hook never ran. allowedHosts is different — it only affects the plugin's route guard and takes effect on reload. waitForExitMs is snapshotted too, but is no longer read by anything (see the note in the config example above).

The registry entry does not disappear because you edited the config. The plugin removes DSH autostart only when it is genuinely uninstalled (evidence: its own service.js is gone); when DSH tears the plugin tree down for a reload or a failed load, the entry is kept.

Coexisting with an autostart entry you already have (important)

This plugin manages DSH only. If you already have your own boot entries (for example DSH Web, DSH frpc, DSH authproxy under HKCU\...\Run), then after enabling this plugin's autostart two entries will both try to start DSH at login.

• ✅ They do not overwrite each other: this plugin writes and deletes only its own DSH autostart value and never touches yours (measured: after enabling, the user's other entries were untouched).
• ⚠️ But they do duplicate work: both dedupe via "skip if the port is already listening", so you still end up with one DSH — yet there is a narrow race: if both run and both probe before either binds the port, both will try to launch, and one will fail because the port is taken (harmless, but it leaves a failure in the log and possibly a stray process).

Option A: keep only this plugin (simple)

Delete your own DSH entry:

reg delete "HKCU\Software\Microsoft\Windows\CurrentVersion\Run" /v "DSH Web" /f

Then click Enable in the settings card.

⚠️ Do not also delete DSH frpc / DSH authproxy — this plugin does not manage frpc or auth-proxy. If phone access depends on them, deleting those entries loses their autostart. Use Option B to merge instead.

Option B: merge into "one autostart + one hook" (least to maintain)

The hook runs at boot and after every restart, so put "make sure my other processes are running" in it and let this plugin be your only autostart entry.

1. Write a hook, for example ~/.dsh/hooks/after-service-up.ps1:

   # once the service is up, make sure the other processes run (adjust the paths)
   & "$env:USERPROFILE\.dsh\scripts\start-frpc.ps1"
   & "$env:USERPROFILE\.dsh\scripts\start-authproxy.ps1"
   

2. Point the plugin at it in the profile's cordis.patch.yml:

   - id: dsh-autostart
     name: dsh-autostart
     config:
       hookScript: 'C:\Users\<you>\.dsh\hooks\after-service-up.ps1'
   

3. Click Enable again in the settings card (hookScript is snapshotted into config.json when you enable), then delete DSH Web / DSH frpc / DSH authproxy and keep only this plugin's DSH autostart.

A failing hook does not block DSH (it is only logged), so its steps may fail independently. To check whether it ran, look for hook exited code=… in ~/.dsh/dsh-autostart/service.log.

Your existing entry	Option A	Option B
DSH Web (starts DSH)	delete	delete
DSH frpc / DSH authproxy	keep	delete; the hook takes over

Generated files

~/.dsh/dsh-autostart/
├── config.json               # the real launch command, read by service.js
├── bootstrap.vbs             # boot entry point: launches the resident supervisor (wscript, no window)
├── dsh-web-server.log        # DSH stdout (contains the access URL)
├── dsh-web-server.err.log
├── service.log               # supervisor log; look here first when debugging
├── supervise.pid             # the supervisor's own pid (single-instance guard)
├── restart.request           # written by a restart; names the DSH the supervisor saw exit
└── supervise.stop            # tells a running supervisor to stop once DSH is gone

The last three are transient state files: they are created and deleted as needed (all best-effort), and their absence is normal. They are not all cleared the same way, though. supervise.pid and supervise.stop are removed whenever the supervisor that owns them acts on them, but a restart.request is consumed only when the DSH it names actually exits — so a request from a restart that was refused, or that never reached that exit, can survive on disk until the next matching exit picks it up.

If the service will not start (recovery)

The card lives inside DSH's page — so when DSH is down you cannot open the card. Recovery therefore has to be command-line. Work down this list.

0) Wait a few minutes first — the supervisor retries in place

DSH is started by the resident supervisor — the login autostart entry is the supervisor, so it is always there when DSH is supposed to be. When a new instance does not come up, the supervisor does not simply give up:

1. It retries in place, with the interval growing 1s → 1.5s → 2.25s → …, up to 5 attempts and a 5-minute budget. Each attempt also waits startTimeoutMs (30s by default) for the port — so the budget plus the final attempt's own wait is the longest you can be waiting, and the loop normally ends earlier than the budget. It only retries once the failed child is really gone — while one is still alive it will not start a competitor for the same port.
2. Nothing is scheduled for later: the supervisor itself outlives the attempt, so the retry happens inside the one process that is already watching the port.

So after a failure, wait a few minutes before intervening by hand — the budget is 5 minutes, plus the last attempt's startTimeoutMs. The supervisor says what it is doing:

spawned dsh pid=… (attempt 2/5)                        # retrying
giving up: DSH did not come up after 5 attempt(s); supervisor exiting

The giving up line reports the number of attempts actually made, which is not always the configured cap of 5.

Only if all of that fails, continue below.

About the resident supervisor (two things you must know)

1. Its life and DSH's are the same. DSH is spawned attached to the supervisor's hidden console (that sharing is what stops each command from opening a visible window), so when the supervisor exits, DSH goes with it.
2. Disabling autostart does not stop it. Disabling cancels the login autostart only — the supervisor and your running DSH keep going for the rest of this session, and simply will not come back at the next login.
   • Uninstalling additionally writes a stop marker, so a running supervisor will not linger once DSH next goes away.
   • To end both immediately, close DSH — the supervisor deliberately does not linger when its child exits normally. It restarts DSH only for a restart you asked for from the settings page; it is not a watchdog.
   • There is no stop mode in the CLI, and writing the stop marker does not stop the supervisor on the spot: the supervisor reads that marker only after its child (DSH) exits. That ordering is deliberate — disabling autostart must not close the DSH you are using. The only modes are supervise and its alias start.

1) Read the logs first

~/.dsh/dsh-autostart/service.log            # the supervisor's log: start here
~/.dsh/dsh-autostart/dsh-web-server.err.log # DSH's own errors

Three common shapes:

• WARN port 3080 did not come up in time → DSH was launched but never listened; look at dsh-web-server.err.log
• hook not found: / hook exited code=… → a hook problem; it does not block DSH
• cannot read config → config.json is missing or corrupt

2) The general fix: run the boot entry point once by hand

This is exactly "run boot autostart right now". It is idempotent (it skips when the port is already listening) and it opens no window:

wscript.exe "$env:USERPROFILE\.dsh\dsh-autostart\bootstrap.vbs"

It runs <node> <service.js> start --config <config.json> (start is an alias of supervise). That becomes the resident supervisor, which owns a hidden console — DSH is spawned attached to it, so DSH has no visible window, and its stdout is written to ~/.dsh/dsh-autostart/dsh-web-server.log — on success a fresh token URL appears there.

The supervisor stays running for as long as DSH does and keeps owning it. Do not kill it: it is DSH's parent, and when it exits DSH goes with it.

If you would rather run the CLI directly

node "<path to the plugin>\service.js" start --config "<absolute path to config.json>"

Both paths must be absolute (a bare service.js only resolves if your shell's cwd happens to be the plugin directory). This does the same thing as the bootstrap.vbs form, but it ties DSH's life to the console you ran it from: DSH is spawned attached, so closing that window terminates DSH — and the supervisor stays in the foreground until DSH exits. If you use this form, leave the window open for as long as you want DSH up; otherwise prefer the bootstrap.vbs form above, which gives the supervisor its own hidden console and returns immediately.

3) If config.json does not exist at all

Autostart was never enabled. Start DSH the way you normally do, then enable autostart in the settings page.

4) Your own launcher script works too — with two rules

The rules are start it hidden / in the background, and never let a console window be the service's host:

• ✅ Start-Process … -WindowStyle Hidden, or a wscript VBS, so DSH becomes a background process
• ❌ Do not use a foreground console launch such as npx @deepseek-ai/dsh web; and never "grab the tokenised address, then close that window" — the window is DSH's console, and closing it makes Windows terminate DSH, which kills the link too. You then get "connection refused" rather than 401, and pasting it again will not help.

On the author's machine this step is ~/.dsh/scripts/start-dsh-web.ps1 (it launches with Start-Process -WindowStyle Hidden and captures stdout into ~/.dsh/logs/dsh-web-server.log). That is the author's local script, not part of this plugin — substitute your own equivalent, or just use step 2.

5) Do not confuse the two failure modes

What you see	What it means	What to do
401 Unauthorized	the service is running; this browser just has no session	open the tokenised address from "access URL" once; do not restart
This site can't be reached / connection refused	the service is not running	work through 1)–4) above

Three facts about that tokenised address: (1) it is local-only (127.0.0.1; the phone uses the domain plus the password, and the reverse proxy exchanges the token for you); (2) the session cookie it grants lasts 30 days and survives closing the browser and restarting DSH; (3) but the token itself is per DSH process and dies on every restart — so use the current one (the card always shows the latest); bookmarking one for later does not work.

6) How you know recovery worked

• port 3080 is LISTENING
• service.log contains port 3080 is up
• the card's "service" line says running

7) If you recently upgraded or moved DSH

config.json stores an absolute path captured at the time (it may contain an npx cache hash directory such as …\_npx\<hash>\node_modules\@deepseek-ai\dsh\lib\bin.js). After an upgrade or a move that path can go stale, and autostart then fails silently (nothing happens at login). Open the settings card and click Enable again so the current command is captured.

Uninstall

1. Disable boot autostart in the settings page first (this removes the registry entry)

   This step is required, not optional. Two reasons: (1) the registry entry points at ~/.dsh/dsh-autostart/bootstrap.vbs, and that file and config.json live outside the plugin directory, so removing the plugin does not delete them; (2) pnpm remove keeps the node_modules/dsh-autostart symlink, so this plugin's service.js is still reachable — and that reachability is exactly the plugin's cleanup test. So uninstalling without disabling first leaves a dead entry (it runs once at login and fails silently). Deleting DSH autostart from HKCU\...\Run by hand afterwards works too.

   Note: Settings → Plugins has no uninstall button for this plugin (that page only manages plugins installed from the markets), so step 2's command line is the normal path.

2. Remove the plugin: dsh plugin --profile web remove dsh-autostart

3. To clean up completely, delete ~/.dsh/dsh-autostart/ by hand

Why it is built this way

• Why wscript.exe instead of powershell -WindowStyle Hidden: the latter is unreliable for long-running scripts and leaves an empty console window that cannot be closed.
• Why waiting for the port uses conditional polling instead of a fixed Start-Sleep: a fixed wait once made a single restart take over 80 seconds; conditional polling (waitForPort, 250ms apart, bounded by startTimeoutMs) brought it down to a few seconds. The supervisor does not poll the DSH process it owns — it holds that child's handle and waits for its exit event. (Pids are still polled where there is no handle to hold: waiting for the outgoing DSH to exit on a takeover, and waiting for a new supervisor to claim supervise.pid.)
• Why the port check uses a TCP connection instead of a netstat/:port substring: substring matching also hits TIME_WAIT and client connections, so it reported "already running" when nothing had actually started.
• Why the logic is Node rather than PowerShell: Chinese text in PowerShell scripts tends to hit encoding problems, and execution policy gets in the way.
• Why --no-open is mandatory: DSH 0.1.2-rc.1 mints a new token on every start and prints the access URL to stdout; the plugin captures it into the log and shows it in the settings page, so opening a browser at boot is neither needed nor wanted.