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. Copy the package into the DSH profile dependency directory:

   $src = '.\dsh-port-manager'
   $dst = "$env:USERPROFILE\.dsh\profiles\node_modules\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: 'dsh-port-manager'
         config:
           role: provider
   
       - id: dsh-port-manager-routes
         name: '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

Source	Priority
dsh web --port <n>	highest
$DSH_HOME/dsh-port-manager.json	high
DSH_WEB_PORT environment variable	medium
3080	default

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:

Method	Path	Description
GET	/status	current port, desired port, URL
GET	/ports	local listening ports (?force=1 to bypass cache)
POST	/apply	switch port, body {"port": 3210}

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.