vLLM Stats — GNOME Shell extension

Shows live vLLM metrics in the GNOME top bar. Polls each configured vLLM server's /metrics endpoint every 2 seconds by default, with status color-coding.

What it shows

Top bar (compact): gen-tok/s · KV% · prefix-hit% · running

Popup menu (click the indicator):

• Header: model, endpoint, last update time
• Eight metrics in equally sized square tiles (2 rows of 4), color-coded: Requests running · Queued for capacity · Preemptions · Prefix hit rate · Generation tok/s · Prefill tok/s · KV cache % · Spec-decode acceptance %
• Status notes under each tile (for example OVERSUBSCRIBED, lifetime hit rate, low under load); full note on hover
• Error status when a server is unreachable
• "Open dashboard" menu action (opens the configured dashboard URL; hidden when no URL is set)

Requirements

• GNOME Shell 48–50
• One or more vLLM servers exposing Prometheus metrics at /metrics
• libsoup3 (gi://Soup)

Install

Run the one-shot installer for the current user. Requires GNOME Shell 48–50, gnome-extensions, glib-compile-schemas, Python 3, tar, and curl or wget.

curl -fsSL https://git.salix.host/salix/vllm-status-bar/raw/branch/master/install.sh | bash

It downloads the source, compiles the settings schema, bundles all extension files, installs the bundle, and tries to enable it. Run it again to update. Configured servers are preserved.

To install a different branch:

curl -fsSL https://git.salix.host/salix/vllm-status-bar/raw/branch/master/install.sh | bash -s -- some-branch

You can also set BRANCH=some-branch on the bash command.

From a local checkout, install the working copy with:

./install.sh

Passing a branch to ./install.sh downloads that branch instead.

Log out and back in to load the installed version. On X11, you can instead restart GNOME Shell with Alt+F2, then r. If the installer could not enable the extension before the restart, run:

gnome-extensions enable vllm-stats@dyo

Configure

Open the settings page with:

gnome-extensions prefs vllm-stats@dyo

The settings window has:

• Primary endpoint — vLLM server base URL, for example http://127.0.0.1:8000. The extension polls that host's native /metrics endpoint. This server is shown in the top bar and the popup.
• Add server adds another endpoint. There is no fixed server limit. Each extra server has a remove button. All configured servers appear in the popup; the first nonempty endpoint supplies the top bar.
• Dashboard URL (optional) — URL opened by "Open dashboard" in the popup. If empty, the action is hidden.
• Refresh interval (seconds)
• Test per endpoint — verifies /metrics and shows the model name

Existing primary and secondary endpoints migrate automatically on first use. Blank endpoints are ignored. With no servers configured, the popup prompts you to add one in preferences.

Changes apply to the running indicator immediately. The same settings can be set directly via GSettings:

gsettings set org.gnome.shell.extensions.vllm-stats endpoints "['http://127.0.0.1:8000', 'http://host:8001']"
gsettings set org.gnome.shell.extensions.vllm-stats dashboard-url 'http://127.0.0.1:3000'
gsettings set org.gnome.shell.extensions.vllm-stats refresh-interval 2

Development

• extension/extension.js — main extension logic
• extension/endpoints.js — endpoint settings and migration
• extension/prefs.js — preferences dialog
• extension/schemas/ — GSettings schema
• extension/stylesheet.css — colors and status styling

Edits to extension.js are picked up with:

gnome-extensions reset vllm-stats@dyo
gnome-extensions enable vllm-stats@dyo

stylesheet.css is also re-read on extension reload.

Check the shell log for errors:

journalctl -f -o cat /usr/bin/gnome-shell