dsh-instance-manager

September 4, 2026 · View on GitHub

中文 | English

npm DSH plugin License: MIT

View, start, and stop local DSH Web instances, with optional access to trusted remote instances. Open it from the Mini Utility Dock at the bottom-left of the page.

Features

  • List instance ports, PIDs, uptime, sessions, memory, and version status.
  • Inspect stdout/stderr logs, memory trends, and active-session summaries.
  • Start new instances and gracefully stop one, the current instance, or all local instances.
  • On DSH 0.1.2-rc.1+, web-panel starts open the one-time token URL so the new instance can issue its browser cookie; agent-tool starts remain headless.
  • View remote instances, logs, and sessions through authenticated peer links.
  • Expose the instance_list, instance_start, instance_stop, instance_logs, and instance_sessions agent tools.

Install

# install from npm and register with the web profile (recommended)
dsh plugin --profile web add dsh-instance-manager

# install the npm package only
npm install dsh-instance-manager

# or install from GitHub
dsh plugin --profile web add github:xswt442-cmd/dsh-instance-manager

npm install installs the package only; DSH still needs the bundle in its profile. dsh plugin add performs both steps. Restart DSH Web after installation.

Configuration

DSH settings control Dock placement, refresh interval, fleet token, peers, and the launch port band. Environment variables provide defaults:

The UI language follows the global DSH Settings → General language; the plugin no longer stores a separate language preference.

$env:DSHIM_DOCK_PLACEMENT = 'main-bottom-left'
$env:DSHIM_REFRESH_INTERVAL_MS = '4000'
$env:DSHIM_PORT_RANGE = '3080-3129'
$env:DSHIM_FLEET_TOKEN = '<long-random-secret>'
$env:DSHIM_PEERS = 'office@http://192.168.1.20:3080'

Peer configuration is directional; configure each side when both machines should see each other. Remote rows are read-only and excluded from local stop-all.

Security

  • The local API rejects cross-site origins, non-loopback hosts, and unsafe Fetch Metadata.
  • Mutating actions are POST-only; ports must be decimal integers from 1 to 65535.
  • Whether a fleet bearer is required is decided by the real TCP peer address (socket), not just the Host header: an off-loopback peer OR an off-loopback Host triggers the bearer. A forged Host: 127.0.0.1 cannot hide an off-loopback peer, and a missing peer address is rejected outright. Requests fail closed when the token is missing or unresolved.
  • The fleet token has no action-level scopes. A holder can start or stop local instances and read session information, so grant it only to trusted devices.
  • On DSH 0.1.2-rc.1+, browser APIs and event streams reuse the Connection signed cookie; instance confirmation and forwarding use private strict-loopback probes.
  • SSE remains local-only.

Development

Do not symlink the working tree into a running DSH profile. Deploy a snapshot instead:

powershell -File scripts\deploy-profile.ps1

Before committing:

npm test
npm run docs:check
npm pack --dry-run

License

MIT