labwatch-lite 1.1.0

Install

One command, nothing to configure:

uvx labwatch-lite

That is the whole install. uvx fetches LabWatch, starts it, and opens the dashboard.

Prefer a permanent command? Any of these work:

uv tool install labwatch-lite   # then: labwatch
pipx install labwatch-lite      # then: labwatch
pip install labwatch-lite       # then: python -m labwatch

Why the package is called labwatch-lite but the command is labwatch

The name labwatch on PyPI belongs to an unrelated project (rbretschneider/labwatch_cli), so this project publishes under the distribution name labwatch-lite to avoid silently installing someone else's tool. The import package and the console command both remain labwatch; only the name you type into pip/uvx/pipx differs. Installing plain labwatch from PyPI will give you the other project, not this one.

No NVIDIA GPU yet? Explore the UI with synthetic data:

uvx labwatch-lite --demo

Use

labwatch                     # start and open the dashboard
labwatch --port 8124         # a different port
labwatch --demo              # synthetic GPUs, no hardware needed
labwatch doctor              # can this machine run LabWatch?
labwatch start --background  # run it in the background
labwatch status              # is it running, and what are the GPUs doing
labwatch stop                # stop the background instance
labwatch open                # open the dashboard again

labwatch doctor is the answer to "why is it not working":

LabWatch Doctor

✓ Python — 3.12.7
✓ Dependencies — 7 runtime packages importable
✓ NVML — available (driver 580.173.02)
✓ GPUs — 8 detected
  8 × NVIDIA GeForce RTX 4090
✓ Port — 127.0.0.1:8123 available
✓ Database — /home/you/.local/share/labwatch
✓ Dashboard — bundled (640 KB)

✓ Ready — 8 GPUs available.

labwatch status is the one-liner:

LabWatch 1.1.0
  gpu-node-01  ·  http://127.0.0.1:8123

  4 busy / 8 GPUs  ·  4 free  driver 580.173.02

  GPU 0  NVIDIA GeForce RTX 4090    98.4%      33 GB / 48 GB   67°C   448 W  busy
  GPU 1  NVIDIA GeForce RTX 4090     0.0%       1 GB / 48 GB   31°C    16 W  free

  CPU 9%  ·  RAM 9%  ·  8 GPU processes

--json on status and doctor gives machine-readable output, which is what the VS Code extension consumes.

VS Code

A lightweight extension puts the GPU state where you are already looking.

• Status bar: GPU 4 busy / 8 or GPU 0 98% · 33/48GB, refreshed on an interval.
• LabWatch sidebar: one compact card per GPU — utilisation, VRAM, temperature.
• Open Full Dashboard: jumps to the web UI for history, processes and charts.

It works locally and over Remote-SSH: the extension runs in the remote workspace, sees the remote GPUs, and VS Code forwards the dashboard port to your browser automatically. LabWatch is never reimplemented inside the editor — the extension is a view onto the same collector.

See vscode-extension/README.md to build and install it from source (the Marketplace listing is not published yet).

What it shows

One card per GPU — eight RTX 4090s under live load	GPU processes — sortable, filterable, searchable
Host overview — CPU, RAM, every filesystem	History — 1H / 6H / 24H
Light theme — same information density

Configuration

Everything is an environment variable with the LABWATCH_ prefix; the full list is in .env.example. The common ones:

The quick start above uses the CLI's defaults (127.0.0.1:8123). labwatch sets these variables for the server it starts; running labwatch serve or the server module directly uses the defaults in the table.

Architecture

One process, one host, three data sources: NVML for GPU telemetry and compute process IDs, psutil for host metrics and process enrichment, SQLite for history. The dashboard polls /api/overview, so a refresh is a single round trip, and polling pauses while the tab is hidden.

The built dashboard ships inside the Python package, which is why uvx labwatch-lite needs no Node toolchain. v1 deliberately has no WebSockets, no queue, no cache layer and no authentication: at a two second refresh they would add operational surface without changing the experience.

labwatch/
├── labwatch/                 # the Python package
│   ├── cli/                  # labwatch doctor / status / start / stop
│   ├── server/               # FastAPI app, collectors, services
│   └── ui/                   # the built dashboard, shipped in the wheel
├── vscode-extension/         # status bar, sidebar, open-dashboard
├── docker-compose.yml        # server deployment option
└── docs/                     # report, acceptance checklist, screenshots

Advanced deployment

Docker is the right answer for a shared server, not for a laptop:

docker compose up -d

GPU access needs the NVIDIA Container Toolkit on the host. Without a GPU the container still monitors CPU, RAM and disk.

From source

git clone https://github.com/Galaxy-Chjs/LabWatch.git
cd labwatch
pip install -e ".[dev]"
labwatch --demo

The dashboard is committed under labwatch/ui, so a source checkout needs no npm either. Only rebuild it if you change the frontend:

cd frontend && npm install && npm run build   # writes into labwatch/ui

API

Interactive documentation is at /api/docs.

curl -s localhost:8123/api/overview | jq '.gpus.gpus[] | {index, utilization_percent, temperature_c}'

Testing

pip install -e ".[dev]"
pytest              # 179 backend tests
ruff check labwatch tests

cd frontend
npm run test        # 77 frontend tests
npm run e2e         # 8 Playwright tests, starts its own demo backend

cd ../vscode-extension
npm install && npm run compile && npm test   # 13 extension tests

CI additionally verifies that labwatch/ui matches the frontend sources, that the wheel contains and serves the dashboard, and that the Docker image comes up healthy.

Tech stack

Package hatchling · console-script entry point · standard-library-only CLI Backend Python 3.10+ · FastAPI · pydantic-settings · psutil · nvidia-ml-py · SQLAlchemy 2 · SQLite · pytest Frontend React 19 · TypeScript (strict) · Vite · Tailwind CSS v4 · Recharts · SWR · Vitest · Testing Library Editor VS Code extension (TypeScript) Deployment Docker (multi-stage) · Docker Compose · GitHub Actions

Limitations

• Single host. LabWatch monitors the machine it runs on.
• No authentication. Intended for trusted private networks; process command lines can be sensitive. Use a reverse proxy if you must expose it.
• NVIDIA only. AMD and Intel GPUs are not read.
• Graphics contexts on Windows are noisy; compute processes are the default.
• Load average is N/A on Windows, which does not expose it.
• uvx labwatch-lite needs a published release. Packaging and verification are in place and tested against the built wheel; the PyPI publication itself has not been done, so for now use uvx --from <path-or-wheel> labwatch.

Roadmap

• Publish to PyPI so uvx labwatch-lite resolves without --from
• VS Code extension on the Marketplace
• Prometheus /metrics export
• Threshold alerts (VRAM, temperature, disk) with webhook delivery
• Multi-host aggregation

Documentation

• docs/PROJECT_REPORT.html — consolidated report (English + 中文): features, architecture, test results, every bug found and fixed, release readiness.
• docs/ACCEPTANCE.md — acceptance checklist with measured results, including the 8-GPU server validation.
• docs/RELEASING.md — what a human has to do: GitHub, PyPI (so uvx labwatch-lite works) and the VS Code Marketplace.

License

MIT

LabWatch is intended for trusted private networks by default. It performs no authentication and may reveal process command lines.