dsh-restart

August 18, 2026 · View on GitHub

Start, restart, and troubleshoot your local DeepSeek Harness (dsh) web service — one tool, two entry points: in-chat skill and OS-level launcher.

What is DeepSeek Harness (dsh)?

DeepSeek Harness (dsh) is a local agent harness for DeepSeek-powered workflows. Its web profile serves a browser UI on a local port (default 3080) and keeps its configuration and session data under $DSH_HOME (default ~/.dsh).

Because dsh is a long-running local service, everyone eventually hits the same operational questions: "the UI won't open", "port 3080 is occupied", "I need to restart it". dsh-restart answers them with two complementary entry points:

Entry point	When to use	How
DSH skill (`skills/`)	dsh is running — operate from the conversation	Say "start dsh / restart dsh"; the model executes the procedure with its own tools
Launcher (`launch/`)	dsh is down or headless — bootstrap from the OS	Double-click `launch.vbs` (Windows) or run `launch.sh` / `launcher.js`

The skill is also mirrored in awesome-dsh-skills as a sibling project entry point.

Features
Repository layout
How it works
Prerequisites
Quick start
Launcher reference
Safety model
Troubleshooting
Development
Contributing
License

Features

Safe restart logic — identifies the process holding the port; never kills non-node/dsh processes without explicit --force.
Session preservation — a healthy running instance is never restarted implicitly; the browser is simply opened, so conversation history is kept.
Cross-platform — Windows, macOS, Linux, and Android (Termux), with a /proc fallback for minimal Linux environments.
Zero dependencies — the launcher uses only Node.js core modules; the skill is a plain validated SKILL.md.
Verified skill format — the bundled skill passes tools/validate-skills.mjs, enforced by CI on Ubuntu and Windows for every push and PR.
Works when dsh is down — unlike in-chat operations, the launcher requires no running dsh instance.

Repository layout

dsh-restart/
├── skills/
│   └── dsh-restart/SKILL.md   # DSH skill — in-chat entry point
├── launch/
│   ├── launcher.js            # cross-platform core launcher
│   ├── launch.vbs             # Windows: hidden start + auto-open browser
│   ├── launch.bat             # Windows: console entry
│   └── launch.sh              # macOS / Linux / Termux entry
├── tools/
│   └── validate-skills.mjs    # zero-dependency skill format validator
├── CONTRIBUTING.md            # contribution guidelines
└── .github/workflows/
    └── validate.yml           # CI — Ubuntu + Windows matrix

How it works

check port 3080
      │
      ├─ free ──────────────────────────► start dsh web ──► poll ──► open browser
      │
      └─ occupied ──► identify process
                        │
                        ├─ non-node/dsh ──► abort (--force required)
                        │
                        └─ node/dsh ──► probe http://127.0.0.1:3080/
                                          │
                                          ├─ healthy ──► open browser (no restart)
                                          └─ stale ────► kill ──► wait port free ──► start

Check the default port 3080 (override with --port or DSH_PORT).
Identify the occupying process; refuse to kill non-node/dsh processes unless --force is passed.
Probe the service — a healthy response means "just open the browser": restarting would discard the current session.
Recover stale processes — terminate, wait for the port to free, then start dsh web (prefers a local install, falls back to npx -y @deepseek-ai/dsh).
Verify by polling until the UI responds, then open the browser.

Prerequisites

Node.js — required by both the launcher and dsh itself.
dsh — the launcher starts it via a local install or npx -y @deepseek-ai/dsh (network required on first use).
No other dependencies.

Quick start

Option A — install the skill (in-chat)

git clone https://github.com/hackerFish/dsh-restart.git
mkdir -p ~/.dsh/skills
cp -r dsh-restart/skills/* ~/.dsh/skills/

Skill roots are scanned at session startup — start a new session, then say "start dsh" or "restart dsh".

Option B — run the launcher (bootstrap)

# Windows
launch\launch.vbs            # double-click, or from a terminal:
node launch\launcher.js

# macOS / Linux / Termux
./launch/launch.sh
node launch/launcher.js

Optional — desktop shortcut (Windows)

Create a shortcut to launch\launch.vbs. Double-clicking starts dsh hidden and opens the browser automatically.

Launcher reference

Option	Description
`--dry-run`	Inspect port/process state only; start nothing.
`--force`	Kill a non-`node`/`dsh` process holding the port — confirm first.
`--port <n>`	Override the listen port (default `3080`).
`-- <args>`	Forward remaining arguments to `dsh`, e.g. `-- web --port 4000`.
`DSH_PORT`	Environment variable equivalent of `--port`.

Safety model

The launcher never kills a process that does not look like node/dsh/deno/bun unless --force is passed.
A healthy running instance is not restarted by default — only the browser is opened.
Restarting dsh terminates the process hosting the current conversation; the skill warns the user before doing so.
The skill performs no side effects beyond process management and opening the UI.

Troubleshooting

Symptom	Resolution
Port 3080 occupied by an unknown process	`node launch/launcher.js --dry-run` to inspect; use `--force` only after confirming.
Port 3080 taken by another application	`node launch/launcher.js --port 8080`.
dsh starts but the UI never opens	`dsh web --help`; `dsh web --port 0` lets the OS pick a free port.
Skill not triggered in conversation	Confirm it landed in a discovery root (`~/.dsh/skills` or project `.dsh/skills`); a new session is required.

Development

node tools/validate-skills.mjs   # validate the bundled skill (zero dependencies)
node launch/launcher.js --dry-run # launcher self-check (inspect only, starts nothing)

CI (.github/workflows/validate.yml) runs the validator on Ubuntu and Windows for every push and pull request, so platform-specific path bugs are caught before merge.

Contributing

See CONTRIBUTING.md.