oh-my-gpustack

A preflight doctor for GPUStack v2 — it finds the environment problems GPUStack itself only fails on much later.

English | 简体中文

---

GPUStack itself installs in one docker run. What is hard is everything underneath it: the driver that turns out to be two CUDA versions too old, the container toolkit that was installed but never registered with the daemon, the Postgres already sitting on 5432, the worker that silently never joins because the host is running Docker Desktop.

oh-my-gpustack is a doctor for that layer.

$ omg doctor --role worker

── operating system
  · Ubuntu 24.04  (amd64)
  ✔ architecture amd64 is supported
  ✔ Linux — supported for worker nodes

── container runtime
  ✔ docker daemon reachable (server 27.3.1)
  ✔ Docker Engine detected (Ubuntu 24.04 LTS)

── accelerator
  · NVIDIA GeForce RTX 4090  ×2
  ✘ NVIDIA driver 535.183.01 is too old
      GPUStack v2 needs a driver supporting CUDA 12.8+ (>= 570.26).
  ✘ nvidia container toolkit is not configured
      docker info does not mention 'nvidia'. Install the vendor container
      toolkit and restart the docker daemon.

Install

No installer, no dependencies beyond bash, awk and curl.

git clone https://github.com/zxcrf/oh-my-gpustack.git
cd oh-my-gpustack
./omg doctor

Optionally put it on your PATH:

ln -s "$PWD/omg" ~/.local/bin/omg

What it checks

Every check is derived from GPUStack's own installation requirements, not from folklore.

Area	What it catches
OS and role	macOS/Windows used as a worker node (unsupported); WSL2 caveats
Container runtime	Docker missing, daemon unreachable, Docker Desktop on a worker
Accelerator	Driver older than CUDA 12.8 / ROCm 7.0; container toolkit not registered with the daemon
Time sync	Missing or unsynchronised NTP, which GPUStack requires across nodes
Ports	All 21 documented server, worker and gateway ports
Disk	Free space on the docker data root, where model weights actually land
Network	Docker Hub vs. quay.io mirror; Hugging Face vs. ModelScope

doctor never modifies the host. install prints the command it would run and only executes it when you pass --yes.

Roles matter

GPUStack v2 draws a hard line between the two roles, and the same host can pass as one and fail as the other:

omg doctor --role server   # any OS with Docker, no GPU needed
omg doctor --role worker   # Linux only, real driver, real container toolkit

Getting this wrong is the single most common way to waste an afternoon: a Mac or a Docker Desktop host can run the GPUStack server perfectly well, but cannot be a worker at all.

Example configurations (experimental)

A secondary, honestly incomplete part of the repo. recipes/ holds deployment configurations in a small YAML format, and render prints them in the shape the GPUStack UI asks for, field by field, so you transcribe rather than translate.

$ omg recipe list
ID                                         BACKEND    STATUS      HARDWARE
ascend/qwen3-32b-910b                      MindIE     unverified  Ascend 910B
nvidia/qwen3-32b-dual-a100                 vLLM       unverified  NVIDIA A100 80GB
nvidia/qwen3-8b-single-rtx4090             vLLM       unverified  NVIDIA GeForce RTX 4090

$ omg recipe render nvidia/qwen3-8b-single-rtx4090

Read the unverified status literally. Every configuration here is reasoned from model size, card memory and the backends' documented behaviour. None has been run. They are a starting point that saves you some arithmetic, not a measurement, and they may simply be wrong.

The intent was a corpus of configurations someone had actually run and recorded. That requires hardware the maintainer does not have, so a recipe only flips to verified if a contributor runs it and reports real numbers — CI refuses to let the status be claimed without them. Whether that corpus ever materialises is an open question; see ROADMAP.md, which is candid about the odds.

If you have a GPU and 45 minutes, the verification issues say exactly what to run and what to paste back. Format details are in docs/recipe-format.md, submission in CONTRIBUTING.md.

Commands

omg doctor [--role server|worker|both]   Run every preflight check. Read-only.
omg install server [--port N] [--yes]    Print or run the server container.
omg install worker --server-url U --token T [--advertise-address IP] [--yes]
omg ports                                The full documented port inventory.
omg recipe list | show <id> | render <id>

Scope

This is a companion to GPUStack, not a fork or a wrapper around its API. It does not manage clusters, deploy models for you, or keep state. GPUStack's own UI and API do those things well; duplicating them would only add a second thing to keep in sync.

The preflight doctor is the part that works today and is worth your time. The configuration corpus is an experiment that may not reach critical mass — ROADMAP.md says why, and what would have to change.

Tracks GPUStack v2.2.x. Version-sensitive facts (ports, driver floors, supported platforms) are cited inline in the source so they can be rechecked when upstream moves.

License

MIT — see LICENSE.

Not affiliated with the GPUStack project. GPUStack is Apache-2.0 licensed.