Introduction

DeepSeek Harness (DSH) allows you to run multiple instances locally on different ports (such as 3080–3129) at the same time. Manually switching tabs to view logs, check process states, or stop instances can add operational overhead. The dsh-instance-manager plugin centralizes monitoring and control of all local instances in a persistent sidebar panel.

What Is This?

This is a persistent DSH plugin that provides a sidebar panel to uniformly view and gracefully stop local dsh instances on ports 3080–3129. The project is maintained by xswt442-cmd and licensed under the MIT License.

Core Features

The plugin provides the following core capabilities:

  1. Instance List and Details
    Displays detailed information for each instance, including port, PID, uptime, session count, resident memory, and version. The current instance is always placed in the first row of the list; other instances are sorted by ascending port number.

  2. Start a New Instance
    When starting a new instance from the sidebar panel, if the port is left blank, the plugin automatically selects the first available port within the managed port range (default 3080–3129) and starts the instance. If the specified port is already in use, it returns an error directly and does not attempt to use another port.

  3. Open and Navigate
    Clicking the :port link in the list navigates to that instance’s interface. The plugin automatically handles token redirection logic.

  4. Stop Instances
    Supports stopping a single instance, stopping the current instance, or stopping all local instances. All stop operations are performed through the target instance’s own graceful exit process, rather than force-killing the process.

  5. Log and Session Viewing
    Provides a read-only view for each instance, allowing inspection of stdout/stderr logs and session summaries.

  6. Remote Instance Support
    After configuring a peer, the panel can view remote instances and their logs. Remote instance rows are read-only and do not participate in stop-all operations.

  7. Agent Tools
    Provides command-line tools such as instance_list, instance_start, instance_stop, instance_logs, and instance_sessions.

Installation and Enablement

Install the npm package and register it to the web profile. After installation, restart DSH Web for the changes to take effect.

dsh plugin --profile web add dsh-instance-manager

Configuration

The plugin can be configured in DSH Settings, and default values can also be set via environment variables. Main configuration options include:

  • Dock Placement: The dock position of the control panel in the main interface.
  • Refresh Interval: Controls how frequently list data is refreshed.
  • Startup Port Range: Sets the available port range when starting instances.
  • Fleet Token: Used for remote authentication and security validation.
  • Peers: Configures remote peer addresses to monitor.

Example environment variables:

$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'

Security

The plugin includes built-in local guard mechanisms:

  • Access Control: Rejects requests with cross-origin Origins and non-loopback Hosts.
  • Token Verification: The validity of a Fleet token is evaluated based on the actual TCP peer address (socket), not solely the HTTP Host header. If the peer address is missing or the token cannot be resolved, the request is rejected.
  • Permission Division: Fleet token holders have the permission to start or stop local instances and read session information, but there is no finer operational permission separation. Tokens should only be granted to trusted devices.
  • Interface Exposure: Server-Sent Events (SSE) are only exposed to localhost.

Notes

  • Remote Instance Limitations: After configuring a peer, viewed remote instances are read-only and do not participate in local one-click stop operations.
  • Development Requirements: Before submitting code, run npm test, npm run docs:check, and npm pack --dry-run.

Resources