Paseo can install this plugin directly from GitHub. You do not need to clone the repository or run npm install first.
Recommended GitHub shorthand:
\npaseo plugin add infectiousstupidity/paseo-prometheus-status\nOr use the full Git URL:
\npaseo plugin add https://github.com/infectiousstupidity/paseo-prometheus-status.git\nVerify that it is running:
\npaseo plugin ls paseo-prometheus-status\nPaseo tracks the repository's default branch, so later updates are also handled directly by Paseo:
\npaseo plugin update paseo-prometheus-status\nConfigure the plugin in Settings → Plugins → GPU status, then open the GPU status panel from Paseo's workspace/Explorer panel launcher or search for Open GPU status in the Command Center.
","readmeText":"# Paseo Prometheus Status\n\nA Paseo 0.8+ plugin that shows GPU utilization, temperature, VRAM, and power from Prometheus. The composer stays clear during normal operation and only shows a GPU pill when temperature needs attention.\n\n## Install\n\nPaseo can install this plugin directly from GitHub. You do **not** need to clone the repository or run `npm install` first.\n\nRecommended GitHub shorthand:\n\n```bash\npaseo plugin add infectiousstupidity/paseo-prometheus-status\n```\n\nOr use the full Git URL:\n\n```bash\npaseo plugin add https://github.com/infectiousstupidity/paseo-prometheus-status.git\n```\n\nVerify that it is running:\n\n```bash\npaseo plugin ls paseo-prometheus-status\n```\n\nPaseo tracks the repository's default branch, so later updates are also handled directly by Paseo:\n\n```bash\npaseo plugin update paseo-prometheus-status\n```\n\nConfigure the plugin in **Settings → Plugins → GPU status**, then open the GPU status panel from Paseo's workspace/Explorer panel launcher or search for **Open GPU status** in the Command Center.\n\n## Composer alert\n\nThe composer pill is alert-only:\n\n- Below `75°C`: hidden.\n- `75–84°C`: shown in the warning color while GPU utilization is above `0%`.\n- `85°C` or hotter: always shown in the danger color, even if utilization has fallen to `0%`.\n\nThe critical-temperature override is intentional. A dangerously hot idle GPU should not disappear just because utilization reads zero.\n\nPress the pill to open the full GPU status panel. The panel shows utilization, temperature, VRAM, and power for each GPU.\n\n\n\n## Data source\n\nPrometheus is the only data source. By default, the plugin reads these NVIDIA DCGM Exporter metrics:\n\n- `DCGM_FI_DEV_GPU_UTIL`\n- `DCGM_FI_DEV_GPU_TEMP`\n- `DCGM_FI_DEV_FB_USED`, `DCGM_FI_DEV_FB_FREE`, and `DCGM_FI_DEV_FB_RESERVED`\n- `DCGM_FI_DEV_POWER_USAGE`\n\nThe plugin connects only to the configured Prometheus endpoint. It does not connect directly to GPU hosts.\n\n## Temperature thresholds and Prometheus alerts\n\nThe composer alert currently uses the plugin's built-in `75°C` warning and `85°C` critical thresholds. These are the same thresholds used by the status panel.\n\nPrometheus alerting rules can also be used as a single source of truth, but the threshold itself is not part of the normal GPU metric. Prometheus exposes active alert rules through the synthetic `ALERTS` metric. Supporting that cleanly would require the plugin to know which alert rule or labels represent GPU temperature warnings and critical alerts.\n\n## Configuration\n\nOpen **Settings → Plugins → GPU status**. The native Paseo settings screen lets you configure:\n\n- Prometheus URL\n- Metric selector\n- Host label\n- Whether the host label appears in the composer pill\n- Optional custom Prometheus queries\n\nSaving updates the plugin immediately. You do not need to reload Paseo.\n\nThe settings are stored in `paseo-prometheus-status.json`:\n\n- Windows: `%USERPROFILE%\\.paseo\\paseo-prometheus-status.json`\n- macOS and Linux: `~/.paseo/paseo-prometheus-status.json`\n- Custom home: `$PASEO_HOME/paseo-prometheus-status.json`\n\nThe file can still be edited by hand if needed:\n\n```json\n{\n \"prometheusUrl\": \"http://prometheus.example:9090\",\n \"selector\": \"job=\\\"dcgm-exporter\\\",instance=\\\"gpu-host.example:9400\\\"\",\n \"hostLabel\": \"Inference server\",\n \"showHostLabelInPill\": false\n}\n```\n\n`selector` is inserted inside the label braces of the built-in Prometheus queries. Do not include the braces yourself.\n\nWith `showHostLabelInPill` set to `false`, an active alert pill shows a compact summary such as `GPU 42% · 78°C`. Set it to `true` to include the host label.\n\n### Custom queries\n\nThe **Advanced queries** section can replace any built-in query. Leave a field blank to keep the default.\n\nThe matching JSON properties are:\n\n```json\n{\n \"gpuQuery\": \"DCGM_FI_DEV_GPU_UTIL{job=\\\"dcgm-exporter\\\"}\",\n \"gpuTimestampQuery\": \"timestamp(DCGM_FI_DEV_GPU_UTIL{job=\\\"dcgm-exporter\\\"})\",\n \"temperatureQuery\": \"DCGM_FI_DEV_GPU_TEMP{job=\\\"dcgm-exporter\\\"}\",\n \"memoryUsedQuery\": \"DCGM_FI_DEV_FB_USED{job=\\\"dcgm-exporter\\\"}\",\n \"memoryTotalQuery\": \"DCGM_FI_DEV_FB_USED{job=\\\"dcgm-exporter\\\"} + DCGM_FI_DEV_FB_FREE{job=\\\"dcgm-exporter\\\"} + DCGM_FI_DEV_FB_RESERVED{job=\\\"dcgm-exporter\\\"}\",\n \"powerQuery\": \"DCGM_FI_DEV_POWER_USAGE{job=\\\"dcgm-exporter\\\"}\"\n}\n```\n\nBy default, freshness uses the source timestamp of the GPU utilization metric. If a custom utilization query changes that behavior, set `gpuTimestampQuery` to a query that returns each GPU's source timestamp in Unix seconds with the same GPU identity labels.\n\n### Environment variables\n\nEnvironment variables are available for containers and automated deployments. They override matching saved settings:\n\n- `PASEO_PROMETHEUS_URL`\n- `PASEO_PROMETHEUS_SELECTOR`\n- `PASEO_PROMETHEUS_HOST_LABEL`\n- `PASEO_PROMETHEUS_SHOW_HOST_LABEL_IN_PILL`\n- `PASEO_PROMETHEUS_GPU_QUERY`\n- `PASEO_PROMETHEUS_GPU_TIMESTAMP_QUERY`\n- `PASEO_PROMETHEUS_GPU_TEMPERATURE_QUERY`\n- `PASEO_PROMETHEUS_GPU_MEMORY_USED_QUERY`\n- `PASEO_PROMETHEUS_GPU_MEMORY_TOTAL_QUERY`\n- `PASEO_PROMETHEUS_GPU_POWER_QUERY`\n\nThe settings screen shows which environment variables are overriding saved values. Restart the Paseo daemon after changing environment variables.\n\nThe plugin refreshes every 10 seconds. A sample older than 30 seconds is shown as stale. A missing or unreachable Prometheus URL is shown as offline in the full status panel.\n\n## Security\n\nThe server part of this plugin runs with the same permissions as the Paseo daemon. It writes one configuration file and makes HTTP or HTTPS requests to the configured Prometheus URL. It does not run shell commands or connect directly to GPU hosts.\n\nUse HTTPS when Prometheus traffic crosses a network you do not trust. The plugin does not support custom authentication headers. Credentials placed directly in `prometheusUrl` are stored as plain text in the configuration file.\n\nOn macOS and Linux, settings saved through the plugin are written with mode `0600`. Windows uses the normal permissions of the current account.\n\n## Known limitations\n\n- One Prometheus endpoint and selector can be configured per plugin installation.\n- The default queries expect NVIDIA DCGM Exporter metric names. Other exporters need custom queries.\n- Prometheus authentication headers and bearer tokens are not supported.\n- Status updates every 10 seconds, so this is not a real-time GPU monitor.\n- Freshness is based on GPU utilization. Temperature, memory, or power queries can fail without hiding utilization data.\n- Composer temperature thresholds are currently built into the plugin rather than read from Prometheus alert rules.\n\n## Development\n\nThis branch targets Paseo 0.8 and later. It does not include a v0.7 compatibility entry.\n\n```bash\nnpm ci\nnpm run typecheck\nnpm run lint\nnpm run format:check\nnpm test\npaseo plugin install /absolute/path/to/paseo-prometheus-status\n```\n\nAfter source changes:\n\n```bash\nnpm run typecheck\nnpm test\npaseo plugin reload paseo-prometheus-status\npaseo plugin ls paseo-prometheus-status\n```\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n"}