📦 @goodandready/dsh-server-monitor

---

A standalone, read-only Linux server monitor for the DeepSeek Harness sidebar. This package owns its server profiles and credentials; it does not depend on dsh-remote-workspace or reuse another plugin’s connection settings.

MVP scope

• Add and manage SSH profiles for Linux, macOS, BSD, and Windows OpenSSH.
• Connect with an SSH private key (inline or server-side key path) or password authentication.
• Generate Ed25519 SSH keys directly in the UI, copy a ready-to-use setup command for target servers, and verify the connection.
• Show current host, CPU, memory, swap, disk, process, container, network, and listening-port data.
• Refresh every 15 seconds while the sidebar is visible.
• Container management for Docker and Podman: status cards (running/exited), quick start/stop/restart, and container logs modal.
• System log viewer (journalctl): filter by unit and priority (err..emerg), with one-click "Analyze with AI" diagnostic context export.
• Maintenance runbooks: curated snippet library and custom scripts, executable on target host or across servers by tag (#prod, #staging).
• The last hour is drawn as sparklines, and the operator can open an interactive terminal session.

Credential boundary

Credentials belong to this plugin and are stored in its private vault on the DSH host. On POSIX hosts the plugin enforces and verifies owner-only mode 0600, and stops if that permission cannot be established. SSH keys generated via the UI are saved to ~/.dsh/keys/id_ed25519_dsh (directory 0700, file 0600). Secret values and private keys are never written to DSH settings or returned to the browser; profile APIs expose only masked values and presence flags. A configured private-key path is read on the DSH host.

Development checks

Run the same checks used by Gitea Actions:

npm ci
npm test

Tests use mocked SSH connections and do not connect to real servers. The Gitea Actions workflow runs these commands for pushes and pull requests.

Languages

The plugin UI ships English and Chinese dictionaries and uses the DSH locale service, allowing dsh-russian-lang to supply Russian translations. See README.zh.md and README.ru.md.

Requirements

• A DSH web profile with the plugin installed and SSH reachability from DSH to each Linux host.
• A remote account allowed to run standard read-only system commands. Docker/Podman data requires permission to query that runtime.
• A private-key path must be readable by the DSH service account on the DSH host.
• Runtime Dependency (ssh2): Requires ssh2 (^1.17.0) in dependencies (not peer) for SSH protocol handling and Ed25519 keypair generation. It is automatically installed from the package registry.
• Pure JavaScript Fallback: No C/C++ compiler or Python build toolchain is required on the host. While ssh2 includes optional native acceleration modules (cpu-features, sshcrypto), it falls back automatically and cleanly to a pure JavaScript implementation if native build tools are unavailable.
• Air-Gapped / Offline Environments: When installing from a .tgz tarball in an isolated network, ensure ssh2 and its transitive dependencies are available in your local package manager store or internal mirror.

Install

Replace web with your DSH profile:

dsh plugin --profile web add @goodandready/dsh-server-monitor

Follow the CLI prompts. In the plugin settings card, add a server, choose key or password authentication, test the connection, and save. Open Server Monitor in the sidebar. Remove with dsh plugin --profile web remove @goodandready/dsh-server-monitor.

Configuration

Manage profiles in the DSH settings card. Import from SSH config reads ~/.ssh/config, skips wildcard and git hosts, and lets you choose which hosts to add. The agent tools server_monitor_hosts and server_monitor_exec list hosts without secrets and run one non-interactive command with a 1–300 second timeout. Settings contain connection metadata only: do not place passwords, private-key contents, or passphrases in settings or config files.

Field	Type	Default	Meaning
profiles	array	[]	Plugin-owned SSH profiles.
profiles[].id	string	generated	Stable profile ID.
profiles[].name	string	empty	Display name.
profiles[].host	string	empty	Linux host reachable from DSH.
profiles[].port	number	22	SSH port.
profiles[].username	string	root	Remote account; prefer restricted permissions.
profiles[].authType	string	key	key or password.
profiles[].privateKeyPath	string	empty	Optional key path on the DSH host.
profiles[].shell	string	posix	posix sends probes to /bin/sh -s on stdin. powershell uses powershell.exe -EncodedCommand. Without /proc/meminfo, macOS and BSD are collected with sysctl. Choose powershell for Windows. The Terminal button opens a loopback xterm session.
profiles[].tags	string list	empty	Comma-separated labels. The server list can filter by one tag and by search text.
profiles[].proxyJump	string	empty	Another profile id, or user@host:port. The connection is opened through that bastion.
activeProfileId	string	empty	Selected profile ID.
pollIntervalSec	number	30	Background probe interval: 10, 30, 60, or 300. Other values use 30.

The settings card stores secret values in the plugin-owned vault on the DSH host. POSIX vault operations require verified owner-only permissions (0600).

SSH key generation and sharing with other plugins

You can generate a dedicated Ed25519 keypair directly from the settings card by clicking Generate SSH key. The private key is saved on the DSH host at ~/.dsh/keys/id_ed25519_dsh (mode 0600). The UI displays the public key and a one-line setup command to paste on your target server. Once executed, click Command ran — test connection to test connectivity immediately.

This key path can also be configured in other local plugins such as dsh-remote-workspace to share the same management key without duplicating credentials.

Collected data

The bounded, read-only collector reports host/OS/kernel/CPU, load and uptime, memory and swap, mounted filesystem usage, up to 12 CPU-heavy processes, running Docker or Podman containers, network byte/packet counters and the one-second Rx/Tx rate measured on the host, and listening TCP/UDP ports (ss, falling back to netstat). A section can be empty if a command, runtime, or permission is unavailable. The server card shows the last SSH error and the probe latency in milliseconds. History is stored under the plugin metrics directory as raw, 1-minute, 15-minute and 1-hour samples, and GET /dsh-server-monitor/history returns one field for a time range. The first successful probe copies the previous day of CPU and memory from sar when sysstat is installed. Month traffic adds byte deltas for the UTC calendar month, ignores a counter drop after reboot, and starts again on the first day of the next month. Each server card draws the last hour of CPU, memory and disk as an SVG sparkline. A gap longer than 90 seconds breaks the line. CPU is stored as a percent of the core count when that count is known.

Architecture

flowchart LR
  UI[DSH sidebar] --> Client[Plugin client]
  Client --> Routes[Trusted local routes]
  Routes --> Settings[Profiles]
  Routes --> Vault[Credential vault]
  Routes --> SSH[SSH service]
  SSH --> Linux[Read-only Linux collector]
  Linux --> Snapshot[Current snapshot]
  Snapshot --> Client

Module	Responsibility
lib/index.js	Cordis registration, settings, service lifecycle.
lib/client.js	Sidebar/settings UI; pauses polling while hidden.
lib/routes.js	Trusted-request checks, profile operations, snapshot cache.
lib/profile.js	Profile normalization and validation.
lib/vault-service.js	Credential storage and POSIX permission verification.
lib/ssh-service.js	SSH authentication, bounded commands, reuse and cleanup.
lib/linux-collector.js	Snapshot parsing and the Linux /proc probe.
lib/snapshot-commands.js	macOS, BSD, and Windows collection commands.
lib/pty-bridge.js	Loopback terminal upgrade and xterm assets.
lib/agent-tools.js	Agent tools that list hosts and run one bounded command.
lib/plugin-updater.js	Version checking and one-click in-card plugin updates.

Internal HTTP routes

These DSH-client routes accept only a loopback client. Origin, Referer and Sec-Fetch-Site are checked for that local browser and do not admit another machine. They are not a public or remote-management API.

Method	Path	Purpose
GET	/dsh-server-monitor/state	Sanitized profiles and selected ID.
GET	/dsh-server-monitor/snapshot?profileId=<id>	Current snapshot; defaults to active profile.
GET	/dsh-server-monitor/update	Current and latest version status.
POST	/dsh-server-monitor/update	Run one-click plugin update via DSH CLI.
POST	/dsh-server-monitor/profiles/save	Create/update a profile.
POST	/dsh-server-monitor/profiles/delete	Delete profile, stored secrets, the SSH session and local metric files.
POST	/dsh-server-monitor/profiles/active	Select active profile.
POST	/dsh-server-monitor/keys/generate	Generate Ed25519 keypair in ~/.dsh/keys (0600) and return public key + setup command.
POST	/dsh-server-monitor/test	Test SSH connection.
GET	/dsh-server-monitor/history	Stored samples for one profile and field.
GET	/dsh-server-monitor/profiles/import-ssh-config	Concrete hosts from the local SSH config.
GET	/dsh-server-monitor/vendor/*	xterm files for the terminal, loopback only.
WebSocket	/dsh-server-monitor/pty	Interactive shell for one saved host, loopback only.
POST	/dsh-server-monitor/containers/action	Start, stop, or restart a Docker/Podman container.
GET	/dsh-server-monitor/containers/logs	Fetch container logs with tail limit.
GET	/dsh-server-monitor/logs	Query system logs (journalctl) with unit and priority filtering.
GET	/dsh-server-monitor/runbooks	List configured and default maintenance runbooks.
POST	/dsh-server-monitor/runbooks/save	Add or update a maintenance runbook.
POST	/dsh-server-monitor/runbooks/delete	Delete a maintenance runbook.
POST	/dsh-server-monitor/runbooks/exec	Execute runbook on a single server or across hosts matching a tag.
GET	/dsh-server-monitor/alerts/config	Retrieve current alert thresholds and webhook URL.
POST	/dsh-server-monitor/alerts/save	Update alert thresholds and webhook configuration.
POST	/dsh-server-monitor/alerts/test	Trigger a test incident alert delivery.
GET	/dsh-server-monitor/alerts/history	Retrieve recent incident alert history.
GET	/dsh-server-monitor/files/read	Read remote configuration file safely over SSH.
POST	/dsh-server-monitor/files/write	Save remote file with atomic .bak backup creation.

Snapshots are cached per profile for 15 seconds from collection start; concurrent requests share a collection. Save/delete invalidates that profile’s cache.

Security and support

The plugin owns its SSH credentials and never returns secrets to the browser. Background probes are read-only. The Terminal button opens one interactive SSH session and accepts the upgrade only from loopback. Alerts are not included.

• Issues: GitHub Issues
• License: MIT

Visual verification