sparkDash ⚡ — Multi-unit monitoring dashboard for NVIDIA DGX Spark

_{by Mia'a AI Lab}

sparkDash is a real-time web dashboard for one or more NVIDIA DGX Spark (GB10) machines in a single browser window. It streams GPU, CPU, unified memory, storage, network, and local LLM metrics — and lets you add, edit, reorder, or remove Sparks from the UI without restarts or code changes.

It also supports non-Spark units: any Linux machine with an NVIDIA GPU (e.g. a workstation with a dedicated RTX/L-series card) can be added as a dedicated GPU host and monitored the same way via SSH and nvidia-smi. For these units the dashboard correctly separates RAM (system memory) from VRAM (discrete GPU memory).

LLM Prompt Showcase

_{Download MP4 · also in assets/llm-showcase.mp4}

Table of contents

• Latest version changelog
• Features
• ComfyUI monitoring
• Hermes Agent monitoring
• Full changelog
• Quick start
• Architecture
• Tech stack
• Repository layout
• REST API
• Configuration
• Security
• Scripts
• How it works
• Contributing
• License

Latest version changelog

Version 1.8.0 — Non-Spark units, prefill, and host RAM/VRAM

• Non-Spark unit support — add a dedicated GPU host (kind host): any Linux box with an NVIDIA GPU, monitored via the same SSH + nvidia-smi collectors but not labeled as a DGX Spark. Hosts get a detected hardware summary (GPU model / driver / CPU / RAM) and separate RAM vs VRAM panels — VRAM is real discrete GPU memory from nvidia-smi, RAM is system memory from /proc/meminfo. On the unit page the Resources layout for hosts is GPU in the left column with RAM → Network → Storage stacked in the right column (Sparks keep their original layout). Overview cards add a RAM bar for hosts.
• Prefill tok/s next to decode — live LLM panel sparkline, Overview cards as two columns (tok/s | prefill), decode-bench Prefill column (prompt_tokens ÷ TTFT)
• Live prefill — vLLM engine-step tokens (including short prefills that share a poll with first decode); ds4 computed prefill diffs; 0 when idle. Shows while the engine is reading the prompt / building KV cache (send or regenerate), not when you only open a saved chat

Version 1.6.0 — ComfyUI monitoring & compact default

• ComfyUI — opt-in per Spark (port 8188): live jobs, progress, last run, cancel, queue ETA, Open on LAN IP, model inventory
• Overview — Comfy status chip (idle / run / Nq)
• Layout — collapsible Resources / Services; LLM + Comfy side-by-side; multi-LLM row rules
• Compact UI — default density (comfortable still in Settings)

Full history: CHANGELOG.md

Features

ComfyUI monitoring

sparkDash can optionally monitor a ComfyUI instance on each Spark — the same way it probes local LLMs, but focused on jobs and queue, not a second copy of GPU/RAM bars (those stay on the GPU / CPU panels).

What is supported

Not claimed: true per-job VRAM (Comfy does not expose that cleanly over HTTP). Host GPU/VRAM remains on the GPU panel. Live step progress depends on Comfy broadcasting WS events; stock Comfy often scopes detailed progress to the client that submitted the prompt.

How to enable (per Spark)

1. Open the Spark tab → Edit (pencil).
2. Enable ComfyUI monitoring.
3. Set port if needed (default 8188).
4. Save.

The Spark page Services section shows the ComfyUI card. On Overview, a small Comfy chip appears for that unit.

Connectivity Test (in Edit) includes ComfyUI when monitoring is enabled.

ComfyUI side requirements

• ComfyUI must be reachable from the sparkDash server on the probe host:
• Local Spark (isLocal): sparkDash probes 127.0.0.1:{port} (use Docker network_mode: host if the dashboard runs in a container).
• Remote Spark: probe uses the Spark LAN IP (same as LLM probes).
• For Open from another machine’s browser, Comfy should listen on a reachable interface (e.g. --listen 0.0.0.0), not only loopback, and the Spark’s LAN IP must be set correctly in Edit.

Config fields (persisted on the Spark)

Related API

Env (optional): COMFY_PORT (default 8188), COMFY_PROBE_TIMEOUT_MS, POLL_INTERVAL_COMFY.

Hermes Agent monitoring

sparkDash can optionally monitor Hermes Agent (nousresearch/hermes-agent) on each unit and run one-click updates for you over SSH.

What is supported

How to enable (per Spark)

1. Open the Spark tab → Edit (pencil).
2. Enable Hermes Agent.
3. Save — background checks start immediately.

The Update Hermes button appears in the Spark header/mobile action row; it turns warning-yellow with a commit-count badge only when an update is actually available. It also appears on Overview (batch) when at least one unit has Hermes enabled.

Connectivity check note: local units run the check as the host user (via setpriv/nsenter, never as container root); remote units run it over SSH. Either way, the logged-in user needs permission to read the Hermes repo.

Side requirements

• Hermes Agent must be installed on the target machine — sparkDash only checks & updates; it does not install it. The binary is looked up in ~/.local/bin and /usr/local/bin.
• SSH user must be able to run hermes update --check / hermes update non-interactively (key auth recommended).
• An update can take a few minutes (repo pull + dependency reinstall); a stale *.lock file from a crashed run is cleared before each attempt.

Config fields (persisted on the Spark)

Related API

Env (optional): POLL_INTERVAL_HERMES (default 600000 ms), HERMES_UPDATE_TIMEOUT_MS (default 600000 ms).

Quick start

git clone https://github.com/MiaAI-Lab/sparkDash.git
cd sparkDash

# Production (Docker)
docker compose up --build -d

# Or development (host, with hot reload)
npm install
npm run dev

• Docker: open http://<host-ip>:5555 (arm64 image, auto-restart, host mounts for GPU/metrics access)
• Dev: Vite on http://localhost:5173 (proxies API/WS to Express)

For development with Docker (source-mounted, HMR):

docker compose -f docker-compose.dev.yml up --build

Architecture

Design principle: one Spark model, N instances. Every unit is a record in config/sparks.json with a kind field (spark or host). The same SparkMonitor, SystemCollector, and LlmProbe code runs for all of them. Adding a unit is a config change, not a code change.

┌────────────────────── Docker container (sparkDash) ──────────────────────┐
│  Express (server/)                                                         │
│  ├─ config/sparks.json        Spark registry (API read/write)              │
│  ├─ SparkRegistry             load/persist Sparks; change events           │
│  ├─ SparkMonitor (per Spark)  collector + LLM probe + rate baselines       │
│  │   ├─ SystemCollector       local sysfs/proc OR remote SSH               │
│  │   └─ LlmProbe              HTTP to host:LLM_PORT, backend autodetect    │
│  ├─ REST /api/*                                                            │
│  └─ WebSocket /ws             snapshot stream to browsers                  │
│  React SPA (src/)  — Overview + per-Spark pages, themes, dialogs           │
└────────────────────────────────────────────────────────────────────────────┘
         │ SSH (key or sshpass)                    │ HTTP :8888
         ▼                                         ▼
    remote Spark(s)                         each Spark’s LLM server

Data flow

Browser  ←→  WebSocket /ws   ←→  SparkMonitor.snapshot()  ←→  collectors
Browser  ←→  REST /api/*     ←→  SparkRegistry + SparkMonitor

Poll loops run in the background (even with no clients) so rate metrics — tokens/s, network bytes/s, disk I/O — stay correct.

Tech stack

Repository layout

sparkDash/
├── src/                 React + TypeScript SPA
│   ├── api/             REST client + shared types
│   ├── components/      Overview, Spark pages, dialogs, UI primitives
│   ├── hooks/           WebSocket snapshot, routing
│   └── theme / CSS      Tailwind v4 + four themes
├── server/              Express + WebSocket (plain JS ESM)
│   ├── sparks/          SparkRegistry, SparkMonitor
│   ├── collectors/      SystemCollector, LlmProbe, ssh
│   ├── secretsStore.js  Encrypted password persistence
│   └── validate.js      Host/user validation (SSRF-minded)
├── config/              Runtime state (volume; secrets gitignored)
├── assets/              Screenshots
├── Dockerfile           Production multi-stage arm64
├── docker-compose.yml   Production
├── docker-compose.dev.yml
└── deploy.sh            Rebuild / recreate helpers

REST API

There is no authentication on the HTTP/WebSocket API. Run sparkDash only on a trusted network (or behind your own reverse proxy with auth).

Configuration

Global settings (UI or API)

Gear icon in the header, or GET/PUT /api/settings:

Environment variables

Copy .env.example to .env if needed:

When using Docker's default bridge network, keep BIND_HOST=0.0.0.0.
With network_mode: host, use BIND_HOST=127.0.0.1 to restrict access to the local host or a reverse proxy.

Adding a unit

1. Open the + tab.
2. Choose Unit type: - NVIDIA DGX Spark — the default; hardware summary shows DGX Spark specs and the CX7 IP field is available. - Dedicated GPU host — any Linux machine with an NVIDIA GPU. It is monitored exactly like a Spark (SSH + nvidia-smi) but is not reported as a DGX Spark: the header shows a detected hardware summary (GPU model, CPU, RAM) instead of fixed GB10 specs, and the page shows separate RAM and VRAM panels (VRAM from nvidia-smi, RAM from system memory). On the unit page, RAM → Network → Storage stack in the right column with GPU filling the left column.
3. Set Name, LAN IP (required), optional CX7 IP (Sparks only), SSH user, and auth (key or password). Wake-on-LAN MAC is auto-read from enP7s7 when online (optional override in Edit).
4. Test Connection for SSH + LLM reachability.
5. Save — a tab appears and metrics start streaming.

Power controls (shutdown / Wake-on-LAN)

• Shutdown (per Spark or Shutdown All on Overview) runs over SSH:
  sudo -n /usr/local/bin/spark-shutdown
  Install that script on each Spark and allow passwordless sudo for it only.
• Wake / Wake All send a UDP magic packet (port 9). The MAC is taken from the enP7s7 interface automatically while the Spark is online (persisted as detectedMacAddress). Optionally set a MAC override in Edit Spark. Broadcast is derived as /24 from LAN IP, or 255.255.255.255 if LAN IP is missing.
• Batch shutdown only targets online Sparks; offline nodes are skipped.
• Same trust model as the rest of the API: do not expose port 5555 beyond a trusted network — power actions are not separately authenticated.

Themes

Header theme control cycles:

Choice is stored in localStorage.

Security

• SSH passwords are not stored in sparks.json and are never returned by the API.
• Passwords are encrypted with AES-256-GCM in config/sparks-secrets.json (survives restarts).
• Encryption key: config/.secrets-key (auto-generated) or SPARKDASH_SECRETS_KEY. Do not delete the key file or encrypted secrets become unreadable.
• Target validation rejects clearly unsafe IPv4 targets (link-local 169.254.0.0/16, 0.0.0.0/8, multicast/reserved ≥ 224). Private, loopback, and public addresses are allowed so LAN and remote Sparks work.
• SSH and HTTP probes use short timeouts (about 5 s SSH connect, 3 s HTTP) so a hung host cannot stall the poll loop.
• Prefer SSH keys over passwords.
• Treat the dashboard as LAN-trusted: the API is intentionally unauthenticated for ease of use on a private network. That includes power APIs (shutdown / Wake-on-LAN): anyone who can reach the dashboard can request fleet power actions.

Scripts

How it works

Local vs remote Sparks

One SystemCollector path for both modes. When spark.isLocal is true, metrics come from host sysfs/proc and nvidia-smi (often via nsenter into the host namespace). Remote Sparks wrap the same commands in a shared sshExec() helper (key agent or sshpass). For kind: "host" units, actual hardware (GPU model, driver version, CPU, RAM) is detected once and cached in place of the static DGX Spark specs, and GPU VRAM comes straight from nvidia-smi while system RAM is read from /proc/meminfo.

Graceful degradation

Collectors catch errors and return zero/default metrics instead of crashing the loop. After sustained liveness failures, a Spark is marked offline; the UI shows stale or empty states rather than hard errors.

Hot configuration

Name, IP, SSH credentials, LLM port, and device/interface filters update the running SparkMonitor without tearing down poll loops or losing rate baselines. Registry writes are atomic (temp file + rename).

LLM probe

Each configured LLM port gets its own LlmProbe instance running in parallel. Probes auto-detect backends:

• llama.cpp — /slots for live decode rates; model from /props
• ds4-server (Entrpi/ds4-on-spark) — /v1/models (owned_by: ds4.c) + Prometheus ds4_* token counters for live tok/s
• vLLM / sglang — /v1/models; sglang via /get_server_info (last_gen_throughput when metrics off), vLLM via Prometheus /metrics counters (scientific notation supported)

Rates are derived from per-probe cumulative counter diffs (or SGLang sticky throughput while it moves). Multiple ports can be added or removed at runtime without restarting the monitor.

Contributing

Contributions are welcome. Conventions:

• Server: plain JavaScript ESM
• Client: TypeScript + React
• Prefer extending the shared Spark model over per-unit special cases

License

MIT — Copyright (c) 2026 Mia'a AI Lab

Acknowledgements

• Built for the NVIDIA DGX Spark (GB10) on ARM64
• Rebuilt from a legacy multi-unit dashboard with a single shared Spark model (no copy-pasted “Spark N” code paths)
• LLM probe behavior refined from production monitoring experience