dsh-top

dsh-top

A plugin for the DeepSeek Harness (DSH) web GUI: a system monitoring tool that shows live system stats in a floating, collapsible panel pinned to the top-right corner.

Features

• CPU — live utilisation (computed from os.cpus() tick deltas) + core count
• MEM — used / total with percentage bar (from os.totalmem() / os.freemem())
• DISK — used / total with percentage bar (platform-specific)
• NETWORK — download / upload throughput (platform-specific byte deltas)
• Top 6 processes — PID, name, CPU%, MEM% (platform-specific)
• Dark color-coded palette (cyan CPU, magenta RAM, yellow disk, blue/green network), monospace
• Draggable via the title bar, collapsible via the – / + button
• Transient monitor processes (ps, awk, head, …) are filtered out of the top-processes list

How it works

Part	File	What it does
Host half	lib/index.js	Registers GET /api/dsh-top-stats; CPU + memory use Node os APIs with container-aware cgroup overrides; disk, network and processes use per-platform collectors that degrade to null when unavailable.
Browser half	lib/client.js	dsh.client web bundle; registers the panel into the frame-wide shell.overlay slot; polls every 2 s (pauses while collapsed).
Composition	cordis.patch.yml	The dsh.bundle patch layer that inserts the loader entry.

Platform support

DSH host code runs on Linux, but the DSH server can be run on any OS Node.js supports. dsh-top is multi-platform: it always reports at least CPU + memory (Node os, no subprocess), and fills in disk / network / processes where the platform allows. Missing sections are shown as n/a in the widget rather than failing the whole request.

Platform	CPU	MEM	DISK	NETWORK	PROCESSES
Linux	✅	✅	df	/proc/net/dev	ps
macOS	✅	✅	df	netstat -ib	ps (BSD)
Windows	✅	✅	PowerShell Get-PSDrive	PowerShell Get-NetAdapterStatistics	PowerShell Get-Process†
Containers (cgroup)	✅*	✅*	df*	/proc/net/dev*	ps*
Other / unknown	✅	✅	n/a	n/a	n/a

† Windows process CPU is a lifetime-average percentage — Get-Process.CPU (cumulative CPU seconds) divided by process age, the same semantics Linux ps pcpu reports — and MEM% is derived from the real RSS bytes, not the raw working-set value. Every external collector (ps, df, powershell, …) runs with a 5 s timeout, so a wedged tool degrades its section to n/a instead of hanging the request.

* Container support is container-aware and graceful:

• Memory — when a cgroup memory limit is set (Docker --memory, a Kubernetes limit, systemd unit limit), the MEM meter reports the container's limit and current usage (cgroup v2 memory.max/memory.current, or v1 memory.limit_in_bytes/usage_in_bytes) instead of the host's total. On an unlimited cgroup it falls back to the host os.totalmem() view.
• CPU cores — when the cgroup restricts CPU (v2 cpu.max quota/period, or v1 cpu.cfs_quota_us/period_us), the core count reflects the quota; otherwise it uses os.cpus().length.
• Tightest ancestor wins, sentinels are safe — the limit files are read by walking our own cgroup path upward (not just the cgroup root), so a Docker limit under a host-level cap is reported correctly. Kernel-default sentinels are treated as "no limit": v2 max, v1 CFS -1, and the ~2^63 bytes v1 memory.limit_in_bytes reports on an unrestricted root — so an unrestricted host is never misread as having exabyte-sized RAM.
• Slim/distroless images that lack df/ps still report CPU + memory; the missing DISK/NETWORK/PROCESSES sections render as n/a.

The CPU + memory meters work on every Node platform. Disk, network and process meters depend on the listed command/pseudo-file being present — otherwise those sections render as n/a while the rest keep working.

Testing

npm test

Runs a zero-dependency suite (node --test) over the pure collector parsers with realistic fixtures: Linux (df, /proc/net/dev, ps), macOS (netstat -ib, BSD ps), and Windows (PowerShell JSON output — including the CPU-seconds→percentage and RSS-bytes→percent conversions), plus the cgroup file parsers (memory.max, cpu.max, CFS quota, and the "no limit" sentinels) and the live container memory/CPU fallback contract. The macOS/Windows parsers are verified here without needing a live Mac or Windows machine — only the thin command-execution wrapper around them is platform-bound.

Security

Because it is a system monitor, the host half reads host-wide CPU, memory, disk, network and process state. The cross-platform core (CPU + memory) uses Node's built-in os module — no subprocess and no OS-specific pseudo-files. Linux /proc reads go through Node's own fs.readFileSync. Only the platform collectors that need system tools invoke them — ps, df, and on Windows powershell — every time via execFileSync with a static argv array (never a shell string, no shell -Command interpolation of untrusted data), so there is no shell-injection surface and no attacker-controlled input. On Windows the PowerShell sub-command is a fixed script literal; none of its values come from the HTTP request. No data leaves the host, no credentials are read, and every read is read-only.

dsh.so's static scanner flags node:child_process as "critical". That is a heuristic signal on the mere presence of process access — not a vulnerability. Process access is intrinsic to a monitoring tool; review the (small) source yourself: the collectors are platform-whitelisted, argument-confined, and read-only, and any failure degrades to "n/a" rather than failing the request.

Install

dsh plugin --profile web add dsh-top

Then restart the web app and refresh the page — the panel appears at the top-right.

License

MIT