dsh-port-manager

中文 | English

A DeepSeek Harness (DSH) community plugin: stop pinning the DSH web UI to port
3080, see every listening port on the machine, and pick a free one.

This is a community project. It is not an official DeepSeek plugin and does
not imply any endorsement by DeepSeek.

Features

• Settings → Port Manager: view and switch the DSH web port from the UI
• Local port inventory: TCP/UDP listening ports with address, process name,
  and PID; the current DSH port is highlighted
• Free-port suggestions: recommended ports derived from the live inventory
• Hot switch: rebind the HTTP listener without restarting the dsh process
  or losing sessions; the browser jumps to the new URL automatically
• Persistence: the port is saved to $DSH_HOME/dsh-port-manager.json and
  reused after restart
• Occupancy guard: switching to a taken port is refused with the owning
  process and PID in the error

Install

Requires the DSH web profile (@deepseek-ai/dsh-web-app).

1. Clone or download this repository:

   git clone https://github.com/WASD258-jpg/dsh-port-manager.git

2. Install into the DSH profile dependency directory (choose one):

   Option A: npm install (recommended)

   cd "$env:USERPROFILE\.dsh\profiles"
   npm install @wasd258/dsh-port-manager --no-save

   Option B: copy from source

   $src = '.\dsh-port-manager'
   $dst = "$env:USERPROFILE\.dsh\profiles\node_modules\@wasd258\dsh-port-manager"
   New-Item -ItemType Directory -Force -Path "$dst\lib" | Out-Null
   Copy-Item "$src\package.json" $dst -Force
   Copy-Item "$src\lib\index.js","$src\lib\client.js" "$dst\lib" -Force
   Copy-Item "$src\LICENSE","$src\NOTICE" $dst -Force

   On Linux/macOS use ~/.dsh (or $DSH_HOME if set) instead of
   $env:USERPROFILE\.dsh.

3. Append this to $DSH_HOME/profiles/web/cordis.patch.yml:

   # Port manager: CLI --port > plugin config > DSH_WEB_PORT > 3080
   - id: webserver
    inject: [webStartup, dshPortManager]
    config:
      host: !!js ctx.webStartup.host ?? '127.0.0.1'
      port: !!js ctx.dshPortManager.startupPort(ctx.webStartup.port)
   
   - insert:
      - id: dsh-port-manager
        name: '@wasd258/dsh-port-manager'
        config:
          role: provider
   
      - id: dsh-port-manager-routes
        name: '@wasd258/dsh-port-manager'
        inject: [webServer, dshPortManager, subprocess, sandboxPolicy]
        config:
          role: routes

   If you already customized the webserver entry, replace its port
   expression with !!js ctx.dshPortManager.startupPort(ctx.webStartup.port)
   and make sure inject contains both webStartup and dshPortManager.

4. Restart DSH web once. The Port Manager section appears in Settings.

Usage

1. Open DSH web → Settings → Port Manager
2. Review "Local ports in use"; click Rescan to force a refresh
3. Click a suggested free port, or type one in the 1–65535 range
   (0 = let the OS assign one)
4. Click Apply new port and jump; the page navigates to the new URL after
   about one second

Other open tabs lose their connection during the switch; open the new URL in
those tabs manually.

Port precedence

The UI writes the actual listening port back to the config (when 0 is
requested, the OS-assigned port is persisted). Delete
dsh-port-manager.json to fall back to 3080.

HTTP API

Host half registers routes under /api/dsh-port-manager:

On Windows the inventory prefers PowerShell
(Get-NetTCPConnection/Get-NetUDPEndpoint) and falls back to netstat; on
Linux/macOS it falls back to /proc or netstat.

How it works

• lib/index.js (host half)
  • role: provider: reads dsh-port-manager.json and provides the
    dshPortManager service
  • role: routes: registers the HTTP API; a switch first binds a new
    node:http server on the target port, then closes the old listener after
    the response is delivered
• lib/client.js (web half): registers the Settings → Port Manager card
• No process restart: the route table stays on the webServer service; only
  the underlying node:http server is replaced

Privacy & security

• No network requests, no telemetry, no data leaves the machine
• Port enumeration runs local system commands only (PowerShell on Windows;
  netstat//proc elsewhere)
• Configuration is written only to local $DSH_HOME/dsh-port-manager.json
• The port inventory and hot-switch API are loopback-only: even if DSH is
  configured to bind 0.0.0.0, this plugin's API is not exposed to LAN/public
• Write requests to /apply additionally require Content-Type: application/json and a same-origin browser request, blocking cross-site
  port switching from malicious web pages
• The plugin never changes the bind host; it stays under DSH's webserver
  configuration

Compatibility

Developed and verified on:

• DeepSeek Harness 0.1.0-rc.6 (web profile, Windows 11 + PowerShell)
• Bundle patch interfaces at commit
  47f9438

If a newer DSH release changes the webserver entry, adjust the patch snippet
as described in the install section.

Official ecosystem requirements

DeepSeek currently suggests community authors publish plugins in their own
GitHub repositories and add the
dsh-plugin topic for discoverability.
The official repository does not accept external PRs and does not mandate a
community plugin template. See
CONTRIBUTING.zh.md.

License

MIT. The webserver port expression in the suggested cordis.patch.yml snippet
is adapted from the DeepSeek Harness web app bundle patch; the original
DeepSeek copyright and MIT notice are preserved in NOTICE.