DSH Web supports running multiple instances. Managing multiple local instances requires a clear view to check status, start a new instance, or stop an existing instance. dsh-instance-manager is the instance manager for DSH Web and handles these operations.

It is maintained by xswt442-cmd and licensed under the MIT license.

Installation and Enablement

Use the following command to install the plugin and register it in the web profile:

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

This step installs the npm package and registers the profile. Restart DSH Web after installation to apply the changes. Note: running npm install alone only installs the package; it does not enable the plugin.

Core Features

  1. Status display: Displays one line of information for each instance, including port, PID, uptime, session count, resident memory, and version. The current instance is listed first.
  2. Start a new instance: If the port is left empty, the first free port in the configured starting port range is used. If a specified port is already in use, an error is reported directly, and no other ports are attempted.
  3. Stop an instance: Supports stopping a single instance, the current instance, or all local instances. Remote instance rows are read-only and do not participate in stop-all operations.
  4. View: Provides a read-only view for each instance, including stdout/stderr logs, a session summary, and the contents the instance is running.
  5. Remote instances: After configuring the peer list, instances on remote machines, along with their logs and sessions, can be viewed in the panel.
  6. Agent tools: Provides the command-line tools instance_list, instance_start, instance_stop, instance_logs, and instance_sessions.

Entry and Configuration

The panel entry is the menu icon in the lower-left area of the workspace, to the right of the sidebar.

The plugin can be configured through the live and startup sections.

  • live: Includes the refresh interval (refreshIntervalMs), Fleet token (fleetToken), and peer list (peers). Changes to this section usually take effect immediately.
  • startup: Includes the port range (portRange). This section has applies: 'restart'; it is read only on restart, and changes that have not taken effect are marked as pending in the settings interface.

The default port range is '3080-3129,19387'.

Environment variables can also be used for configuration:

$env:DSHIM_REFRESH_INTERVAL_MS = '4000'
$env:DSHIM_FLEET_TOKEN = '<secret>'
$env:DSHIM_PEERS = 'id@origin'
$env:DSHIM_PORT_RANGE = '3080-3129,19387'

Notes

  • Permission security: The Fleet token does not provide operation-level permission controls; the holder can start or stop local instances and read session information. Therefore, the token should be granted only to trusted devices.
  • Port conflicts: During startup, if the specified port is already in use, the plugin reports an error and does not automatically switch to another port.
  • Remote limitations: Remote instances are read-only in the panel. They cannot be stopped directly from the panel and can only be operated on through Agent tools.