Reserve CPU cores and require memory for CPU models

A profile's cpu_cores is reserved out of its node's CPUs by placement, as
memory is, and becomes the engine's thread count. Agents report their CPU
count in registration and heartbeats. New CPU models must declare memory;
model views show reserved against measured memory with warnings, and
ctl model resources sets both for a stored model.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

.gitea/workflows/release.yml

@@ -55,6 +55,13 @@ jobs:
             (cd dist && sha256sum "${name}" >> checksums.txt)
           done
 
+          # The reverse proxy configurations, so a release page carries
+          # everything install.md asks for and the repository is not needed.
+          for f in deploy/proxy/Caddyfile deploy/proxy/nginx.conf; do
+            cp "$f" dist/
+            (cd dist && sha256sum "$(basename "$f")" >> checksums.txt)
+          done
+
           # An NVML build for nodes with NVLink, which the portable binary
           # cannot serve.
           #

CHANGELOG.md

@@ -13,11 +13,876 @@ is only released once its **exit criterion** is met, not when its code lands.
 | v0.6.0 | 4 | Multi-node replicas and fabric awareness | released |
 | v0.7.0 | — | Conversations, agent memory, disk management | released |
 | v0.8.0 | — | PostgreSQL, leader election, agent failover | released |
+| v0.9.0 | — | Managing people and the tenancy tree | released |
+| v0.10.0 | — | InfiniBand fabrics and NVLink, doctor, node add, engines installed by the nodes | released |
 | v1.0.0 | 5 | Tenancy, prefix affinity, benchmarking | planned |
 
 Until v1.0.0 the minor version is the breaking one: configuration formats and Go
 APIs change between minors without a deprecation period.
 
+## Unreleased
+
+Changes since v0.10.4, published as release candidates (v0.10.5-rc.N) until
+there are enough for v0.10.5.
+
+### CPU cores are reserved, and memory has to be declared
+
+The first step of resource allocation for larger clusters: what a replica
+holds of a node is reserved, not assumed.
+
+- **Cores.** A profile's `cpu_cores` is reserved out of its node's CPUs, as
+  memory is, and is what its engine computes on (llama.cpp's `--threads`). A
+  node holds as many CPU replicas as it has cores for, and two on one node no
+  longer spin against each other. Agents report their CPU count; a node that
+  does not, and a profile that declares no cores, constrain nothing.
+- **Memory is required of new CPU models.** A model with no GPU is all host
+  memory, and one declaring none looked to placement as if it fitted
+  everywhere, any number of times. Adding one without `min_memory_gb` is now
+  refused. Models stored before this still load, and say what is missing.
+- **Declared against measured.** Each model shows what one replica reserves
+  and the most one of its replicas uses — in `ctl models` (RESERVES) and on the
+  cluster page — with a warning when nothing is declared or when it uses more
+  than a tenth over what it reserves.
+- **Setting them.** `llmgw ctl model resources MODEL --memory GB --cores N`
+  (and `POST /api/v1/models/{name}/resources`) for a model added at runtime.
+  `ctl model serve` and the mirror's serve form fill in cores — half the
+  smallest node the model fits on — beside the memory they already estimate.
+  Running replicas keep their old figures until restarted.
+
+### The mirror page in tabs
+
+/admin/mirror was one long page: what the mirror holds, the Hugging Face
+explorer and the fetch form, one under another, with every visit waiting on
+Hugging Face for a list it might not show. It is now three tabs — Held (with
+how many are held, downloading and failed), Explore Hugging Face, and Fetch by
+URL — each with its own address. Only the tab shown does its work, and only
+Held reloads while something downloads. A download started from the explorer
+links to Held, where its progress is; a fetch the mirror refused comes back on
+the form it was sent from.
+
+### A held model opens to where it runs, and how many
+
+Clicking a model under Held opens a card beneath it: each replica with its
+node, state, age and the CPU and memory its engine uses, and how many more
+replicas the cluster has room for now, on which nodes, and why not more. The
+replicas it always runs and the most it grows to under load are changed there.
+Room is found by trying the scheduler itself on a copy of the inventory — the
+same decisions the next passes would make, not an estimate beside them — and a
+number of always-running replicas it cannot place is refused with the reason,
+rather than accepted and left short. A ceiling above the room is taken, and
+said. The same answer is at `GET /api/v1/models/{name}/headroom` on the admin
+API.
+
+Each row also says how its model runs without being opened: replicas ready of
+those it should have, how many are still starting, and the nodes they are on —
+in amber when short, in red when parked or when it does not fit. It is one line
+per model beside its mode, and nodes drop the part of the name every node
+shares (node05 for llmgw-node05, the full name on hover).
+
+### One line per record, in every table
+
+The same rule across the admin pages. Headers do not wrap; a record is one
+line; free text is cut to its column with the whole of it on hover rather than
+given a row of its own; a row across the whole table is only a note or an open
+form. On the cluster page that means a node is one line (its address and logs
+beside its name, not under it), a model's description is a column rather than a
+second row, node names drop the prefix they all share, and the GPUs, classes,
+fabrics and fallbacks columns appear only when some row has something in them —
+on a CPU-only cluster they were three columns of dashes pushing the table past
+the page. On People, a person in many teams shows two and a count, the rest on
+hover.
+
+## v0.10.4 — 2026-09-30
+
+Published first as release candidates v0.10.4-rc.1 to rc.9.
+
+After upgrading, run `llmgw ctl restart --all` once: CPU replicas take the new
+thread count below only when they start.
+
+### CPU replicas no longer fight over the CPUs
+
+llama.cpp computes on every CPU of the machine unless told otherwise, and the
+agent did not tell it. Two busy CPU replicas on one node then spin against each
+other: on an 8-vCPU node, 7B generation fell from 10 tokens a second alone to
+0.8 each with both busy, in two rounds of the same test. The agent now starts a
+CPU replica on half the machine's CPUs, where one alone makes 6.5 and two busy
+make 5.5 each. `llamacpp.threads` in the agent's configuration sets it for a
+node — all of them suits a node that only ever runs one CPU replica — and a
+profile's own `--threads` still wins. Measured on VMs whose host is
+oversubscribed; the proportions, not the numbers, are the point.
+
+### Tracing
+
+With `tracing.endpoint` set (or `OTEL_EXPORTER_OTLP_ENDPOINT`), each inference
+request is traced over OTLP/HTTP: a span for the request, carrying its
+`X-Request-Id`, with admission, scheduling and each attempt at an engine under
+it. A caller's own `traceparent` is continued, and the engine is sent one for
+its attempt. `tracing.sample_ratio` traces a share of the requests that arrive
+without a decision. Off, it costs nothing.
+
+### Restarting replicas
+
+`llmgw ctl restart REPLICA... | --model M | --all` replaces replicas with new
+ones. Each replacement is started beside the replica it replaces, which keeps
+serving until the new one is ready; replicas of one model go one at a time.
+Where no second copy fits anywhere, the old replica is stopped after the drain
+grace period and the new one starts in its place. This is how running engines
+pick up the keys introduced in v0.10.3, an edited profile, or a new engine
+version.
+
+### A model that keeps failing is parked, and everybody is told
+
+A model whose replicas failed at every start was retried forever: kev-0.5b,
+whose architecture the nodes' llama.cpp did not know, was started 155 times in
+eight hours. After five failures in a row a model is now parked — not placed
+again until its definition changes or `llmgw ctl retry MODEL` is run — and
+`ctl status`, `ctl models` and the admin API say so with the last error.
+
+A request for a model that will not come up — parked, or fitting on no node —
+is answered at once with the reason, instead of "the model is loading; retry
+shortly", which a client would retry forever. Each request still makes the
+control plane try placing it afresh, so a model that fits once room is made is
+not refused on an old answer. "no placement for model" is logged when its
+reason changes or every ten minutes, not on every pass: it was 250 identical
+lines in two days for one model.
+
+### Metrics and alerts for what goes wrong
+
+New series: `llmgw_model_replicas_desired`, `llmgw_model_start_failures`,
+`llmgw_model_parked`, `llmgw_model_unplaceable`, `llmgw_node_engine_install`,
+`llmgw_control_plane_leader` and `llmgw_certificate_expiry_timestamp_seconds`.
+`llmgw_model_replicas_ready` is now published at 0 for every model that should
+be running; it was published only while a replica was ready, so
+ModelHasNothingServing could never fire. New alerts: ModelParked,
+ModelFailingToStart, ModelCannotBePlaced, EngineInstallFailed,
+ControlPlaneLeadership, CertificateExpiresSoon and CertificateExpiresVerySoon.
+
+`ctl status` counts a model against the replicas it should have now rather
+than its minimum, so an on-demand model that was asked for and fitted nowhere
+no longer reads as satisfied.
+
+### Backups
+
+`llmgw server backup` writes the store and `/etc/llmgw` — configuration,
+secrets, and the certificate authority's key — to one archive readable by root
+only, keeping the newest 14. `deploy/systemd/llmgw-backup.timer` runs it
+nightly. The control plane publishes the newest archive's time as
+`llmgw_backup_last_success_timestamp_seconds`, and BackupTooOld fires when it is
+more than 26 hours old or there has never been one. docs/install.md now says how
+to restore, including why running engines survive it: the engine-key secret
+comes back with the store.
+
+### Replicas follow load between min and max
+
+A model's `max` was a ceiling nothing reached: every model ran exactly its
+minimum however long its queue. Now, when requests are waiting at the engines —
+every slot of every replica busy — at one or more per replica for a minute, one
+replica is added, up to `max`; ten minutes with nothing waiting takes one of
+those away, down to `min`. One step at a time, and not while the previous one
+is still starting, so a spike that is over before a replica loads does not
+leave several behind. Each decision is logged with the load that made it.
+`llmgw ctl scale MODEL --min 1 --max 3` turns it on for a model.
+
+### A model from the registry in one command
+
+`llmgw ctl model serve OWNER/REPO` takes a model from the registry to a replica
+that answers. It picks the GGUF file (`--quant`, Q4_K_M by default), has the
+mirror fetch it and checks what arrived against the registry's published
+sha256, checks that the nodes' llama.cpp can load it, sizes its memory from its
+header, adds it to the catalog, waits for a replica — stopping early with the
+reason if it fits nowhere or keeps failing — and asks it to say hello. Each step
+is shown as it happens. It runs in the control plane as a job, so a download of
+hours does not depend on a terminal staying open. `--on-demand` adds it without
+starting a replica.
+
+### Upgrading from one command
+
+`sudo llmgw ctl upgrade VERSION`, run on the control plane, upgrades that
+machine and then every node in turn. Each agent is told the version over its
+existing stream, fetches the release for its own platform, checks it against
+the release's checksums, keeps the old binary beside the new and restarts,
+while its engines keep serving. A node that does not come back on the new
+version, ready, with its replicas, stops the upgrade before the next one.
+Running it again resumes. Agents from before this have to be moved by hand
+once.
+
+### Following a request
+
+Every response carries `X-Request-Id` — the client's own when it sends a plain
+one, otherwise one the gateway makes — and the engine receives it too. One
+access log line per request records it with the model asked for and served,
+the replica, status, time queued, time to the first token, total time,
+tokens, and the key, project and user. Usage records keep the id, replica,
+queue time and time to first token, and `llmgw ctl request ID` reads one back:
+the answer to "why was this slow?".
+
+### Rate-limit headers
+
+Responses carry OpenAI's `x-ratelimit-limit-*`, `x-ratelimit-remaining-*` and
+`x-ratelimit-reset-*` for requests and tokens, from whichever level of the
+tenancy tree will refuse first, so SDKs and editors can slow down before they
+are refused.
+
+### Memory sized from the model
+
+The mirror's serve form sizes a llama.cpp model's memory from its GGUF header:
+weights, plus the KV cache for the context pool from its layers, KV heads and
+head width, plus the engine's own. At a 16k pool that cache ranges from 0.44 GB
+to 5.25 GB across the models on the live mirror, which the old "weights plus
+half again plus two" could not see.
+
+### Security
+
+- **Alertmanager answered anyone on the network**, including requests to
+  silence alerts. The monitoring README now binds it to loopback, where
+  Prometheus beside it is its only client.
+- **Login and signup could be made to use gigabytes.** Each attempt hashes with
+  64 MiB of argon2, with no bound on how many ran at once, and the per-address
+  throttle grew by one entry per address tried. Hashes now run a few at a time
+  and the rest wait; the throttle expires old entries, and when it is still
+  full it refuses new addresses rather than dropping live ones — which would
+  have let a flood of made-up addresses reset the throttle on a real one.
+- **Any key holder could grow Prometheus without bound** by asking for made-up
+  model names, each of which became a metric label. Requests are counted under
+  the catalog's name for their model, or "unknown".
+- **A SQLite backup left a full copy of the store readable** by local users
+  while it ran. The snapshot is now made in a private directory, and
+  llmgw-backup.service sets `UMask=0077`.
+- **An engine archive could write outside its directory through chained
+  links.** Archives are unpacked through `os.Root`, and a link may only point
+  at a file beside it. Every llama.cpp b10991 archive, CPU and CUDA, already
+  follows that rule.
+- **Onboarding made every node trust the cluster's root for everything.** It
+  was added to the system store, so a certificate the control plane signed
+  would pass for any site with every TLS client on the node. The agent trusts
+  it through its own configuration only; onboarding no longer adds it, and
+  takes it out of a node that an older version onboarded.
+- **Any node could manage a mirror running mutual TLS**, since one root signs
+  every node's certificate. `llmgw mirror serve --api-client NAME` answers only
+  the certificate with that common name, and the mirror warns when mutual TLS
+  runs without one.
+- **The administrator's password stayed in `init.log`.** It is shown once, on
+  the screen, and the log keeps a placeholder.
+- **Auth off on a public address was silent.** The server now warns at start
+  when the API listens beyond loopback without keys.
+- **The actor recorded with a change was whatever the caller sent**, line
+  breaks included. It is cut to a short printable name, and `sudo llmgw ctl`
+  records the person who ran sudo rather than root.
+- **vLLM's Ray head ran its dashboard**, whose job API runs code for anyone who
+  reaches it. It is off. The head itself still has no authentication, and
+  SGLang still takes its key as a flag; docs/install.md says what to do about
+  both. The monitoring README says how to keep Prometheus's queries to the
+  control plane.
+
+### Fixes
+
+- Tests that slept a fixed time and then asserted now wait for their
+  condition. They are the likeliest cause of CI's intermittent failures on a
+  loaded runner.
+- `ctl` reported a change the API had queued (202 Accepted) as an error, as
+  `ctl restart` did on its first real use.
+- The status each failure is answered with — 499, 502, 503 with and without
+  Retry-After, 504, 429 — is now tested case by case.
+
+### Releases
+
+Small fixes are published as release candidates of the next version —
+v0.10.4-rc.1, rc.2 — which sort after v0.10.3 and before v0.10.4. Their release
+notes come from this section, and they are marked as pre-releases. Onboarding
+treats a release candidate as a release and downloads it.
+
+## v0.10.3 — 2026-09-30
+
+Security fixes from a review of v0.10.2. Three of them were confirmed on the
+live cluster before being fixed.
+
+### Engines demand a key only the router holds
+
+Engines listened on every address of their node with no key. A request from a
+neighbouring node reached the model directly, past the gateway's
+authentication, quotas and accounting. Each replica's engine is now started
+with a key derived from the replica id and a secret in the store. The router,
+its metrics scrape, the agent's readiness check and `ctl bench` send it.
+llama.cpp and vLLM receive it through their environment, not their command
+line. Engines started before this keep running without a key until their
+replica is next started.
+
+### The mirror's management API answers only who it was told to
+
+Without `--api-allow`, the management API answered anyone who could reach it,
+including every node. It now answers this machine only; the control plane is
+let in with `--api-allow` or mutual TLS. **Upgrading a mirror set up by hand:
+add `--api-allow <control plane address>` to its unit.** Downloads started
+through the API go to http and https only, and never to loopback, private or
+link-local addresses (`--allow-private-sources` to permit that). Model,
+version and file names can no longer be `..` or start with a dot.
+
+### The admin listener refuses what a browser page could send
+
+The admin API has no login and trusts whoever reaches it. A page open in an
+operator's browser, reaching it over an ssh tunnel, could post a model
+definition. The listener now requires Host to be an address or localhost,
+refuses cross-site requests, and takes changes only as `application/json`.
+A profile's `env` may no longer set variables that make an engine run other
+code (`LD_*`, `PATH`, `PYTHON*` start-up variables, `BASH_ENV` and similar).
+They are refused where a model is defined and dropped again before an engine
+starts.
+
+### Fixes
+
+- The agent installs only engine versions that look like one, whatever the
+  control plane sent; a version of `../x` could have installed outside
+  `/opt/llmgw/engines`.
+
+## v0.10.2 — 2026-09-29
+
+- After `server init`'s screen closes, only the administrator's password and
+  the next steps are printed, not the whole run again under the screen that
+  just showed it. The whole run is kept in `/var/lib/llmgw/init.log`, root's
+  only, and printed in full when init fails.
+- The screens' spinner and text field are llmgw's own rather than from
+  bubbles, one dependency fewer. Every llmgw command still asks the terminal
+  for its colours as it starts, which bubbletea v1 does on purpose; a terminal
+  that never answers waits for its timeout.
+
+## v0.10.1 — 2026-09-29
+
+### `llmgw ctl fabric-test`: two nodes, rail by rail
+
+`llmgw doctor` checks a node on its own, and every check can pass while two
+nodes still cannot reach each other: a cable into the wrong switch, a
+partition key, a RoCE network with no route. `llmgw ctl fabric-test A B` runs
+`ib_write_bw` from each of A's adapters on a fabric to the same adapter on B,
+one rail at a time, through the agents — no SSH between nodes, and perftest is
+installed the first time — and grades each against its link's rate: ok at 80%,
+slow at 50%, fail below or when nothing got through.
+
+Agents now say which requests they answer beyond the usual (`features`), so
+one too old for the test is refused at once instead of waited for.
+
+Written against perftest's real output and tested with it, but not yet run
+over real InfiniBand or RoCE: this cluster has neither.
+
+### The mirror on its own machine, in two commands
+
+`llmgw mirror init --control-plane <address>` sets a machine up as the model
+mirror: the user, `/srv/models`, and a service serving files to every node on
+:8081 and the management API on :8082. `server init --mirror
+http://<mirror>:8082` uses it instead of running one beside the control plane.
+It took a unit written by hand and an edit to `server.yaml` before.
+
+The management API can fetch and delete models; `mirror serve --api-allow`
+makes it answer only the addresses given and the machine itself, and `mirror
+init` gives it the control plane's. With `--no-node`, the starter model is
+fetched and catalogued anyway, unpinned, and starts on the first node added.
+
+Tried on three empty VMs: mirror, control plane and a node, and a request
+answered by the starter model on the node.
+
+### `server init` asks, and `node add` takes several nodes
+
+- **`sudo llmgw server init`** in a terminal, without `--admin`, asks for the
+  administrator's email, the other names nodes will reach the machine by
+  (showing the addresses it already found), SQLite or PostgreSQL, and whether
+  to run the mirror, a node and the starter model here. Then its steps fill
+  in as a list, downloads updating in place, and the administrator's password
+  stays in a box until the end — and is printed again after, with the whole
+  run, so it is in the terminal's history. The last screen says how to add a
+  node and to back up the authority's key. `--plain`, or no terminal, prints
+  lines as before.
+- **`llmgw node add a b c`** adds each in turn and ends with which were added.
+  A fabric named for one node's adapters is recognised on the next by what the
+  adapters report, and not asked again.
+
+Both tried on empty VMs: init from the form to a starter model answering, and
+two nodes added to it in one command in 40 seconds.
+
+## v0.10.0 — 2026-09-29
+
+Independent InfiniBand fabrics and NVLink domains, told apart, drawn and
+placed on; a node checked by `llmgw doctor` and added by `llmgw node add`; vLLM
+installed by the nodes themselves; people in many places at once; and a chat
+page, editor setup and a model explorer for the people using it.
+
+### Independent InfiniBand fabrics, told apart and drawn
+
+A fabric was whatever `agent.yaml` called it, and nothing checked. At a site
+with several independent fabrics, two given one name would have had a replica
+spread across both — started, then hung on its first collective. Now:
+
+- **Identity.** Each active InfiniBand port reports the master subnet manager
+  it sees (`sminfo`) and every subnet manager on its fabric (`saquery SMIR`),
+  asked once a minute through one port per fabric. Ports whose managers are
+  listed together are one physical fabric, so a failover does not split one in
+  two. A RoCE port's fabric is the IP network of its RoCE v2 address. The agent
+  installs `infiniband-diags` where there are adapters and no `sminfo`.
+- **Placement** divides a declared fabric by that identity and forms a replica
+  on one part only. A node whose adapters for one name are cabled to two
+  fabrics is refused; a node that cannot say is kept apart from those that can.
+- **Subnet managers.** The cluster page lists each fabric's master, its
+  priority, its standbys and its master changes over the last day, and warns
+  when a fabric has no standby, when its ports disagree on the master, when a
+  port is up with no subnet manager (INIT), and when one name covers two
+  fabrics or two names one fabric.
+- **Ports while running.** The agent re-reads every InfiniBand and RoCE port on
+  each heartbeat: state, physical state, rate, error and data counters. A port
+  going down takes its fabric off the node within seconds, and back when it
+  returns — it used to wait for the agent to restart.
+- **Maps.** Every five minutes one node on each fabric
+  runs `ibnetdiscover`, and the control plane parses it. `/admin/fabrics` draws
+  the fabric: switches in their tiers, adapters under their leaves, cables
+  coloured by rate, degraded ones — trained below the rest of their kind —
+  marked in red, rail alignment, and the cluster's own adapters live, with
+  their traffic running along the cables. It zooms, pans, highlights what a
+  switch or adapter touches, and opens detail on a click. Placement prefers
+  the nodes of one leaf and puts nodes with a degraded cable last.
+
+### NVLink, on every build and across nodes
+
+- **The release binary sees NVLink.** It is built without cgo, so without NVML,
+  which was the only source of NVLink peers: on every NVLink machine the
+  portable agent reported none. Discovery now reads `nvidia-smi topo -m`: NVLink
+  peers, each card's NUMA node, and how near each network adapter is.
+- **GPUs are chosen by it.** Every set of the right size is scored: NVLink pairs
+  within it, then — for a multi-node shard — nearness to the fabric's adapters,
+  then NUMA nodes spanned. It used to grow one card's peers, which took cards
+  joined to that one but not to each other.
+- **Multi-node NVLink domains** — an NVL72 rack, an NVLink Switch system — are
+  found from each GPU's fabric state, ClusterUUID and CliqueId, with
+  `nvidia-imex` and its channels. A replica spanning nodes is placed inside one
+  domain first, on nodes whose every card is joined and whose IMEX is up, and
+  its shards get `NCCL_MNNVL_ENABLE=1`; InfiniBand is the fallback.
+  `/admin/nvlink` draws each domain as a rack of trays and says what keeps a
+  tray out. A node's page shows its GPU-by-GPU NVLink matrix.
+
+### Multi-node launches fixed before they meet hardware
+
+- **vLLM launches multi-node its own way by default.** An empty
+  `engines.vllm.launch_mode` meant `ray`, never checked against a real cluster;
+  it now means `mp`, every node running `vllm serve` with `--nnodes`,
+  `--node-rank` and `--master-addr`, the workers `--headless`, as vLLM
+  documents. The `mp` path used to give workers no rank and the leader's
+  address as their own. Set `launch_mode: ray` to keep Ray.
+- **NCCL bootstraps over the node's own interface.** The agent's default of
+  `eth0` meant it never looked for the interface holding its management
+  address, and the control plane sent one name for every node. A node on
+  `ens3` or `bond0` had NCCL bind nothing.
+- **RoCE** shards get `NCCL_IB_GID_INDEX`, the RoCE v2 entry with an IPv4
+  address; NCCL's default is a v1 link-local one that does not route.
+- A Ray worker now waits for its head before joining.
+- The agent unit sets `LimitMEMLOCK=infinity`, which RDMA needs.
+
+### `llmgw doctor`
+
+Checks a node for what llmgw needs of its GPUs and fabric, and says what is
+wrong and how to fix it, most serious first: NVSwitch without the fabric
+manager, GPUs not joined to their NVLink domain, IMEX, `nvidia_peermem` and
+`ib_uverbs`, each port's link and subnet manager, a fabric with no standby,
+RoCE without a v2 GID, the agent's declared fabrics against the adapters, the
+interface NCCL will use, the unit's memlock limit, and the NCCL environment a
+shard on each fabric would be given. `--json` writes every fact it read, to
+send back; it exits non-zero when something fails.
+
+It also says when the CPU offers no AVX2 — a VM left on QEMU's default CPU
+model, where llama.cpp runs several times slower and nothing else looks wrong —
+and whether vLLM can be installed on the node, and why not.
+
+### vLLM installs itself on GPU nodes
+
+The agent installs vLLM as it does llama.cpp: on every node with an NVIDIA GPU
+that can run it, with nothing done by hand. A Python 3.12 environment is built
+by uv — itself a GitHub release checked against its checksum — from PyPI,
+resolved as PyPI stood a day after that vLLM was published and installed with
+`--require-hashes`, so every node gets the same files whenever it is built. The
+resolved list stays in the environment as `llmgw-requirements.txt`.
+
+- The default is vLLM 0.30.0, which takes every flag llmgw passes. Set
+  `engines.vllm` in `server.yaml` to change it, or to `""` to keep your own.
+- It is built for CUDA 13: it needs driver 580 and a Turing GPU or newer, and
+  25 GB free while it installs. A node that lacks one says which on the
+  cluster page; a node with no GPU skips vLLM without a word.
+- gcc is installed with it, since Triton compiles its kernel launcher on the
+  first model load.
+- SGLang installs the same way, on GPU nodes, when `engines.sglang` names a
+  version.
+
+Checked by installing vLLM 0.30.0 this way on a node of the test cluster: 7.7 GB,
+torch 2.13 for CUDA 13.0, importing cleanly. That node has no GPU, so vLLM
+itself was not started there.
+
+A node is asked only for engines its agent says it can install. An agent older
+than this release says nothing, and is asked for llama.cpp alone, so a cluster
+half way through its upgrade does not show every node as failing vLLM.
+
+### `llmgw node add`: a node in one command
+
+Adding a node was a bash script from the repository, not installed anywhere,
+that needed the node's name, the control plane's address and a dozen flags.
+It is now part of the binary:
+
+```
+sudo llmgw node add ubuntu@10.0.0.21
+```
+
+run on the control plane. The node id is the machine's hostname and the
+address its agent dials is this machine's on the route to it, checked against
+the server certificate. It installs llmgw on the node — the release for its
+architecture, fetched and checked there, which works on RHEL too — runs
+`llmgw doctor` there and stops on a problem, issues and installs the
+certificate, writes `agent.yaml` and the unit, starts the agent, and waits for
+the node to join and install llama.cpp.
+
+In a terminal it is a checklist that fills in, and asks what a script cannot:
+which fabric each group of active adapters is on — grouped by the subnet
+manager or RoCE network they report — and whether to go on past a problem.
+Elsewhere it prints one line per step. Running it again on a node is safe.
+
+`llmgw node remove` forgets a node that is gone for good, which otherwise
+stays listed as lost until the control plane restarts; only a lost node, or an
+unreachable one with nothing placed on it, is removed. `llmgw ctl nodes` no
+longer lists vLLM as skipped on every CPU node.
+
+Tried on an empty VM, from the terminal screen and plain: joined with
+llama.cpp ready in under a minute, and 17 seconds to add it again.
+
+### People belong to many places, or to none
+
+A person was in exactly one project, chosen at approval, and could not use the
+gateway before that. Now:
+
+- **Memberships.** A person can be a member of any number of organizations,
+  teams and projects, or of none. A member of a team or organization may use
+  every project in it. `llmgw users join/leave`, and the people page adds and
+  removes them from either side. Approving no longer requires a project.
+- **Personal keys.** A key can belong to a person with no project. On
+  `/profile` a person chooses what a new key spends against: one of their
+  projects, or Personal. `llmgw keys create --for <person>` does the same.
+  `auth.personal` sets default limits for personal use, or turns it off.
+- **Limits for people.** `--scope user` limits a person across every key,
+  project and the chat page. `--per-member` on an organization, team or
+  project gives each member their own share there. Both are on the quotas
+  page, and are enforced alongside the tree, each in its own pool.
+- **The chat page** asks what to spend against when a person has more than one
+  choice, and checks it on every message.
+- **Spend is recorded with who spent it**, so a person's budget survives a
+  restart, personal use and the chat page included.
+
+Leaving a project revokes the keys the person made there, unless another
+membership still reaches it. A personal key keeps no conversations or notes:
+those are kept per project.
+
+### An organization's own page
+
+A member of an organization can be made its **manager** (`users join --org …
+--role manager`, or the star on the people page). A manager gets `/org`: the
+organization's usage over time by team, project or person, its teams and
+projects with limits and spend, and its members — read-only, and only what was
+spent in its projects. Administrators can open every organization's page.
+
+### The chat page
+
+- A model that is not running shows a progress bar while it loads — waiting
+  for a node, downloading, starting — and the message is sent once it is up,
+  rather than failing after 45 seconds with "the model is loading".
+- A finished reply is rendered as markdown, by the server under the model
+  cards' rules, with its maths typeset by KaTeX: "$5 and $10" stays prose.
+- Stop, while a reply streams; its tokens, speed and time to first token under
+  it; a system prompt and a temperature; and the conversation kept in the
+  browser across a reload — the gateway still keeps none.
+
+### Connect an editor, and the Responses API
+
+- The account page makes a key for **Continue**, **Codex** or **Cline** and
+  shows what the tool needs, filled in: Continue's assistant file, Codex's
+  provider and profile, Cline's four settings. Continue and Codex get a one-line
+  command (`curl -fsSL <gateway>/setup/<tool>?model=… | sh`) whose script holds
+  no secret — the key comes from the environment — keeps a copy of whatever it
+  replaces, and leaves the rest of the file alone.
+- **`POST /v1/responses`** translates the Responses API, which Codex speaks, to
+  chat completions and back — instructions, messages, function and custom
+  tools with their calls and outputs, usage, streamed or not — down the same
+  path as any request.
+
+### Your own use
+
+The account page (was "Your keys") shows the last thirty days of a person's own
+use and, for each place they spend, a bar for every budget that applies — their
+own, or a project's shared with others, said as such.
+
+### The mirror page
+
+- **Explore models** opens on what is trending on Hugging Face, with views for
+  new and most downloaded, filters for task and size, and each repository's
+  parameters, architecture (✓ where the nodes' llama.cpp loads it), context,
+  base model and license. "Only what these nodes can run" is on by default.
+- A repository opens beneath its row with its model card, and a download
+  started there starts in place, its progress followed in the table above.
+- What the mirror holds is grouped by model family.
+- An importance matrix published beside a model's quantisations is no longer
+  offered as a model.
+
+**How a model runs.** Each model a mirrored file is serving now shows how it runs — always on, on
+demand, or stopped — and it can be changed there, without the CLI. The serve
+form asks the same: on demand loads the model when somebody asks for it and
+stops it after 15 minutes unused. A model declared in `server.yaml` shows its
+mode and says to change it there, because the file is read on every start.
+
+**Weights the nodes cannot load are not fetched.** `kev-0.5b` was a GGUF whose architecture, `ggmlc`, llama.cpp does not know. It
+was downloaded, catalogued and placed, and failed on every node it was tried on.
+The architecture was in the first kilobytes of the file all along. Now:
+
+- The mirror page's registry listing shows each file's architecture and, for
+  one the nodes' llama.cpp cannot load, says so instead of offering to fetch
+  it. A vision projector (`mmproj`) is marked as not a model on its own.
+- A fetch reads the file's header first — a range request, not a download —
+  and refuses one that cannot be served, unless "fetch anyway" is ticked.
+- Serving from the mirror and `llmgw ctl model add` refuse the same.
+
+The list of architectures is llama.cpp's own (`LLM_ARCH_NAMES`) at the build
+llmgw pins, b10991: 152 of them. A different build configured in `engines:` is
+not refused, only not checked.
+
+### Each node's CPU and memory, and a page per node
+
+The agent reads `/proc` between heartbeats: CPU across all cores, load, memory
+used and available, and each engine's cores and resident memory. The cluster
+page's node table shows CPU and RAM as bars; each node has a page with its
+current load, its engines, its fabric ports, its GPUs, and an hour of charts
+from Prometheus.
+
+### The admin pages
+
+- The cluster page leads with capacity, nodes, models and replicas, then usage;
+  it refreshes in place instead of reloading, and its usage table names people
+  and projects instead of ids.
+- The usage page's legend gives each line's total, not its last hour.
+- The people page keeps an account on one line and its rarer actions in a menu.
+- Every page fits a phone: a wide table scrolls in its own box.
+- Static files are named by their content, so a deploy's new styles and
+  scripts reach browsers at once instead of a day later.
+
+**One menu on every page.** Each page drew its own menu, and no two agreed: different links, in a different
+order, the page you were on sometimes listed and sometimes not. Every signed-in
+page now draws the same one — Cluster, People, Quotas, Usage, Mirror on the
+left for an administrator, Chat, Account and Sign out on the right for
+everyone — with the current page marked. The chat and key pages name the
+person's project by its path rather than its id.
+
+**The quotas page says what actually applies.** A branch that sets no limit of its own used to read "—" in every column while
+its organization held it to sixty requests a minute. Each limit now shows the
+value it is held to from above, muted and marked ↑, with where it comes from on
+hover; a larger value set below a stricter one says what caps it, for rate and
+token limits as well as budgets. Spend and budget share a column with a meter
+that turns red past 90%. The tree is indented like the people page, opening a
+form or saving one no longer reloads the page, and the explanations moved under
+"How limits combine". Projects are placed under their team by id rather than by
+the start of their path, which misplaced them when two organizations shared a
+name.
+
+### The project's website, in every gateway
+
+`/about` is llmgw's own page: what it does, InfiniBand and NVLink, installing,
+the reverse proxy configurations, and the release's files to download. It is
+served without a key like `/`, whose footer links to it, and says nothing about
+the installation. Its fonts are in the binary, so it makes no request elsewhere.
+The published website is rendered from the same template.
+
+### Metrics
+
+`llmgw_node_cpu_utilization_percent`, `llmgw_node_cpus`, `llmgw_node_load`,
+`llmgw_node_memory_used_bytes`, `llmgw_node_memory_available_bytes`,
+`llmgw_shard_cpu_cores`, `llmgw_shard_memory_bytes`, `llmgw_ib_port_active`,
+`llmgw_ib_port_rate_gbps`, `llmgw_ib_port_counter_total`,
+`llmgw_fabric_master_sm`, `llmgw_fabric_subnet_managers`,
+`llmgw_fabric_problems`, `llmgw_gpu_nvlink_joined`, `llmgw_imex_up`.
+
+### Fixes
+
+- PostgreSQL queries with an apostrophe in a comment failed: the placeholder
+  rewriting read it as the start of a string. Comments are now skipped.
+- Chart axes read "20.0BB" for sizes and 0% for a quiet CPU.
+- Usage by team, project or organization, and the spend on the quotas page,
+  left out every request made on the chat page: they were joined through the
+  key, and the chat page has none. They now count where a request was spent.
+- `/org` was answered with "no api key was provided" for a signed-in browser;
+  a test now drives every session page through the authentication middleware.
+
+### Upgrading
+
+Upgrade the control plane first, then the agents: an older agent is served as
+before and simply reports none of the new measurements. Existing agent units
+keep their old limits until `LimitMEMLOCK=infinity` is added to them. A node
+that set `mgmt_interface` keeps it; one that did not now uses the interface
+holding its management address rather than `eth0`. Multi-node vLLM replicas
+start with `mp` unless `launch_mode: ray` is set.
+
+The store migrates on its first start. Migration 0010 turns everyone's project into a membership and
+attributes past usage to people where a key had an owner. On SQLite it rebuilds
+the keys table; it was run against a copy of a production PostgreSQL store
+before release. `llmgw users move` is gone: use `join` and `leave`.
+
+vLLM is installed on every GPU node that can run it, once its agent is
+upgraded: about 8 GB each, from PyPI. Set `engines.vllm: ""` in `server.yaml`
+before upgrading to keep vLLM your own. `deploy/bootstrap/onboard-node.sh` is
+replaced by `llmgw node add`; it still works, for a machine holding the
+authority but not this llmgw.
+
+## v0.9.2 — 2026-09-28
+
+### A new control plane serves a model by itself
+
+`llmgw server init` now also runs a model mirror on the same machine, makes the
+machine a node of its own control plane, and fetches Qwen2.5 0.5B into the
+mirror and serves it there — on the machine's NVIDIA GPU when `nvidia-smi` finds
+one (the node installs the CUDA build of llama.cpp), on CPU otherwise, with a
+CPU profile as the fallback. An NVIDIA card on the PCI bus with no working
+driver is reported. `--no-mirror`, `--no-node` and `--no-model` leave these out,
+and every step is skipped on a rerun when it is already done.
+
+Not yet run end to end on a real machine.
+
+## v0.9.1 — 2026-09-28
+
+### The mirror page is one line per model
+
+What the mirror holds used to take two table rows per file — seven columns and
+the address under them — so a sharded model filled the screen. Now each version
+is one line: model and version, the file (or "4 files" for a set), total size,
+and which catalog models use it. The address moved into a "copy address" button;
+the checksum is in the file's tooltip. A version already in use is not offered
+for serving again, and removing one warns that the catalog uses it. The header
+counts versions rather than files.
+
+## v0.9.0 — 2026-09-28
+
+### Managing people and the tenancy tree
+
+Organizations, teams and projects can now be renamed, moved and removed, and an
+approved person can be moved to another project or removed — none of which
+could be done at all before, from the web or the CLI.
+
+- **`/admin/users`** shows the whole tree, each project opening onto its people
+  and keys, with approve, move, suspend, reinstate and remove for people,
+  revoke for keys, and add, rename, move and remove at every level. A search
+  over every account sits below it. Changes update the page in place (htmx,
+  embedded in the binary) and it still works with scripts off.
+- **`llmgw org`** — `tree [--people]`, `add`, `rename`, `move`, `remove`.
+- **`llmgw users move`** and **`llmgw users delete`**.
+- **`llmgw keys list --all`** lists every key with its project and owner.
+- Every command that takes a project, team or organization accepts an id, a
+  path such as `Acme/platform/gateway`, or a unique name, and `--project` may
+  be omitted when there is only one. Users are named by id or email.
+
+Moving a person takes the keys they made with them; keys an operator issued stay
+with the project. Only empty things are removed, and a project that ever had a
+key is never removed, because usage history refers to it.
+
+### Changes
+
+- **`--project` no longer defaults to `default`** in `keys create`, `keys list`,
+  `users approve`, `users create`, `keys threads` and `keys memory`: a tree
+  built from the web has no project of that name. With one project it is
+  chosen; with several the command lists them.
+- **`keys limits --budget` is in whole units**, as the quotas page takes it,
+  rather than micro-units. `--budget 50000000` now means fifty million units;
+  divide existing scripts' figures by 1 000 000.
+
+### Fixes
+
+- `keys init` could silently move an existing team or project to another
+  organization or team by redeclaring it. It now refuses.
+- An account rejected while pending and then reinstated became active with no
+  project, and failed at its first key. Reinstating one is refused; approving
+  gives it a project. Rejecting a signup now removes it.
+
+## v0.8.8 — 2026-09-28
+
+### Fixes
+
+- **`server init --postgres` failed on Rocky Linux** with "postgresql-setup:
+  executable file not found". The PostgreSQL project's own packages (PGDG)
+  provide `postgresql-server` too, so dnf can answer that name with
+  `postgresql16-server`, which names its unit `postgresql-16.service` and keeps
+  its tools in `/usr/pgsql-16/bin`. init now finds the server unit systemd has,
+  reads the data directory from it, and runs `initdb` itself when the directory
+  is empty. A PostgreSQL that was already installed is used as it is.
+
+### Known gaps
+
+Not yet run on a real machine. Three arrangements are not handled: a
+PostgreSQL initialised with `ident` for TCP logins (the connection check fails
+and says so), one listening on a port other than 5432, and several PGDG
+versions where the highest is not the one on 5432.
+
+## v0.8.7 — 2026-09-28
+
+### PostgreSQL in one command
+
+```
+sudo llmgw server init --postgres
+```
+
+Installs PostgreSQL with the machine's own package manager when there is none,
+creates the `llmgw` role and database with a generated password kept in
+`/etc/llmgw/secrets/store-dsn`, and checks that it connects. On a control plane
+already running on SQLite it stops the gateway, copies the store across so
+every account and key survives, points `auth.store` at PostgreSQL and starts
+the gateway again; if the move fails, the gateway is started again on SQLite.
+Given on the first run, there is never a SQLite store.
+
+`server.yaml` is edited in place with its comments intact, and the previous
+file is kept beside it. A PostgreSQL that init did not install is left sized as
+it was, since something else may depend on it.
+
+The PostgreSQL installation itself has not yet run on a real machine; the move,
+the configuration edit and the rerun behaviour are tested.
+
+### Fixes
+
+- **A new control plane with no models did not start.** A configuration with
+  no static endpoints and no models was refused as having nothing to serve, so
+  under systemd the unit restarted every two seconds and nothing listened on
+  8080. It now runs as a control plane with an empty catalog.
+
+## v0.8.6 — 2026-09-28
+
+### Reverse proxy configurations
+
+`deploy/proxy/` has a Caddyfile and an nginx configuration for the client
+port, and both are attached to every release beside the binaries. They do not
+buffer streamed replies, their read timeout outlasts a model's wait before its
+first token, their body limit matches the router's, and they set
+`X-Forwarded-Proto` and `X-Forwarded-Host` themselves — llmgw marks session
+cookies `Secure` from the first and shows the second as the base URL on its
+landing page.
+
+## v0.8.5 — 2026-09-28
+
+### A control plane in one command
+
+```
+sudo llmgw server init --admin you@example.com
+```
+
+Creates the llmgw user and its directories, the certificate authority, the
+control plane's certificate for the machine's hostname and every address it
+has, `server.yaml`, the default project, and an administrator whose password is
+generated and printed once — then installs the systemd unit, starts it and
+waits until it answers. What used to be two steps of install.md is now this.
+
+Each step is skipped when its result exists, so running it again finishes an
+install that stopped and changes nothing on one that did not. `--host` adds an
+address the machine cannot see of itself (a DNS alias, a NAT or floating
+address) and reissues the certificate keeping the old ones. It never overwrites
+`server.yaml` or an authority, and certificates issued by an authority kept on
+another machine are left as they are.
+
+### Fixes
+
+- **The configuration install.md showed could not start.** An empty catalog
+  without `control.enabled: true` is refused as having nothing to serve. The
+  documentation and the file `init` writes both set it.
+
 ## v0.8.4 — 2026-09-28
 
 ### Node logs on the admin page

README.md

@@ -1,7 +1,7 @@
 # llmgw
 
-A single-binary LLM gateway for clusters with multiple InfiniBand fabrics and
-heterogeneous GPUs.
+A single-binary LLM gateway for clusters with multiple InfiniBand fabrics,
+NVLink domains and heterogeneous GPUs.
 
 It serves LLMs running on your own GPU servers (vLLM / SGLang) behind one
 OpenAI-compatible endpoint. Design document: [llmgw-plan.md](llmgw-plan.md).
@@ -32,6 +32,7 @@ Releases track the roadmap phases; see [CHANGELOG.md](CHANGELOG.md).
 | v0.6.0 | 4 | Multi-node placement and fabric awareness | released |
 | v0.7.0 | — | Conversations, agent memory, disk management | released |
 | v0.8.0 | — | PostgreSQL, leader election, agent failover | released |
+| v0.9.0 | — | Managing people and the tenancy tree | released |
 | v1.0.0 | 5 | Tenancy, prefix affinity, benchmarking | planned |
 
 As of v0.6.0 a cluster runs unattended: agents report their hardware, the
@@ -48,15 +49,23 @@ a header would let any client promote itself into the top priority band.
 
 One thing is worth saying plainly:
 multi-node replicas are proven on a simulated cluster and on real hardware
-without a fabric. The InfiniBand, NVML and NCCL paths are written against the
-formats and failure modes those tools actually have, but they have not yet run
-on a machine that has them.
+without a fabric. The InfiniBand, NVLink and NCCL paths — telling fabrics apart
+by their subnet managers, mapping them, finding NVLink domains, launching across
+nodes — are written against the formats and failure modes those tools actually
+have and tested against them, but they have not yet run on a machine that has
+them. On such a machine, run `llmgw doctor --json` first and keep the report;
+[docs/fabrics.md](docs/fabrics.md) says what to look at after that.
 
 ## Documentation
 
-- [docs/install.md](docs/install.md) — installing from nothing: control plane,
-  nodes, engines, weights, first request
-- [docs/quickstart.md](docs/quickstart.md) — the short path
+- [docs/quick-install.md](docs/quick-install.md) — installing on servers, in
+  six steps: start here
+- [docs/install.md](docs/install.md) — the same from nothing, with every option
+  explained: control plane, nodes, engines, weights, first request
+- [docs/quickstart.md](docs/quickstart.md) — one workstation, from source
+- [docs/fabrics.md](docs/fabrics.md) — InfiniBand fabrics and NVLink: what
+  llmgw needs of them, checking a node with `llmgw doctor`, and what to look at
+  when a replica spanning nodes will not run
 - [docs/choosing-models.md](docs/choosing-models.md) — which models to run,
   how many of each, and where the weights should live
 - [docs/data.md](docs/data.md) — what llmgw stores, what it does not, and
@@ -66,6 +75,8 @@ on a machine that has them.
   does not exist or miss one that does
 - [deploy/mirror/](deploy/mirror/) — a model mirror, which is the cheapest
   and most useful thing to build around llmgw
+- [deploy/proxy/](deploy/proxy/) — Caddy and nginx in front of the client
+  port, with streaming and the forwarded headers right
 - [deploy/ha/](deploy/ha/) — running two control planes, and the one health
   check that has to be right
 - [docs/node-onboarding.md](docs/node-onboarding.md),
@@ -88,6 +99,7 @@ llmgw ctl replicas --model llama     # replicas and their shards
 llmgw ctl explain-placement llama    # why a model has not been placed
 llmgw ctl drain gpu-a-01             # move work off a node, one replica at a time
 llmgw ctl cordon gpu-a-01            # stop new placement, leave what runs
+sudo llmgw doctor                    # on a node: what its GPUs, NVLink and fabric need
 ```
 
 `ctl` talks to the admin port (`:9090` by default), not the client-facing one.

api/proto/llmgw/v1/agent.proto

@@ -24,6 +24,9 @@ message AgentMessage {
     Heartbeat heartbeat = 2;
     ShardStatus shard = 3;
     LogsReply logs = 4;
+    FabricScanReply fabric_scan = 5;
+    FabricTestReply fabric_test = 6;
+    UpgradeReply upgrade = 7;
   }
 }
 
@@ -37,6 +40,9 @@ message ControlMessage {
     RemoveWeights remove_weights = 5;
     Provision provision = 6;
     LogsRequest logs = 7;
+    FabricScanRequest fabric_scan = 8;
+    FabricTestRequest fabric_test = 9;
+    UpgradeAgent upgrade = 10;
   }
 }
 
@@ -114,6 +120,25 @@ message Register {
   // meant "an agent too old to say" and constrained nothing — so a freshly
   // built node with no engine installed yet was a candidate for every model.
   bool engines_probed = 14;
+  // cpu_count is the CPUs the agent may run on. Placement reserves cores
+  // for CPU replicas out of it, the way it reserves memory out of
+  // memory_total_mb; zero, from an older agent, reserves nothing.
+  int32 cpu_count = 18;
+  // imex is the service that lets a multi-node NVLink domain share memory.
+  IMEX imex = 15;
+
+  // installable_engines are the engines this agent knows how to install
+  // itself. The control plane asks it for no others. Empty is an agent older
+  // than the field, which could install llama.cpp and nothing else: asked for
+  // vLLM, it answered "unsupported", and every node of a cluster half way
+  // through an upgrade showed as failing.
+  repeated string installable_engines = 16;
+
+  // features are the requests this agent answers beyond the ones every agent
+  // does: "fabric-test". An agent that does not know a request ignores it, so
+  // without this the control plane would wait minutes for an answer that is
+  // never coming.
+  repeated string features = 17;
 }
 
 // Host describes the operating system and processor of a node.
@@ -207,6 +232,17 @@ message GPU {
   // Zero when the driver is too old to report it, which is not the same as
   // idle: the metric is simply absent rather than wrong.
   int32 utilization_percent = 15;
+  // nic_paths is how far each network adapter is from this card, by HCA
+  // name: PIX, PXB, PHB, NODE or SYS, from nvidia-smi topo.
+  map<string, string> nic_paths = 16;
+  // The card's multi-node NVLink membership, from nvidia-smi -q: state is
+  // Completed once the fabric manager has joined it; cluster_uuid and
+  // clique_id name the domain it joined.
+  string fabric_state = 17;
+  string fabric_status = 18;
+  string cluster_uuid = 19;
+  string clique_id = 20;
+  string fabric_bandwidth = 21;
 }
 
 message FabricAttachment {
@@ -231,6 +267,102 @@ message LocalWeights {
   bool shared = 3;
 }
 
+// NodeLoad is a node's use of its own CPU and memory, and each engine's share.
+//
+// Carried on the heartbeat rather than scraped from the node: the control
+// plane already exports the fleet from one place, and a node exporter per
+// machine would be a scrape target, a port and a firewall rule each.
+message NodeLoad {
+  // cpu_percent is the whole machine, 0 to 100 however many cores it has.
+  double cpu_percent = 1;
+  int32 cpu_count = 2;
+  // The kernel's run-queue averages over 1, 5 and 15 minutes.
+  double load1 = 3;
+  double load5 = 4;
+  double load15 = 5;
+  // memory_used_bytes is total less available: what the machine could not
+  // hand to a new process without evicting something.
+  int64 memory_used_bytes = 6;
+  int64 memory_available_bytes = 7;
+  repeated ShardLoad shards = 8;
+}
+
+// ShardLoad is one engine process group's use.
+message ShardLoad {
+  string shard_id = 1;
+  // cpu_cores is in cores, the way top counts a process: 2.5 is two and a
+  // half cores busy, which a percentage of the machine would hide on a large
+  // one.
+  double cpu_cores = 2;
+  int64 memory_rss_bytes = 3;
+}
+
+// IBPort is one InfiniBand or RoCE port's state and counters.
+message IBPort {
+  string hca = 1;
+  int32 port = 2;
+  // state is ACTIVE, INIT, DOWN...; phys_state tells a cable unplugged
+  // (Polling, Disabled) from a link up with no subnet manager (LinkUp and INIT).
+  string state = 3;
+  string phys_state = 4;
+  int32 rate_gbps = 5;
+  // link_layer is InfiniBand or Ethernet (RoCE).
+  string link_layer = 6;
+  // counters are cumulative, by sysfs name; data counters in bytes.
+  map<string, uint64> counters = 7;
+
+  // Identity: the adapter's node GUID and the port's own, as the fabric
+  // knows them.
+  string node_guid = 8;
+  string port_guid = 9;
+  // The subnet manager this port sees as master, on InfiniBand. Every port on
+  // one physical fabric sees the same one, which is what tells separate
+  // fabrics apart when their names are only what somebody typed.
+  string sm_guid = 10;
+  int32 sm_lid = 11;
+  int32 sm_priority = 12;
+  string sm_state = 13;
+  // sm_error says why sm_guid is empty on an active InfiniBand port:
+  // infiniband-diags missing, or no subnet manager answering.
+  string sm_error = 14;
+  // network is, on RoCE, the IP network of the RoCE v2 address: RoCE has no
+  // subnet manager, and the network is what its fabric is.
+  string network = 15;
+  string gid_prefix = 16;
+  // subnet_managers is every subnet manager the fabric's subnet
+  // administrator lists — master and standbys — asked through one port per
+  // fabric, so it is on that port only. It is what keeps a fabric one fabric
+  // through a failover: the master changes, the list does not.
+  repeated SubnetManager subnet_managers = 17;
+  string subnet_managers_error = 18;
+}
+
+// SubnetManager is one subnet manager on a fabric.
+message SubnetManager {
+  string guid = 1;
+  int32 lid = 2;
+  int32 priority = 3;
+  // state is master, standby, discovering or not active.
+  string state = 4;
+}
+
+// IMEX is the nvidia-imex service and its channels.
+message IMEX {
+  // state is systemd's word for it, empty where it is not installed.
+  string state = 1;
+  int32 channels = 2;
+}
+
+// GPUFabricState is one GPU's NVLink domain membership.
+message GPUFabricState {
+  int32 index = 1;
+  string state = 2;
+  string status = 3;
+  string cluster_uuid = 4;
+  string clique_id = 5;
+  string bandwidth = 6;
+}
+
 message Heartbeat {
   string node_id = 1;
   // gpu_memory_used_mb, indexed by GPU, catches a foreign process appearing on
@@ -271,6 +403,29 @@ message Heartbeat {
   // than "nothing to say", as for weights.
   bool provision_changed = 10;
   repeated ProvisionStatus provision = 11;
+
+  // load is how busy the machine is, sampled over the interval since the
+  // previous heartbeat. Absent on the first one, which has nothing to take a
+  // difference from, and from an agent on a system without /proc.
+  NodeLoad load = 12;
+
+  // ib_ports is every InfiniBand or RoCE port as it stands now, re-read on
+  // each heartbeat: a port that goes down after the agent started used to go
+  // unnoticed until the agent restarted.
+  repeated IBPort ib_ports = 13;
+  // fabrics is the fabrics this node can now carry traffic on, sent only when
+  // that changed since registration or the last heartbeat that said so — a
+  // port going down takes its fabric away, and one coming back returns it.
+  bool fabrics_changed = 14;
+  repeated FabricAttachment fabrics = 15;
+
+  // gpu_fabric is each GPU's NVLink domain membership as it stands now, sent
+  // once a minute: a fabric manager restarting drops every card out of its
+  // domain, and the node has to stop being offered work that spans it.
+  repeated GPUFabricState gpu_fabric = 16;
+  IMEX imex = 17;
+  // cpu_count as in Register, for a VM given more CPUs while it runs.
+  int32 cpu_count = 18;
 }
 
 // Provision is the software a node should have: which engines, at which
@@ -377,6 +532,13 @@ message StartShard {
   // profile_fp identifies the version of the profile, so the agent can say
   // which one a running shard was started from. The agent never interprets it.
   string profile_fp = 15;
+  // api_key is what the engine demands of every request, derived by the
+  // control plane from the replica id. The router sends it; nothing else
+  // that can reach the node's ports has it.
+  string api_key = 16;
+  // cpu_threads is how many CPU threads a shard with no GPU computes on:
+  // the cores placement reserved for it. Zero leaves it to the agent.
+  int32 cpu_threads = 17;
 }
 
 message EngineProfile {
@@ -446,3 +608,80 @@ message LogsReply {
   // error says why the lines are absent: an unknown source, say.
   string error = 4;
 }
+
+// FabricScanRequest asks a node to map the fabric one of its ports is on,
+// with ibnetdiscover: every switch, every adapter and every link between
+// them. One node per fabric is asked, every few minutes; a fabric looks the
+// same from all of its ports.
+message FabricScanRequest {
+  string request_id = 1;
+  string hca = 2;
+  int32 port = 3;
+}
+
+// FabricScanReply is ibnetdiscover's output as it printed it. Parsed by the
+// control plane, so a format the parser does not yet know is a control plane
+// upgrade rather than one on every node.
+message FabricScanReply {
+  string request_id = 1;
+  string output = 2;
+  string error = 3;
+  int64 took_ms = 4;
+}
+
+// FabricTestRequest asks a node for one side of an RDMA bandwidth test
+// between two nodes: ib_write_bw, from perftest, over one adapter. The
+// server side is asked first and answers when the test is over; the client
+// dials it. What it proves is what a replica spanning nodes needs and nothing
+// on one node can show: that these two adapters reach each other through the
+// fabric, and how fast.
+message FabricTestRequest {
+  string request_id = 1;
+  // role is "server" or "client".
+  string role = 2;
+  string hca = 3;
+  int32 port = 4;
+  // peer is the server's management address, for the client. perftest
+  // exchanges its connection details over TCP before any RDMA.
+  string peer = 5;
+  // tcp_port is that exchange's port, the same on both sides.
+  int32 tcp_port = 6;
+  int32 seconds = 7;
+}
+
+// FabricTestReply is what one side measured.
+message FabricTestReply {
+  string request_id = 1;
+  // gbps is the average bandwidth, in gigabits a second.
+  double gbps = 2;
+  // output is the end of the tool's output, for when the number is not
+  // enough.
+  string output = 3;
+  string error = 4;
+  int64 took_ms = 5;
+}
+
+// UpgradeAgent tells an agent to replace its own binary with a release and
+// restart.
+//
+// The agent fetches the release for its own platform and checks it against
+// the release's checksums before replacing anything, keeps the old binary
+// beside the new, then exits so systemd starts the new one. Engines keep
+// running throughout, as for any agent restart, and are adopted on the way
+// back. Over the stream the agent already holds, so upgrading a fleet needs
+// no ssh into it.
+message UpgradeAgent {
+  string request_id = 1;
+  // version must be a release: v0.10.4 or v0.10.4-rc.2.
+  string version = 2;
+  // releases is the base URL release files are downloaded from.
+  string releases = 3;
+}
+
+// UpgradeReply says whether the new binary is in place. Sent before the
+// agent exits; an empty error means it will be back on the new version.
+message UpgradeReply {
+  string request_id = 1;
+  string version = 2;
+  string error = 3;
+}

deploy/bootstrap/onboard-node.sh

@@ -35,8 +35,9 @@ usage: $0 --node ID --addr HOST --server URL [options]
   --mgmt-if NAME    interface NCCL bootstraps over (default: the one holding
                     that address)
   --llamacpp-bin P  use this llama-server instead of the one the agent installs
-  --vllm-bin P      path to the vllm entry point (not yet installed by the agent)
-  --sglang-python P python interpreter of the SGLang virtualenv
+  --vllm-bin P      use this vllm instead of the one the agent installs on a
+                    GPU node (also set engines.vllm: "" in server.yaml)
+  --sglang-python P python interpreter of an SGLang virtualenv you installed
   --nvidia-smi PATH where nvidia-smi lives, when it is not on PATH. Containerized
                     driver installs routinely put it somewhere else.
   --ib-root DIR     the sysfs InfiniBand directory (default /sys/class/infiniband)
@@ -121,9 +122,10 @@ TMP="$(mktemp -d)"
 trap 'rm -rf "$TMP"' EXIT
 "$BINARY" ctl cert issue-client "$NODE" --dir "$PKI" --out "$TMP" >/dev/null
 
-# 2 and 3. Identity, and trusting the root so future tooling on that machine
-#    does not treat our certificates as strangers.
-say "installing the certificate and trusting the root"
+# 2 and 3. Identity. The root is trusted by the agent's configuration only,
+#    never system-wide: it signs whatever the control plane asks, and every
+#    TLS client on the machine would take it for any site.
+say "installing the certificate"
 scp -q $SSHOPTS "$PKI/ca.pem" "$TMP/$NODE.pem" "$TMP/$NODE-key.pem" "$SSH_USER@$ADDR:/tmp/"
 $SSH "set -e
   sudo install -d -m 0755 /etc/llmgw
@@ -131,8 +133,10 @@ $SSH "set -e
   sudo install -m 0644 /tmp/$NODE.pem /etc/llmgw/agent.pem
   sudo install -m 0600 /tmp/$NODE-key.pem /etc/llmgw/agent-key.pem
   sudo chown root:root /etc/llmgw/*
-  sudo install -m 0644 /tmp/ca.pem /usr/local/share/ca-certificates/llmgw-ca.crt
-  sudo update-ca-certificates >/dev/null 2>&1 || true
+  if [ -f /usr/local/share/ca-certificates/llmgw-ca.crt ]; then
+    sudo rm -f /usr/local/share/ca-certificates/llmgw-ca.crt
+    sudo update-ca-certificates --fresh >/dev/null 2>&1 || true
+  fi
   rm -f /tmp/ca.pem /tmp/$NODE.pem /tmp/$NODE-key.pem"
 
 # 4. The binary, the configuration and the unit.
@@ -142,7 +146,7 @@ $SSH "set -e
 # that is not a release (a developer's, with commits past the tag) has no such
 # file, and is copied as before.
 TAG="$("$BINARY" --version 2>/dev/null | awk '{print $NF}')"
-if printf '%s' "$TAG" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
+if printf '%s' "$TAG" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+(-rc\.[0-9]+)?$'; then
   say "installing llmgw $TAG from the release"
   $SSH "set -e
     arch=\$(dpkg --print-architecture)
@@ -226,6 +230,10 @@ ExecStart=/usr/local/bin/llmgw agent --config /etc/llmgw/agent.yaml
 KillMode=process
 Restart=on-failure
 RestartSec=2s
+# RDMA pins the buffers it registers, and NCCL registers a great deal: with
+# systemd's default 8 MB lock limit, an engine that drops the capability that
+# lets root ignore it fails its first collective over InfiniBand.
+LimitMEMLOCK=infinity
 StateDirectory=llmgw-agent
 
 [Install]

deploy/examples/agent.yaml

@@ -47,26 +47,24 @@ heartbeat_interval: 5s
 reconnect_base: 1s
 reconnect_max: 30s
 
-# Fabric labelling is explicit and there is no way around it. OpenSM's default
-# subnet prefix is fe80:: on every fabric, so a matching prefix proves nothing
-# and a wrong guess produces a replica that starts, passes health checks and
-# then hangs on its first all-reduce (plan §5.2).
+# Each fabric this node's adapters are on, by name. The name is checked against
+# what the adapters report — the subnet managers every port on one fabric sees —
+# so two independent fabrics given one name are placed as two and the cluster
+# page says so; give each its own. The rate is measured, not read from here.
 #
 # A node with no fabrics is its own single-node island: it can host single-node
-# replicas and will never be given a multi-node one.
+# replicas and will never be given a multi-node one. docs/fabrics.md has more.
 fabrics:
   - name: ib-a
     hcas: [mlx5_0, mlx5_1, mlx5_2, mlx5_3]
-    rate_gbps: 200
 
 discovery:
   # Worth setting where the driver lives outside the default paths, which
   # containerized driver installs often do.
   nvidia_smi: ""
   ib_root: /sys/class/infiniband
-  # NVML is the only source of NVLink topology, which is what keeps a
-  # tensor-parallel group off the PCIe path inside a node. It needs a binary
-  # built with `-tags nvml`; otherwise this silently falls back to nvidia-smi.
+  # NVLink topology comes from `nvidia-smi topo -m` on every build; a binary
+  # built with `-tags nvml` reads it from NVML instead, when this is set.
   prefer_nvml: true
 
 # Where this node keeps model weights besides /var/lib/llmgw-weights, which is
@@ -96,10 +94,11 @@ discovery:
 engines:
   vllm:
     bin: /opt/venvs/vllm/bin/vllm
-    # Which multi-node mechanism works depends on the vLLM version, and the
-    # flags have changed more than once. Check the version you deploy.
-    launch_mode: ray      # "ray" or "mp"
-    ray_bin: /opt/venvs/vllm/bin/ray
+    # How a replica spanning nodes is launched. mp, the default, is what vLLM
+    # documents today and needs nothing but vLLM; ray is for a vLLM too old
+    # for mp's multi-node flags, and needs Ray on every node.
+    launch_mode: mp       # "mp" or "ray"
+    # ray_bin: /opt/venvs/vllm/bin/ray
   sglang:
     # SGLang is launched as a module, which is its documented entry point.
     python: /opt/venvs/sglang/bin/python

deploy/monitoring/README.md

@@ -46,6 +46,19 @@ apt-get install prometheus prometheus-alertmanager
 install -m 0644 prometheus.yml            /etc/prometheus/prometheus.yml
 install -m 0644 llmgw-rules.yml           /etc/prometheus/rules/llmgw.yml
 install -m 0644 alertmanager.yml          /etc/prometheus/alertmanager.yml
+# Alertmanager answers on loopback only. Its API takes silences from anyone who
+# can reach it, with no login, and silencing BackupTooOld or ModelParked is how
+# something that should be noticed is not. Prometheus beside it is its only
+# client; one Alertmanager needs no cluster port.
+echo 'ARGS="--web.listen-address=127.0.0.1:9093 --cluster.listen-address="' \
+    > /etc/default/prometheus-alertmanager
+# Prometheus itself is read-only as installed: its admin and lifecycle APIs
+# stay off (no --web.enable-admin-api, no --web.enable-lifecycle). It still
+# answers any query from anyone who reaches :9090, which says which models and
+# nodes there are and how busy each is. Its readers are the control plane
+# (monitoring.prometheus) and Grafana beside it; to keep it to those, allow
+# the control plane and drop the rest, e.g. with nftables:
+#   nft add rule inet filter input tcp dport 9090 ip saddr != { 127.0.0.1, CONTROL_PLANE_IP } drop
 promtool check config /etc/prometheus/prometheus.yml
 systemctl restart prometheus prometheus-alertmanager
 
@@ -75,7 +88,8 @@ Alertmanager groups and holds alerts and has no receiver.
 Where an alert should go — an address, a Slack workspace, a webhook — is a
 decision with credentials attached, and a monitoring system that quietly starts
 mailing people is worse than one that is visibly not wired up. Alerts are
-visible at `:9093` and in Prometheus; add a receiver to `alertmanager.yml` to
+visible in Prometheus, and at `:9093` on the monitoring host itself (`ssh -L
+9093:127.0.0.1:9093 <host>` to open its page); add a receiver to `alertmanager.yml` to
 make them travel. `critical` already routes separately so it can be pointed
 somewhere else without touching the rest.
 
@@ -86,7 +100,7 @@ An alerting system nobody has seen fire is an assumption.
 ```
 llmgw ctl cordon <node>     # work already there keeps running
 # ~2 minutes later
-curl -s http://<host>:9093/api/v2/alerts | jq '.[].labels'
+ssh <host> curl -s http://127.0.0.1:9093/api/v2/alerts | jq '.[].labels'
 llmgw ctl uncordon <node>   # the alert resolves on its own
 ```
 

deploy/monitoring/llmgw-rules.yml

@@ -42,10 +42,97 @@ groups:
         annotations:
           summary: "{{ $labels.model }} has no replica ready"
           description: >-
-            The model is placed and nothing is serving it. Ten minutes, because
-            a large model on CPU legitimately takes minutes to load. A model
-            that is deliberately stopped publishes no series at all, so this
-            cannot fire for one nobody asked for.
+            The model should be running and nothing is serving it. Ten minutes,
+            because a large model on CPU legitimately takes minutes to load. The
+            series is published at 0 for every model that should be running —
+            before v0.10.4 it was published only while a replica was ready, so
+            this could not fire at all. A model deliberately stopped, or an
+            on-demand one nobody is asking for, publishes nothing.
+
+      - alert: ModelParked
+        expr: llmgw_model_parked == 1
+        labels: { severity: critical }
+        annotations:
+          summary: "{{ $labels.model }} failed every time it started and is no longer retried"
+          description: >-
+            Five replicas in a row failed at start. Before this existed a model
+            whose weights its engine could not load was started 155 times over
+            eight hours. `llmgw ctl status` has the last error; once it is dealt
+            with, `llmgw ctl retry <model>`. Changing the model's definition
+            also retries it.
+
+      - alert: ModelFailingToStart
+        expr: llmgw_model_start_failures >= 2
+        for: 5m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.model }} has failed to start {{ $value }} times in a row"
+          description: >-
+            On its way to being parked. The engine's own words are in
+            `llmgw ctl logs <node> --source <shard>` for the next attempt, or in
+            the control plane's log for the last one.
+
+      - alert: ModelCannotBePlaced
+        expr: llmgw_model_unplaceable == 1
+        for: 10m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.model }} is wanted and fits on no node"
+          description: >-
+            Short of replicas, and the last attempt found nowhere with the
+            memory, cards or engine it needs. `llmgw ctl explain-placement
+            <model>` says what each node lacks. For an on-demand model, requests
+            for it are told this rather than asked to retry.
+
+      - alert: EngineInstallFailed
+        expr: llmgw_node_engine_install{state="failed"} == 1
+        for: 15m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.engine }} {{ $labels.version }} will not install on {{ $labels.node }}"
+          description: >-
+            The node takes no model needing it until it does. The agent retries
+            on its own; `llmgw ctl nodes` and the node's logs on the cluster
+            page say why it failed.
+
+      - alert: ControlPlaneLeadership
+        expr: sum(llmgw_control_plane_leader) != 1
+        for: 2m
+        labels: { severity: critical }
+        annotations:
+          summary: "{{ $value }} control planes believe they are placing work"
+          description: >-
+            None means nothing is placed or replaced; two means both are, each
+            into GPUs the other believes free. The lease is in the store: check
+            it is reachable from every control plane.
+
+      - alert: CertificateExpiresSoon
+        expr: (llmgw_certificate_expiry_timestamp_seconds - time()) < 30 * 86400
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.cert }} ({{ $labels.subject }}) expires in {{ $value | humanizeDuration }}"
+          description: >-
+            Certificates last a year and nothing renews them. When the agent
+            server's runs out every agent refuses to connect at once. Reissue
+            with `llmgw ctl cert` and restart the control plane.
+
+      - alert: CertificateExpiresVerySoon
+        expr: (llmgw_certificate_expiry_timestamp_seconds - time()) < 7 * 86400
+        labels: { severity: critical }
+        annotations:
+          summary: "{{ $labels.cert }} ({{ $labels.subject }}) expires in {{ $value | humanizeDuration }}"
+          description: See CertificateExpiresSoon; a week is not long.
+
+      - alert: BackupTooOld
+        expr: time() - llmgw_backup_last_success_timestamp_seconds > 26 * 3600
+        labels: { severity: warning }
+        annotations:
+          summary: "The newest llmgw backup is {{ $value | humanizeDuration }} old"
+          description: >-
+            llmgw-backup.timer runs nightly. Also fires when there has never
+            been a backup (the series is 0 then). `journalctl -u
+            llmgw-backup.service` on the control plane says why the last one
+            failed; docs/install.md, "Backing up", says how to set it up.
 
       - alert: PoolSaturated
         expr: llmgw_pool_saturation > 1

deploy/proxy/Caddyfile

@@ -0,0 +1,41 @@
+# llmgw behind Caddy: the client-facing port (8080) on a public name, with a
+# certificate Caddy obtains and renews by itself.
+#
+# Replace llm.example.com, point its DNS at this machine, open 80 and 443, and
+# run: caddy run --config /etc/caddy/Caddyfile
+#
+# Only 8080 goes through here. 7443 (agents) is mutual TLS with the cluster's
+# own authority and must reach llmgw directly; 9090 and 9091 stay private.
+
+llm.example.com {
+	# The router reads at most 32 MiB of body (router.max_body_bytes). Refusing
+	# more here gives the client a 413 before the upload, not after it.
+	request_body {
+		max_size 32MB
+	}
+
+	reverse_proxy 127.0.0.1:8080 {
+		# Tokens are written the moment they are generated. Without this a
+		# streamed reply can arrive in bursts, and a client measuring time to
+		# first token measures the proxy instead.
+		flush_interval -1
+
+		# Caddy sets X-Forwarded-Proto and X-Forwarded-Host itself and, with
+		# no trusted_proxies, discards whatever the client sent. llmgw relies
+		# on that: the proto decides whether session cookies are Secure, and
+		# the host is the base URL the landing page tells people to use.
+		# Behind a load balancer of your own, name it in trusted_proxies.
+
+		transport http {
+			# A long generation can be silent for a while before the first
+			# token. llmgw has its own limits (timeouts.*); this must not be
+			# the shorter one.
+			response_header_timeout 15m
+		}
+	}
+
+	# No `encode` on purpose: compressing a stream buffers it.
+
+	# Access log to stderr, which under systemd is the journal.
+	log
+}

deploy/proxy/README.md

@@ -0,0 +1,39 @@
+# A reverse proxy in front of llmgw
+
+The client-facing port (8080) is plain HTTP. On anything but a trusted network,
+put it behind a proxy that holds a publicly trusted certificate.
+
+| File | For |
+| --- | --- |
+| [Caddyfile](Caddyfile) | Caddy — obtains and renews its own certificate; the least work |
+| [nginx.conf](nginx.conf) | nginx, with a certificate from certbot |
+
+Both are also attached to every release.
+
+The `/about` page shows both, from copies in `internal/web/proxy`; a test fails
+when those differ from these, so change them here and copy them over.
+
+Four things both files get right, and any other proxy has to as well:
+
+- **Streaming is not buffered.** Replies are server-sent events; a buffering
+  proxy delivers them in one burst at the end.
+- **The read timeout is longer than a model's silence.** nginx's default of 60
+  seconds turns a slow first token into a 504.
+- **`X-Forwarded-Proto` and `X-Forwarded-Host` are set by the proxy**, replacing
+  whatever the client sent. llmgw uses the first to mark session cookies
+  `Secure` and the second for the base URL on its landing page.
+- **The body limit matches llmgw's** (32 MiB, `router.max_body_bytes`), so an
+  oversized request is refused before it is uploaded.
+
+Only port 8080 is proxied. Agents reach 7443 directly — it is mutual TLS with
+the cluster's own authority, and a proxy terminating it would take away the
+node identity it carries. 9090 (admin, pprof) stays on loopback; 9091
+(metrics) goes to your monitoring host only.
+
+With a proxy on the same machine, bind llmgw to loopback so nothing reaches it
+around the proxy:
+
+```yaml
+# /etc/llmgw/server.yaml
+listen: "127.0.0.1:8080"
+```

deploy/proxy/nginx.conf

@@ -0,0 +1,63 @@
+# llmgw behind nginx: the client-facing port (8080) on a public name.
+#
+# Put this in /etc/nginx/sites-available/llmgw (or conf.d/llmgw.conf), replace
+# llm.example.com, and get a certificate — certbot --nginx -d llm.example.com
+# fills in the ssl_ lines below. Then: nginx -t && systemctl reload nginx
+#
+# Only 8080 goes through here. 7443 (agents) is mutual TLS with the cluster's
+# own authority and must reach llmgw directly; 9090 and 9091 stay private.
+
+upstream llmgw {
+    server 127.0.0.1:8080;
+    keepalive 32;
+}
+
+server {
+    listen 80;
+    listen [::]:80;
+    server_name llm.example.com;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    # `listen ... http2` rather than `http2 on;`: the latter needs nginx
+    # 1.25.1, and Ubuntu 22.04 and Debian 12 ship older ones. Newer nginx
+    # accepts this form with a deprecation warning.
+    listen 443 ssl http2;
+    listen [::]:443 ssl http2;
+    server_name llm.example.com;
+
+    ssl_certificate     /etc/letsencrypt/live/llm.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/llm.example.com/privkey.pem;
+
+    # The router reads at most 32 MiB of body (router.max_body_bytes).
+    client_max_body_size 32m;
+
+    location / {
+        proxy_pass http://llmgw;
+        proxy_http_version 1.1;
+        proxy_set_header Connection "";
+
+        # Set, never appended: llmgw decides from X-Forwarded-Proto whether
+        # session cookies are Secure, and builds the base URL the landing page
+        # shows from X-Forwarded-Host. A value passed through from the client
+        # would be the client's choice.
+        proxy_set_header Host              $host;
+        proxy_set_header X-Forwarded-Host  $host;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+
+        # Streamed replies: tokens go out as they are generated. Buffering
+        # turns a stream into one late burst, and gzip buffers too.
+        proxy_buffering off;
+        proxy_cache off;
+        gzip off;
+
+        # nginx's default is 60 seconds between two reads from upstream. A
+        # large model can think longer than that before its first token, and
+        # the client then sees a 504 for a request that was about to succeed.
+        # llmgw has its own limits (timeouts.*); this must not be the shorter.
+        proxy_read_timeout 15m;
+        proxy_send_timeout 15m;
+    }
+}

deploy/systemd/llmgw-agent.service

@@ -11,6 +11,10 @@ ExecStart=/usr/local/bin/llmgw agent --config /etc/llmgw/agent.yaml
 KillMode=process
 Restart=on-failure
 RestartSec=2s
+# RDMA pins the buffers it registers, and NCCL registers a great deal: with
+# systemd's default 8 MB lock limit, an engine that drops the capability that
+# lets root ignore it fails its first collective over InfiniBand.
+LimitMEMLOCK=infinity
 StateDirectory=llmgw-agent
 
 [Install]

deploy/systemd/llmgw-backup.service

@@ -0,0 +1,14 @@
+[Unit]
+Description=llmgw backup: the store and /etc/llmgw, to /var/backups/llmgw-server
+After=llmgw-server.service postgresql.service
+
+[Service]
+Type=oneshot
+# Nothing it writes is for anyone else: the archive holds the CA's key and a
+# copy of the store.
+UMask=0077
+# Root, because the archive includes /etc/llmgw/secrets and the certificate
+# authority's key, which the llmgw user deliberately cannot read all of.
+ExecStart=/usr/local/bin/llmgw server backup --config /etc/llmgw/server.yaml --keep 14
+Nice=10
+IOSchedulingClass=idle

deploy/systemd/llmgw-backup.timer

@@ -0,0 +1,12 @@
+[Unit]
+Description=Back up llmgw every night
+
+[Timer]
+OnCalendar=*-*-* 03:15:00
+# A machine that was off at 03:15 backs up when it next starts, rather than
+# waiting another day with a gap nobody notices until the alert.
+Persistent=true
+RandomizedDelaySec=10m
+
+[Install]
+WantedBy=timers.target

docs/choosing-models.md

@@ -141,7 +141,7 @@ not count the same free terabyte once per node.
 Set budgets and limits on day one, not later:
 
 ```
-llmgw keys limits --scope project --id <project> --rpm 60 --budget 50000000
+llmgw keys limits --scope project --id <project> --rpm 60 --budget 50
 ```
 
 The reason is not technical. A resource that appears free and unlimited becomes,

docs/fabrics.md

@@ -0,0 +1,210 @@
+# InfiniBand fabrics and NVLink
+
+For a site whose GPU nodes are joined by InfiniBand or RoCE, by NVLink, or both
+— several independent fabrics, NVL72 racks, eight-GPU HGX boards. It says what
+llmgw does with them, what it needs from you before it can, how to check a node
+in one command, and where to look when a replica spanning nodes will not run.
+
+Read [install.md](install.md) first; this is the part of it that only matters
+once there is a fabric.
+
+> **Where this stands.** Every piece here was written against the real formats
+> of `sminfo`, `saquery`, `ibnetdiscover`, `nvidia-smi topo -m` and
+> `nvidia-smi -q`, and tested against them — but none of it has yet run on a
+> site with the hardware. Run `llmgw doctor --json` on two or three nodes first
+> and keep the reports: if a parser meets a format it does not know, that report
+> is what fixes it, and the fix is a control plane upgrade, not one per node.
+
+## What llmgw does with them
+
+**Two kinds of interconnect.** InfiniBand or RoCE joins nodes (scale-out).
+NVLink joins GPUs — inside one machine on an HGX board, or across the nodes of a
+rack on an NVL72 or an NVLink Switch system (scale-up). A replica spanning nodes
+is placed, in order of preference:
+
+1. inside one **multi-node NVLink domain**, if any has enough usable nodes:
+   tensor parallelism between its nodes then runs over NVLink;
+2. on one **physical InfiniBand or RoCE fabric**, preferring nodes under one
+   leaf switch and putting nodes with a degraded cable last.
+
+It is never split across two fabrics or two NVLink domains. Within a node, the
+GPUs a shard gets are the set with the most NVLink pairs, then the nearest to
+the fabric's adapters, then on one NUMA node.
+
+**A fabric has a name and an identity.** The name is what `agent.yaml` says; the
+identity is what the adapters report — on InfiniBand the subnet managers every
+port on one fabric sees, on RoCE the IP network of its RoCE v2 address. The name
+is how you address a fabric; the identity is how llmgw catches the name being
+wrong: two independent fabrics given one name are placed as two, and the
+cluster page says so.
+
+## Before a node joins
+
+On every GPU node:
+
+| What | Why | Check |
+|---|---|---|
+| NVIDIA driver | everything | `nvidia-smi` |
+| `nvidia-fabricmanager`, on an NVSwitch machine | without it CUDA does not start on those GPUs | `systemctl is-active nvidia-fabricmanager` |
+| `rdma-core`, `ib_uverbs` loaded | user-space RDMA at all | `ls /sys/class/infiniband`, `lsmod \| grep ib_uverbs` |
+| `nvidia_peermem` loaded | GPUDirect RDMA; without it NCCL copies every transfer through host memory | `lsmod \| grep nvidia_peermem` |
+| `infiniband-diags` | tells llmgw which fabric a port is on; the agent installs it if missing | `which sminfo` |
+
+On an NVL72 or NVLink Switch system, also:
+
+| What | Why | Check |
+|---|---|---|
+| `nvidia-imex` running, every node of the domain in `/etc/nvidia-imex/nodes_config.cfg` | GPUs in different nodes share memory through it | `systemctl is-active nvidia-imex` |
+| an IMEX channel (`options nvidia NVreg_CreateImexChannel0=1`) | an engine opens one | `ls /dev/nvidia-caps-imex-channels` |
+| every GPU joined to its domain | the fabric manager does this | `nvidia-smi -q \| grep -A6 Fabric` shows `State: Completed` |
+
+On each InfiniBand fabric:
+
+- **A subnet manager, and a standby.** Without one, ports come up to `INIT` and
+  stay there; without a standby, the fabric keeps its routes if the master
+  stops but cannot recover from any change after. llmgw watches this but does
+  not run one.
+- **Its own name** in `agent.yaml` on every node attached to it. Optionally, a
+  distinct `subnet_prefix` in each subnet manager's configuration, which makes
+  GIDs unique across fabrics; llmgw does not need it.
+
+## Declaring the fabrics
+
+In `/etc/llmgw/agent.yaml`, the adapters on each fabric, by name:
+
+```yaml
+fabrics:
+  - name: ib-compute
+    hcas: [mlx5_0, mlx5_1, mlx5_2, mlx5_3, mlx5_6, mlx5_7, mlx5_8, mlx5_9]
+  - name: ib-storage
+    hcas: [mlx5_4]
+```
+
+or `--fabric ib-compute:mlx5_0,mlx5_1,…` when onboarding ([node-onboarding.md](node-onboarding.md)).
+An adapter belongs to one fabric; a node may be on several. A replica on
+`ib-compute` is given only `ib-compute`'s adapters (`NCCL_IB_HCA`).
+
+The rate is measured, not taken from the file: a fabric's rate on a node is the
+slowest of its active adapters, because a collective runs at the speed of its
+slowest link.
+
+The agent checks the declaration against the adapters on every heartbeat. An
+adapter that is missing, or whose port is down, takes that fabric off the node
+within seconds — the node stops being offered multi-node work on it — and
+returns it when the port comes back.
+
+## Checking a node: `llmgw doctor`
+
+```
+sudo llmgw doctor                 # uses /etc/llmgw/agent.yaml when present
+sudo llmgw doctor --json > $(hostname)-doctor.json
+```
+
+It reads the node and says what is wrong and how to fix it, most serious first,
+and exits non-zero when anything fails:
+
+```
+FAIL  nvlink  this machine has NVSwitch but nvidia-fabricmanager is inactive: CUDA will not initialise on its GPUs
+              → systemctl enable --now nvidia-fabricmanager (its version must match the driver's)
+WARN  fabric  nvidia_peermem is not loaded: GPUDirect RDMA is off, and NCCL copies every transfer through host memory
+              → modprobe nvidia_peermem
+OK    gpu     8 GPUs: 8× NVIDIA H100 80GB HBM3
+OK    nvlink  NVLink groups: [0 1 2 3 4 5 6 7]
+OK    fabric  mlx5_0/1 ACTIVE at 400 Gb/s (InfiniBand), subnet manager 0x248a07030030f0c0 (LID 1, SMINFO_MASTER)
+OK    fabric  subnet managers of 0x248a07030030f0c0's fabric: 0x248a07030030f0c0 (master, priority 15), 0x248a07030030f1d4 (standby, priority 14)
+OK    agent   fabric ib-compute: mlx5_0,mlx5_1,… usable at 400 Gb/s
+OK    agent   NCCL bootstraps over ens3 (10.1.0.21)
+```
+
+followed by each GPU's NVLink peers and nearest adapter, each port's state,
+rate and errors, and the NCCL environment a shard on each fabric would be given.
+`--json` writes every fact it read as well as what it concluded — send that
+file when the report is not enough.
+
+## Checking two nodes: `llmgw ctl fabric-test`
+
+Every check on one node can pass while two nodes still cannot reach each other
+— a cable into the wrong switch, a partition key, a RoCE network with no route
+— and a replica spanning them then hangs on its first all-reduce. Before
+placing one, on the control plane:
+
+```
+llmgw ctl fabric-test gpu01 gpu02
+```
+
+```
+gpu01 → gpu02 on ib-compute, 41s
+
+RAIL              LINK      MEASURED    VERDICT  DETAIL
+mlx5_0 → mlx5_0   400 Gb/s  388.2 Gb/s  ok       97% of 400 Gb/s
+mlx5_1 → mlx5_1   400 Gb/s  241.0 Gb/s  slow     60% of 400 Gb/s: check the cable, and the card's PCIe width and NUMA node
+mlx5_2 → mlx5_2   400 Gb/s  0.0 Gb/s    fail     gpu01: ib_write_bw: Couldn't connect to 10.1.0.22:18517
+```
+
+It runs `ib_write_bw` (perftest, installed on a node the first time) from each
+of the first node's adapters on the fabric to the same adapter on the second —
+mlx5_0 to mlx5_0, the way NCCL pairs them — one rail at a time, through the
+agents, so no SSH between nodes is needed. Each rail is graded against its
+link's rate: **ok** at 80% or more, **slow** at 50%, **fail** below that or when
+nothing got through. `--fabric` picks one when the nodes share several,
+`--seconds` the length of each rail's run. The traffic is real: run it when the
+fabric is quiet.
+
+It measures RDMA between adapters, not GPUDirect or NCCL itself: a pass says
+the fabric carries traffic between these two nodes at its rate, which is what
+a first all-reduce needs and what nothing on one node can show.
+
+## Watching them
+
+- **Cluster page, Fabrics.** Each declared fabric and what it physically is;
+  a table of subnet managers per fabric — master, priority, standbys, the last
+  change of master — and every disagreement: one name on two fabrics, two names
+  on one, an adapter up but undeclared, ports up with no subnet manager, a
+  fabric with no standby, a recent failover.
+- **`/admin/fabrics`.** Each fabric's map, from `ibnetdiscover` run by one of
+  its nodes every five minutes: switches in their tiers, adapters under their
+  leaves, cables coloured by rate, degraded ones in red, rail alignment, and
+  the cluster's own adapters live with their traffic. Click anything for its
+  detail.
+- **`/admin/nvlink`.** Each multi-node NVLink domain as a rack of trays: which
+  GPUs are joined, which node's IMEX is down, which link runs degraded.
+- **A node's page.** Its ports with state, rate, errors and what they are
+  physically on; its GPU-by-GPU NVLink matrix; its load.
+- **Metrics**, for alerts:
+
+| Metric | Alert when |
+|---|---|
+| `llmgw_ib_port_active` | a declared port is 0 |
+| `llmgw_ib_port_counter_total{counter="symbol_error"}` and `link_downed` | rising |
+| `llmgw_ib_port_rate_gbps` | below its usual rate |
+| `llmgw_fabric_subnet_managers{state="standby"}` | absent or 0 |
+| `llmgw_fabric_master_sm` | its `sm_guid` changes (a failover) |
+| `llmgw_fabric_problems{level="fail"}` | above 0 |
+| `llmgw_gpu_nvlink_joined` | 0 |
+| `llmgw_imex_up` | 0 |
+
+## What an engine is given
+
+For a shard on an InfiniBand or RoCE fabric:
+
+| Variable | Value |
+|---|---|
+| `NCCL_IB_HCA` | that fabric's adapters on this node, and no others |
+| `NCCL_IB_DISABLE` | `0` (`1` for a single-node shard) |
+| `NCCL_SOCKET_IFNAME`, `GLOO_SOCKET_IFNAME` | the node's management interface: `mgmt_interface`, or the one holding its management address |
+| `NCCL_IB_GID_INDEX` | on RoCE only: the RoCE v2 entry with an IPv4 address |
+| `NCCL_MNNVL_ENABLE`, `NCCL_CUMEM_ENABLE` | `1`, for a replica inside a multi-node NVLink domain |
+
+A profile's `env` overrides any of them. vLLM launches a multi-node replica
+with its own multiprocessing (`engines.vllm.launch_mode: mp`, the default):
+every node runs `vllm serve` with its rank and the leader's address, the
+workers headless. `launch_mode: ray` is there for a vLLM too old for that.
+
+## When a replica spanning nodes will not run
+
+| It | Look at |
+|---|---|
+| is not placed | `llmgw ctl explain-placement <model>`: a fabric split by identity, a node whose IMEX is down, a node refused because its adapters are cabled to two fabrics |
+| starts and hangs on its first collective | `llmgw ctl fabric-test` between two of its nodes; the cluster page's fabric problems; `doctor` on each node — a port down, the wrong interface, RoCE without a v2 GID |
+| runs, slowly | `nvidia_peermem`; the map for a degraded cable; the node page's NVLink matrix for a group that crossed PCIe |
+| worked yesterday | the subnet manager table for a failover; `link_downed` on the node's ports |

docs/install.md

@@ -1,7 +1,8 @@
 # Installing llmgw from nothing
 
 Written for whoever is standing up the cluster: you have servers, you have root
-on them, and nothing is installed yet. By the end there is a control plane, a
+on them, and nothing is installed yet. For only the commands, read
+[quick-install.md](quick-install.md) first; this page explains them. By the end there is a control plane, a
 node in the fleet, and a model answering requests.
 
 It assumes Debian or Ubuntu and adjusts nothing for other distributions beyond
@@ -29,7 +30,7 @@ The reason is boring and unavoidable: drivers and engines are platform decisions
 with kernel modules and version matrices attached.
 
 Weights are the one item on that list llmgw does handle. It includes a mirror —
-step 4 — which holds the files on your own network and hands them to the nodes,
+step 3 — which holds the files on your own network and hands them to the nodes,
 so getting weights onto every machine is not a problem you solve before
 starting. What llmgw will not do is choose the models for you.
 
@@ -58,7 +59,8 @@ them, so nodes need no inbound access except your own SSH.
 | 8082 | the control plane administering the mirror | the control plane only — this port can delete models and start downloads |
 
 Decide now which address nodes will use to reach the control plane. It goes into
-a certificate and changing it later means reissuing one.
+a certificate: the machine's own addresses are found for you, and any other name
+— a DNS alias, a NAT or floating address — has to be given with `--host`.
 
 ## 1. The binary
 
@@ -83,141 +85,121 @@ git clone https://gitea.mynodes.xyz/ilker/llmgw && cd llmgw
 CGO_ENABLED=0 go build -o llmgw ./cmd/llmgw
 ```
 
-## 2. The certificate authority
+## 2. The control plane
 
-Agents authenticate to the control plane with mutual TLS, and a node's identity
-is taken from its certificate's common name. A public authority cannot supply
-these: Let's Encrypt and its peers stopped issuing certificates carrying the
-`clientAuth` usage, so nothing they hand out can authenticate an agent.
-
-Run this wherever you intend to keep the authority. It talks to nothing and
-works on files, so it does not have to be a cluster machine — and there is an
-argument that it should not be.
+On the machine that will be the control plane, as root:
 
 ```
-sudo llmgw ctl cert init-ca --dir /etc/llmgw/pki
+sudo llmgw server init --admin you@example.com
 ```
 
-That writes `ca.pem` and `ca-key.pem`. **Whoever holds `ca-key.pem` can mint any
-node's identity**, so it stays here; `ca.pem` is copied to every machine and is
-not a secret.
+That is the whole step. In order, it:
 
-Now the control plane's own certificate. Every address an agent might dial must
-appear in `--host`, bare IP addresses included — hostname verification reads
-subject alternative names and ignores the common name entirely, so a certificate
-naming the host only in its subject is rejected by every client:
+1. creates the `llmgw` system user, `/etc/llmgw` and `/var/lib/llmgw`
+2. creates the cluster's certificate authority in `/etc/llmgw/pki`
+3. issues the control plane's certificate for this machine's hostname and
+   every address it has, and copies `ca.pem` beside it
+4. writes `/etc/llmgw/server.yaml`: mutual TLS, authentication, default limits
+   and a price, and a control plane with an empty catalog
+5. creates the store, the `default` project, and your account, already approved
+   and promoted to administrator — the password is generated and **printed
+   once**
+6. installs the systemd unit, starts it, and waits until `/health` answers
+7. runs a model mirror beside it (`/srv/models`, bytes on `:8081`, its
+   management API on loopback) and points the control plane at it
+8. makes this machine a node of its own control plane — on its GPUs when
+   `nvidia-smi` finds any, on CPU otherwise — and waits for it to install its
+   engine
+9. fetches Qwen2.5 0.5B into the mirror and serves it on this node, so the
+   first thing anyone opens `/chat` to find is a model that answers
+
+`--no-mirror`, `--no-node` and `--no-model` leave the last three out. An NVIDIA
+card with no working driver is reported rather than silently ignored; install
+the driver and run init again to serve on it.
+
+Add `--postgres` to keep accounts and keys in PostgreSQL rather than SQLite:
+init installs it and sets it up, and on a machine already running on SQLite it
+moves everything across. See [PostgreSQL](#postgresql-when-sqlite-is-no-longer-the-right-shape).
+
+Every step looks before it acts. Running it again finishes an install that
+stopped halfway and changes nothing on one that did not; it never overwrites
+`server.yaml`, the authority, or an existing account's password.
+
+**The addresses in the certificate matter.** Agents check that the address
+they dial is named in it, and the certificate names only what this machine
+could see of itself. If nodes will reach it by another name — a DNS alias, a
+NAT address, a floating IP — give it:
 
 ```
-sudo llmgw ctl cert issue-server llmgw-ctl \
-  --host 10.0.0.140 --host llmgw-ctl.internal \
-  --dir /etc/llmgw/pki --out /etc/llmgw
+sudo llmgw server init --host llmgw-ctl.internal --host 203.0.113.10
 ```
 
+Run that at any time: the certificate is reissued with the new names added to
+the old ones, and the service restarted.
+
+**`ca-key.pem` signs every node's identity.** `init` leaves it in
+`/etc/llmgw/pki`, because onboarding a node needs it and the control plane is
+where most people run onboarding from. Back it up; there is no recovering it.
+If this machine is exposed, move the directory elsewhere once the nodes are in
+and pass `--pki` to onboarding.
+
 This covers the fleet-facing port only. The client-facing API is public and
-belongs behind an ordinary publicly trusted certificate, usually terminated by a
-reverse proxy in front of port 8080.
-
-## 3. The control plane
-
-### The user and directories
-
-```
-sudo useradd --system --home /var/lib/llmgw --shell /usr/sbin/nologin llmgw
-sudo install -d -o llmgw -g llmgw -m 0750 /var/lib/llmgw
-sudo install -d -m 0755 /etc/llmgw
-sudo chown root:llmgw /etc/llmgw/ca.pem /etc/llmgw/server.pem /etc/llmgw/server-key.pem
-sudo chmod 0640 /etc/llmgw/server-key.pem
-```
-
-### The configuration
-
-`/etc/llmgw/server.yaml`. This is the smallest file that is not a toy: mutual
-TLS on, authentication on, one model, and limits that apply to anyone nobody has
-given limits to.
-
-```yaml
-listen: ":8080"
-admin_listen: "127.0.0.1:9090"
-agent_listen: ":7443"
-
-agent_tls:
-  ca: /etc/llmgw/ca.pem
-  cert: /etc/llmgw/server.pem
-  key: /etc/llmgw/server-key.pem
-
-auth:
-  enabled: true
-  store: /var/lib/llmgw/llmgw.db
-  signup_open: true
-  # Applied to any key no scope gives a limit to. Without these, a project
-  # created without limits is metered by nothing at all, and the first sign of
-  # that is the bill or the outage.
-  default_rpm: 60
-  default_tpm: 200000
-  # What a request costs, which is what makes a budget mean anything. Without
-  # a price every request costs zero, so a budget is displayed, counted against
-  # nothing, and never binds — and nobody finds out until they expected it to
-  # stop something. Self-hosted models have no per-token price, so the unit is
-  # yours to choose: GPU-seconds, a notional rate, or 1000 everywhere, which
-  # turns a budget into a plain token quota.
-  default_price:
-    prompt_per_1k: 1000
-    completion_per_1k: 1000
-  # pricing:
-  #   qwen2.5-coder-7b-instruct: { prompt_per_1k: 500, completion_per_1k: 1500 }
-
-landing:
-  contact: "platform@example.com"
-
-# Start with none. Models are added while the cluster runs — see step 8 —
-# and anything listed here is declarative: it is in the catalog on every start
-# and cannot be removed without editing this file.
-models: []
-```
-
-`admin_listen` is on loopback on purpose. It serves pprof, which can dump the
-process heap, and API keys sit in that heap in plaintext. To see the dashboard
-from elsewhere, promote an account and use `/admin` on the client port — do not
-move this listener.
-
-The store file is created on first start; there is no separate migration step.
-
-### The service
-
-```
-sudo cp deploy/systemd/llmgw-server.service /etc/systemd/system/
-sudo systemctl daemon-reload
-sudo systemctl enable --now llmgw-server
-systemctl status llmgw-server
-```
-
-### Your account
-
-Accounts are created and approved from a shell on this machine, deliberately:
-having a shell here is what makes someone an administrator, and there are no
-roles to get subtly wrong.
-
-```
-sudo -u llmgw llmgw users create you@example.com --password 'change me now'
-# prints a user id, usr-xxxxxxxx
-sudo -u llmgw llmgw users promote usr-xxxxxxxx
-```
-
-`promote` is what grants `/admin`. Sign in at `http://<control-plane>:8080/login`,
-change the password, and issue yourself a key from the profile page.
+belongs behind an ordinary publicly trusted certificate, terminated by a
+reverse proxy in front of port 8080. [deploy/proxy/](../deploy/proxy/) has a
+Caddyfile and an nginx configuration that get streaming, timeouts and the
+forwarded headers right; both are attached to every release.
 
 ### Check it
 
 ```
-curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/health   # 200, with an empty body
-sudo -u llmgw llmgw ctl status
+curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/health   # 200
+llmgw ctl status
 ```
 
 `ctl status` will report no nodes and no models, which is correct — nothing has
-been added yet. It is worth running now so its output is familiar before you
-need it.
+been added yet. Sign in at `http://<control-plane>:8080/login` with the printed
+password, change it, and issue yourself a key from the profile page.
 
-## 4. The mirror
+### The configuration
+
+`/etc/llmgw/server.yaml` is yours from here on. Three things in it are worth
+knowing before you edit it:
+
+- `admin_listen` is on loopback on purpose. It serves pprof, which can dump the
+  process heap, and API keys sit in that heap in plaintext. To see the dashboard
+  from elsewhere use `/admin` on the client port — do not move this listener.
+- `default_rpm`, `default_tpm` and `default_price` are what make limits and
+  budgets mean anything. Without a price every request costs zero and a budget
+  never binds; without the defaults, a project created without limits is
+  metered by nothing at all.
+- `control.enabled: true` is what makes this a control plane while its catalog
+  is empty. Without it, a file with no models is refused as having nothing to
+  serve.
+
+Every key is in [reference.md](reference.md).
+
+### Keeping the authority off the control plane
+
+Create it on another machine, issue the control plane's certificate there, and
+bring only the results:
+
+```
+# on the authority's machine
+llmgw ctl cert init-ca --dir /etc/llmgw/pki
+llmgw ctl cert issue-server llmgw-ctl --host 10.0.0.140 --host llmgw-ctl.internal \
+  --dir /etc/llmgw/pki --out ./ctl
+
+# copy ca.pem, ctl/server.pem and ctl/server-key.pem into /etc/llmgw on the
+# control plane, then there:
+sudo llmgw server init --admin you@example.com
+```
+
+`init` finds certificates in `/etc/llmgw` and no authority beside them, and
+keeps them as they are. Adding an address later is then done where the
+authority is; `init --host` says so rather than minting a second authority no
+node trusts.
+
+## 3. The mirror
 
 Do this before the nodes, not after. Every node fetches its own copy of a
 model's weights, and where they fetch from decides whether bringing up a cluster
@@ -313,7 +295,7 @@ llmgw mirror fetch --model qwen2.5-14b-instruct --version 2026-03 \
 or from the admin page, or by copying files into the directory by hand — the
 mirror is a directory, and anything that puts files in it works.
 
-## 5. Preparing a node
+## 4. Preparing a node
 
 **Do this before onboarding.** A node missing its driver or engine registers
 healthy and fails on first placement, and the reason is three logs away.
@@ -337,32 +319,26 @@ hardware to it.
 
 ### NVLink, if your GPUs have it
 
-The published binary cannot see NVLink topology. NVML is the only source of it,
-its bindings need cgo, and the portable binary is built without cgo on purpose
-so it runs on a node whose libc is older than the builder's.
+The agent reads the topology from `nvidia-smi topo -m`: which cards NVLink
+joins, each card's NUMA node, and which network adapter is nearest each. A
+tensor-parallel group is then the set of cards with the most NVLink between
+them — on a PCIe box where bridges pair specific cards, a group straddling two
+bridges falls back to PCIe and runs several times slower, and nothing else
+would report it.
 
-Without that topology, a tensor-parallel group takes the lowest free GPU
-indices. On an SXM board with NVSwitch that is correct, because every card is
-equidistant. On a PCIe box where NVLink bridges pair specific cards, a group
-straddling two bridges falls back to PCIe and runs several times slower — and
-nothing reports it, because from the outside it is simply a replica that is
-slow.
-
-For those nodes, install the `-nvml` build published beside the portable one:
+On an NVSwitch machine, `nvidia-fabricmanager` has to be running, at the
+driver's version, or CUDA will not start on its GPUs. On an NVL72 rack or an
+NVLink Switch system, the GPUs of several nodes form one domain, and a replica
+can run tensor parallelism across its nodes — which needs `nvidia-imex` and an
+IMEX channel as well. [fabrics.md](fabrics.md) has the list, and `llmgw doctor`
+checks it:
 
 ```
-sudo install -m0755 llmgw-$VERSION-linux-amd64-nvml /usr/local/bin/llmgw
+sudo llmgw doctor
 ```
 
-It is dynamically linked, so it needs a libc no older than the builder's and the
-NVIDIA driver present. Check it took effect with:
-
-```
-llmgw ctl nodes --json | grep -c nvlink_peers    # 0 means the topology is unknown
-```
-
-`llmgw_gpu_nvlink_peers` in the metrics says the same thing across a fleet: a
-flat zero everywhere means the topology is unknown rather than absent.
+A `-nvml` build is still published beside the portable one; it reads NVLink
+from NVML directly, and needs a libc no older than the builder's.
 
 ### InfiniBand, if you have it
 
@@ -372,53 +348,65 @@ ibstat            # must list your HCAs with State: Active
 ls /sys/class/infiniband
 ```
 
-The agent checks what you declare against what the node has. An adapter that is
-not there, or that has no ACTIVE port — physically linked but with no subnet
-manager, which survives a reboot and looks like a software problem — takes that
-fabric out of service on this node, loudly, in the log. Without that check the
-replica starts, passes its health checks, and hangs on its first all-reduce.
+Each fabric needs a subnet manager, and should have a standby; `nvidia_peermem`
+should be loaded for GPUDirect RDMA. You name each fabric when you onboard the
+node, and llmgw checks the name against what the adapters report: every port on
+one fabric sees the same subnet managers, so two independent fabrics given one
+name are placed as two, and the cluster page says so. An adapter that is not
+there, or whose port goes down, takes that fabric off the node within seconds,
+and gives it back when the port returns.
 
-Fabric membership is configuration, not discovery, and there is no way around
-that: OpenSM's default subnet prefix is the same on every fabric, so a matching
-prefix proves nothing and a wrong guess produces a replica that starts, passes
-health checks, and then hangs on its first all-reduce. You name the fabric when
-you onboard the node, and two nodes are only in the same fabric if you said so.
+[fabrics.md](fabrics.md) covers declaring several fabrics, what the cluster and
+fabric pages show, and what to look at when a replica spanning nodes will not
+run. Run `llmgw doctor` on the node before it joins.
 
-### An engine
+### Engines
 
-Pick what you will actually serve. For a first cluster, llama.cpp is the least
-trouble and runs without a GPU.
+Nothing to do: the agent installs them once the node joins, under
+`/opt/llmgw/engines`, and checks each one runs before the node offers it.
 
-```
-# llama.cpp, from a release build
-sudo apt-get install -y libgomp1          # it will not start without this
-sudo mkdir -p /opt/llama.cpp
-# unpack a llama.cpp release into /opt/llama.cpp
-/opt/llama.cpp/llama-server --version
+| Engine | On | How |
+|---|---|---|
+| llama.cpp | every node | the release build for its processor, CUDA where there is a GPU, checked against GitHub's checksum |
+| vLLM | nodes with an NVIDIA GPU it can run on | a Python environment built by uv from PyPI, about 8 GB |
+| SGLang | only when you ask for it | the same way as vLLM |
+
+vLLM is resolved as PyPI stood a day after that vLLM was published, so every
+node gets the same dependencies whenever it is built, and installed with
+`--require-hashes` against the sha256 PyPI publishes. The resolved list stays in
+the environment as `llmgw-requirements.txt`. It needs:
+
+- **driver 580 or newer and a Turing GPU or newer** (compute capability 7.5):
+  vLLM is built for CUDA 13. A V100 cannot run it;
+- **about 25 GB free** under the engines directory while it installs;
+- **gcc**, which Triton builds its kernel launcher with. The agent installs it.
+
+A node with no GPU skips vLLM and says nothing about it. A node that has a GPU
+but cannot run it — an old driver, a V100, a small disk — says why on the
+cluster page. `llmgw doctor` checks the same before the node joins.
+
+The versions are the control plane's, in `server.yaml`:
+
+```yaml
+engines:
+  vllm: "0.30.0"      # the default; "" leaves vLLM to you
+  sglang: "0.5.20"    # SGLang only when named
 ```
 
-That `libgomp1` line is not padding. A `llama-server` binary missing it exists,
-is executable, and cannot start — and the node reports `ready` throughout.
+A changed version reaches every node when it next connects. To use an engine
+you installed yourself instead, set its version to `""` and name its path in
+the node's `agent.yaml` (`engines.vllm.bin`, `engines.sglang.python`).
 
-For vLLM, a virtualenv on the node:
+After changing a version, check it still takes the flags llmgw builds for it,
+which drift between releases:
 
 ```
-sudo apt-get install -y python3-venv
-sudo python3 -m venv /opt/venvs/vllm
-sudo /opt/venvs/vllm/bin/pip install vllm
-/opt/venvs/vllm/bin/vllm --version
-```
-
-Check the engine still takes the flags llmgw builds for it, which drift between
-releases:
-
-```
-llmgw ctl engine-check vllm --bin /opt/venvs/vllm/bin/vllm
+llmgw ctl engine-check vllm --bin /opt/llmgw/engines/vllm/0.30.0-cu13/bin/vllm
 ```
 
 ### Weights
 
-Nothing to do here if you built the mirror in step 4 — the agent fetches what a
+Nothing to do here if you built the mirror in step 3 — the agent fetches what a
 model's `source` names, and that source is your mirror. This section is for the
 arrangements where the files are already on the machine.
 
@@ -441,7 +429,7 @@ model's `source` at a file to download and the agent fetches it once, before the
 engine is launched:
 
 ```yaml
-# your mirror, which is what step 4 was for
+# your mirror, which is what step 3 was for
 source: http://models.internal:8081/qwen2.5-coder-3b-instruct/2026-03/q4_k_m.gguf
 # a whole version, for a model of several files — the trailing slash is the signal
 source: http://models.internal:8081/llama-3.1-70b-instruct/2026-03/
@@ -498,42 +486,46 @@ How much disk a node needs follows from the models rather than a rule of thumb.
 `llmgw ctl model plan <repo>` prints the sizes; as a starting point, a 70B at
 bf16 is 141 GB and the same model at q4 is 43 GB.
 
-## 6. Adding the node
+## 5. Adding the node
 
-Two halves, because they need different access: building the machine needs the
-hypervisor, and issuing its identity needs the certificate authority. Where one
-person holds both — the common case — one command does it:
+On the control plane, which holds the certificate authority:
 
 ```
-llmgw-add-node \
-  --name llmgw-node01 --ip 10.0.0.141/24 \
-  --server https://10.0.0.140:7443 \
-  --cores 16 --memory 131072 --disk 200 \
-  --fabric ib-a:mlx5_0,mlx5_1 \
-  --llamacpp-bin /opt/llama.cpp/llama-server
+sudo llmgw node add ubuntu@10.0.0.141 --fabric ib-a:mlx5_0,mlx5_1
 ```
 
-**The VM name, the hostname, the node id and the certificate's common name are
-all the same string.** They do not have to be, and every time they are not,
-somebody spends an afternoon working out which of the four a message refers to.
+It logs in to the machine over SSH as that user, who needs passwordless sudo
+there, and:
 
-For a machine that already exists — bare metal, or a VM you built yourself — skip
-provisioning and issue the identity only:
+1. installs llmgw: the release for the machine's architecture, downloaded by
+   the machine and checked against the release's checksums, or this machine's
+   copy when it cannot download;
+2. runs `llmgw doctor` there and stops on any problem, printing the fix. Run it
+   again once fixed, or add `--ignore-checks`;
+3. issues the node's certificate and installs it, with the cluster's root,
+   trusted system-wide;
+4. writes `agent.yaml` — only what the node cannot find for itself — and the
+   systemd unit, and starts the agent;
+5. waits for the node to join and to install llama.cpp (`--wait` also waits
+   for vLLM, `--no-wait` for neither).
 
-```
-llmgw-onboard-node \
-  --node llmgw-node01 --addr 10.0.0.141 \
-  --server https://10.0.0.140:7443 \
-  --fabric ib-a:mlx5_0,mlx5_1 \
-  --llamacpp-bin /opt/llama.cpp/llama-server
-```
+In a terminal it draws this as a checklist and asks what a script cannot: which
+fabric each group of the node's active adapters is on, when `--fabric` was not
+given, and whether to go on past a problem doctor found.
 
-Onboarding needs SSH from the CA host to the node. It waits for SSH rather than
-failing on it, and learns the host key of a machine it has not seen — a new
-machine spends its first minute regenerating host keys and restarting sshd.
+**The node id is the machine's hostname**, and the address its agent dials is
+this machine's on the route to it; `--node` and `--server` override them. The
+VM name, the hostname, the node id and the certificate's common name being the
+same string saves an afternoon each time they would differ.
 
-It also checks that a configured engine actually runs, and says so loudly when
-it does not. That check exists because the failure is otherwise invisible.
+**SSH runs as root under sudo**, with root's keys. To use yours, log in to the
+control plane with `ssh -A` and run `sudo --preserve-env=SSH_AUTH_SOCK llmgw node
+add …`. It waits for SSH rather than failing on it, and learns the host key of
+a machine it has not seen — a new machine spends its first minute regenerating
+host keys and restarting sshd.
+
+Running it again on a node is safe: a fresh certificate and configuration, and
+the engines it runs are adopted by the restarted agent.
 
 Within a few seconds:
 
@@ -555,7 +547,7 @@ Repeat for each node. Nodes in the same fabric must be given the same `--fabric`
 name; nodes with no InfiniBand take no `--fabric` at all and are each their own
 island, which is fine for single-node models.
 
-## 7. Setting the node's CPU model, if it is a VM
+## 6. Setting the node's CPU model, if it is a VM
 
 Proxmox defaults a VM to `kvm64`, which hides AVX, AVX2, FMA and even SSE4.2
 from the guest. Inference then falls back to scalar code and is not slightly
@@ -572,7 +564,7 @@ only change being `--cpu host`:
 probably did not, and nothing about it looks broken — every number is simply
 small. Check with `grep -qw avx2 /proc/cpuinfo` on the node.
 
-## 8. Adding a model
+## 7. Adding a model
 
 Write the definition. This is the same shape a model takes in `server.yaml`, so
 an entry moves between the two by being copied:
@@ -714,7 +706,7 @@ An engine that publishes no metrics endpoint is measured from the outside only.
 The run says so, and queue depth and KV occupancy are then not part of the
 answer.
 
-## 9. The first request
+## 8. The first request
 
 ```
 curl http://<control-plane>:8080/v1/chat/completions \
@@ -777,6 +769,20 @@ turn, which is the first per-request load this store has had; and SQLite takes
 one writer at a time, so those turns serialise. And a second control plane is
 impossible while the store is a file on one machine's disk.
 
+On the control plane, one command does all of it — installs PostgreSQL if the
+machine has none, creates its role and database with a generated password kept
+in `/etc/llmgw/secrets/store-dsn`, stops the gateway, copies the SQLite store
+into it so every account and key survives, points `server.yaml` at it, and
+starts the gateway again:
+
+```
+sudo llmgw server init --postgres
+```
+
+It can be given on the first run too, and then there is never a SQLite store.
+The rest of this section is what that command does, for a PostgreSQL somewhere
+else.
+
 The setting is the same one, and the address decides:
 
 ```yaml
@@ -903,88 +909,123 @@ refuses every request.
 
 ## Upgrading
 
-One binary on every machine, so an upgrade is a copy and a restart. The part
-worth care is the copy, not the order.
+On the control plane:
+
+```
+sudo llmgw ctl upgrade v0.10.4
+```
+
+It upgrades this machine first — fetching the release for its platform,
+checking it against the release's checksums, keeping the old binary as
+`/usr/local/bin/llmgw.bak-pre-<version>`, restarting `llmgw-server` and waiting
+for every node to reconnect — and then each node in turn. A node's agent is told
+the version over the stream it already holds, fetches and checks the release
+itself, swaps it in and restarts; no ssh into the nodes is needed. Release
+candidates (`v0.10.4-rc.2`) work the same way.
+
+A node counts as done when it is back on the new version, ready, with as many
+ready replicas as before. One that is not within `--timeout` (three minutes)
+stops the upgrade there, so a bad release reaches one node rather than all of
+them; `llmgw ctl logs <node>` says why, and the node keeps its previous binary
+beside the new one. Nodes already on the version are skipped, so running the
+command again resumes where it stopped. `--nodes a,b` limits it to some nodes,
+and `--skip-control-plane` leaves this machine alone.
 
 **Nothing stops serving.** Engines are started with `KillMode=process`, so they
 keep running when the agent restarts, and the agent reports them back on its
 next connection. The control plane holds no replica state across its own
-restart either — it rebuilds the fleet from what the agents report. A rolling
-upgrade of the whole cluster interrupts no request that is not in flight at the
-moment of the restart.
+restart either — it rebuilds the fleet from what the agents report.
 
 **A mixed fleet is fine while you roll.** The agent protocol only ever gains
 fields, and both sides treat an absent one as unknown rather than as a default.
-Order does not matter; finish the roll the same day anyway, because
-`ctl nodes` reports each agent's version and a fleet that disagrees with itself
-is one more thing to hold in your head.
-
-```
-VERSION=v0.9.0
-# copy to every machine first, install nowhere yet
-for h in 10.0.0.140 10.0.0.141 10.0.0.142 10.0.0.146; do
-  ssh $h 'cat > /tmp/llmgw-new; stat -c %s /tmp/llmgw-new' < llmgw-$VERSION-linux-amd64
-done
-```
-
-**Check every size before installing anything.** This is not defensive writing:
-on a host whose login shell prints anything, `scp` fails outright, and the
-obvious workaround — `ssh -n host 'cat > file'` — points stdin at `/dev/null`
-and writes a *zero-byte file* while reporting success. Installing that on a
-fleet takes the fleet down. Compare the number on each machine with the local
-one, then:
-
-```
-sudo install -m0755 /tmp/llmgw-new /usr/local/bin/llmgw
-sudo systemctl restart llmgw-agent     # or llmgw-server, or llmgw-mirror
-llmgw --version
-```
+Agents older than v0.10.4 cannot upgrade themselves: move those by hand once,
+installing the release binary and restarting `llmgw-agent`, and every upgrade
+after that is the command above. The mirror, which is not an agent, is
+upgraded the same way by hand.
 
 Then confirm what you have, rather than assuming:
 
 ```
-llmgw ctl nodes       # every agent back, LAST SEEN in seconds
+llmgw ctl nodes       # every agent on the new version, LAST SEEN in seconds
 llmgw ctl replicas    # same replicas, adopted rather than replaced
 ```
 
 A replica may come back marked **`ready (stale profile)`**. That means it is
 running a profile that has since been edited — the reconciler leaves a serving
 replica alone on purpose, because churning one costs more than the difference.
-Restart it when you want the new profile to take effect; the flag is there so
-the choice is yours rather than silent.
+`llmgw ctl restart <replica>` replaces it with one on the new profile, starting
+the new one before stopping the old.
 
 ## Backing up
 
-Three things, in descending order of how badly you want them.
+`llmgw server backup` writes one archive holding everything a control plane
+cannot be rebuilt without:
 
-**The certificate authority.** `ca-key.pem`, wherever you put it in step 2.
-Losing it does not stop the cluster, and it means every node identity has to be
-reissued the next time you touch one. Nothing in llmgw can reconstruct it.
+- **the store** — users, API keys, the tenancy tree, limits and budgets, usage
+  history, models added at runtime, measured capacity, and the secret every
+  engine key is derived from (`pg_dump` in its custom format for PostgreSQL, a
+  consistent `VACUUM INTO` snapshot for SQLite; both are safe against a running
+  gateway);
+- **`/etc/llmgw`** — the configuration, the store's address, and the
+  certificate authority's key (`pki/`). Nothing in llmgw can reconstruct that
+  key; losing it means reissuing every node's identity.
 
-**The store.** Users, API keys, organisations, teams, projects, every limit and
-budget, all usage history, models added at runtime, and measured capacity.
+Archives go to `/var/backups/llmgw-server`, readable by root only because of the CA
+key, and the newest 14 are kept. Run it nightly with the timer:
 
 ```
-# SQLite
-sqlite3 /var/lib/llmgw/llmgw.db ".backup '/backup/llmgw-$(date +%F).db'"
-
-# PostgreSQL
-pg_dump --format=custom llmgw > /backup/llmgw-$(date +%F).dump
+sudo install -m 0644 deploy/systemd/llmgw-backup.service deploy/systemd/llmgw-backup.timer /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now llmgw-backup.timer
+sudo systemctl start llmgw-backup.service     # one now, to see it work
+ls -l /var/backups/llmgw-server
 ```
 
-`.backup` and `pg_dump` are both safe against a running gateway. Copying the
-SQLite file with `cp` while it is being written is not.
+The control plane publishes when the newest archive was written as
+`llmgw_backup_last_success_timestamp_seconds`, and **BackupTooOld** fires when
+it is more than 26 hours old — including when there has never been one.
+
+**Copy the archives off the machine.** They sit on the disk they back up and do
+not survive losing it. Anything that copies files will do — rsync from the
+mirror, a NAS mount, an offsite bucket — as long as it keeps the archives
+readable by root only.
 
 **Keys are stored hashed and cannot be recovered from a backup or from
 anywhere else.** Restoring an old store restores which keys exist and who owns
 them, not their secrets. A key created after the backup is gone and has to be
-reissued — which is why the store is worth backing up on a schedule rather than
-before upgrades.
+reissued.
+
+### Restoring
+
+On a machine with llmgw installed (the same version or newer) and, for
+PostgreSQL, an empty database and role as `server init --postgres` would create
+them:
+
+```
+sudo systemctl stop llmgw-server
+mkdir /tmp/restore && sudo tar -xzf /var/backups/llmgw-server/llmgw-backup-<host>-<time>.tar.gz -C /tmp/restore
+cat /tmp/restore/MANIFEST                     # version and time it was taken
+
+# /etc/llmgw: configuration, secrets, certificates and the CA
+sudo cp -a /tmp/restore/etc/llmgw/. /etc/llmgw/
+
+# the store — PostgreSQL
+sudo -u postgres pg_restore --clean --if-exists --no-owner --role=llmgw -d llmgw /tmp/restore/store.pgdump
+# the store — SQLite
+sudo install -o llmgw -g llmgw -m 0600 /tmp/restore/store.sqlite /var/lib/llmgw/llmgw.db
+
+sudo systemctl start llmgw-server
+sudo rm -rf /tmp/restore
+```
+
+Running engines keep serving throughout: agents reconnect to the restored
+control plane and their replicas are adopted, and because the engine-key secret
+came back with the store, the router can still reach them.
 
 **The mirror's directory** is the one thing you can rebuild, by downloading it
-all again. Worth remembering that a pinned version may no longer be upstream to
-download: that is exactly what pinning it protected you from, and a backup is
-what makes the protection outlive the disk.
+all again. A pinned version may no longer be upstream to download: that is
+exactly what pinning it protected you from, and a copy of the directory is what
+makes the protection outlive the disk.
 
 ## Reclaiming disk
 
@@ -1028,7 +1069,7 @@ output, which is the actual diagnosis.
 node and the reason: wrong GPU class, not enough free cards, too little memory,
 no fabric, a label it does not carry.
 
-**Everything is slow.** On a VM, check AVX2 (step 7). On CPU, check the
+**Everything is slow.** On a VM, check AVX2 (step 6). On CPU, check the
 quantisation — the difference between `q8_0` and `q4_k_m` is roughly a factor of
 two. `llmgw ctl status` shows how full the cluster is.
 
@@ -1053,6 +1094,8 @@ requests. On a slow model, set `timeouts.generation` higher.
   and what belongs on which port
 - `deploy/monitoring/README.md` — Prometheus, Grafana and the alerts, with what
   each one assumes about this system
+- `docs/fabrics.md` — InfiniBand fabrics and NVLink: what llmgw needs of them,
+  checking a node, and what to look at when a replica spanning nodes will not run
 - `docs/node-onboarding.md` — adding nodes in more detail, and what onboarding
   deliberately does not do
 - `docs/onboarding.md` — giving people accounts and keys
@@ -1065,17 +1108,27 @@ requests. On a slow model, set `timeouts.generation` higher.
   those eight local, which is most of the problem; on a fabric where the nodes
   can see each other, seeding between them is the obvious next thing to build.
 - **A budget without a price never binds.** Set `default_price` or `pricing`
-  (step 3) or every request costs zero, and a budget is something the dashboard
+  (step 2) or every request costs zero, and a budget is something the dashboard
   displays rather than something that stops anything. The quotas page says so
   where it can, which is not the same as being told before you rely on it.
-- **Engines are yours to install.** Onboarding verifies one runs; it installs
-  nothing.
+- **vLLM needs CUDA 13.** The version the agent installs needs driver 580
+  and a Turing GPU or newer. On older hardware, set `engines.vllm` to `""` and
+  install a vLLM built for your CUDA yourself.
 - **Two control planes have not been run for long.** The leader election and
   agent failover work and there is a pattern in `deploy/ha/`, but every cluster
   this has been run on in anger has had one. A single control plane is the
   well-trodden path.
-- **Multi-node replicas have not been run on real InfiniBand.** The scheduling,
-  the fabric invariant and the rendezvous are exercised against simulated
-  hardware only. Single-node placement on real GPUs is the well-trodden path;
-  if you are the first to run a TP group across real cards, expect to find
-  something.
+- **Multi-node replicas have not been run on real InfiniBand or NVLink.** The
+  scheduling, the fabric identity, the maps and the launch are written against
+  the real tools' formats and tested against them, not yet run on hardware that
+  has them. Single-node placement on real GPUs is the well-trodden path; if you
+  are the first to run a TP group across real cards, run `llmgw doctor --json`
+  on each node first and keep the reports.
+- **Two engine setups are weaker than the rest.** An engine's key is passed
+  in its environment, where only root and its own user can read it, except
+  SGLang's, which takes it only as a flag: other users on the node can see it
+  in the process list. Mount `/proc` with `hidepid=2` on nodes where that
+  matters. vLLM's `launch_mode: ray` starts a Ray head without
+  authentication, so anyone who can reach its port can run code on the
+  node. The dashboard is off, but firewall the port to the other nodes in the
+  replica, or use the default `mp` launch mode, which needs no Ray at all.

docs/node-onboarding.md

@@ -4,24 +4,16 @@ Written for whoever runs the cluster.
 
 ## The short version
 
-Where one person holds both the hypervisor and the certificate authority —
-which is the common case — one command does the whole thing in about
-45 seconds:
+On the control plane:
 
 ```
-llmgw-add-node \
-  --name llmgw-node05 --ip 10.0.0.145/24 \
-  --server https://10.0.0.140:7443 \
-  --cores 8 --memory 32768 --disk 60 \
-  --llamacpp-bin /opt/llama.cpp/llama-server
+sudo llmgw node add ubuntu@10.0.0.145
 ```
 
-The VMID defaults to the last octet of the address, so `qm list` and
-`llmgw ctl nodes` stay in the same order. `--provision-only` and
-`--onboard-only` split it back into the two halves below when the two kinds
-of access belong to different people.
-
-The rest of this page is what that command does, and what it still does not.
+That is all a machine that already exists needs — bare metal, or a VM you
+built. [install.md](install.md#5-adding-the-node) says what it does. On
+Proxmox, the machine itself can be built first by the script below, on the
+hypervisor.
 
 ## The two halves
 
@@ -54,41 +46,31 @@ their working tree.
 
 ## 2. The identity
 
-On the host that holds the certificate authority — this is the part that cannot
-be delegated, because it issues the credential by which the control plane
-believes the node is who it says it is:
+On the control plane, which holds the certificate authority — this is the
+part that cannot be delegated, because it issues the credential by which the
+control plane believes the node is who it says it is:
 
 ```
-llmgw-onboard-node \
-  --node llmgw-node04 \
-  --addr 10.0.0.144 \
-  --server https://10.0.0.140:7443 \
-  --fabric ib-b
+sudo llmgw node add ilker@10.0.0.144 --fabric ib-b:mlx5_0,mlx5_1
 ```
 
-It issues a client certificate whose common name is the node id, installs it
-along with the CA root, trusts that root system-wide so other tooling on the
-machine stops treating llmgw's certificates as strangers, installs the binary
-and the unit, and starts the agent. The node appears in `llmgw ctl nodes` within
-a few seconds.
+It checks the machine with `llmgw doctor`, issues a client certificate whose
+common name is the node id (the hostname), installs it along with the CA root,
+trusts that root system-wide, installs the binary and the unit, starts the
+agent, and waits for the node to join.
 
-If it does not, the control plane's log says why. A certificate whose common
-name does not match the claimed node id is refused by design — that check is
-what makes a node's identity something it proves rather than something it picks.
+If it does not join, the agent's log on the node says why. A certificate whose
+common name does not match the claimed node id is refused by design — that
+check is what makes a node's identity something it proves rather than
+something it picks.
 
-**It needs ssh from the CA host to the node.** Provisioning copies that host's
-`authorized_keys` into the new machine, so a node built by the script above
-already satisfies it; an older machine may need the key added.
+**It needs SSH from the control plane to the node.** Provisioning copies the
+hypervisor's `authorized_keys` into the new machine; with `ssh -A` to the
+control plane and `sudo --preserve-env=SSH_AUTH_SOCK`, the same key that
+reaches the hypervisor reaches the node.
 
-It waits for ssh rather than failing on it, and learns the host key of a machine
-it has not seen (`accept-new`, which still refuses a *changed* key — the risk
-being guarded against is a substituted machine, not a new one). Both are needed
-to run the halves back to back: for the first minute of its life a new machine
-is still regenerating host keys and restarting sshd, so it refuses connections
-it accepted a moment earlier.
-
-It also checks that a configured engine actually runs, which is cheap here and
-expensive later — see below.
+`deploy/bootstrap/onboard-node.sh` is the script this replaced, for a machine
+holding an authority but not a current llmgw.
 
 ## The CPU model matters, and its default is wrong
 
@@ -116,32 +98,23 @@ The trade is live migration: a VM pinned to the host CPU cannot move to a
 machine with a different one. For a node whose job is arithmetic that is the
 right way round, and `--cpu` overrides it where it is not.
 
-## What onboarding does not do
+## Engines
 
-It gives a machine an identity and an agent. It does **not** install inference
-engines or model weights, and a node missing either looks healthy in
-`llmgw ctl nodes` right up until a replica is placed on it and the shard dies
-with "executable file not found".
+The script installs none, and does not need to: once the agent is connected,
+the control plane tells it which engines to have and it installs them itself
+— llama.cpp on every node, vLLM on every node with an NVIDIA GPU it can run
+on, SGLang where the control plane names a version. Each is checked to run
+before the node offers it, so a node never advertises an engine that cannot
+start. [install.md](install.md#engines) says what vLLM needs of the node.
 
-Onboarding does check that an engine you point it at can be executed, and says
-so loudly when it cannot. That check exists because the failure is invisible
-otherwise: `llama-server` on node05 was present, executable, and could not start
-for want of `libgomp1`, and the node reported `ready` in `llmgw ctl nodes` the
-whole time. Being told at onboarding beats finding out when a replica is placed
-and the reason is three logs away.
+`--llamacpp-bin`, `--vllm-bin` and `--sglang-python` are for an engine you
+installed yourself. For the agent to use yours rather than install its own,
+also set that engine's version to `""` under `engines` in `server.yaml`.
 
-So the node is not finished until:
-
-- the engines its catalog profiles name are installed (`vllm`, `sglang`,
-  `llama-server`), at the paths the agent configuration gives
-- the weights are on disk, at the `source` each model declares
-
-Both are deliberately outside this script. Engines are a platform decision with
-versions and drivers attached, and distributing weights is its own problem —
-hundreds of gigabytes that want a shared filesystem or a cache, not an scp from
-a laptop. llmgw will fetch weights for a model whose `source` is a URL, one
-copy per node, which covers the simple case; anything larger stays the
-operator's arrangement, and llmgw is content to find the files already there.
+Weights are the other thing a node needs. llmgw fetches them for a model whose
+`source` is a URL, one copy per node, which covers the simple case; anything
+larger — a shared filesystem, a cache — stays the operator's arrangement, and
+llmgw is content to find the files already there.
 
 The `sim` engine needs neither, which is what makes it useful for exercising
 everything else.
@@ -178,18 +151,24 @@ was cut short.
 
 ## Fabrics
 
-`--fabric` is how a node says which InfiniBand fabric it is attached to, and
-there is no way around stating it. OpenSM's default subnet prefix is `fe80::` on
-every fabric, so a matching prefix proves nothing and a wrong guess produces a
-replica that starts, passes health checks, and then hangs on its first
-all-reduce.
+`--fabric` is how a node says which InfiniBand fabric it is attached to. The
+name is checked against what the adapters report — every port on one fabric
+sees the same subnet managers — so two independent fabrics given one name are
+placed as two, and the cluster page says so; give each fabric its own name.
+The agent installs `infiniband-diags`, which that check needs, if it is missing.
+
+Before a node with a fabric joins, run `sudo llmgw doctor` on it: it checks the
+subnet manager, GPUDirect RDMA, the fabric manager and IMEX on NVLink machines,
+and the declared fabrics against the adapters. [fabrics.md](fabrics.md) has the
+rest.
 
 Omit it for a node with no fabric. Such a node is its own island: it can host
 single-node replicas and will never be given a multi-node one.
 
 Two adapters per fabric is the default; `--fabric ib-b:mlx5_2,mlx5_3` names them
 explicitly. An adapter must never appear under two fabrics — the agent refuses
-that configuration, because the consequence is the hang above.
+that configuration: a replica given adapters on two fabrics starts, passes its
+health checks, and hangs on its first all-reduce.
 
 ## Where the driver is
 

docs/onboarding.md

@@ -39,16 +39,40 @@ The landing page then links to it, and the rest is:
 
 ```
 llmgw users list --pending --store …
-ID                    EMAIL              NAME   STATE    PROJECT  SIGNED UP
-usr-k4mq…             ayse@example.com   Ayşe   pending  -        4m12s ago
+ID          EMAIL              STATE    ADMIN  MEMBER OF     SIGNED UP
+usr-k4mq…   ayse@example.com   pending  -      on their own  4m12s ago
 
-llmgw users approve usr-k4mq… --project default --by ilker --store …
+llmgw users approve ayse@example.com --by ilker --store …
+llmgw users approve ayse@example.com --project Acme/ml/training --store …   # or straight into a project
 ```
 
 That is the whole operator loop. From then on they sign in at `/login`, and
-`/profile` is where they create keys, see when each was last used, and revoke the
-ones they are done with. A key is shown once on the page that creates it and
-never again.
+their account page (`/profile`) is where they create keys, see when each was
+last used, revoke the ones they are done with, and see their own use over the
+last thirty days against every budget that applies to them. A key is shown once
+on the page that creates it and never again.
+
+### Connecting an editor
+
+The account page's **Connect your editor** makes a key for Continue, Codex or
+Cline and shows what the tool needs with that key, this gateway's address and a
+model already in it:
+
+- **Continue** — an assistant file of its own, `~/.continue/assistants/llmgw.yaml`,
+  so their `config.yaml` is not touched.
+- **Codex** — a provider and a profile in `~/.codex/config.toml`, run with
+  `codex --profile llmgw`; their default model stays as it was. Codex speaks the
+  Responses API, which the gateway translates at `/v1/responses`.
+- **Cline** — four settings to paste into its own screen, since it keeps them
+  in VS Code's secret storage where no file reaches.
+
+For Continue and Codex there is a one-line command,
+`curl -fsSL <gateway>/setup/<tool>?model=… | sh`. Its script is served without
+signing in and holds no secret — the key comes from the environment — and it
+keeps a copy of anything it replaces. Revoking the key disconnects the tool.
+
+How well an editor's agent mode works depends on the model: it needs one that
+calls tools well, which the coder models do and small general ones often do not.
 
 **This gateway sends no email.** There is no "your account was approved" message
 and no password reset, so tell people what to expect: they sign up, they tell
@@ -88,11 +112,90 @@ means anything.
 If you have no structure yet, one of each is fine:
 
 ```
-llmgw keys init --store … --org mynodes --team default --project default
+llmgw org add org mynodes
+llmgw org add team default --in mynodes
+llmgw org add project default --in mynodes/default
+llmgw org tree --people
 ```
 
-It is idempotent: running it again renames rather than duplicating, so it can
-live in whatever provisions the machine.
+Everything that takes an organization, team or project — here, in `users` and
+in `keys` — accepts its id, its path (`mynodes/default/default`) or its name
+when the name is unique, so an id never has to be copied off a page. When there
+is only one project, `--project` can be left out.
+
+The tree is not fixed once made:
+
+```
+llmgw org rename project Acme/platform/gateway api-gateway
+llmgw org move project Acme/platform/gateway --to Scania/ml
+llmgw org remove team Acme/old                 # only when nothing is in it
+llmgw users delete ayse@example.com --yes      # signs out, revokes their keys
+llmgw keys list --all                          # every key, where it spends, and whose
+```
+
+A project that ever had a key cannot be removed, because usage history refers
+to it — rename it instead.
+
+### Where people belong
+
+A person can be a member of any number of organizations, teams and projects, or
+of none:
+
+```
+llmgw users join ayse@example.com --team Acme/ml          # every project in ml
+llmgw users join ayse@example.com --project Scania/research/vision
+llmgw users leave ayse@example.com --project Acme/ml/training
+```
+
+A member of a team or organization may use every project in it. Leaving revokes
+the keys the person made in projects they can no longer reach; a project they
+still reach through another membership keeps them.
+
+Someone who is a member of nothing still uses the gateway, on their own:
+personal keys, and the chat page, within their personal limits. When they make
+a key on `/profile` they choose what it spends against — one of their projects,
+or "Personal". An operator can do the same:
+
+```
+llmgw keys create laptop --for ayse@example.com                      # personal
+llmgw keys create ci --for ayse@example.com --project Acme/ml/training
+```
+
+Personal use can be limited by default, or turned off so people use the gateway
+only through their projects:
+
+```yaml
+auth:
+  personal:
+    rpm: 20
+    tpm: 50000
+    budget: 10        # whole units
+    period: month
+    # disabled: true
+```
+
+A personal key has no project, so it keeps no conversations or agent notes;
+those are kept per project.
+
+### Organization managers
+
+A member of an organization can be made its manager:
+
+```
+llmgw users join boss@acme.com --org Acme --role manager
+```
+
+or with the star on their organization membership on `/admin/users`. A manager
+gets an **Organization** link and a page at `/org`: usage over time by team,
+project or person, the teams and projects with their limits and spend, and every
+member. Only what was spent in that organization's projects is on it; what its
+people do elsewhere is not. The page is read-only — a manager is not an
+administrator of the cluster, and limits and memberships stay with those who
+are.
+
+`llmgw keys init` still works for provisioning scripts and is idempotent, but it
+will no longer move a team or project that already exists under another parent;
+it says so and stops.
 
 Split it when you want separate limits or separate reporting, not before.
 
@@ -156,18 +259,34 @@ Allowlists compose by intersection: a key cannot add a model its team withheld.
 A model's canonical name and any of its aliases name the same thing, so either
 form works.
 
-Budgets are counted in micro-units, and what a unit means is yours to decide.
-Self-hosted models have no per-token price, so it can be GPU-seconds, a notional
-rate, or 1 000 000 everywhere — which turns a budget into a plain token quota.
+Budgets are given in whole units, as the quotas page shows them, and what a unit
+means is yours to decide. Self-hosted models have no per-token price, so it can
+be GPU-seconds, a notional rate, or one unit per thousand tokens everywhere —
+a price of 1 000 000 in `auth.pricing`, which is in micro-units — and a budget
+becomes a plain quota of thousands of tokens.
 Models are priced in the server's `auth.pricing` section; a model priced at zero
 is exempt from budget checks, which is what lets a key with nothing left still be
 served a cheap fallback.
 
 ```
-llmgw keys limits --store … --scope project --id default \
-  --budget 50000000 --period month        # 50 units a month
+llmgw keys limits --store … --scope project --id Acme/platform/gateway \
+  --budget 50 --period month              # 50 units a month
 ```
 
+Two more kinds of limit follow people rather than the tree:
+
+```
+# A person, everywhere: every key they hold, every project, the chat page
+llmgw keys limits --scope user --id ayse@example.com --budget 25
+
+# Each member of a project separately — a fair share, not one shared pool
+llmgw keys limits --scope project --id Acme/ml/training --per-member --rpm 20
+```
+
+A request is held to all of them at once: the key's own, its project's, team's
+and organization's, each per-member limit on those for its owner, and the
+owner's own. The strictest wins, and each is counted in its own pool.
+
 ## The landing page
 
 Someone who reaches the gateway without a key sees the landing page. Tell it who
@@ -286,9 +405,14 @@ page exists.
 
 ## Managing accounts from the browser
 
-`/admin/users` lists who is waiting and who is active. Approving (into a project)
-and suspending are there, because that is the work an operator does constantly
-and it should not need a terminal.
+`/admin/users` is the tree: organizations, teams and projects, each project
+opening onto its members and its keys. From there an admin approves people
+(into a project or on their own), adds them to and takes them out of
+organizations, teams and projects, suspends and removes them, revokes keys, and
+adds, renames, moves and removes organizations, teams and projects. `/admin/quotas`
+sets limits on the tree, per member of any part of it, and per person. A searchable list of every account is at the
+bottom. The page works as plain forms; with scripts on, a change updates it in
+place and the projects you had open stay open.
 
 Three things are deliberately not there:
 

docs/quick-install.md

@@ -0,0 +1,202 @@
+# Quick install
+
+From empty servers to a model answering requests, in six steps. This page
+has only the commands and what to check after each; [install.md](install.md)
+explains every choice.
+
+## What you need
+
+| | |
+|---|---|
+| **One control plane machine** | Linux, x86-64 or ARM64. Debian 12, Ubuntu 22.04+ or RHEL 10. No GPU needed; 2 GB RAM, 20 GB disk. |
+| **GPU nodes** (optional to start) | The same Linux, with the NVIDIA driver installed. vLLM needs driver 580 or newer and a Turing GPU or newer (not V100). |
+| **root** | on the control plane, and `sudo` without a password on every node. |
+| **SSH** | from the control plane to each node, as a user with passwordless `sudo` there. |
+| **Network** | nodes reach the control plane on 7443 and 8081; users reach it on 8080. The machines need internet access to download engines and models. |
+
+You do not install llama.cpp, vLLM, Python or CUDA. The nodes do that
+themselves once they join.
+
+## 1. Put llmgw on the control plane
+
+```
+VERSION=$(curl -fsSL https://gitea.mynodes.xyz/api/v1/repos/ilker/llmgw/releases/latest \
+  | grep -o '"tag_name":"[^"]*"' | cut -d'"' -f4)
+U=https://gitea.mynodes.xyz/ilker/llmgw/releases/download/$VERSION
+curl -fsSLO $U/llmgw-$VERSION-linux-amd64          # -linux-arm64 on ARM
+curl -fsSL $U/checksums.txt | sha256sum -c --ignore-missing
+sudo install -m0755 llmgw-$VERSION-linux-amd64 /usr/local/bin/llmgw
+llmgw --version
+```
+
+`sha256sum` must print `OK`. If it does not, the download is damaged; do not
+install it.
+
+## 2. Set up the control plane
+
+```
+sudo llmgw server init
+```
+
+It asks for your email and a few choices, then sets up everything on this
+machine, in a few minutes. In a script, give them as flags instead:
+`sudo llmgw server init --admin you@example.com`.
+
+- the service, its certificates and its configuration;
+- your administrator account. **The password is printed once. Copy it now.**
+- a model mirror, which downloads model files once for the whole cluster;
+- this machine as a first node, and a small model (Qwen2.5 0.5B) on it.
+
+If nodes will reach this machine by a name or address it does not know itself
+(a DNS name, a NAT address), add `--host` for each:
+
+```
+sudo llmgw server init --admin you@example.com --host llm.example.com
+```
+
+It is safe to run again. It keeps what exists and finishes what is missing.
+
+**The mirror on its own machine**, when it wants a larger disk than the
+control plane has: first on that machine, with llmgw installed as in step 1,
+
+```
+sudo llmgw mirror init --control-plane <control plane address>
+```
+
+then on the control plane `sudo llmgw server init --mirror http://<mirror
+address>:8082`. The mirror serves model files to every node, and takes
+orders only from the control plane. Untick "This machine as a node" in the
+form (or add `--no-node`) to keep models off the control plane; the starter
+model then starts on the first node you add.
+
+**Check:** open `http://<control-plane>:8080/chat`, sign in with the printed
+password, and ask something. The small model answers. Change the password on
+the account page.
+
+## 3. Add the GPU nodes
+
+On the control plane:
+
+```
+sudo llmgw node add ubuntu@10.0.0.21
+```
+
+Several at once: `sudo llmgw node add ubuntu@10.0.0.21 ubuntu@10.0.0.22 ubuntu@10.0.0.23`.
+
+Replace `ubuntu` with the user you log in to the node as, and `10.0.0.21` with
+its address. That user needs `sudo` without a password on the node.
+
+It logs in over SSH and, while you watch:
+
+1. installs llmgw on the node, the release for its processor, checksum checked;
+2. runs `llmgw doctor` there, and stops if the node has a problem. Each problem
+   comes with the command that fixes it. Fix it and run the same command again;
+3. gives the node its certificate and configuration, and starts its agent;
+4. waits for the node to join and install llama.cpp.
+
+The node's name in the cluster is its hostname. vLLM installs by itself after
+that, in a few more minutes on a GPU node (about 8 GB). The cluster page
+(`/admin`) shows its progress, or why the node cannot run it.
+
+**InfiniBand.** When the node's adapters are up, `node add` shows them grouped
+by the fabric they are on and asks for each fabric's name. Give every node on
+the same fabric the same name. In a script, give it instead:
+
+```
+sudo llmgw node add ubuntu@10.0.0.21 --fabric ib-a:mlx5_0,mlx5_1,mlx5_2,mlx5_3
+```
+
+Once two nodes on a fabric are in, check they reach each other at the link's
+rate before placing anything across them:
+
+```
+llmgw ctl fabric-test gpu01 gpu02
+```
+
+**If it cannot log in.** `sudo` runs SSH as root, with root's keys. To use your
+own keys instead, log in to the control plane with `ssh -A` and keep your
+agent through sudo:
+
+```
+sudo --preserve-env=SSH_AUTH_SOCK llmgw node add ubuntu@10.0.0.21
+```
+
+**Check:** `llmgw ctl nodes` lists the node. Running `node add` again on the
+same node is safe: it renews its certificate and configuration, and keeps what
+runs there.
+
+A machine retired for good is removed with `llmgw node remove <name>` once its
+agent is stopped.
+
+## 4. Add a model
+
+Open `/admin/mirror` and choose **Explore models**. It lists what is popular on
+Hugging Face, showing only what your nodes can run.
+
+1. Click a model to read its card.
+2. Pick one of its files, usually a `q4_k_m` for a first try, and click
+   **Fetch**. It is downloaded into the mirror once, for every node.
+3. When the download finishes, click **serve** on its row in the table above.
+4. In the form, choose how it runs: **always on**, or **on demand**, which
+   loads it on the first request and stops it after 15 minutes unused. Click
+   **Add to the catalog**.
+
+The model is placed on a node that fits it, and its status on `/admin` turns
+`ready`.
+
+**Check:** the model appears in the list on `/chat`. Ask it something.
+
+## 5. Give people access
+
+**A key for a program:** each person makes their own on the account page
+(`/profile`). The key is shown once.
+
+```
+curl http://<control-plane>:8080/v1/chat/completions \
+  -H "Authorization: Bearer $LLMGW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model": "<model-name>", "messages": [{"role": "user", "content": "hello"}]}'
+```
+
+Any OpenAI client works. Only the base URL changes:
+`http://<control-plane>:8080/v1`.
+
+**An editor:** the account page connects Continue, Codex or Cline. Pick the
+tool and a model, and it gives a one-line command that writes the
+configuration.
+
+**Other people's accounts:** they sign up at `/signup`, and you approve them on
+the people page (`/admin/users`).
+
+## 6. Put it behind HTTPS
+
+Port 8080 is plain HTTP. Before users outside a trusted network use it, put a
+reverse proxy in front with a real certificate. With Caddy, which gets the
+certificate by itself:
+
+```
+sudo apt-get install -y caddy          # Debian and Ubuntu
+curl -fsSL $U/Caddyfile | sed 's/llm.example.com/YOUR.DOMAIN/' | sudo tee /etc/caddy/Caddyfile
+sudo systemctl reload caddy
+```
+
+Keep 7443 (nodes) and 8081 (mirror) on the internal network. They never go
+through the proxy. There is an nginx configuration too:
+[deploy/proxy/](../deploy/proxy/).
+
+## When something does not work
+
+| What you see | What to do |
+|---|---|
+| `node add` stops at `join` | `sudo journalctl -u llmgw-agent -n 50` on the node. Usually it cannot reach port 7443 on the control plane. |
+| `node add` says the address is not in the certificate | Run `sudo llmgw server init --host <that address>`, then `node add` again. |
+| A node says it cannot run vLLM | The reason is on `/admin`: the driver is older than 580, the GPU is older than Turing, or there is less than 25 GB free. |
+| A model shows `not placed` | `llmgw ctl explain-placement <model>` names each node and why it was not used. |
+| A reply stops after 60 seconds behind nginx | Use the nginx configuration from the release. Its timeouts are set for slow models. |
+| Anything else about a node | `sudo llmgw doctor` on it. `--json` writes everything it read, to send to whoever helps you. |
+
+## Next
+
+- [install.md](install.md): the same steps with every option explained.
+- [fabrics.md](fabrics.md): InfiniBand and NVLink.
+- [onboarding.md](onboarding.md): accounts, projects, budgets and keys.

docs/quickstart.md

@@ -1,8 +1,8 @@
 # Quickstart: one machine, one model, ten minutes
 
-Written for someone who wants to see llmgw answer a request on a single
-workstation before reading anything else. No systemd, no `sudo`. For a real
-cluster, see [install.md](install.md).
+Written for a developer who wants to see llmgw answer a request on a single
+workstation, built from source, with no systemd and no `sudo`. **To install
+llmgw on servers, read [quick-install.md](quick-install.md) instead.**
 
 What you end up with: an OpenAI-compatible endpoint on `localhost:8080` in front
 of a real model served by llama.cpp.

docs/reference.md

@@ -29,6 +29,7 @@ rather than repeated.
 | `default_rpm` | `int` | [Auth](#auth) |
 | `default_tpm` | `int` | [Auth](#auth) |
 | `signup_open` | `bool` | [Auth](#auth) |
+| `personal` | `Personal` | [Auth](#auth) |
 | `pricing` | `map[string]Price` | [Auth](#auth) |
 | `default_price` | `Price` | [Auth](#auth) |
 | `flush_interval` | `time.Duration` | [Auth](#auth) |
@@ -70,6 +71,7 @@ rather than repeated.
 | `lease_ttl` | `time.Duration` | [Control](#control) |
 | `id` | `string` | [Endpoint](#endpoint) |
 | `url` | `string` | [Endpoint](#endpoint) |
+| `api_key` | `string` | [Endpoint](#endpoint) |
 | `models` | `[]string` | [Endpoint](#endpoint) |
 | `engine` | `string` | [Endpoint](#endpoint) |
 | `pool` | `string` | [Endpoint](#endpoint) |
@@ -79,6 +81,7 @@ rather than repeated.
 | `notice` | `string` | [Landing](#landing) |
 | `bin` | `string` | [LlamaCppConfig](#llamacppconfig) |
 | `parallel` | `int` | [LlamaCppConfig](#llamacppconfig) |
+| `threads` | `int` | [LlamaCppConfig](#llamacppconfig) |
 | `api` | `string` | [Mirror](#mirror) |
 | `tls` | `tlsconf.Config` | [Mirror](#mirror) |
 | `registry` | `string` | [Mirror](#mirror) |
@@ -102,6 +105,11 @@ rather than repeated.
 | `ib_root` | `string` | [Options](#options) |
 | `prefer_nvml` | `bool` | [Options](#options) |
 | `skip_gpus` | `bool` | [Options](#options) |
+| `disabled` | `bool` | [Personal](#personal) |
+| `rpm` | `int` | [Personal](#personal) |
+| `tpm` | `int` | [Personal](#personal) |
+| `budget` | `float64` | [Personal](#personal) |
+| `period` | `string` | [Personal](#personal) |
 | `enabled` | `bool` | [Prefix](#prefix) |
 | `max_nodes` | `int` | [Prefix](#prefix) |
 | `min_match` | `int` | [Prefix](#prefix) |
@@ -121,6 +129,7 @@ rather than repeated.
 | `args` | `[]string` | [Profile](#profile) |
 | `env` | `map[string]string` | [Profile](#profile) |
 | `min_memory_gb` | `int` | [Profile](#profile) |
+| `cpu_cores` | `int` | [Profile](#profile) |
 | `min_disk_gb` | `int` | [Profile](#profile) |
 | `node_selector` | `map[string]string` | [Profile](#profile) |
 | `weight` | `float64` | [Profile](#profile) |
@@ -160,8 +169,11 @@ rather than repeated.
 | `landing` | `Landing` | [Server](#server) |
 | `agent_tls` | `tlsconf.Config` | [Server](#server) |
 | `monitoring` | `Monitoring` | [Server](#server) |
+| `tracing` | `Tracing` | [Server](#server) |
 | `mirror` | `Mirror` | [Server](#server) |
 | `engines` | `map[string]string` | [Server](#server) |
+| `backup_dir` | `string` | [Server](#server) |
+| `releases` | `string` | [Server](#server) |
 | `router` | `Router` | [Server](#server) |
 | `control` | `Control` | [Server](#server) |
 | `models` | `[]catalog.Model` | [Server](#server) |
@@ -175,6 +187,8 @@ rather than repeated.
 | `first_token` | `time.Duration` | [Timeouts](#timeouts) |
 | `idle` | `time.Duration` | [Timeouts](#timeouts) |
 | `total` | `time.Duration` | [Timeouts](#timeouts) |
+| `endpoint` | `string` | [Tracing](#tracing) |
+| `sample_ratio` | `float64` | [Tracing](#tracing) |
 | `bin` | `string` | [VLLMConfig](#vllmconfig) |
 | `launch_mode` | `string` | [VLLMConfig](#vllmconfig) |
 | `ray_bin` | `string` | [VLLMConfig](#vllmconfig) |
@@ -267,6 +281,15 @@ SignupOpen serves the signup form. Accounts it creates are pending until
 an operator approves them, so this is not a way in — but turning it off
 means accounts are made with `llmgw users create` instead.
 
+### `personal`
+
+`Personal`
+
+Personal is what a person may do on their own, outside any project: make
+personal keys and use the chat page personally, within these limits.
+
+Takes a [Personal](#personal) block.
+
 ### `pricing`
 
 `map[string]Price`
@@ -551,6 +574,13 @@ reading the alert. Zero takes the default.
 
 `string`
 
+### `api_key`
+
+`string`
+
+APIKey is sent to the engine as a bearer token, for an engine started
+with one.
+
 ### `models`
 
 `[]string`
@@ -609,6 +639,20 @@ Parallel is how many requests a server handles at once, when a profile
 does not say. llama.cpp defaults to one, which would make every second
 request wait behind the first no matter what the router decided.
 
+### `threads`
+
+`int`
+
+Threads is how many CPU threads a shard with no GPU computes on. Zero
+takes half this machine's CPUs.
+
+Not all of them, which is llama.cpp's own default: two busy servers
+that each spin on every CPU fight for them, and on an 8-vCPU node
+that made 7B generation fall from 10 tokens a second to under 1 each.
+At half, one server alone is about a third slower and two together
+keep 5.5 each. A node that only ever runs one CPU replica does better
+with all of them; say so here.
+
 ## Mirror
 
 ### `api`
@@ -778,8 +822,9 @@ IBRoot is the sysfs InfiniBand directory.
 
 `bool`
 
-PreferNVML uses the NVML backend when this binary has one. It is the only
-source of NVLink topology.
+PreferNVML uses the NVML backend when this binary has one. NVLink
+topology is read from nvidia-smi topo -m on every build; NVML, where it
+is used, is the more exact source of the peers.
 
 ### `skip_gpus`
 
@@ -788,6 +833,33 @@ source of NVLink topology.
 SkipGPUs omits GPU discovery. A node without nvidia-smi is already
 found to have none, so this is for one whose driver is broken.
 
+## Personal
+
+### `disabled`
+
+`bool`
+
+Disabled refuses personal keys and personal chat; people then use the
+gateway only through projects they are members of.
+
+### `rpm`
+
+`int`
+
+### `tpm`
+
+`int`
+
+### `budget`
+
+`float64`
+
+Budget is in whole units per Period ("day" or "month").
+
+### `period`
+
+`string`
+
 ## Prefix
 
 ### `enabled`
@@ -895,6 +967,20 @@ this. A node that does not report its memory is not excluded either —
 an older agent must not have its nodes quietly emptied by an upgrade of
 the control plane.
 
+### `cpu_cores`
+
+`int`
+
+CPUCores is the cores a replica of a profile with no GPU is given:
+reserved out of its node's CPUs by placement, as memory is, and what
+its engine computes on (llama.cpp's --threads).
+
+Reserved because an engine takes every core it is told about, and two
+on one node that each think they have all of them spin against each
+other: on an 8-vCPU node, two 7B replicas fell from 10 tokens a second
+to under one each. Zero reserves nothing and leaves the thread count to
+the node, which is every profile from before this.
+
 ### `min_disk_gb`
 
 `int`
@@ -1193,6 +1279,16 @@ Monitoring is where the dashboard reads its history from.
 
 Takes a [Monitoring](#monitoring) block.
 
+### `tracing`
+
+`Tracing`
+
+Tracing sends a trace of each inference request to an OpenTelemetry
+collector. Off unless an endpoint is set here or in
+OTEL_EXPORTER_OTLP_ENDPOINT.
+
+Takes a [Tracing](#tracing) block.
+
 ### `mirror`
 
 `Mirror`
@@ -1214,6 +1310,22 @@ never trusted to already have what somebody once put there.
 Unset keeps DefaultEngines. A version replaces the default; an empty
 one leaves that engine to be installed by hand.
 
+### `backup_dir`
+
+`string`
+
+BackupDir is where `llmgw server backup` writes, and where the newest
+archive's age is read for llmgw_backup_last_success_timestamp_seconds.
+Empty means /var/backups/llmgw-server.
+
+### `releases`
+
+`string`
+
+Releases is where `llmgw ctl upgrade` fetches release binaries from,
+for this machine and — through their agents — every node. Empty means
+the project's own releases.
+
 ### `router`
 
 `Router`
@@ -1297,6 +1409,22 @@ about a hundred tokens on a slow model.
 
 `time.Duration`
 
+## Tracing
+
+### `endpoint`
+
+`string`
+
+Endpoint is the collector, for example http://otel.internal:4318.
+Empty falls back to OTEL_EXPORTER_OTLP_ENDPOINT, and to no tracing.
+
+### `sample_ratio`
+
+`float64`
+
+SampleRatio is the share of requests traced, 0 to 1, when the caller
+did not decide it with a sampled traceparent of its own. Zero takes 1.
+
 ## VLLMConfig
 
 ### `bin`
@@ -1309,11 +1437,13 @@ Bin is the vllm executable.
 
 `string`
 
-LaunchMode selects the multi-node mechanism: "ray" or "mp".
+LaunchMode selects the multi-node mechanism: "mp", the default, or
+"ray".
 
-Which one works depends on the vLLM version, and the flags have changed
-more than once (plan §14). Both paths exist so a cluster can pick the one
-its version supports instead of waiting for a code change.
+mp is what vLLM documents today — every node runs serve with its rank,
+the workers headless — and needs nothing but vLLM. ray is the older way,
+kept for a vLLM too old for mp's multi-node flags; it needs Ray on every
+node and has not been checked against a real cluster.
 
 ### `ray_bin`
 

go.mod

@@ -6,15 +6,23 @@ require (
 	connectrpc.com/connect v1.21.0
 	github.com/NVIDIA/go-nvml v0.13.4-0
 	github.com/cespare/xxhash/v2 v2.3.0
+	github.com/charmbracelet/bubbletea v1.3.10
+	github.com/charmbracelet/lipgloss v1.1.0
 	github.com/jackc/pgx/v5 v5.11.0
 	github.com/knadh/koanf/parsers/yaml v1.1.1
 	github.com/knadh/koanf/providers/env/v2 v2.0.1
 	github.com/knadh/koanf/providers/file v1.2.1
 	github.com/knadh/koanf/v2 v2.3.6
+	github.com/mattn/go-isatty v0.0.24
 	github.com/prometheus/client_golang v1.24.1
 	github.com/prometheus/client_model v0.6.3
 	github.com/prometheus/common v0.71.0
 	github.com/spf13/cobra v1.10.2
+	github.com/yuin/goldmark v1.8.6
+	go.opentelemetry.io/otel v1.46.0
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.46.0
+	go.opentelemetry.io/otel/sdk v1.46.0
+	go.opentelemetry.io/otel/trace v1.46.0
 	golang.org/x/crypto v0.57.0
 	golang.org/x/net v0.59.0
 	golang.org/x/sync v0.23.0
@@ -23,27 +31,54 @@ require (
 )
 
 require (
+	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/cenkalti/backoff/v5 v5.0.3 // indirect
+	github.com/charmbracelet/colorprofile v0.4.1 // indirect
+	github.com/charmbracelet/x/ansi v0.11.6 // indirect
+	github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
+	github.com/charmbracelet/x/term v0.2.2 // indirect
+	github.com/clipperhouse/displaywidth v0.9.0 // indirect
+	github.com/clipperhouse/stringish v0.1.1 // indirect
+	github.com/clipperhouse/uax29/v2 v2.5.0 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
 	github.com/fsnotify/fsnotify v1.9.0 // indirect
-	github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
+	github.com/go-logr/logr v1.4.4 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
 	github.com/google/uuid v1.6.0 // indirect
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.30.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/knadh/koanf/maps v0.1.2 // indirect
-	github.com/mattn/go-isatty v0.0.24 // indirect
+	github.com/lucasb-eyer/go-colorful v1.3.0 // indirect
+	github.com/mattn/go-localereader v0.0.1 // indirect
+	github.com/mattn/go-runewidth v0.0.19 // indirect
 	github.com/mitchellh/copystructure v1.2.0 // indirect
 	github.com/mitchellh/reflectwalk v1.0.2 // indirect
+	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
+	github.com/muesli/cancelreader v0.2.2 // indirect
+	github.com/muesli/termenv v0.16.0 // indirect
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/ncruces/go-strftime v1.0.0 // indirect
 	github.com/prometheus/procfs v0.21.1 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/spf13/pflag v1.0.9 // indirect
+	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.46.0 // indirect
+	go.opentelemetry.io/otel/metric v1.46.0 // indirect
+	go.opentelemetry.io/proto/otlp v1.11.0 // indirect
 	go.yaml.in/yaml/v3 v3.0.5 // indirect
 	golang.org/x/sys v0.48.0 // indirect
 	golang.org/x/text v0.42.0 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20260819154853-08b0e4226688 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260819154853-08b0e4226688 // indirect
+	google.golang.org/grpc v1.83.1 // indirect
 	modernc.org/libc v1.75.7 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
 	modernc.org/memory v1.12.1 // indirect

go.sum

@@ -2,24 +2,57 @@ connectrpc.com/connect v1.21.0 h1:LhqSJt7jHf5NJBo9Jq/t/9FjcYAideif0mg+qe2jCUs=
 connectrpc.com/connect v1.21.0/go.mod h1:A2ygJrukXwWy32vkCAAHNVguZrqZ+jeZ9rGRnGR4dN4=
 github.com/NVIDIA/go-nvml v0.13.4-0 h1:o3jp9u2x1R9ShFE3v+Aesp55XOSIQFMJz/VGNUcJaNE=
 github.com/NVIDIA/go-nvml v0.13.4-0/go.mod h1:id63qwpoDWpFXwnwM6psDCSqW4BmNu6mWpr4YeQtPGo=
+github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
+github.com/aymanbagabas/go-osc52/v2 v2.0.1/go.mod h1:uYgXzlJ7ZpABp8OJ+exZzJJhRNQ2ASbcXHWsFqH8hp8=
 github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
 github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
+github.com/cenkalti/backoff/v5 v5.0.3 h1:ZN+IMa753KfX5hd8vVaMixjnqRZ3y8CuJKRKj1xcsSM=
+github.com/cenkalti/backoff/v5 v5.0.3/go.mod h1:rkhZdG3JZukswDf7f0cwqPNk4K0sa+F97BxZthm/crw=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/charmbracelet/bubbletea v1.3.10 h1:otUDHWMMzQSB0Pkc87rm691KZ3SWa4KUlvF9nRvCICw=
+github.com/charmbracelet/bubbletea v1.3.10/go.mod h1:ORQfo0fk8U+po9VaNvnV95UPWA1BitP1E0N6xJPlHr4=
+github.com/charmbracelet/colorprofile v0.4.1 h1:a1lO03qTrSIRaK8c3JRxJDZOvhvIeSco3ej+ngLk1kk=
+github.com/charmbracelet/colorprofile v0.4.1/go.mod h1:U1d9Dljmdf9DLegaJ0nGZNJvoXAhayhmidOdcBwAvKk=
+github.com/charmbracelet/lipgloss v1.1.0 h1:vYXsiLHVkK7fp74RkV7b2kq9+zDLoEU4MZoFqR/noCY=
+github.com/charmbracelet/lipgloss v1.1.0/go.mod h1:/6Q8FR2o+kj8rz4Dq0zQc3vYf7X+B0binUUBwA0aL30=
+github.com/charmbracelet/x/ansi v0.11.6 h1:GhV21SiDz/45W9AnV2R61xZMRri5NlLnl6CVF7ihZW8=
+github.com/charmbracelet/x/ansi v0.11.6/go.mod h1:2JNYLgQUsyqaiLovhU2Rv/pb8r6ydXKS3NIttu3VGZQ=
+github.com/charmbracelet/x/cellbuf v0.0.15 h1:ur3pZy0o6z/R7EylET877CBxaiE1Sp1GMxoFPAIztPI=
+github.com/charmbracelet/x/cellbuf v0.0.15/go.mod h1:J1YVbR7MUuEGIFPCaaZ96KDl5NoS0DAWkskup+mOY+Q=
+github.com/charmbracelet/x/term v0.2.2 h1:xVRT/S2ZcKdhhOuSP4t5cLi5o+JxklsoEObBSgfgZRk=
+github.com/charmbracelet/x/term v0.2.2/go.mod h1:kF8CY5RddLWrsgVwpw4kAa6TESp6EB5y3uxGLeCqzAI=
+github.com/clipperhouse/displaywidth v0.9.0 h1:Qb4KOhYwRiN3viMv1v/3cTBlz3AcAZX3+y9OLhMtAtA=
+github.com/clipperhouse/displaywidth v0.9.0/go.mod h1:aCAAqTlh4GIVkhQnJpbL0T/WfcrJXHcj8C0yjYcjOZA=
+github.com/clipperhouse/stringish v0.1.1 h1:+NSqMOr3GR6k1FdRhhnXrLfztGzuG+VuFDfatpWHKCs=
+github.com/clipperhouse/stringish v0.1.1/go.mod h1:v/WhFtE1q0ovMta2+m+UbpZ+2/HEXNWYXQgCt4hdOzA=
+github.com/clipperhouse/uax29/v2 v2.5.0 h1:x7T0T4eTHDONxFJsL94uKNKPHrclyFI0lm7+w94cO8U=
+github.com/clipperhouse/uax29/v2 v2.5.0/go.mod h1:Wn1g7MK6OoeDT0vL+Q0SQLDz/KpfsVRgg6W7ihQeh4g=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f h1:Y/CXytFA4m6baUTXGLOoWe4PQhGxaX0KpnayAqC48p4=
+github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f/go.mod h1:vw97MGsxSvLiUE2X8qFplwetxpGLQrlU1Q9AUEIzCaM=
 github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
 github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
-github.com/go-viper/mapstructure/v2 v2.4.0 h1:EBsztssimR/CONLSZZ04E8qAkxNYq4Qp9LvH92wZUgs=
-github.com/go-viper/mapstructure/v2 v2.4.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.4 h1:tG4xh9yMsRCAiodLVTxyrkzSZ9+o0L1Kg/+cPVcbP/8=
+github.com/go-logr/logr v1.4.4/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/go-viper/mapstructure/v2 v2.5.0 h1:vM5IJoUAy3d7zRSVtIwQgBj7BiWtMPfmPEgAXnvj1Ro=
+github.com/go-viper/mapstructure/v2 v2.5.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3 h1:LMLX+LgTNWpfvCBdFebv6EsYotImrt/Ppc5cXIriCSo=
 github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3/go.mod h1:jl5iWTm0/hd5PjEYEOuwAJ57L/CibdZfrqZ5XA5GrCk=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.30.0 h1:/Tnpcb2E0Pz/tN9s3bfEY2Q8ePCEX9iuS+cneUwncnw=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.30.0/go.mod h1:zOBXOsUaBSjKgmH4OGzV1esUpR3oUSCPYVd2cUBjKYY=
 github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
 github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
@@ -46,12 +79,24 @@ github.com/knadh/koanf/v2 v2.3.6 h1:JoQPSJmvS4aP0xNc8xMDr5tcrkSEInL23/Il7pITAKo=
 github.com/knadh/koanf/v2 v2.3.6/go.mod h1:gRb40VRAbd4iJMYYD5IxZ6hfuopFcXBpc9bbQpZwo28=
 github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
 github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
+github.com/lucasb-eyer/go-colorful v1.3.0 h1:2/yBRLdWBZKrf7gB40FoiKfAWYQ0lqNcbuQwVHXptag=
+github.com/lucasb-eyer/go-colorful v1.3.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
 github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI=
 github.com/mattn/go-isatty v0.0.24/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A=
+github.com/mattn/go-localereader v0.0.1 h1:ygSAOl7ZXTx4RdPYinUpg6W99U8jWvWi9Ye2JC/oIi4=
+github.com/mattn/go-localereader v0.0.1/go.mod h1:8fBrzywKY7BI3czFoHkuzRoWE9C+EiG4R1k4Cjx5p88=
+github.com/mattn/go-runewidth v0.0.19 h1:v++JhqYnZuu5jSKrk9RbgF5v4CGUjqRfBm05byFGLdw=
+github.com/mattn/go-runewidth v0.0.19/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
 github.com/mitchellh/copystructure v1.2.0 h1:vpKXTN4ewci03Vljg/q9QvCGUDttBOGBIa15WveJJGw=
 github.com/mitchellh/copystructure v1.2.0/go.mod h1:qLl+cE2AmVv+CoeAwDPye/v+N2HKCj9FbZEVFJRxO9s=
 github.com/mitchellh/reflectwalk v1.0.2 h1:G2LzWKi524PWgd3mLHV8Y5k7s6XUvT0Gef6zxSIeXaQ=
 github.com/mitchellh/reflectwalk v1.0.2/go.mod h1:mSTlrgnPZtwu0c4WaC2kGObEpuNDbx0jmZXqmk4esnw=
+github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 h1:ZK8zHtRHOkbHy6Mmr5D264iyp3TiX5OmNcI5cIARiQI=
+github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6/go.mod h1:CJlz5H+gyd6CUWT45Oy4q24RdLyn7Md9Vj2/ldJBSIo=
+github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELUXHmA=
+github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIfMUZ4EgX0QYo=
+github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc=
+github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
 github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
@@ -67,6 +112,8 @@ github.com/prometheus/procfs v0.21.1 h1:GljZCt+zSTS+NZq88cyQ1LjZ+RCHp3uVuabBWA5+
 github.com/prometheus/procfs v0.21.1/go.mod h1:aB55Cww9pdSJVHk0hUf0inxWyyjPogFIjmHKYgMKmtY=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
+github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
 github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
@@ -77,6 +124,28 @@ github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UV
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE=
 github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg=
+github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
+github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
+github.com/yuin/goldmark v1.8.6 h1:d0VcaP1sx9GkFVkoW+KtggpGi2KZ965i14b0+bDQST4=
+github.com/yuin/goldmark v1.8.6/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v1.46.0 h1:FHt5/CDyVxi/8IM1CH7VE/rRgq3kLHa2mSTVMO8AWyc=
+go.opentelemetry.io/otel v1.46.0/go.mod h1:Gj3SEScelsNC45tp4nSxRYlS+f5iez7W8XPMCt905kE=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.46.0 h1:OFnwLJr+pF3iHrlGSzbxyuo6/6HyBlnlN1CWEJmBVcw=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.46.0/go.mod h1:716wFneO0ov19A2beH5hjfh9AK5z/VWNAtDijp1Y0/g=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.46.0 h1:KrC1YrQeSt46ITMWAbgQx1M1eV1/1TKzttrBzymPmss=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.46.0/go.mod h1:zDSEzoEqsOrgBeGvH66KRgxh90VonFyJqBHA0Pk3+rM=
+go.opentelemetry.io/otel/metric v1.46.0 h1:yBnkXvgV7AXFILZc5K6IZe/CBFF3OS7BJ8ov6/lj0K8=
+go.opentelemetry.io/otel/metric v1.46.0/go.mod h1:iPmdWqifKUdzziPkvvzIJXITl56fQx2mGM/DHLB3/2o=
+go.opentelemetry.io/otel/sdk v1.46.0 h1:h5CNQQjEbuQXY/JfZtgt3i7HVFV3aHPO2OAwO2eTYPI=
+go.opentelemetry.io/otel/sdk v1.46.0/go.mod h1:GAERFXFt5SYCEB+YiKUbMBeza6UaDH7GmGOZEfh2gSM=
+go.opentelemetry.io/otel/sdk/metric v1.46.0 h1:0piZ26EG4RBfebb2jhDH6ERCYHoVWduc3kLgPCwSnSE=
+go.opentelemetry.io/otel/sdk/metric v1.46.0/go.mod h1:I1PbKrdVc8Qu8HYVDNtqVIwLwjNrhsV/uFuxfwg8mO4=
+go.opentelemetry.io/otel/trace v1.46.0 h1:OULy7ccdJnZtJ0UDYFOIGaCmiWzJ8Vi2G/Rsu60qs1c=
+go.opentelemetry.io/otel/trace v1.46.0/go.mod h1:J7GAXweO77XSFkB/rmAqk9D6ihszhFjLU+d9WuUxDLI=
+go.opentelemetry.io/proto/otlp v1.11.0 h1:5rrYs0Ykyj50sdU/JU0x8etU+LubXWb+gED6TbEdMIk=
+go.opentelemetry.io/proto/otlp v1.11.0/go.mod h1:SmVizdCOAm3XBtG1g1NnOdhW6jtddT72hLMhv8VwA8E=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
 go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
 go.yaml.in/yaml/v2 v2.4.4 h1:tuyd0P+2Ont/d6e2rl3be67goVK4R6deVxCUX5vyPaQ=
@@ -86,18 +155,29 @@ go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw=
 go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg=
 golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M=
 golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA=
+golang.org/x/exp v0.0.0-20231006140011-7918f672742d h1:jtJma62tbqLibJ5sFQz8bKtEM8rJBtfilJ2qTU199MI=
+golang.org/x/exp v0.0.0-20231006140011-7918f672742d/go.mod h1:ldy0pHrwJyGW56pPQzzkH36rKxoZW1tw7ZJpeKx+hdo=
 golang.org/x/mod v0.41.0 h1:qJmnOUb4YB+FsEuM3HcWucdZASCPGhsX6uljO6pog0c=
 golang.org/x/mod v0.41.0/go.mod h1:Ek9pY8RKWXwsWvd3rQiHYtMqkjSUV+s1Rj7j4H5Ur6o=
 golang.org/x/net v0.59.0 h1:5zfYln+w5XCxwrnMMJPufRgNoXEaGxl0wo5GqPXyues=
 golang.org/x/net v0.59.0/go.mod h1:2DA/G1UfVbCpQPeWTmMPGY7Cs2PkBkwu743bVX5PIVg=
 golang.org/x/sync v0.23.0 h1:KameEIfc1IkluZyXWLn39Wd4tURc6GbCiISGiZm2bQk=
 golang.org/x/sync v0.23.0/go.mod h1:sUUOizhqBxiL6pEWpqNLUiaJn1ShEbZ6BBqskPbjZm0=
+golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
 golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
 golang.org/x/text v0.42.0 h1:JbOZXgfeCPU9gacVtYliJqOhD+zhrEqK4LfdpmlUZqI=
 golang.org/x/text v0.42.0/go.mod h1:ojzP1Z+2QtioaF8DTtO8K5q7JWVVYwZKenzujK0Zd0E=
 golang.org/x/tools v0.49.0 h1:3NI7VXzL9+1WZD52Dx2ttoPwD5DWrFGpl9mFZDlmisI=
 golang.org/x/tools v0.49.0/go.mod h1:SJNXV9DBKT0UbdttsQjbfJlAE/q+y36++zo3uL3N0Oo=
+gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
+gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
+google.golang.org/genproto/googleapis/api v0.0.0-20260819154853-08b0e4226688 h1:ax2KzoSRIZU/M0cIxri3pKxy99vniH1PVxWC6si/eZI=
+google.golang.org/genproto/googleapis/api v0.0.0-20260819154853-08b0e4226688/go.mod h1:1RJ9BQGyNdZwkGc1eTqkErfRZ6RJyYPHZo73BZ1vQqI=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260819154853-08b0e4226688 h1:cYNAzI2sUwhmCcoj9TxvihSrqsxt6uIkj3rDRhSDmW4=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260819154853-08b0e4226688/go.mod h1:DjtHYE8FKJLivXcBEjGwndXfIC23G0VpXiXKqG179uA=
+google.golang.org/grpc v1.83.1 h1:HIO0+BEtBP6soyqvqC8sNUjZ7bTs+0hFQuFF+RAy++Y=
+google.golang.org/grpc v1.83.1/go.mod h1:kDyl6SKsiHKt0uylY5gtn5cEjkrIOhQOGDgIc4JGwzQ=
 google.golang.org/protobuf v1.36.12 h1:pJOKDDOyeXErUroCihFAd5LQuwXBSpVnKGrj5o/fwxc=
 google.golang.org/protobuf v1.36.12/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

internal/account/account_test.go

@@ -99,17 +99,21 @@ func TestApprovalIsWhatMakesAnAccountWork(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if got.ProjectID != "proj" {
-		t.Errorf("the approved account landed in project %q", got.ProjectID)
+	if ok, err := st.CanUseProject(ctx, got.ID, "proj"); err != nil || !ok {
+		t.Errorf("the approved account is not a member of the project it was approved into: %v", err)
 	}
 }
 
-func TestApprovalNeedsAProject(t *testing.T) {
-	// An approved account with nowhere to put its keys passes every check and
-	// then fails at the first key it tries to make.
-	_, st := newStoreAndUser(t)
-	if err := st.ApproveUser(context.Background(), "usr-1", "", "ilker", time.Now()); err == nil {
-		t.Error("an account was approved into no project")
+func TestApprovalNeedNotNameAProject(t *testing.T) {
+	// A person need not belong to anything to use the gateway: approved into
+	// nothing, they work on their own within their personal limits.
+	svc, st := newStoreAndUser(t)
+	ctx := context.Background()
+	if err := st.ApproveUser(ctx, "usr-1", "", "ilker", time.Now()); err != nil {
+		t.Fatalf("approving with no project: %v", err)
+	}
+	if _, _, err := svc.SignIn(ctx, "ayse@example.com", goodPassword); err != nil {
+		t.Errorf("an account approved into nothing cannot sign in: %v", err)
 	}
 }
 

internal/account/password.go

@@ -15,6 +15,7 @@ import (
 	"encoding/base64"
 	"errors"
 	"fmt"
+	"runtime"
 	"strings"
 
 	"golang.org/x/crypto/argon2"
@@ -56,7 +57,7 @@ func HashPassword(password string) (string, error) {
 	if _, err := rand.Read(salt); err != nil {
 		return "", err
 	}
-	sum := argon2.IDKey([]byte(password), salt, argonTime, argonMemory, argonThreads, argonKeyLen)
+	sum := idKey([]byte(password), salt, argonTime, argonMemory, argonThreads, argonKeyLen)
 
 	b64 := base64.RawStdEncoding.EncodeToString
 	return fmt.Sprintf("$argon2id$v=%d$m=%d,t=%d,p=%d$%s$%s",
@@ -93,7 +94,7 @@ func VerifyPassword(password, encoded string) (bool, error) {
 		return false, ErrBadHash
 	}
 
-	got := argon2.IDKey([]byte(password), salt, time, memory, threads, uint32(len(want)))
+	got := idKey([]byte(password), salt, time, memory, threads, uint32(len(want)))
 	return subtle.ConstantTimeCompare(got, want) == 1, nil
 }
 
@@ -110,3 +111,16 @@ func init() {
 	}
 	dummyHash = h
 }
+
+// argonSlots bounds how many hashes run at once. Each takes 64 MiB, and the
+// login and signup forms are on the client-facing port: without a bound, a
+// few hundred parallel attempts at random addresses asked for gigabytes at
+// once, and the per-address throttle does not see them — each address is new.
+// Beyond the bound, attempts wait their turn instead.
+var argonSlots = make(chan struct{}, max(2, runtime.NumCPU()/2))
+
+func idKey(password, salt []byte, time, memory uint32, threads uint8, keyLen uint32) []byte {
+	argonSlots <- struct{}{}
+	defer func() { <-argonSlots }()
+	return argon2.IDKey(password, salt, time, memory, threads, keyLen)
+}

internal/account/service.go

@@ -230,6 +230,22 @@ func (s *Service) allowAttempt(email string) bool {
 	defer s.mu.Unlock()
 
 	w, ok := s.attempts[email]
+	if !ok && len(s.attempts) >= maxTrackedAddresses {
+		// Full of addresses nobody has signed in as for a while: forget the
+		// ones whose window has passed. Only expiring, never evicting early —
+		// dropping a live window is how an attacker spraying random addresses
+		// would buy unlimited guesses at the one they care about.
+		for k, v := range s.attempts {
+			if now.Sub(v.since) > s.cfg.AttemptWindow {
+				delete(s.attempts, k)
+			}
+		}
+		if len(s.attempts) >= maxTrackedAddresses {
+			// Still full, so somebody is spraying addresses faster than they
+			// expire. New ones wait; those already tracked are unaffected.
+			return false
+		}
+	}
 	if !ok || now.Sub(w.since) > s.cfg.AttemptWindow {
 		s.attempts[email] = &attemptWindow{count: 1, since: now}
 		return true
@@ -238,6 +254,10 @@ func (s *Service) allowAttempt(email string) bool {
 	return w.count <= s.cfg.MaxAttempts
 }
 
+// maxTrackedAddresses bounds the throttle's memory. Unbounded, it grew by one
+// entry per address tried and shrank only on a successful sign-in.
+const maxTrackedAddresses = 50000
+
 func (s *Service) clearAttempts(email string) {
 	s.mu.Lock()
 	delete(s.attempts, email)

internal/account/throttle_bound_test.go

@@ -0,0 +1,33 @@
+package account
+
+import (
+	"fmt"
+	"testing"
+	"time"
+)
+
+func TestSprayingAddressesCannotGrowTheThrottleOrEscapeIt(t *testing.T) {
+	now := time.Unix(0, 0)
+	s := &Service{cfg: DefaultConfig(), attempts: map[string]*attemptWindow{}, now: func() time.Time { return now }}
+
+	// The target is being guessed at.
+	for i := 0; i < s.cfg.MaxAttempts; i++ {
+		s.allowAttempt("victim@example.com")
+	}
+	// Then the table is flooded with made-up addresses.
+	for i := 0; i < maxTrackedAddresses+100; i++ {
+		s.allowAttempt(fmt.Sprintf("x%d@example.com", i))
+	}
+	if n := len(s.attempts); n > maxTrackedAddresses {
+		t.Errorf("the table grew to %d", n)
+	}
+	if s.allowAttempt("victim@example.com") {
+		t.Error("flooding the table reset the target's throttle")
+	}
+
+	// Once the window passes, everything expires and sign-ins work again.
+	now = now.Add(s.cfg.AttemptWindow + time.Second)
+	if !s.allowAttempt("new@example.com") {
+		t.Error("a new address was refused after the flood expired")
+	}
+}

internal/accounting/accounting.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"fmt"
 	"log/slog"
+	"strings"
 	"time"
 
 	"gitea.mynodes.xyz/ilker/llmgw/internal/auth"
@@ -79,14 +80,27 @@ func (a *Accountant) RestoreBudgets(ctx context.Context, s store.Store, period s
 	// totals would bring the control plane back up believing the team had spent
 	// nothing — which is a budget that resets on every restart, for exactly the
 	// scopes where it matters most.
-	spend := make(map[string]int64, len(rows)*4)
+	// And every pool a person is in: their own, and each per-member limit of
+	// the project, team and organization they spent it in.
+	spend := make(map[string]int64, len(rows)*8)
 	for _, r := range rows {
-		for _, o := range []store.LimitOwner{
+		owners := []store.LimitOwner{
 			{Scope: store.ScopeKey, ID: r.KeyID},
 			{Scope: store.ScopeProject, ID: r.ProjectID},
 			{Scope: store.ScopeTeam, ID: r.TeamID},
 			{Scope: store.ScopeOrg, ID: r.OrgID},
-		} {
+			{Scope: store.ScopeUser, ID: r.UserID},
+		}
+		if r.UserID != "" && r.ProjectID != "" {
+			owners = append(owners,
+				store.MemberOwner(store.ScopeProjectMember, r.ProjectID, r.UserID),
+				store.MemberOwner(store.ScopeTeamMember, r.TeamID, r.UserID),
+				store.MemberOwner(store.ScopeOrgMember, r.OrgID, r.UserID))
+		}
+		for _, o := range owners {
+			if o.ID == "" || strings.HasPrefix(o.ID, "/") {
+				continue
+			}
 			if k := o.CounterKey(); k != "" {
 				spend[k] += r.Micros
 			}
@@ -369,3 +383,39 @@ func keyCounter(keyID string) string {
 // they are asking is whether the budgets they are about to display mean
 // anything, and the accountant is what would enforce them.
 func (a *Accountant) AnythingPriced() bool { return a.pricing.AnythingPriced() }
+
+// Headroom is the tightest of a principal's request and token limits: how
+// much is left of each, and when the minute it is counted over rolls on.
+type Headroom struct {
+	RequestLimit, RequestsLeft int
+	TokenLimit, TokensLeft     int
+	Reset                      time.Duration
+}
+
+// Headroom reports what a principal has left, after whatever Check just
+// charged. Of several levels the one with least left is the one that will
+// refuse first, so that is the one reported. A limit of 0 means none is set.
+func (a *Accountant) Headroom(p auth.Principal) Headroom {
+	var h Headroom
+	firstReq, firstTok := true, true
+	for _, l := range levels(p.Limits, p.KeyID) {
+		if l.RPM != nil && *l.RPM > 0 {
+			left := max(0, *l.RPM-int(a.requests.Rate(l.Counter)))
+			if firstReq || left < h.RequestsLeft {
+				h.RequestLimit, h.RequestsLeft, firstReq = *l.RPM, left, false
+			}
+		}
+		if l.TPM != nil && *l.TPM > 0 {
+			left := max(0, *l.TPM-int(a.tokens.Rate(l.Counter)))
+			if firstTok || left < h.TokensLeft {
+				h.TokenLimit, h.TokensLeft, firstTok = *l.TPM, left, false
+			}
+		}
+	}
+	// The windows slide, so room comes back continuously; the next minute
+	// boundary is when a whole window's worth has moved on, and is the figure
+	// a client pacing itself can act on.
+	now := time.Now()
+	h.Reset = now.Truncate(windowLen).Add(windowLen).Sub(now)
+	return h
+}

internal/accounting/accounting_test.go

@@ -630,3 +630,31 @@ func TestAnEmptyPriceTableMeansNoBudgetCanEverBind(t *testing.T) {
 		t.Error("no price table at all is not priced")
 	}
 }
+
+func TestHeadroomIsTheTightestLimitAfterThisRequest(t *testing.T) {
+	// A project allowing 100 a minute under a team allowing 3: the team is
+	// what will refuse, so the team is what a client is told about.
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	p := principal("k1", func(e *store.Effective) {
+		e.Chain = []store.Limits{
+			{Scope: store.ScopeProject, ScopeID: "proj", RPM: intp(100), TPM: intp(50000)},
+			{Scope: store.ScopeTeam, ScopeID: "team", RPM: intp(3)},
+		}
+	})
+	if _, err := a.Check(p, "m", 10); err != nil {
+		t.Fatal(err)
+	}
+	h := a.Headroom(p)
+	if h.RequestLimit != 3 || h.RequestsLeft != 2 {
+		t.Errorf("requests %d left of %d; expected 2 of the team's 3", h.RequestsLeft, h.RequestLimit)
+	}
+	if h.TokenLimit != 50000 || h.TokensLeft != 50000-10 {
+		t.Errorf("tokens %d left of %d", h.TokensLeft, h.TokenLimit)
+	}
+	if h.Reset <= 0 || h.Reset > time.Minute {
+		t.Errorf("reset %v", h.Reset)
+	}
+	if none := a.Headroom(principal("k2", nil)); none.RequestLimit != 0 || none.TokenLimit != 0 {
+		t.Errorf("a key with no limits advertised some: %+v", none)
+	}
+}

internal/accounting/people_test.go

@@ -0,0 +1,126 @@
+package accounting
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/auth"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
+)
+
+// peopleStore has Acme/ml/training with two members, ayse and deniz.
+func peopleStore(t *testing.T) (*store.DB, string) {
+	t.Helper()
+	ctx := context.Background()
+	s, err := store.OpenSQLite(ctx, filepath.Join(t.TempDir(), "p.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = s.Close() })
+	org, _ := s.CreateOrg(ctx, "Acme")
+	team, _ := s.CreateTeam(ctx, org, "ml")
+	proj, _ := s.CreateProject(ctx, team, "training")
+	for _, id := range []string{"ayse", "deniz"} {
+		if err := s.CreateUser(ctx, store.User{ID: id, Email: id + "@x", Name: id,
+			PasswordHash: "h", State: store.UserPending, CreatedAt: time.Now()}); err != nil {
+			t.Fatal(err)
+		}
+		if err := s.ApproveUser(ctx, id, proj, "test", time.Now()); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return s, proj
+}
+
+// keyFor makes a key for a person and resolves it the way authentication does.
+func keyFor(t *testing.T, s *store.DB, id, user, project string) auth.Principal {
+	t.Helper()
+	ctx := context.Background()
+	_, k, _ := store.NewKey(id, id, project)
+	if err := s.CreateUserKey(ctx, user, k); err != nil {
+		t.Fatal(err)
+	}
+	e, err := s.Resolve(ctx, id)
+	if err != nil {
+		t.Fatalf("resolving %s: %v", id, err)
+	}
+	return auth.Principal{KeyID: id, UserID: e.UserID, ProjectID: e.ProjectID, Limits: e}
+}
+
+func TestAPersonsLimitIsOnePoolAcrossTheirKeys(t *testing.T) {
+	s, proj := peopleStore(t)
+	if err := s.PutLimits(context.Background(),
+		store.Limits{Scope: store.ScopeUser, ScopeID: "ayse", RPM: intp(2)}); err != nil {
+		t.Fatal(err)
+	}
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	personal := keyFor(t, s, "k-personal", "ayse", "")
+	inProject := keyFor(t, s, "k-project", "ayse", proj)
+
+	// Two requests, one on each key, use up the person's two a minute.
+	for _, p := range []auth.Principal{personal, inProject} {
+		if _, err := a.Check(p, "free", 1); err != nil {
+			t.Fatalf("%s: %v", p.KeyID, err)
+		}
+	}
+	if _, err := a.Check(personal, "free", 1); !errors.Is(err, ErrRateLimited) {
+		t.Errorf("a third request across her keys was allowed: %v", err)
+	}
+	// Deniz is somebody else.
+	if _, err := a.Check(keyFor(t, s, "k-deniz", "deniz", proj), "free", 1); err != nil {
+		t.Errorf("another person was limited by hers: %v", err)
+	}
+}
+
+func TestAPerMemberLimitCountsEachMemberApart(t *testing.T) {
+	s, proj := peopleStore(t)
+	if err := s.PutLimits(context.Background(),
+		store.Limits{Scope: store.ScopeProjectMember, ScopeID: proj, RPM: intp(1)}); err != nil {
+		t.Fatal(err)
+	}
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	ayse := keyFor(t, s, "k-a", "ayse", proj)
+	deniz := keyFor(t, s, "k-d", "deniz", proj)
+
+	if _, err := a.Check(ayse, "free", 1); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := a.Check(ayse, "free", 1); !errors.Is(err, ErrRateLimited) {
+		t.Errorf("her second request passed a one-a-minute per-member limit: %v", err)
+	}
+	// Her share is hers: Deniz still has his.
+	if _, err := a.Check(deniz, "free", 1); err != nil {
+		t.Errorf("one member's use counted against another: %v", err)
+	}
+	// And outside the project it does not apply at all.
+	if _, err := a.Check(keyFor(t, s, "k-a-own", "ayse", ""), "free", 1); err != nil {
+		t.Errorf("a project's per-member limit held her personal key: %v", err)
+	}
+}
+
+func TestAPersonsBudgetSurvivesARestart(t *testing.T) {
+	s, _ := peopleStore(t)
+	ctx := context.Background()
+	if err := s.PutLimits(ctx, store.Limits{Scope: store.ScopeUser, ScopeID: "ayse",
+		Budget: i64p(1000), BudgetPeriod: store.PeriodMonth}); err != nil {
+		t.Fatal(err)
+	}
+	// Spent before the restart, personally and on the chat page.
+	if err := s.WriteUsage(ctx, []store.Usage{
+		{At: time.Now(), KeyID: "k-old", UserID: "ayse", CostMicros: 600, Model: "paid", ServedModel: "paid"},
+		{At: time.Now(), KeyID: "session:ayse", UserID: "ayse", CostMicros: 500, Model: "paid", ServedModel: "paid"},
+	}); err != nil {
+		t.Fatal(err)
+	}
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	if err := a.RestoreBudgets(ctx, s, store.PeriodMonth); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := a.Check(keyFor(t, s, "k-new", "ayse", ""), "paid", 1); !errors.Is(err, ErrBudgetSpent) {
+		t.Errorf("a restart forgot what she had spent: %v", err)
+	}
+}

internal/agent/agent.go

@@ -14,11 +14,10 @@ import (
 	"math/rand/v2"
 	"net"
 	"net/http"
-	"net/url"
 	"os"
 	"path/filepath"
+	"runtime"
 	"slices"
-	"strings"
 	"sync"
 	"time"
 
@@ -32,275 +31,9 @@ import (
 	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/supervisor"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/weights"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/control/agentsvc"
-	"gitea.mynodes.xyz/ilker/llmgw/internal/control/inventory"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/tlsconf"
 )
 
-// Config configures the agent.
-type Config struct {
-	// NodeID defaults to the hostname. It must equal the common name of the
-	// agent's certificate, so set it only where the two differ.
-	NodeID string `koanf:"node_id"`
-	// Server is the control plane, and Servers is the same thing when there is
-	// more than one. Both are accepted: every configuration written before
-	// there could be a second control plane names one address, and none of
-	// them should have to change.
-	//
-	// The order is tried in order, and a refusal moves to the next. Only the
-	// leader accepts an agent, so a standby is skipped in the time it takes to
-	// be told so — which is what makes failover a reconnect rather than an
-	// edit to every node's configuration.
-	Server  string   `koanf:"server"`
-	Servers []string `koanf:"servers"`
-	// Hostname defaults to the machine's.
-	Hostname string `koanf:"hostname"`
-	// MgmtAddr is the address engines are reached on. It defaults to this
-	// machine's address on the route to the control plane, which is the one
-	// the control plane and the router can reach.
-	MgmtAddr string `koanf:"mgmt_addr"`
-	// Labels are free-form facts about a node for a profile's node_selector.
-	// Nothing needs them: memory, GPUs, engines and disk are measured, and a
-	// label restating one of those goes stale the day the machine changes.
-	Labels map[string]string `koanf:"labels"`
-
-	// MgmtInterface is the ethernet interface NCCL bootstraps over. It
-	// defaults to the interface holding MgmtAddr, then eth0.
-	MgmtInterface string `koanf:"mgmt_interface"`
-	// Fabrics labels this node's HCAs. It is explicit on purpose: OpenSM's
-	// default subnet prefix is the same on every fabric, so nothing can be
-	// inferred from the wire (plan §5.2).
-	Fabrics []inventory.FabricAttachment `koanf:"fabrics"`
-
-	HeartbeatInterval time.Duration `koanf:"heartbeat_interval"`
-	// ReconnectBase is the first reconnect delay; it backs off from there.
-	ReconnectBase time.Duration `koanf:"reconnect_base"`
-	ReconnectMax  time.Duration `koanf:"reconnect_max"`
-
-	// AdoptReadyTimeout bounds how long an adopted engine is given to answer a
-	// health check before the agent stops waiting on it.
-	//
-	// Shorter than a startup timeout on purpose: this engine is already
-	// running, so it is not loading a model, it is either serving or it is not.
-	AdoptReadyTimeout time.Duration `koanf:"adopt_ready_timeout"`
-
-	// TLS authenticates both ends of the control-plane stream. Leaving it unset
-	// keeps the plaintext behaviour, which only belongs on a trusted network.
-	TLS tlsconf.Config `koanf:"tls"`
-
-	// ModelDirs are the directories this node keeps model weights in, beyond
-	// WeightsCache, which is always looked in. Storage differs at every installation,
-	// so llmgw observes it rather than owning it: a Lustre mount, an image
-	// exported over the fabric, local NVMe and a copy made by hand all look
-	// identical from here, and placement only needs to know whether the file
-	// is present.
-	ModelDirs []string `koanf:"model_dirs"`
-
-	// EnginesDir is where the agent installs engines, one directory per
-	// build. Defaults to /opt/llmgw/engines.
-	EnginesDir string `koanf:"engines_dir"`
-
-	// WeightsCache is where a remote source is downloaded to. Defaults to the
-	// first entry of ModelDirs, because a node that says where its models live
-	// has already answered this question, and otherwise to
-	// /var/lib/llmgw-weights.
-	//
-	// Fetching is the simple arrangement: every node keeps its own copy. The
-	// exotic ones need no code — weights on a shared filer or an image exported
-	// over the fabric are simply present, and present means nothing is fetched.
-	WeightsCache string `koanf:"weights_cache"`
-
-	Discovery discovery.Options `koanf:"discovery"`
-	Engines   engines.Config    `koanf:"engines"`
-	Superv    supervisor.Config `koanf:"supervisor"`
-
-	Version string
-}
-
-// DefaultConfig returns sensible defaults.
-func DefaultConfig() Config {
-	return Config{
-		MgmtInterface:     "eth0",
-		HeartbeatInterval: 5 * time.Second,
-		ReconnectBase:     time.Second,
-		ReconnectMax:      30 * time.Second,
-		AdoptReadyTimeout: 60 * time.Second,
-		Superv:            supervisor.DefaultConfig(),
-		// NVML gives NVLink topology, so prefer it when this build has it.
-		Discovery: discovery.Options{PreferNVML: true},
-	}
-}
-
-func (c *Config) normalize() error {
-	d := DefaultConfig()
-	if err := c.TLS.Validate(); err != nil {
-		return err
-	}
-	if err := c.normalizeServerURL(); err != nil {
-		return err
-	}
-	// Everything below is found rather than written. A file that has to say
-	// which machine it is on, and at what address, is a file that differs on
-	// every node — and a copy taken from one node to the next registers the
-	// second as the first.
-	host, _ := os.Hostname()
-	if c.NodeID == "" {
-		c.NodeID = host
-	}
-	if c.NodeID == "" {
-		return errors.New("node_id is not set and the hostname could not be read")
-	}
-	if c.Hostname == "" {
-		c.Hostname = host
-	}
-	if c.MgmtAddr == "" {
-		c.MgmtAddr = addrToward(c.Server)
-	}
-	if c.MgmtInterface == "" {
-		c.MgmtInterface = interfaceOf(c.MgmtAddr)
-	}
-	if c.MgmtInterface == "" {
-		c.MgmtInterface = d.MgmtInterface
-	}
-	// The directory downloads land in is always one that is looked in. When
-	// they were two settings, a node could fill its disk with fetched weights
-	// that placement never saw — which is what every node here was doing.
-	if c.WeightsCache == "" && len(c.ModelDirs) > 0 {
-		c.WeightsCache = c.ModelDirs[0]
-	}
-	if c.WeightsCache == "" {
-		c.WeightsCache = DefaultWeightsCache
-	}
-	if !slices.Contains(c.ModelDirs, c.WeightsCache) {
-		c.ModelDirs = append(c.ModelDirs, c.WeightsCache)
-	}
-	if c.HeartbeatInterval <= 0 {
-		c.HeartbeatInterval = d.HeartbeatInterval
-	}
-	if c.ReconnectBase <= 0 {
-		c.ReconnectBase = d.ReconnectBase
-	}
-	if c.AdoptReadyTimeout <= 0 {
-		c.AdoptReadyTimeout = d.AdoptReadyTimeout
-	}
-	if c.ReconnectMax < c.ReconnectBase {
-		c.ReconnectMax = max(c.ReconnectBase, d.ReconnectMax)
-	}
-	return nil
-}
-
-// normalizeServerURL makes the configured address a URL connect can use, and
-// refuses the combination that would quietly undo the certificates: a scheme
-// that says plaintext while TLS is configured. Silently connecting anyway would
-// mean a cluster believing it has mutual authentication when it has none.
-func (c *Config) normalizeServerURL() error {
-	// One list, however it was written. Server first when both are given,
-	// because an operator adding a standby to an existing file expects the
-	// one already there to stay preferred.
-	all := make([]string, 0, 1+len(c.Servers))
-	if c.Server != "" {
-		all = append(all, c.Server)
-	}
-	all = append(all, c.Servers...)
-
-	seen := map[string]struct{}{}
-	out := make([]string, 0, len(all))
-	for _, s := range all {
-		fixed, err := normalizeOne(s, c.TLS.Enabled())
-		if err != nil {
-			return err
-		}
-		// A duplicate would be tried twice in a row on failover, which reads
-		// as the rotation not working.
-		if _, dup := seen[fixed]; dup {
-			continue
-		}
-		seen[fixed] = struct{}{}
-		out = append(out, fixed)
-	}
-	if len(out) == 0 {
-		return errors.New("server is required")
-	}
-	c.Servers = out
-	c.Server = out[0]
-	return nil
-}
-
-// DefaultWeightsCache is where fetched weights go when nothing says otherwise.
-const DefaultWeightsCache = "/var/lib/llmgw-weights"
-
-// addrToward is this machine's address on the route to the control plane.
-//
-// The address engines are reached on is whichever one the control plane can
-// reach, and the kernel already knows which that is: a UDP "connection" picks
-// the source address for the route without sending a packet. Asking the
-// interfaces instead would have to guess among docker bridges, VPNs and
-// link-local addresses.
-func addrToward(server string) string {
-	u, err := url.Parse(server)
-	if err != nil || u.Host == "" {
-		return ""
-	}
-	host := u.Hostname()
-	port := u.Port()
-	if port == "" {
-		port = "443"
-	}
-	conn, err := net.Dial("udp", net.JoinHostPort(host, port))
-	if err != nil {
-		return ""
-	}
-	defer conn.Close()
-	if a, ok := conn.LocalAddr().(*net.UDPAddr); ok {
-		return a.IP.String()
-	}
-	return ""
-}
-
-// interfaceOf names the interface that holds an address, or "" when none does.
-func interfaceOf(addr string) string {
-	ip := net.ParseIP(addr)
-	if ip == nil {
-		return ""
-	}
-	ifaces, err := net.Interfaces()
-	if err != nil {
-		return ""
-	}
-	for _, ifc := range ifaces {
-		addrs, err := ifc.Addrs()
-		if err != nil {
-			continue
-		}
-		for _, a := range addrs {
-			if n, ok := a.(*net.IPNet); ok && n.IP.Equal(ip) {
-				return ifc.Name
-			}
-		}
-	}
-	return ""
-}
-
-// normalizeOne applies the scheme rules to a single address.
-func normalizeOne(addr string, secure bool) (string, error) {
-	switch {
-	case strings.HasPrefix(addr, "https://"):
-		if !secure {
-			return "", fmt.Errorf("%s is an https:// address but no tls certificates are configured", addr)
-		}
-	case strings.HasPrefix(addr, "http://"):
-		if secure {
-			return "", fmt.Errorf("tls is configured but %s is an http:// address; use https://", addr)
-		}
-	case strings.Contains(addr, "://"):
-		return "", fmt.Errorf("server %q must be an http:// or https:// address", addr)
-	case secure:
-		return "https://" + addr, nil
-	default:
-		return "http://" + addr, nil
-	}
-	return addr, nil
-}
-
 // Agent runs on a GPU node.
 type Agent struct {
 	cfg  Config
@@ -352,6 +85,22 @@ type Agent struct {
 	// failover the old stream's heartbeat loop can still be running when the
 	// new one's starts.
 	lastWeights string
+	// fabricsSent is what the control plane was last told about fabrics.
+	fabricsSent string
+	// sm caches which subnet manager each InfiniBand port sees, asked once
+	// a minute: a management datagram per port per heartbeat is more than
+	// an answer that changes on a failover is worth.
+	sm      map[string]*discovery.SMInfo
+	smErr   map[string]string
+	smAsked time.Time
+	// nvlAsked is when the GPUs' NVLink fabric state was last read.
+	nvlAsked time.Time
+	// sms is every subnet manager on a fabric, asked through one port per
+	// master, keyed by that port; smsErr says why a port could not ask.
+	sms    map[string][]discovery.SMRecord
+	smsErr map[string]string
+	// load measures the machine between heartbeats.
+	load *discovery.LoadSampler
 
 	// fetchWatchers are the shards waiting on each source, so progress on one
 	// download reaches every shard that asked for it. A fetch is single-flight
@@ -396,6 +145,7 @@ func New(cfg Config, httpClient connectHTTPClient, log *slog.Logger) (*Agent, er
 		provStatus:   map[string]provision.Status{},
 		logRing:      ring,
 		provKick:     make(chan struct{}, 1),
+		load:         discovery.NewLoadSampler(),
 	}
 	a.prov = &provision.Installer{Root: cfg.EnginesDir, Log: log, OnStatus: a.provisionStatus}
 	return a, nil
@@ -423,6 +173,7 @@ func (a *Agent) Run(ctx context.Context) error {
 		a.log.Warn("cannot create the weights directory", "dir", a.cfg.WeightsCache, "err", err)
 	}
 	go a.provisionLoop(ctx)
+	go a.ensureDiags(ctx)
 
 	attempt := 0
 	next := 0
@@ -563,38 +314,6 @@ func (a *Agent) settleAdopted(sh *supervisor.Shard, o supervisor.Orphan) {
 		"shard", o.ShardID, "replica", o.ReplicaID)
 }
 
-// usableFabrics reports the fabrics this node can actually carry traffic on.
-//
-// Loud about what it drops. A fabric silently missing from a registration looks
-// identical to one never configured, and the operator who typed the adapter
-// name is the only person who can fix it — so the reason is logged here, on the
-// machine where both halves are visible, rather than inferred later from a
-// replica that will not converge.
-func (a *Agent) usableFabrics(inv discovery.Inventory) []inventory.FabricAttachment {
-	declared := map[string][]string{}
-	for _, f := range a.cfg.Fabrics {
-		declared[f.Fabric] = f.HCAs
-	}
-
-	var out []inventory.FabricAttachment
-	for _, c := range discovery.CheckFabrics(declared, inv.HCAs) {
-		for _, p := range c.Problems {
-			a.log.Error("a declared fabric adapter cannot carry traffic",
-				"fabric", c.Fabric, "problem", p)
-		}
-		if !c.OK() {
-			a.log.Error("fabric not advertised; no declared adapter on it can carry traffic",
-				"fabric", c.Fabric,
-				"consequence", "no multi-node replica will be placed here")
-			continue
-		}
-		out = append(out, inventory.FabricAttachment{
-			Fabric: c.Fabric, HCAs: c.Usable, RateGbps: c.RateGbps,
-		})
-	}
-	return out
-}
-
 // weights builds the fetcher lazily, so an agent that never starts a shard
 // never needs a cache directory.
 func (a *Agent) weights() *weights.Fetcher {
@@ -682,6 +401,7 @@ func (a *Agent) scan(ctx context.Context) error {
 	opts.ModelDirs = a.cfg.ModelDirs
 	inv, err := discovery.Discover(ctx, opts, a.log)
 	host := discovery.DiscoverHost()
+	host.MinComputeCapability = discovery.MinComputeCapability(inv.GPUs)
 	a.mu.Lock()
 	a.inv = inv
 	a.prov.Host = host
@@ -726,6 +446,8 @@ func (a *Agent) session(ctx context.Context, server string) error {
 	// vLLM accepted a vLLM shard and failed it minutes later.
 	reg.EngineVersions = a.engines(parent)
 	reg.EnginesProbed = true
+	reg.InstallableEngines = provision.Installable()
+	reg.Features = []string{FeatureFabricTest}
 	reg.RunningShards = a.runningShards()
 	a.mu.Lock()
 	h := a.prov.Host
@@ -828,6 +550,7 @@ func (a *Agent) heartbeat() *llmgwv1.AgentMessage {
 	// and a node that grew from 7 GB to 32 GB has to be seen to have grown
 	// without anybody restarting anything.
 	hb.MemoryTotalMb = int64(discovery.MemoryTotalMB())
+	hb.CpuCount = int32(runtime.NumCPU())
 
 	a.reprobeEngines()
 	a.mu.Lock()
@@ -883,9 +606,41 @@ func (a *Agent) heartbeat() *llmgwv1.AgentMessage {
 			})
 		}
 	}
+	hb.Load = a.sampleLoad()
+	a.sampleIB(hb)
+	a.sampleNVLink(hb)
 	return &llmgwv1.AgentMessage{Msg: &llmgwv1.AgentMessage_Heartbeat{Heartbeat: hb}}
 }
 
+// sampleLoad measures the machine and each running engine since the last
+// heartbeat. Nil on the first, which has nothing to compare with.
+func (a *Agent) sampleLoad() *llmgwv1.NodeLoad {
+	if a.load == nil {
+		return nil
+	}
+	pids := map[string]int{}
+	for _, st := range a.sup.Statuses() {
+		if st.PID > 0 {
+			pids[st.ID] = st.PID
+		}
+	}
+	l, ok := a.load.Sample(pids)
+	if !ok {
+		return nil
+	}
+	out := &llmgwv1.NodeLoad{
+		CpuPercent: l.CPUPercent, CpuCount: int32(l.CPUCount),
+		Load1: l.Load1, Load5: l.Load5, Load15: l.Load15,
+		MemoryUsedBytes: l.MemUsed, MemoryAvailableBytes: l.MemAvail,
+	}
+	for _, sh := range l.Shards {
+		out.Shards = append(out.Shards, &llmgwv1.ShardLoad{
+			ShardId: sh.ID, CpuCores: sh.CPUCores, MemoryRssBytes: sh.RSSBytes,
+		})
+	}
+	return out
+}
+
 // weightsFingerprint is enough to notice a model appearing, disappearing or
 // finishing its download.
 //
@@ -968,6 +723,8 @@ func (a *Agent) handle(ctx context.Context, msg *llmgwv1.ControlMessage, out cha
 		a.removeWeights(m.RemoveWeights.GetPaths())
 	case *llmgwv1.ControlMessage_Provision:
 		a.setProvision(m.Provision)
+	case *llmgwv1.ControlMessage_Upgrade:
+		go a.upgrade(ctx, m.Upgrade, out)
 	case *llmgwv1.ControlMessage_Logs:
 		reply := a.logsReply(m.Logs)
 		// Off the receive loop: a full send queue must not stop commands being
@@ -978,6 +735,33 @@ func (a *Agent) handle(ctx context.Context, msg *llmgwv1.ControlMessage, out cha
 			case <-ctx.Done():
 			}
 		}()
+	case *llmgwv1.ControlMessage_FabricScan:
+		// A scan takes seconds to minutes: off the receive loop entirely.
+		go func(req *llmgwv1.FabricScanRequest) {
+			start := time.Now()
+			reply := &llmgwv1.FabricScanReply{RequestId: req.GetRequestId()}
+			text, err := scanFabric(ctx, req.GetHca(), int(req.GetPort()))
+			if err != nil {
+				reply.Error = err.Error()
+			} else {
+				reply.Output = text
+			}
+			reply.TookMs = time.Since(start).Milliseconds()
+			select {
+			case out <- &llmgwv1.AgentMessage{Msg: &llmgwv1.AgentMessage_FabricScan{FabricScan: reply}}:
+			case <-ctx.Done():
+			}
+		}(m.FabricScan)
+	case *llmgwv1.ControlMessage_FabricTest:
+		// Seconds of traffic, and a package install the first time: off the
+		// receive loop too.
+		go func(req *llmgwv1.FabricTestRequest) {
+			reply := a.fabricTest(ctx, req)
+			select {
+			case out <- &llmgwv1.AgentMessage{Msg: &llmgwv1.AgentMessage_FabricTest{FabricTest: reply}}:
+			case <-ctx.Done():
+			}
+		}(m.FabricTest)
 	case *llmgwv1.ControlMessage_Ack:
 		if !m.Ack.GetOk() {
 			a.log.Warn("control plane rejected a message",
@@ -1047,6 +831,7 @@ func (a *Agent) startShard(ctx context.Context, m *llmgwv1.StartShard, out chan<
 	}
 
 	spec, timeout := agentsvc.ShardSpecFromStart(m)
+	a.localizeSpec(&spec)
 
 	eng, err := a.reg.Get(spec.Profile.Engine)
 	if err != nil {
@@ -1231,211 +1016,53 @@ func Client(cfg tlsconf.Config, timeout time.Duration) (*http.Client, error) {
 	return &http.Client{Transport: &http2.Transport{TLSClientConfig: tc}}, nil
 }
 
-// engines is what this node can run: what the agent installed and saw run,
-// and what the configuration names and answers. Nothing merely found on the
-// machine — a llama-server on PATH is somebody's, not necessarily one that
-// works, and placing on it is how a replica fails on a node nobody watches.
-func (a *Agent) engines(ctx context.Context) map[string]string {
-	a.engineOnce.Do(func() {
-		vers := a.reg.ProbeConfigured(ctx)
-		a.mu.Lock()
-		a.configuredVers, a.lastEngineProbe = vers, time.Now()
-		a.mu.Unlock()
-		if len(vers) > 0 {
-			a.log.Info("engines named in the configuration",
-				"engines", engines.ProbedNames(vers))
-		}
-	})
-	a.mu.Lock()
-	defer a.mu.Unlock()
-	vers := a.engineReportLocked()
-	// Whatever registration sends is what the control plane now knows, so a
-	// heartbeat repeats it only once it differs.
-	a.enginesSent = enginesFingerprint(vers)
-	return vers
-}
-
-// engineReportLocked merges the two sources. Installed wins: it is the one
-// that was seen to run. Called with mu held.
-func (a *Agent) engineReportLocked() map[string]string {
-	out := maps.Clone(a.configuredVers)
-	if out == nil {
-		out = map[string]string{}
-	}
-	maps.Copy(out, a.installedVers)
-	return out
-}
-
-// provisionEvery is how often installed engines are checked again. A library
-// removed by an unrelated upgrade is found here rather than by the next
-// replica to start.
-const provisionEvery = 10 * time.Minute
-
-// setProvision takes the control plane's list of wanted engines.
-func (a *Agent) setProvision(p *llmgwv1.Provision) {
-	wants := []provision.Want{}
-	for _, e := range p.GetEngines() {
-		wants = append(wants, provision.Want{Engine: e.GetEngine(), Version: e.GetVersion()})
-	}
-	a.mu.Lock()
-	a.provWants = wants
-	a.mu.Unlock()
-	select {
-	case a.provKick <- struct{}{}:
-	default:
-	}
-}
-
-// provisionLoop installs and re-checks the wanted engines, one pass at a time.
-func (a *Agent) provisionLoop(ctx context.Context) {
-	// After a failure the next pass comes sooner, and backs off: a lock held
-	// by a new machine's own updates clears in a minute or two, while ten
-	// minutes' wait left a node idle for no reason.
-	next := provisionEvery
-	retry := time.Minute
-	for {
-		select {
-		case <-ctx.Done():
-			return
-		case <-a.provKick:
-		case <-time.After(next):
-		}
-		a.mu.Lock()
-		wants := slices.Clone(a.provWants)
-		managed := a.provWants != nil
-		a.mu.Unlock()
-		if !managed {
-			continue
-		}
-
-		statuses := a.prov.Converge(ctx, wants)
-		next = provisionEvery
-		for _, st := range statuses {
-			if st.State == provision.Failed {
-				next, retry = retry, min(retry*2, provisionEvery)
-				break
-			}
-		}
-		if next == provisionEvery {
-			retry = time.Minute
-		}
-		installed := map[string]string{}
-		keep := map[string]bool{}
-		for _, st := range statuses {
-			keep[st.Engine] = true
-			if st.State == provision.Ready {
-				a.reg.UseInstalled(st.Engine, st.Binary)
-				installed[st.Engine] = st.Version
-			}
-		}
-		a.mu.Lock()
-		if enginesFingerprint(installed) != enginesFingerprint(a.installedVers) {
-			a.log.Info("engines installed and running", "engines", engines.ProbedNames(installed))
-		}
-		a.installedVers = installed
-		// An engine no longer asked for is no longer reported on.
-		for e := range a.provStatus {
-			if !keep[e] {
-				delete(a.provStatus, e)
-			}
-		}
-		a.mu.Unlock()
-	}
-}
-
-// provisionStatus records a change in one engine's installation.
-func (a *Agent) provisionStatus(st provision.Status) {
-	a.mu.Lock()
-	prev, had := a.provStatus[st.Engine]
-	a.provStatus[st.Engine] = st
-	a.mu.Unlock()
-	if !had || prev.State != st.State || prev.Detail != st.Detail {
-		lvl := slog.LevelInfo
-		if st.State == provision.Failed || st.State == provision.Unsupported {
-			lvl = slog.LevelWarn
-		}
-		a.log.Log(context.Background(), lvl, "engine installation",
-			"engine", st.Engine, "version", st.Version, "variant", st.Variant,
-			"state", st.State, "detail", st.Detail)
-	}
-}
-
-func provisionFingerprint(m map[string]provision.Status) string {
-	var b strings.Builder
-	for _, k := range slices.Sorted(maps.Keys(m)) {
-		st := m[k]
-		fmt.Fprintf(&b, "%s|%s|%s|%s|%s\n", st.Engine, st.Version, st.Variant, st.State, st.Detail)
-	}
-	return b.String()
-}
-
-// engineReprobe is how often the installed engines are looked for again.
+// localizeSpec fills in what only this node knows.
 //
-// Minutes, not seconds: an engine is installed by somebody at a keyboard, so a
-// minute's delay in noticing is invisible, while SGLang's probe starts a
-// Python interpreter that imports it.
-const engineReprobe = time.Minute
-
-// reprobeEngines looks for installed engines again when it is time, off the
-// heartbeat goroutine so a slow probe never delays a heartbeat.
-func (a *Agent) reprobeEngines() {
-	a.mu.Lock()
-	due := !a.probingEngines && !a.lastEngineProbe.IsZero() &&
-		time.Since(a.lastEngineProbe) >= engineReprobe
-	if due {
-		a.probingEngines = true
+// The interface NCCL bootstraps over is this node's, not the cluster's: the
+// control plane sends one name for every node, and a node whose management
+// network is on ens3 rather than eth0 would have NCCL bind nothing. And on
+// RoCE, which GID entry routes is a property of these adapters.
+func (a *Agent) localizeSpec(spec *engines.ShardSpec) {
+	if a.cfg.MgmtInterface != "" {
+		spec.MgmtInterface = a.cfg.MgmtInterface
 	}
-	a.mu.Unlock()
-	if !due {
+	if len(spec.HCAs) == 0 {
 		return
 	}
-	go func() {
-		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-		defer cancel()
-		vers := a.reg.ProbeConfigured(ctx)
-
-		a.mu.Lock()
-		changed := enginesFingerprint(vers) != enginesFingerprint(a.configuredVers)
-		a.configuredVers, a.lastEngineProbe, a.probingEngines = vers, time.Now(), false
-		a.mu.Unlock()
-		if changed {
-			a.log.Info("engines named in the configuration changed",
-				"engines", engines.ProbedNames(vers))
+	a.mu.Lock()
+	hcas := a.inv.HCAs
+	a.mu.Unlock()
+	want := map[string]bool{}
+	for _, h := range spec.HCAs {
+		want[h] = true
+	}
+	for _, h := range hcas {
+		if !want[h.Name] {
+			continue
 		}
-	}()
-}
-
-func enginesFingerprint(vers map[string]string) string {
-	var b strings.Builder
-	for _, k := range slices.Sorted(maps.Keys(vers)) {
-		fmt.Fprintf(&b, "%s=%s\n", k, vers[k])
-	}
-	return b.String()
-}
-
-// logsReply answers a request for one of this node's logs.
-func (a *Agent) logsReply(req *llmgwv1.LogsRequest) *llmgwv1.LogsReply {
-	n := int(req.GetLines())
-	if n <= 0 {
-		n = 200
-	}
-	n = min(n, agentLogLines)
-	shards := a.sup.IDs()
-	slices.Sort(shards)
-	out := &llmgwv1.LogsReply{
-		RequestId: req.GetRequestId(),
-		Sources:   append([]string{"agent"}, shards...),
-	}
-	switch src := req.GetSource(); src {
-	case "", "agent":
-		out.Lines = a.logRing.tail(n)
-	default:
-		sh, err := a.sup.Get(src)
-		if err != nil {
-			out.Error = "no engine " + src + " runs on this node"
-			return out
+		for _, p := range h.Ports {
+			if p.Active() && p.RoCEv2GID >= 0 {
+				idx := p.RoCEv2GID
+				spec.GIDIndex = &idx
+				return
+			}
 		}
-		out.Lines = sh.Logs(n)
 	}
-	return out
+}
+
+// ResolveManagement is the address and interface this node's agent would use,
+// found the way normalize finds them, for a tool that reports them.
+func ResolveManagement(c Config) (addr, iface string) {
+	addr, iface = c.MgmtAddr, c.MgmtInterface
+	server := c.Server
+	if server == "" && len(c.Servers) > 0 {
+		server = c.Servers[0]
+	}
+	if addr == "" {
+		addr = addrToward(server)
+	}
+	if iface == "" {
+		iface = interfaceOf(addr)
+	}
+	return addr, iface
 }

internal/agent/agent_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"crypto/tls"
 	"errors"
+	"fmt"
 	"log/slog"
 	"net"
 	"net/http"
@@ -22,6 +23,8 @@ import (
 	"golang.org/x/net/http2"
 	"golang.org/x/net/http2/h2c"
 
+	llmgwv1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/discovery"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/engines"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/supervisor"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/control/agentsvc"
@@ -397,11 +400,16 @@ func TestHeartbeatKeepsNodeAlive(t *testing.T) {
 	n, _ := h.inv.Get("n1")
 	first := n.LastSeen
 
-	time.Sleep(200 * time.Millisecond)
-	n, _ = h.inv.Get("n1")
-	if !n.LastSeen.After(first) {
-		t.Error("heartbeats are not refreshing LastSeen; the node would be declared lost")
+	// Waited for rather than slept through: four heartbeat intervals was not
+	// always enough on a loaded runner for one to have landed.
+	deadline := time.Now().Add(3 * time.Second)
+	for time.Now().Before(deadline) {
+		if n, _ = h.inv.Get("n1"); n.LastSeen.After(first) {
+			return
+		}
+		time.Sleep(20 * time.Millisecond)
 	}
+	t.Error("heartbeats are not refreshing LastSeen; the node would be declared lost")
 }
 
 func TestStartAndStopShardEndToEnd(t *testing.T) {
@@ -756,3 +764,157 @@ func TestAFabricRateIsTheSlowestActiveLink(t *testing.T) {
 		}
 	}
 }
+
+func TestAPortGoingDownIsToldToTheControlPlaneOnce(t *testing.T) {
+	// Checked only at registration, a port going down went unnoticed until
+	// the agent restarted, and the node went on being offered multi-node
+	// work that would hang on its first collective.
+	root := ibTreeWithActivePorts(t, "mlx5_0")
+	h := start(t, func(c *Config) {
+		c.Discovery.IBRoot = root
+		c.Fabrics = []inventory.FabricAttachment{{Fabric: "ib-a", HCAs: []string{"mlx5_0"}}}
+	})
+	if n, _ := h.inv.Get("n1"); !n.HasFabric("ib-a") {
+		t.Fatalf("the fabric should be advertised at registration: %+v", n.Fabrics)
+	}
+
+	hb := h.ag.heartbeat().GetHeartbeat()
+	if hb.GetFabricsChanged() || len(hb.GetIbPorts()) != 1 || hb.GetIbPorts()[0].GetState() != "ACTIVE" {
+		t.Fatalf("a quiet heartbeat should carry the port and no change: %+v", hb)
+	}
+
+	if err := os.WriteFile(filepath.Join(root, "mlx5_0", "ports", "1", "state"), []byte("1: DOWN\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	hb = h.ag.heartbeat().GetHeartbeat()
+	if !hb.GetFabricsChanged() || len(hb.GetFabrics()) != 0 {
+		t.Errorf("the port going down should withdraw the fabric: changed=%v fabrics=%v",
+			hb.GetFabricsChanged(), hb.GetFabrics())
+	}
+	if hb = h.ag.heartbeat().GetHeartbeat(); hb.GetFabricsChanged() {
+		t.Error("the change should be sent once, not on every heartbeat")
+	}
+}
+
+func TestAShardUsesThisNodesInterfaceAndRoCEIndex(t *testing.T) {
+	// The control plane sends one interface name for every node; a node whose
+	// management network is on another had NCCL bind nothing. And which RoCE
+	// GID entry routes is a property of this node's adapters.
+	a := &Agent{cfg: Config{MgmtInterface: "ens3"}}
+	a.inv.HCAs = []discovery.HCA{{Name: "mlx5_0", Ports: []discovery.Port{
+		{Num: 1, State: "ACTIVE", LinkLayer: discovery.LinkEthernet, RoCEv2GID: 3}}}}
+	spec := engines.ShardSpec{MgmtInterface: "eth0", HCAs: []string{"mlx5_0"}}
+	a.localizeSpec(&spec)
+	if spec.MgmtInterface != "ens3" {
+		t.Errorf("interface = %q", spec.MgmtInterface)
+	}
+	if spec.GIDIndex == nil || *spec.GIDIndex != 3 {
+		t.Errorf("GID index = %v", spec.GIDIndex)
+	}
+
+	ib := engines.ShardSpec{HCAs: []string{"mlx5_1"}}
+	a.inv.HCAs = append(a.inv.HCAs, discovery.HCA{Name: "mlx5_1", Ports: []discovery.Port{
+		{Num: 1, State: "ACTIVE", LinkLayer: discovery.LinkInfiniBand, RoCEv2GID: -1}}})
+	a.localizeSpec(&ib)
+	if ib.GIDIndex != nil {
+		t.Error("an InfiniBand shard was given a GID index")
+	}
+}
+
+func TestTheManagementInterfaceIsFoundNotAssumed(t *testing.T) {
+	// It was defaulted to eth0 before it could be looked for, so it never
+	// was: a node on ens3 or bond0 had NCCL bootstrap over nothing.
+	cfg := DefaultConfig()
+	cfg.Server = "http://127.0.0.1:7443"
+	cfg.NodeID = "n1"
+	cfg.MgmtAddr = "127.0.0.1"
+	if err := cfg.normalize(); err != nil {
+		t.Fatal(err)
+	}
+	if cfg.MgmtInterface == "" || cfg.MgmtInterface == "eth0" {
+		t.Errorf("interface = %q, want the loopback interface holding 127.0.0.1", cfg.MgmtInterface)
+	}
+}
+
+func TestEachFabricsSubnetManagersAreAskedOnce(t *testing.T) {
+	// Two adapters on one fabric see one master. Its managers are listed
+	// through one of them — the same list twice is a query too many — and
+	// every port says which master it sees.
+	oldSM, oldSMs := querySM, querySMs
+	t.Cleanup(func() { querySM, querySMs = oldSM, oldSMs })
+	querySM = func(string, int) (*discovery.SMInfo, error) {
+		return &discovery.SMInfo{GUID: "0x01", LID: 1, State: "SMINFO_MASTER"}, nil
+	}
+	lists := 0
+	querySMs = func(string, int) ([]discovery.SMRecord, error) {
+		lists++
+		return []discovery.SMRecord{{GUID: "0x01", State: "master"}, {GUID: "0x02", State: "standby"}}, nil
+	}
+	h := start(t, func(c *Config) {
+		c.Discovery.IBRoot = ibTreeWithActivePorts(t, "mlx5_0", "mlx5_1")
+		c.Fabrics = []inventory.FabricAttachment{{Fabric: "ib-a", HCAs: []string{"mlx5_0", "mlx5_1"}}}
+	})
+	hb := h.ag.heartbeat().GetHeartbeat()
+	withList := 0
+	for _, p := range hb.GetIbPorts() {
+		if p.GetSmGuid() != "0x01" {
+			t.Errorf("%s sees master %q", p.GetHca(), p.GetSmGuid())
+		}
+		if len(p.GetSubnetManagers()) > 0 {
+			withList++
+		}
+	}
+	if lists != 1 || withList != 1 {
+		t.Errorf("listed %d times, carried on %d ports; want once, on one", lists, withList)
+	}
+}
+
+func TestAFabricScanIsAskedForAndAnswered(t *testing.T) {
+	// One node per fabric maps it; the control plane asks and parses.
+	old := scanFabric
+	t.Cleanup(func() { scanFabric = old })
+	var asked string
+	scanFabric = func(_ context.Context, hca string, port int) (string, error) {
+		asked = fmt.Sprintf("%s/%d", hca, port)
+		return "Switch\t36 \"S-00000000000000a1\"\t\t# \"MF0;leaf-a:QM8700/U1\" enhanced port 0 lid 1 lmc 0\n", nil
+	}
+	h := start(t)
+	r, err := h.svc.ScanFabric(t.Context(), "n1", "mlx5_0", 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if asked != "mlx5_0/1" || !strings.Contains(r.GetOutput(), "leaf-a") || r.GetError() != "" {
+		t.Errorf("asked %q, got %+v", asked, r)
+	}
+}
+
+func TestABandwidthTestIsRunOnTheAdapterAskedFor(t *testing.T) {
+	oldRun, oldHave := runWriteBW, haveWriteBW
+	t.Cleanup(func() { runWriteBW, haveWriteBW = oldRun, oldHave })
+	haveWriteBW = func() bool { return true }
+	var got discovery.WriteBW
+	runWriteBW = func(_ context.Context, w discovery.WriteBW) (float64, string, error) {
+		got = w
+		return 388.2, " #bytes  #iterations  BW peak[Gb/sec]  BW average[Gb/sec]\n", nil
+	}
+	h := start(t, func(c *Config) { c.Discovery.IBRoot = ibTreeWithActivePorts(t, "mlx5_0") })
+
+	r, err := h.svc.FabricTest(t.Context(), "n1", &llmgwv1.FabricTestRequest{
+		Role: "client", Hca: "mlx5_0", Port: 1, Peer: "10.0.0.2", TcpPort: 18515, Seconds: 3})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if r.GetGbps() != 388.2 || r.GetError() != "" {
+		t.Errorf("reply %+v", r)
+	}
+	if got.HCA != "mlx5_0" || got.Peer != "10.0.0.2" || got.TCPPort != 18515 || got.GIDIndex != -1 {
+		t.Errorf("ran %+v", got)
+	}
+
+	// An adapter the node does not have is said so, without running anything.
+	got = discovery.WriteBW{}
+	r, _ = h.svc.FabricTest(t.Context(), "n1", &llmgwv1.FabricTestRequest{Role: "server", Hca: "mlx5_9", Port: 1, Seconds: 1})
+	if !strings.Contains(r.GetError(), "no port mlx5_9/1") || got.HCA != "" {
+		t.Errorf("reply %+v, ran %+v", r, got)
+	}
+}

internal/agent/config.go

@@ -0,0 +1,286 @@
+package agent
+
+import (
+	"errors"
+	"fmt"
+	"net"
+	"net/url"
+	"os"
+	"slices"
+	"strings"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/discovery"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/engines"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/supervisor"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/inventory"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/tlsconf"
+)
+
+// Config configures the agent.
+type Config struct {
+	// NodeID defaults to the hostname. It must equal the common name of the
+	// agent's certificate, so set it only where the two differ.
+	NodeID string `koanf:"node_id"`
+	// Server is the control plane, and Servers is the same thing when there is
+	// more than one. Both are accepted: every configuration written before
+	// there could be a second control plane names one address, and none of
+	// them should have to change.
+	//
+	// The order is tried in order, and a refusal moves to the next. Only the
+	// leader accepts an agent, so a standby is skipped in the time it takes to
+	// be told so — which is what makes failover a reconnect rather than an
+	// edit to every node's configuration.
+	Server  string   `koanf:"server"`
+	Servers []string `koanf:"servers"`
+	// Hostname defaults to the machine's.
+	Hostname string `koanf:"hostname"`
+	// MgmtAddr is the address engines are reached on. It defaults to this
+	// machine's address on the route to the control plane, which is the one
+	// the control plane and the router can reach.
+	MgmtAddr string `koanf:"mgmt_addr"`
+	// Labels are free-form facts about a node for a profile's node_selector.
+	// Nothing needs them: memory, GPUs, engines and disk are measured, and a
+	// label restating one of those goes stale the day the machine changes.
+	Labels map[string]string `koanf:"labels"`
+
+	// MgmtInterface is the ethernet interface NCCL bootstraps over. It
+	// defaults to the interface holding MgmtAddr, then eth0.
+	MgmtInterface string `koanf:"mgmt_interface"`
+	// Fabrics labels this node's HCAs. It is explicit on purpose: OpenSM's
+	// default subnet prefix is the same on every fabric, so nothing can be
+	// inferred from the wire (plan §5.2).
+	Fabrics []inventory.FabricAttachment `koanf:"fabrics"`
+
+	HeartbeatInterval time.Duration `koanf:"heartbeat_interval"`
+	// ReconnectBase is the first reconnect delay; it backs off from there.
+	ReconnectBase time.Duration `koanf:"reconnect_base"`
+	ReconnectMax  time.Duration `koanf:"reconnect_max"`
+
+	// AdoptReadyTimeout bounds how long an adopted engine is given to answer a
+	// health check before the agent stops waiting on it.
+	//
+	// Shorter than a startup timeout on purpose: this engine is already
+	// running, so it is not loading a model, it is either serving or it is not.
+	AdoptReadyTimeout time.Duration `koanf:"adopt_ready_timeout"`
+
+	// TLS authenticates both ends of the control-plane stream. Leaving it unset
+	// keeps the plaintext behaviour, which only belongs on a trusted network.
+	TLS tlsconf.Config `koanf:"tls"`
+
+	// ModelDirs are the directories this node keeps model weights in, beyond
+	// WeightsCache, which is always looked in. Storage differs at every installation,
+	// so llmgw observes it rather than owning it: a Lustre mount, an image
+	// exported over the fabric, local NVMe and a copy made by hand all look
+	// identical from here, and placement only needs to know whether the file
+	// is present.
+	ModelDirs []string `koanf:"model_dirs"`
+
+	// EnginesDir is where the agent installs engines, one directory per
+	// build. Defaults to /opt/llmgw/engines.
+	EnginesDir string `koanf:"engines_dir"`
+
+	// WeightsCache is where a remote source is downloaded to. Defaults to the
+	// first entry of ModelDirs, because a node that says where its models live
+	// has already answered this question, and otherwise to
+	// /var/lib/llmgw-weights.
+	//
+	// Fetching is the simple arrangement: every node keeps its own copy. The
+	// exotic ones need no code — weights on a shared filer or an image exported
+	// over the fabric are simply present, and present means nothing is fetched.
+	WeightsCache string `koanf:"weights_cache"`
+
+	Discovery discovery.Options `koanf:"discovery"`
+	Engines   engines.Config    `koanf:"engines"`
+	Superv    supervisor.Config `koanf:"supervisor"`
+
+	Version string
+}
+
+// DefaultConfig returns sensible defaults.
+func DefaultConfig() Config {
+	// No MgmtInterface: normalize finds the one holding the management
+	// address, and falls back to eth0 only when it cannot. Defaulted here, it
+	// was never found — every node said eth0 unless told otherwise, and a node
+	// on ens3 or bond0 had NCCL bootstrap over an interface it does not have.
+	return Config{
+		HeartbeatInterval: 5 * time.Second,
+		ReconnectBase:     time.Second,
+		ReconnectMax:      30 * time.Second,
+		AdoptReadyTimeout: 60 * time.Second,
+		Superv:            supervisor.DefaultConfig(),
+		// NVML gives NVLink topology, so prefer it when this build has it.
+		Discovery: discovery.Options{PreferNVML: true},
+	}
+}
+
+func (c *Config) normalize() error {
+	d := DefaultConfig()
+	if err := c.TLS.Validate(); err != nil {
+		return err
+	}
+	if err := c.normalizeServerURL(); err != nil {
+		return err
+	}
+	// Everything below is found rather than written. A file that has to say
+	// which machine it is on, and at what address, is a file that differs on
+	// every node — and a copy taken from one node to the next registers the
+	// second as the first.
+	host, _ := os.Hostname()
+	if c.NodeID == "" {
+		c.NodeID = host
+	}
+	if c.NodeID == "" {
+		return errors.New("node_id is not set and the hostname could not be read")
+	}
+	if c.Hostname == "" {
+		c.Hostname = host
+	}
+	if c.MgmtAddr == "" {
+		c.MgmtAddr = addrToward(c.Server)
+	}
+	if c.MgmtInterface == "" {
+		c.MgmtInterface = interfaceOf(c.MgmtAddr)
+	}
+	if c.MgmtInterface == "" {
+		c.MgmtInterface = "eth0"
+	}
+	// The directory downloads land in is always one that is looked in. When
+	// they were two settings, a node could fill its disk with fetched weights
+	// that placement never saw — which is what every node here was doing.
+	if c.WeightsCache == "" && len(c.ModelDirs) > 0 {
+		c.WeightsCache = c.ModelDirs[0]
+	}
+	if c.WeightsCache == "" {
+		c.WeightsCache = DefaultWeightsCache
+	}
+	if !slices.Contains(c.ModelDirs, c.WeightsCache) {
+		c.ModelDirs = append(c.ModelDirs, c.WeightsCache)
+	}
+	if c.HeartbeatInterval <= 0 {
+		c.HeartbeatInterval = d.HeartbeatInterval
+	}
+	if c.ReconnectBase <= 0 {
+		c.ReconnectBase = d.ReconnectBase
+	}
+	if c.AdoptReadyTimeout <= 0 {
+		c.AdoptReadyTimeout = d.AdoptReadyTimeout
+	}
+	if c.ReconnectMax < c.ReconnectBase {
+		c.ReconnectMax = max(c.ReconnectBase, d.ReconnectMax)
+	}
+	return nil
+}
+
+// normalizeServerURL makes the configured address a URL connect can use, and
+// refuses the combination that would quietly undo the certificates: a scheme
+// that says plaintext while TLS is configured. Silently connecting anyway would
+// mean a cluster believing it has mutual authentication when it has none.
+func (c *Config) normalizeServerURL() error {
+	// One list, however it was written. Server first when both are given,
+	// because an operator adding a standby to an existing file expects the
+	// one already there to stay preferred.
+	all := make([]string, 0, 1+len(c.Servers))
+	if c.Server != "" {
+		all = append(all, c.Server)
+	}
+	all = append(all, c.Servers...)
+
+	seen := map[string]struct{}{}
+	out := make([]string, 0, len(all))
+	for _, s := range all {
+		fixed, err := normalizeOne(s, c.TLS.Enabled())
+		if err != nil {
+			return err
+		}
+		// A duplicate would be tried twice in a row on failover, which reads
+		// as the rotation not working.
+		if _, dup := seen[fixed]; dup {
+			continue
+		}
+		seen[fixed] = struct{}{}
+		out = append(out, fixed)
+	}
+	if len(out) == 0 {
+		return errors.New("server is required")
+	}
+	c.Servers = out
+	c.Server = out[0]
+	return nil
+}
+
+// DefaultWeightsCache is where fetched weights go when nothing says otherwise.
+const DefaultWeightsCache = "/var/lib/llmgw-weights"
+
+// addrToward is this machine's address on the route to the control plane.
+//
+// The address engines are reached on is whichever one the control plane can
+// reach, and the kernel already knows which that is: a UDP "connection" picks
+// the source address for the route without sending a packet. Asking the
+// interfaces instead would have to guess among docker bridges, VPNs and
+// link-local addresses.
+func addrToward(server string) string {
+	u, err := url.Parse(server)
+	if err != nil || u.Host == "" {
+		return ""
+	}
+	host := u.Hostname()
+	port := u.Port()
+	if port == "" {
+		port = "443"
+	}
+	conn, err := net.Dial("udp", net.JoinHostPort(host, port))
+	if err != nil {
+		return ""
+	}
+	defer conn.Close()
+	if a, ok := conn.LocalAddr().(*net.UDPAddr); ok {
+		return a.IP.String()
+	}
+	return ""
+}
+
+// interfaceOf names the interface that holds an address, or "" when none does.
+func interfaceOf(addr string) string {
+	ip := net.ParseIP(addr)
+	if ip == nil {
+		return ""
+	}
+	ifaces, err := net.Interfaces()
+	if err != nil {
+		return ""
+	}
+	for _, ifc := range ifaces {
+		addrs, err := ifc.Addrs()
+		if err != nil {
+			continue
+		}
+		for _, a := range addrs {
+			if n, ok := a.(*net.IPNet); ok && n.IP.Equal(ip) {
+				return ifc.Name
+			}
+		}
+	}
+	return ""
+}
+
+// normalizeOne applies the scheme rules to a single address.
+func normalizeOne(addr string, secure bool) (string, error) {
+	switch {
+	case strings.HasPrefix(addr, "https://"):
+		if !secure {
+			return "", fmt.Errorf("%s is an https:// address but no tls certificates are configured", addr)
+		}
+	case strings.HasPrefix(addr, "http://"):
+		if secure {
+			return "", fmt.Errorf("tls is configured but %s is an http:// address; use https://", addr)
+		}
+	case strings.Contains(addr, "://"):
+		return "", fmt.Errorf("server %q must be an http:// or https:// address", addr)
+	case secure:
+		return "https://" + addr, nil
+	default:
+		return "http://" + addr, nil
+	}
+	return addr, nil
+}

internal/agent/discovery/discover.go

@@ -21,8 +21,9 @@ type Options struct {
 	NvidiaSMI string `koanf:"nvidia_smi"`
 	// IBRoot is the sysfs InfiniBand directory.
 	IBRoot string `koanf:"ib_root"`
-	// PreferNVML uses the NVML backend when this binary has one. It is the only
-	// source of NVLink topology.
+	// PreferNVML uses the NVML backend when this binary has one. NVLink
+	// topology is read from nvidia-smi topo -m on every build; NVML, where it
+	// is used, is the more exact source of the peers.
 	PreferNVML bool `koanf:"prefer_nvml"`
 	// SkipGPUs omits GPU discovery. A node without nvidia-smi is already
 	// found to have none, so this is for one whose driver is broken.
@@ -64,8 +65,7 @@ func Discover(ctx context.Context, opts Options, log *slog.Logger) (Inventory, e
 				inv.GPUs, inv.Source = gpus, "nvml"
 				break
 			}
-			log.Warn("NVML discovery failed, falling back to nvidia-smi; "+
-				"NVLink topology will be unavailable", "err", err)
+			log.Warn("NVML discovery failed, falling back to nvidia-smi", "err", err)
 			fallthrough
 		default:
 			gpus, err := DiscoverGPUsSMI(ctx, opts.NvidiaSMI)
@@ -74,6 +74,26 @@ func Discover(ctx context.Context, opts Options, log *slog.Logger) (Inventory, e
 			}
 			inv.GPUs, inv.Source = gpus, "nvidia-smi"
 		}
+		// NVLink and which adapter sits nearest each card, for either path:
+		// NVML knows NVLink but not the adapters, nvidia-smi's query knows
+		// neither. A failure costs the topology and nothing else — the cards
+		// are still cards.
+		if len(inv.GPUs) > 0 {
+			topo, err := DiscoverTopology(ctx, opts.NvidiaSMI)
+			if err != nil {
+				log.Warn("could not read the GPU topology; tensor-parallel groups "+
+					"will be chosen without NVLink", "err", err)
+			} else {
+				topo.Apply(inv.GPUs)
+			}
+			// Multi-node NVLink: which domain each card has joined.
+			if fab, err := DiscoverGPUFabric(ctx, opts.NvidiaSMI); err != nil {
+				log.Warn("could not read the GPUs' NVLink fabric state", "err", err)
+			} else {
+				ApplyFabric(inv.GPUs, fab)
+			}
+			inv.IMEX = DiscoverIMEX(ctx)
+		}
 	}
 
 	hcas, err := DiscoverIB(opts.IBRoot)

internal/agent/discovery/fabrics.go

@@ -10,6 +10,8 @@ import (
 // has.
 type FabricCheck struct {
 	Fabric string
+	// Declared are the adapters the configuration names for it.
+	Declared []string
 	// Usable are the declared adapters that exist and have an active port.
 	Usable []string
 	// RateGbps is the slowest active port among them, because a collective
@@ -49,7 +51,7 @@ func CheckFabrics(declared map[string][]string, discovered []HCA) []FabricCheck
 
 	out := make([]FabricCheck, 0, len(names))
 	for _, fabric := range names {
-		c := FabricCheck{Fabric: fabric}
+		c := FabricCheck{Fabric: fabric, Declared: declared[fabric]}
 		for _, want := range declared[fabric] {
 			hca, found := byName[want]
 			if !found {

internal/agent/discovery/gpu.go

@@ -38,6 +38,13 @@ type GPU struct {
 	// NVLinkPeers are the indices of GPUs reachable over NVLink. Within a node
 	// a TP group should stay inside one NVLink domain.
 	NVLinkPeers []int `json:"nvlink_peers,omitempty"`
+	// NICPaths is how far each network adapter is from this GPU, by HCA name:
+	// PIX, PXB, PHB, NODE or SYS, as nvidia-smi topo reports it. What decides
+	// which adapter a GPU's share of a multi-node job should go through.
+	NICPaths map[string]string `json:"nic_paths,omitempty"`
+	// Fabric is the GPU's multi-node NVLink membership, nil where the
+	// driver reports none.
+	Fabric *GPUFabric `json:"fabric,omitempty"`
 	// Health carries anything that should keep the GPU out of placement.
 	Health GPUHealth `json:"health"`
 }
@@ -117,6 +124,9 @@ type Inventory struct {
 	// Storage is the disk behind those weights, one entry per filesystem.
 	// Empty means the same thing it means for Weights: not asked.
 	Storage []Storage `json:"storage,omitempty"`
+	// IMEX is the service a multi-node NVLink domain needs, read where the
+	// node has GPUs.
+	IMEX IMEX `json:"imex"`
 }
 
 // Classes returns the distinct GPU classes present, sorted.

internal/agent/discovery/gpu_fabric.go

@@ -0,0 +1,160 @@
+package discovery
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"time"
+)
+
+// GPUFabric is a GPU's place in a multi-node NVLink domain, as the driver
+// reports it: the NVL72 rack, or the NVLink Switch system, it belongs to.
+type GPUFabric struct {
+	// State is Completed once the fabric manager has joined the GPU to its
+	// domain; In Progress, Not Started or Not Supported otherwise.
+	State string `json:"state"`
+	// Status is Success, or the reason the join failed.
+	Status string `json:"status,omitempty"`
+	// ClusterUUID and CliqueID name the domain: GPUs sharing both can reach
+	// each other over NVLink whatever node they are in.
+	ClusterUUID string `json:"cluster_uuid,omitempty"`
+	CliqueID    string `json:"clique_id,omitempty"`
+	// Bandwidth is Full, or how the domain's NVLink is degraded.
+	Bandwidth string `json:"bandwidth,omitempty"`
+}
+
+// Domain is the NVLink domain the GPU is joined to, empty when it is in none
+// that crosses nodes: a card with no fabric, one not joined, or one whose
+// cluster is all zeros, which is what a single machine's NVSwitch reports.
+func (f *GPUFabric) Domain() string {
+	if f == nil || !strings.EqualFold(f.State, "Completed") {
+		return ""
+	}
+	u := strings.ToLower(strings.TrimSpace(f.ClusterUUID))
+	if u == "" || strings.Trim(u, "0-") == "" {
+		return ""
+	}
+	return u + "/" + f.CliqueID
+}
+
+// ParseGPUFabric reads the Fabric sections of `nvidia-smi -q`, by the PCI
+// address each GPU's section starts with.
+func ParseGPUFabric(out string) map[string]GPUFabric {
+	res := map[string]GPUFabric{}
+	var bus string
+	fabricIndent := -1
+	var cur *GPUFabric
+	flush := func() {
+		if bus != "" && cur != nil && cur.State != "" {
+			res[bus] = *cur
+		}
+		cur, fabricIndent = nil, -1
+	}
+	for _, line := range strings.Split(out, "\n") {
+		trim := strings.TrimSpace(line)
+		indent := len(line) - len(strings.TrimLeft(line, " \t"))
+		if strings.HasPrefix(line, "GPU ") && indent == 0 {
+			flush()
+			bus = strings.ToLower(strings.TrimSpace(strings.TrimPrefix(line, "GPU ")))
+			continue
+		}
+		if trim == "Fabric" {
+			flush()
+			cur, fabricIndent = &GPUFabric{}, indent
+			continue
+		}
+		if cur == nil {
+			continue
+		}
+		if trim != "" && indent <= fabricIndent {
+			flush()
+			continue
+		}
+		k, v, ok := strings.Cut(trim, ":")
+		if !ok {
+			continue
+		}
+		k, v = strings.TrimSpace(k), strings.TrimSpace(v)
+		if strings.EqualFold(v, "N/A") {
+			v = ""
+		}
+		switch k {
+		case "State":
+			cur.State = v
+		case "Status":
+			cur.Status = v
+		case "ClusterUUID", "Cluster UUID":
+			cur.ClusterUUID = v
+		case "CliqueId", "Clique ID":
+			cur.CliqueID = v
+		case "Bandwidth":
+			cur.Bandwidth = v
+		}
+	}
+	flush()
+	return res
+}
+
+// DiscoverGPUFabric runs `nvidia-smi -q` for the Fabric sections. Nothing
+// is reported on a driver or a card without them.
+func DiscoverGPUFabric(ctx context.Context, binary string) (map[string]GPUFabric, error) {
+	if binary == "" {
+		if _, err := exec.LookPath("nvidia-smi"); err != nil {
+			return nil, nil
+		}
+		binary = "nvidia-smi"
+	}
+	ctx, cancel := context.WithTimeout(ctx, 20*time.Second)
+	defer cancel()
+	out, err := exec.CommandContext(ctx, binary, "-q").Output()
+	if err != nil {
+		return nil, err
+	}
+	return ParseGPUFabric(string(out)), nil
+}
+
+// ApplyFabric puts each GPU's fabric on it, matched by PCI address.
+func ApplyFabric(gpus []GPU, fab map[string]GPUFabric) {
+	for i := range gpus {
+		if f, ok := fab[strings.ToLower(gpus[i].PCIBusID)]; ok {
+			f := f
+			gpus[i].Fabric = &f
+		}
+	}
+}
+
+// IMEX is the service that lets GPUs in different nodes of one NVLink
+// domain share memory: without it, multi-node NVLink carries nothing.
+type IMEX struct {
+	// State is systemd's word for nvidia-imex: active, inactive, or empty
+	// where it is not installed.
+	State string `json:"state,omitempty"`
+	// Channels is how many IMEX channels exist; a process needs one.
+	Channels int `json:"channels"`
+}
+
+// DiscoverIMEX reads the IMEX service and its channels.
+func DiscoverIMEX(ctx context.Context) IMEX {
+	var m IMEX
+	if entries, err := os.ReadDir("/dev/nvidia-caps-imex-channels"); err == nil {
+		m.Channels = len(entries)
+	}
+	if _, err := exec.LookPath("systemctl"); err == nil {
+		ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+		defer cancel()
+		out, _ := exec.CommandContext(ctx, "systemctl", "is-active", "nvidia-imex").Output()
+		m.State = strings.TrimSpace(string(out))
+		if m.State == "inactive" {
+			// "inactive" is also what systemd says of a unit that does not
+			// exist; the binary says which.
+			if _, err := exec.LookPath("nvidia-imex"); err != nil {
+				if _, err := os.Stat(filepath.Join("/usr/bin", "nvidia-imex")); err != nil {
+					m.State = ""
+				}
+			}
+		}
+	}
+	return m
+}

internal/agent/discovery/gpu_fabric_test.go

@@ -0,0 +1,77 @@
+package discovery
+
+import "testing"
+
+// smiQ is an excerpt of `nvidia-smi -q` on a GB200 tray: two GPUs joined to
+// one NVL72 domain, then a PCIe card that has no fabric at all.
+const smiQ = `
+==============NVSMI LOG==============
+
+Timestamp                                 : Mon Sep 29 10:00:00 2026
+Driver Version                            : 570.86.15
+Attached GPUs                             : 3
+GPU 00000008:01:00.0
+    Product Name                          : NVIDIA GB200
+    Minor Number                          : 0
+    Fabric
+        State                             : Completed
+        Status                            : Success
+        CliqueId                          : 32766
+        ClusterUUID                       : 76B1AD76-7c24-4b6b-9f6c-2a1e0d8c11aa
+        Health
+            Bandwidth                     : Full
+    Processes                             : None
+
+GPU 00000009:01:00.0
+    Product Name                          : NVIDIA GB200
+    Fabric
+        State                             : In Progress
+        Status                            : N/A
+        CliqueId                          : N/A
+        ClusterUUID                       : N/A
+    Processes                             : None
+
+GPU 0000000A:01:00.0
+    Product Name                          : NVIDIA L40S
+    Fabric
+        State                             : N/A
+        Status                            : N/A
+`
+
+func TestAGPUsNVLinkDomainIsRead(t *testing.T) {
+	fab := ParseGPUFabric(smiQ)
+	a, ok := fab["00000008:01:00.0"]
+	if !ok {
+		t.Fatalf("fabric = %+v", fab)
+	}
+	if a.State != "Completed" || a.CliqueID != "32766" || a.Bandwidth != "Full" {
+		t.Errorf("GB200 = %+v", a)
+	}
+	if got := a.Domain(); got != "76b1ad76-7c24-4b6b-9f6c-2a1e0d8c11aa/32766" {
+		t.Errorf("domain = %q", got)
+	}
+	// Still joining: no domain yet, and said as such.
+	b := fab["00000009:01:00.0"]
+	if b.State != "In Progress" || b.Domain() != "" {
+		t.Errorf("joining GPU = %+v", b)
+	}
+	// A card with no fabric reports nothing rather than an empty one.
+	if _, ok := fab["0000000a:01:00.0"]; ok {
+		t.Error("a card without a fabric was given one")
+	}
+
+	gpus := []GPU{{Index: 0, PCIBusID: "00000008:01:00.0"}, {Index: 1, PCIBusID: "0000000A:01:00.0"}}
+	ApplyFabric(gpus, fab)
+	if gpus[0].Fabric == nil || gpus[1].Fabric != nil {
+		t.Errorf("applied = %+v %+v", gpus[0].Fabric, gpus[1].Fabric)
+	}
+}
+
+func TestASingleMachinesNVSwitchIsNoDomain(t *testing.T) {
+	// An eight-GPU HGX reports its fabric joined, with a cluster of zeros: its
+	// NVLink ends at the chassis.
+	f := &GPUFabric{State: "Completed", ClusterUUID: "00000000-0000-0000-0000-000000000000", CliqueID: "0"}
+	if f.Domain() != "" {
+		t.Errorf("a single machine read as a domain: %q", f.Domain())
+	}
+}

internal/agent/discovery/gpu_smi.go

@@ -40,8 +40,8 @@ const mandatorySMIFields = 10
 //
 // This is the cgo-free path (plan §3.2): the NVML bindings need cgo, which
 // would force the whole binary — server included — to be built with a C
-// toolchain. nvidia-smi gives everything except NVLink topology, which the
-// NVML build adds.
+// toolchain. The query gives everything except topology, which Discover
+// reads from `nvidia-smi topo -m` afterwards.
 func DiscoverGPUsSMI(ctx context.Context, binary string) ([]GPU, error) {
 	if binary == "" {
 		// Not configured and not installed is a node without an NVIDIA card,

internal/agent/discovery/host.go

@@ -4,6 +4,7 @@ import (
 	"bufio"
 	"os"
 	"runtime"
+	"strconv"
 	"strings"
 )
 
@@ -26,6 +27,9 @@ type Host struct {
 	CPUFlags []string `json:"cpu_flags,omitempty"`
 	// NVIDIADriver is the loaded driver's version, empty when there is none.
 	NVIDIADriver string `json:"nvidia_driver,omitempty"`
+	// MinComputeCapability is the oldest GPU's, 0 when there are none or it
+	// is not known. Not read here but from the GPU inventory, by the agent.
+	MinComputeCapability float64 `json:"min_compute_capability,omitempty"`
 }
 
 // Family is the packaging family: "deb", "rpm", or "" when neither is known.
@@ -152,3 +156,19 @@ func nvidiaDriverFrom(path string) string {
 	}
 	return ""
 }
+
+// MinComputeCapability is the oldest GPU's compute capability, 0 when none
+// is known: an engine built for newer GPUs is refused by the oldest.
+func MinComputeCapability(gpus []GPU) float64 {
+	low := 0.0
+	for _, g := range gpus {
+		cc, err := strconv.ParseFloat(strings.TrimSpace(g.ComputeCapability), 64)
+		if err != nil || cc <= 0 {
+			continue
+		}
+		if low == 0 || cc < low {
+			low = cc
+		}
+	}
+	return low
+}

internal/agent/discovery/ib.go

@@ -5,6 +5,7 @@ package discovery
 import (
 	"errors"
 	"fmt"
+	"net"
 	"os"
 	"path/filepath"
 	"slices"
@@ -42,8 +43,66 @@ type Port struct {
 	GIDPrefix string `json:"gid_prefix"`
 	LID       int    `json:"lid"`
 	SMLID     int    `json:"sm_lid"`
+	// Counters are the port's error and traffic counters, by their sysfs
+	// names, as far as the driver has them. The data counters are converted
+	// to bytes; sysfs counts them in four-byte words.
+	Counters map[string]uint64 `json:"counters,omitempty"`
+	// RoCEv2GID is the GID table index NCCL should use on a RoCE port: the
+	// first RoCE v2 entry holding an IPv4 address, else the first RoCE v2
+	// entry. -1 on InfiniBand, and on a RoCE port with no v2 entry. NCCL's
+	// default of 0 is a RoCE v1 link-local entry on most setups, which does
+	// not route, and a job on it hangs.
+	RoCEv2GID int `json:"rocev2_gid"`
+	// PortGUID is the port's own identifier, the interface half of its GID.
+	PortGUID string `json:"port_guid,omitempty"`
+	// SM is the subnet manager this port sees as master, from sminfo. Nil on
+	// RoCE, which has none, and when infiniband-diags is not installed.
+	SM *SMInfo `json:"sm,omitempty"`
+	// Network is, on RoCE, the IP network of the RoCE v2 address: the only
+	// thing that says two RoCE ports are on the same fabric.
+	Network string `json:"network,omitempty"`
 }
 
+// SMInfo is a subnet manager as a port sees it.
+type SMInfo struct {
+	GUID     string `json:"guid"`
+	LID      int    `json:"lid"`
+	Priority int    `json:"priority"`
+	// State is SMINFO_MASTER, SMINFO_STANDBY, ...
+	State string `json:"state"`
+}
+
+// FabricKey is what identifies the physical fabric this port is on: the
+// master subnet manager on InfiniBand, since every port on one fabric sees
+// the same one and ports on separate fabrics cannot; the IP network on RoCE.
+// Empty when neither is known, and for a port that is not up.
+func (p Port) FabricKey() string {
+	if !p.Active() {
+		return ""
+	}
+	switch {
+	case p.LinkLayer == LinkEthernet && p.Network != "":
+		return "roce:" + p.Network
+	case p.SM != nil && p.SM.GUID != "":
+		return "sm:" + p.SM.GUID
+	}
+	return ""
+}
+
+// PortCounters are the counters worth watching, from each port's counters/
+// directory. The errors are the ones that say a cable, a transceiver or a
+// switch port is going bad before a job fails on it; the data counters say
+// whether the fabric is carrying anything at all.
+var PortCounters = []string{
+	"symbol_error", "link_error_recovery", "link_downed", "port_rcv_errors",
+	"port_rcv_remote_physical_errors", "port_xmit_discards",
+	"local_link_integrity_errors", "excessive_buffer_overrun_errors",
+	"port_xmit_data", "port_rcv_data",
+}
+
+// dataCounter reports whether a counter counts data in four-byte words.
+func dataCounter(name string) bool { return name == "port_xmit_data" || name == "port_rcv_data" }
+
 // Active reports whether the port can carry traffic.
 func (p Port) Active() bool { return strings.EqualFold(p.State, "ACTIVE") }
 
@@ -56,6 +115,9 @@ type HCA struct {
 	// FirmwareVersion is reported by the driver; worth capturing because
 	// NCCL behaviour differs between firmware revisions.
 	FirmwareVersion string `json:"firmware_version,omitempty"`
+	// NodeGUID identifies the adapter on its fabric: it is the name a
+	// switch's view of the fabric, and every other tool, knows it by.
+	NodeGUID string `json:"node_guid,omitempty"`
 }
 
 // ActivePorts returns the ports that can carry traffic.
@@ -102,6 +164,7 @@ func DiscoverIB(root string) ([]HCA, error) {
 func readHCA(dir, name string) (HCA, error) {
 	h := HCA{Name: name, NUMANode: -1}
 	h.FirmwareVersion = readTrimmed(filepath.Join(dir, "fw_ver"))
+	h.NodeGUID = normalizeGUID(readTrimmed(filepath.Join(dir, "node_guid")))
 
 	// device is a symlink into the PCI tree; its target's base name is the
 	// bus address, and numa_node lives beside it.
@@ -138,6 +201,30 @@ func readPort(dir string, num int) Port {
 		LID:       parseMaybeHex(readTrimmed(filepath.Join(dir, "lid"))),
 		SMLID:     parseMaybeHex(readTrimmed(filepath.Join(dir, "sm_lid"))),
 	}
+	p.RoCEv2GID = -1
+	p.PortGUID = portGUID(readTrimmed(filepath.Join(dir, "gids", "0")))
+	if p.LinkLayer == LinkEthernet {
+		p.RoCEv2GID = rocev2GID(dir)
+		if p.RoCEv2GID >= 0 {
+			idx := strconv.Itoa(p.RoCEv2GID)
+			p.Network = RoCENetwork(readTrimmed(filepath.Join(dir, "gid_attrs", "ndevs", idx)),
+				readTrimmed(filepath.Join(dir, "gids", idx)))
+		}
+	}
+	for _, name := range PortCounters {
+		raw := readTrimmed(filepath.Join(dir, "counters", name))
+		v, err := strconv.ParseUint(raw, 10, 64)
+		if err != nil {
+			continue // not every driver has every counter
+		}
+		if dataCounter(name) {
+			v *= 4
+		}
+		if p.Counters == nil {
+			p.Counters = map[string]uint64{}
+		}
+		p.Counters[name] = v
+	}
 	return p
 }
 
@@ -201,3 +288,91 @@ func readTrimmed(path string) string {
 	}
 	return strings.TrimSpace(string(b))
 }
+
+// rocev2GID finds the GID index a RoCE port's traffic should use.
+func rocev2GID(dir string) int {
+	first := -1
+	for i := 0; i < 64; i++ {
+		typ := readTrimmed(filepath.Join(dir, "gid_attrs", "types", strconv.Itoa(i)))
+		if !strings.EqualFold(typ, "RoCE v2") {
+			continue
+		}
+		gid := strings.ToLower(readTrimmed(filepath.Join(dir, "gids", strconv.Itoa(i))))
+		if strings.HasPrefix(gid, "0000:0000:0000:0000:0000:ffff:") {
+			return i
+		}
+		if first < 0 {
+			first = i
+		}
+	}
+	return first
+}
+
+// normalizeGUID writes a GUID one way: sysfs says "0c42:a103:0045:bd6c",
+// sminfo and ibnetdiscover say "0x0c42a1030045bd6c".
+func normalizeGUID(g string) string {
+	g = strings.ToLower(strings.TrimSpace(g))
+	g = strings.TrimPrefix(g, "0x")
+	g = strings.ReplaceAll(g, ":", "")
+	if g == "" || strings.Trim(g, "0") == "" {
+		return ""
+	}
+	for len(g) < 16 {
+		g = "0" + g
+	}
+	return "0x" + g
+}
+
+// NormalizeGUID is normalizeGUID for other packages.
+func NormalizeGUID(g string) string { return normalizeGUID(g) }
+
+// portGUID is the interface identifier of a GID: its last four groups.
+func portGUID(gid string) string {
+	parts := strings.Split(gid, ":")
+	if len(parts) != 8 {
+		return ""
+	}
+	return normalizeGUID(strings.Join(parts[4:], ""))
+}
+
+// RoCENetwork is the IP network an IPv4-mapped RoCE GID's address sits in,
+// read from the interface that carries it. Replaced in tests.
+var RoCENetwork = func(ndev, gid string) string {
+	ip := gidIPv4(gid)
+	if ip == nil || ndev == "" {
+		return ""
+	}
+	ifc, err := net.InterfaceByName(ndev)
+	if err != nil {
+		return ""
+	}
+	addrs, _ := ifc.Addrs()
+	for _, a := range addrs {
+		if n, ok := a.(*net.IPNet); ok && n.IP.Equal(ip) {
+			return (&net.IPNet{IP: ip.Mask(n.Mask), Mask: n.Mask}).String()
+		}
+	}
+	return ""
+}
+
+// gidIPv4 is the IPv4 address in an IPv4-mapped GID, nil otherwise.
+func gidIPv4(gid string) net.IP {
+	g := strings.ToLower(gid)
+	const mapped = "0000:0000:0000:0000:0000:ffff:"
+	if !strings.HasPrefix(g, mapped) {
+		return nil
+	}
+	hex := strings.ReplaceAll(strings.TrimPrefix(g, mapped), ":", "")
+	if len(hex) != 8 {
+		return nil
+	}
+	b := make(net.IP, 4)
+	for i := range 4 {
+		v, err := strconv.ParseUint(hex[i*2:i*2+2], 16, 8)
+		if err != nil {
+			return nil
+		}
+		b[i] = byte(v)
+	}
+	return b
+}

internal/agent/discovery/ib_test.go

@@ -31,6 +31,9 @@ func fakeSysfs(t *testing.T) string {
 	write("ib/mlx5_0/ports/1/gids/0", "FEC0:0000:0000:000A:0002:C903:00A0:1234")
 	write("ib/mlx5_0/ports/1/lid", "0x1a")
 	write("ib/mlx5_0/ports/1/sm_lid", "1")
+	write("ib/mlx5_0/ports/1/counters/symbol_error", "3")
+	write("ib/mlx5_0/ports/1/counters/link_downed", "1")
+	write("ib/mlx5_0/ports/1/counters/port_xmit_data", "1000")
 
 	// mlx5_1: two ports, the second one down.
 	write("ib/mlx5_1/ports/1/state", "4: ACTIVE")
@@ -46,7 +49,13 @@ func fakeSysfs(t *testing.T) string {
 	write("ib/mlx5_2/ports/1/state", "4: ACTIVE")
 	write("ib/mlx5_2/ports/1/rate", "100 Gb/sec (4X EDR)")
 	write("ib/mlx5_2/ports/1/link_layer", "Ethernet")
-	write("ib/mlx5_2/ports/1/gids/0", "0000:0000:0000:0000:0000:ffff:0a00:0001")
+	write("ib/mlx5_2/ports/1/gids/0", "fe80:0000:0000:0000:0000:0000:0000:0001")
+	write("ib/mlx5_2/ports/1/gid_attrs/types/0", "IB/RoCE v1")
+	write("ib/mlx5_2/ports/1/gids/1", "fe80:0000:0000:0000:0000:0000:0000:0001")
+	write("ib/mlx5_2/ports/1/gid_attrs/types/1", "RoCE v2")
+	write("ib/mlx5_2/ports/1/gids/3", "0000:0000:0000:0000:0000:ffff:0a00:0001")
+	write("ib/mlx5_2/ports/1/gid_attrs/types/3", "RoCE v2")
+	write("ib/mlx5_2/ports/1/gid_attrs/ndevs/3", "ens1f0")
 
 	// A PCI device with a NUMA node, linked the way the driver does it.
 	pci := filepath.Join(root, "pci", "0000:0b:00.0")
@@ -214,3 +223,131 @@ func TestParseHelpers(t *testing.T) {
 		}
 	})
 }
+
+func TestAPortsCountersAreRead(t *testing.T) {
+	hcas, err := DiscoverIB(fakeSysfs(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+	c := hcas[0].Ports[0].Counters
+	// Data in bytes: sysfs counts four-byte words.
+	if c["symbol_error"] != 3 || c["link_downed"] != 1 || c["port_xmit_data"] != 4000 {
+		t.Errorf("counters = %v", c)
+	}
+	if _, ok := c["port_rcv_errors"]; ok {
+		t.Error("a counter the driver does not have should be absent, not zero")
+	}
+}
+
+func TestRoCEFindsItsRoutableGID(t *testing.T) {
+	// NCCL's default GID index is a v1 link-local entry on most hosts, which
+	// does not route: the job hangs. The v2 entry holding an IPv4 address is
+	// the one to use, over an earlier v2 link-local one.
+	hcas, err := DiscoverIB(fakeSysfs(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, h := range hcas {
+		p := h.Ports[0]
+		switch h.Name {
+		case "mlx5_2":
+			if p.RoCEv2GID != 3 {
+				t.Errorf("RoCE GID index = %d, want 3", p.RoCEv2GID)
+			}
+		default:
+			if p.RoCEv2GID != -1 {
+				t.Errorf("%s is InfiniBand and has a GID index %d", h.Name, p.RoCEv2GID)
+			}
+		}
+	}
+}
+
+func TestTheSubnetManagerAPortSeesIsRead(t *testing.T) {
+	sm, err := ParseSMInfo("sminfo: sm lid 1 sm guid 0x98039B03009fcfd6, activity count 5452 priority 15 state 3 SMINFO_MASTER\n")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if sm.GUID != "0x98039b03009fcfd6" || sm.LID != 1 || sm.Priority != 15 || sm.State != "SMINFO_MASTER" {
+		t.Errorf("sm = %+v", sm)
+	}
+	if _, err := ParseSMInfo("ibwarn: [1234] mad_rpc_open_port: can't open UMAD port"); err == nil {
+		t.Error("an error from sminfo should not parse")
+	}
+}
+
+func TestAPortsFabricIsItsSubnetManagerOrItsNetwork(t *testing.T) {
+	// Two ports on one InfiniBand fabric see one master SM, and on separate
+	// fabrics cannot; RoCE has no SM, and is its IP network.
+	hcas, err := DiscoverIB(fakeSysfs(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if hcas[0].NodeGUID != "" {
+		t.Errorf("no node_guid file, yet %q", hcas[0].NodeGUID)
+	}
+	err = AttachSM(hcas, func(hca string, port int) (*SMInfo, error) {
+		return &SMInfo{GUID: "0x00000000000000aa", LID: 1, State: "SMINFO_MASTER"}, nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := hcas[0].Ports[0].FabricKey(); got != "sm:0x00000000000000aa" {
+		t.Errorf("IB key = %q", got)
+	}
+	if got := hcas[1].Ports[1].FabricKey(); got != "" {
+		t.Errorf("a port that is down is on no fabric, got %q", got)
+	}
+	if hcas[2].Ports[0].SM != nil {
+		t.Error("RoCE was asked for a subnet manager")
+	}
+	if got := hcas[0].Ports[0].PortGUID; got != "0x0002c90300a01234" {
+		t.Errorf("port GUID = %q", got)
+	}
+}
+
+func TestARoCEPortsNetworkIsItsFabric(t *testing.T) {
+	old := RoCENetwork
+	t.Cleanup(func() { RoCENetwork = old })
+	RoCENetwork = func(ndev, gid string) string {
+		if ip := gidIPv4(gid); ip != nil && ip.String() == "10.0.0.1" {
+			return "10.0.0.0/24"
+		}
+		return ""
+	}
+	hcas, err := DiscoverIB(fakeSysfs(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+	roce := hcas[2].Ports[0]
+	if roce.Network != "10.0.0.0/24" || roce.FabricKey() != "roce:10.0.0.0/24" {
+		t.Errorf("RoCE network %q key %q", roce.Network, roce.FabricKey())
+	}
+}
+
+// smirDump is `saquery SMIR` on a fabric with a master and a standby, in the
+// layout infiniband-diags prints.
+const smirDump = "SMInfoRecord dump:\n\t\tRID\n\t\tLID...................1\n\t\tSMInfo dump:\n" +
+	"\t\tGUID..................0x248a07030030f0c0\n\t\tSM_Key................0x0000000000000000\n" +
+	"\t\tActCount..............386773\n\t\tPriority..............15\n\t\tSMState...............3\n" +
+	"SMInfoRecord dump:\n\t\tRID\n\t\tLID...................12\n\t\tSMInfo dump:\n" +
+	"\t\tGUID..................0x248a07030030f1d4\n\t\tSM_Key................0x0000000000000000\n" +
+	"\t\tActCount..............12\n\t\tPriority..............14\n\t\tSMState...............2\n"
+
+func TestEverySubnetManagerOnAFabricIsListed(t *testing.T) {
+	recs, err := ParseSMIR(smirDump)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(recs) != 2 {
+		t.Fatalf("records = %+v", recs)
+	}
+	if recs[0].GUID != "0x248a07030030f0c0" || recs[0].State != "master" || recs[0].Priority != 15 || recs[0].LID != 1 {
+		t.Errorf("master = %+v", recs[0])
+	}
+	if recs[1].State != "standby" || recs[1].LID != 12 {
+		t.Errorf("standby = %+v", recs[1])
+	}
+	if _, err := ParseSMIR("ibwarn: can't open UMAD port"); err == nil {
+		t.Error("an error should not parse")
+	}
+}

internal/agent/discovery/load.go

@@ -0,0 +1,260 @@
+package discovery
+
+import (
+	"bufio"
+	"bytes"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// Load is how busy a node is: the machine as a whole, and each engine's share.
+type Load struct {
+	CPUPercent float64
+	CPUCount   int
+	Load1      float64
+	Load5      float64
+	Load15     float64
+	MemUsed    int64
+	MemAvail   int64
+	Shards     []ShardLoad
+}
+
+// ShardLoad is one engine process group's use.
+type ShardLoad struct {
+	ID       string
+	CPUCores float64
+	RSSBytes int64
+}
+
+// userHZ is the unit /proc counts CPU time in. Fixed at 100 by the kernel's
+// ABI on every architecture a node runs, whatever the internal tick rate.
+const userHZ = 100
+
+// LoadSampler measures load as the difference between two readings of /proc.
+//
+// CPU time is a counter, so a percentage needs two samples and the time
+// between them. The sampler keeps the previous one; the first call has
+// nothing to compare with and reports no load at all, rather than a zero that
+// would read as an idle machine.
+//
+// Linux only, like every node. Elsewhere the files are missing and it reports
+// nothing, as an older agent does.
+type LoadSampler struct {
+	root string
+	now  func() time.Time
+
+	mu      sync.Mutex
+	prevAt  time.Time
+	prevCPU cpuTimes
+	prevPG  map[int]groupUse // process group -> what it has used
+}
+
+// groupUse is a process group's CPU time so far and its resident memory now.
+type groupUse struct {
+	jiffies  uint64
+	rssPages int64
+}
+
+type cpuTimes struct{ total, idle uint64 }
+
+// NewLoadSampler reads the real /proc.
+func NewLoadSampler() *LoadSampler { return newLoadSampler("/proc", time.Now) }
+
+func newLoadSampler(root string, now func() time.Time) *LoadSampler {
+	return &LoadSampler{root: root, now: now}
+}
+
+// Sample reads the machine and the process groups led by the given shards'
+// PIDs, keyed by shard ID. False when there is nothing to report yet.
+func (s *LoadSampler) Sample(shards map[string]int) (Load, bool) {
+	cpu, ok := s.cpu()
+	if !ok {
+		return Load{}, false
+	}
+	groups := s.groups()
+	at := s.now()
+
+	s.mu.Lock()
+	prevAt, prevCPU, prevPG := s.prevAt, s.prevCPU, s.prevPG
+	s.prevAt, s.prevCPU, s.prevPG = at, cpu, groups
+	s.mu.Unlock()
+
+	if prevAt.IsZero() || cpu.total <= prevCPU.total {
+		return Load{}, false
+	}
+	l := Load{CPUCount: s.cpuCount()}
+	dTotal := float64(cpu.total - prevCPU.total)
+	dIdle := float64(cpu.idle - prevCPU.idle)
+	l.CPUPercent = clamp((dTotal-dIdle)/dTotal*100, 0, 100)
+	l.Load1, l.Load5, l.Load15 = s.loadavg()
+	total, avail := s.meminfo()
+	if total > 0 {
+		l.MemUsed, l.MemAvail = total-avail, avail
+	}
+
+	secs := at.Sub(prevAt).Seconds()
+	for id, pid := range shards {
+		if pid <= 0 {
+			continue
+		}
+		now := groups[pid]
+		sl := ShardLoad{ID: id, RSSBytes: now.rssPages * int64(os.Getpagesize())}
+		if before, ok := prevPG[pid]; ok && secs > 0 && now.jiffies >= before.jiffies {
+			sl.CPUCores = float64(now.jiffies-before.jiffies) / userHZ / secs
+		}
+		l.Shards = append(l.Shards, sl)
+	}
+	return l, true
+}
+
+func clamp(v, lo, hi float64) float64 { return max(lo, min(v, hi)) }
+
+// cpu reads the aggregate line of /proc/stat. Idle includes iowait: a core
+// waiting on the disk is not doing work.
+func (s *LoadSampler) cpu() (cpuTimes, bool) {
+	b, err := os.ReadFile(filepath.Join(s.root, "stat"))
+	if err != nil {
+		return cpuTimes{}, false
+	}
+	line, _, _ := bytes.Cut(b, []byte("\n"))
+	f := strings.Fields(string(line))
+	if len(f) < 5 || f[0] != "cpu" {
+		return cpuTimes{}, false
+	}
+	var t cpuTimes
+	for i, v := range f[1:] {
+		// guest and guest_nice are already counted in user and nice.
+		if i >= 8 {
+			break
+		}
+		n, _ := strconv.ParseUint(v, 10, 64)
+		t.total += n
+		if i == 3 || i == 4 {
+			t.idle += n
+		}
+	}
+	return t, true
+}
+
+func (s *LoadSampler) cpuCount() int {
+	b, err := os.ReadFile(filepath.Join(s.root, "stat"))
+	if err != nil {
+		return 0
+	}
+	n := 0
+	for _, line := range strings.Split(string(b), "\n") {
+		if strings.HasPrefix(line, "cpu") && len(line) > 3 && line[3] >= '0' && line[3] <= '9' {
+			n++
+		}
+	}
+	return n
+}
+
+func (s *LoadSampler) loadavg() (l1, l5, l15 float64) {
+	b, err := os.ReadFile(filepath.Join(s.root, "loadavg"))
+	if err != nil {
+		return 0, 0, 0
+	}
+	f := strings.Fields(string(b))
+	if len(f) < 3 {
+		return 0, 0, 0
+	}
+	l1, _ = strconv.ParseFloat(f[0], 64)
+	l5, _ = strconv.ParseFloat(f[1], 64)
+	l15, _ = strconv.ParseFloat(f[2], 64)
+	return l1, l5, l15
+}
+
+// meminfo returns MemTotal and MemAvailable in bytes.
+func (s *LoadSampler) meminfo() (total, avail int64) {
+	f, err := os.Open(filepath.Join(s.root, "meminfo"))
+	if err != nil {
+		return 0, 0
+	}
+	defer f.Close()
+	sc := bufio.NewScanner(f)
+	for sc.Scan() {
+		k, v, ok := strings.Cut(sc.Text(), ":")
+		if !ok {
+			continue
+		}
+		fields := strings.Fields(v)
+		if len(fields) == 0 {
+			continue
+		}
+		kb, _ := strconv.ParseInt(fields[0], 10, 64)
+		switch k {
+		case "MemTotal":
+			total = kb * 1024
+		case "MemAvailable":
+			avail = kb * 1024
+		}
+	}
+	return total, avail
+}
+
+// procStat is what one /proc/<pid>/stat says that load needs.
+type procStat struct {
+	pgrp     int
+	jiffies  uint64
+	rssPages int64
+}
+
+// readProcStat parses /proc/<pid>/stat. The command name is in parentheses
+// and may itself hold spaces and parentheses, so fields are counted from the
+// last closing one.
+func readProcStat(path string) (procStat, bool) {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return procStat{}, false
+	}
+	i := bytes.LastIndexByte(b, ')')
+	if i < 0 {
+		return procStat{}, false
+	}
+	f := strings.Fields(string(b[i+1:]))
+	// After the name: state(0) ppid(1) pgrp(2) ... utime(11) stime(12) ... rss(21)
+	if len(f) < 22 {
+		return procStat{}, false
+	}
+	var st procStat
+	st.pgrp, _ = strconv.Atoi(f[2])
+	ut, _ := strconv.ParseUint(f[11], 10, 64)
+	stt, _ := strconv.ParseUint(f[12], 10, 64)
+	st.jiffies = ut + stt
+	st.rssPages, _ = strconv.ParseInt(f[21], 10, 64)
+	return st, true
+}
+
+// groups totals CPU time and memory per process group, in one pass over
+// /proc. An engine is started as the leader of its own group, so its workers
+// — vLLM starts several — are counted with it.
+func (s *LoadSampler) groups() map[int]groupUse {
+	out := map[int]groupUse{}
+	s.eachProc(func(st procStat) {
+		g := out[st.pgrp]
+		g.jiffies += st.jiffies
+		g.rssPages += st.rssPages
+		out[st.pgrp] = g
+	})
+	return out
+}
+
+func (s *LoadSampler) eachProc(fn func(procStat)) {
+	entries, err := os.ReadDir(s.root)
+	if err != nil {
+		return
+	}
+	for _, e := range entries {
+		if _, err := strconv.Atoi(e.Name()); err != nil {
+			continue
+		}
+		if st, ok := readProcStat(filepath.Join(s.root, e.Name(), "stat")); ok {
+			fn(st)
+		}
+	}
+}

internal/agent/discovery/load_test.go

@@ -0,0 +1,96 @@
+package discovery
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+// fakeProc is a /proc with two CPUs, a memory picture and processes.
+type fakeProc struct {
+	t    *testing.T
+	root string
+}
+
+func newFakeProc(t *testing.T) *fakeProc {
+	f := &fakeProc{t: t, root: t.TempDir()}
+	f.write("loadavg", "1.50 0.75 0.25 2/300 4242\n")
+	f.write("meminfo", "MemTotal:       8000000 kB\nMemFree:        1000000 kB\nMemAvailable:   3000000 kB\n")
+	return f
+}
+
+func (f *fakeProc) write(name, body string) {
+	f.t.Helper()
+	p := filepath.Join(f.root, name)
+	if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+		f.t.Fatal(err)
+	}
+	if err := os.WriteFile(p, []byte(body), 0o644); err != nil {
+		f.t.Fatal(err)
+	}
+}
+
+// cpu sets the aggregate counters: user and idle, the rest zero.
+func (f *fakeProc) cpu(user, idle uint64) {
+	f.write("stat", fmt.Sprintf("cpu  %d 0 0 %d 0 0 0 0 0 0\ncpu0 0 0 0 0 0 0 0 0 0 0\ncpu1 0 0 0 0 0 0 0 0 0 0\nintr 1\n", user, idle))
+}
+
+// proc sets one process: its group, CPU jiffies (as utime) and RSS in pages.
+func (f *fakeProc) proc(pid, pgrp int, jiffies uint64, rss int64) {
+	// The name holds a space and a parenthesis, as real ones can.
+	f.write(fmt.Sprintf("%d/stat", pid), fmt.Sprintf(
+		"%d (llama-server (x)) S 1 %d %d 0 -1 0 0 0 0 0 %d 0 0 0 20 0 1 0 100 1000 %d 0\n",
+		pid, pgrp, pgrp, jiffies, rss))
+}
+
+func TestLoadIsTheDifferenceBetweenTwoReadings(t *testing.T) {
+	p := newFakeProc(t)
+	at := time.Unix(1000, 0)
+	s := newLoadSampler(p.root, func() time.Time { return at })
+
+	p.cpu(100, 900)
+	p.proc(42, 42, 1000, 10)
+	p.proc(43, 42, 500, 5) // a worker in the engine's group
+	p.proc(7, 7, 99999, 1) // something else entirely
+	if _, ok := s.Sample(map[string]int{"shard-a": 42}); ok {
+		t.Fatal("the first reading has nothing to compare with and should report nothing")
+	}
+
+	// Two seconds later: 300 of the 400 jiffies that passed were busy, and
+	// the engine's group used 400 of them.
+	at = at.Add(2 * time.Second)
+	p.cpu(400, 1000)
+	p.proc(42, 42, 1300, 10)
+	p.proc(43, 42, 600, 6)
+	l, ok := s.Sample(map[string]int{"shard-a": 42})
+	if !ok {
+		t.Fatal("the second reading should report")
+	}
+	if l.CPUPercent != 75 || l.CPUCount != 2 {
+		t.Errorf("cpu %.1f%% of %d, want 75%% of 2", l.CPUPercent, l.CPUCount)
+	}
+	if l.Load1 != 1.5 || l.Load15 != 0.25 {
+		t.Errorf("load %v %v", l.Load1, l.Load15)
+	}
+	if l.MemUsed != 5000000*1024 || l.MemAvail != 3000000*1024 {
+		t.Errorf("memory used %d available %d", l.MemUsed, l.MemAvail)
+	}
+	if len(l.Shards) != 1 {
+		t.Fatalf("shards = %+v", l.Shards)
+	}
+	sh := l.Shards[0]
+	// 400 jiffies over 2 seconds at 100 a second is two cores.
+	if sh.ID != "shard-a" || sh.CPUCores != 2 || sh.RSSBytes != 16*int64(os.Getpagesize()) {
+		t.Errorf("shard = %+v", sh)
+	}
+}
+
+func TestNoProcMeansNoLoad(t *testing.T) {
+	s := newLoadSampler(filepath.Join(t.TempDir(), "missing"), time.Now)
+	s.Sample(nil)
+	if _, ok := s.Sample(nil); ok {
+		t.Error("a system without /proc should report nothing, not zeros")
+	}
+}

internal/agent/discovery/perftest.go

@@ -0,0 +1,133 @@
+package discovery
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os/exec"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// WriteBW is one side of an ib_write_bw run, from perftest: an RDMA write
+// bandwidth test between two adapters, which is what a collective spanning
+// nodes rides on.
+type WriteBW struct {
+	HCA  string
+	Port int
+	// GIDIndex is the RoCE v2 GID to use; negative on InfiniBand, where the
+	// port's LID is used.
+	GIDIndex int
+	// Peer is the server's address, for the client; empty makes the server.
+	Peer    string
+	TCPPort int
+	Seconds int
+}
+
+// Args are the command line: a duration rather than a count, so the test
+// takes as long on a slow link as a fast one, and results in Gb/s.
+func (w WriteBW) Args() []string {
+	args := []string{"-d", w.HCA, "-i", strconv.Itoa(max(w.Port, 1)),
+		"-p", strconv.Itoa(w.TCPPort), "-D", strconv.Itoa(max(w.Seconds, 1)),
+		"-F", "--report_gbits"}
+	if w.GIDIndex >= 0 {
+		args = append(args, "-x", strconv.Itoa(w.GIDIndex))
+	}
+	if w.Peer != "" {
+		args = append(args, w.Peer)
+	}
+	return args
+}
+
+// RunWriteBW runs one side and returns the average bandwidth the output
+// reports, in Gb/s, and the output. The client retries its connection for a
+// while: the server is started first, but a few seconds may pass before it
+// listens.
+func RunWriteBW(ctx context.Context, w WriteBW) (float64, string, error) {
+	bin, err := exec.LookPath("ib_write_bw")
+	if err != nil {
+		return 0, "", errors.New("ib_write_bw is not installed (the perftest package)")
+	}
+	limit := time.Duration(w.Seconds+60) * time.Second
+	var out []byte
+	for attempt := 0; ; attempt++ {
+		cctx, cancel := context.WithTimeout(ctx, limit)
+		out, err = exec.CommandContext(cctx, bin, w.Args()...).CombinedOutput() //nolint:gosec // fixed tool
+		cancel()
+		if err == nil || w.Peer == "" || !refused(string(out)) || attempt >= 10 {
+			break
+		}
+		select {
+		case <-ctx.Done():
+			return 0, string(out), ctx.Err()
+		case <-time.After(time.Second):
+		}
+	}
+	text := string(out)
+	if err != nil {
+		return 0, text, fmt.Errorf("ib_write_bw: %v: %s", err, lastNonEmpty(text))
+	}
+	gbps, perr := ParseWriteBW(text)
+	if perr != nil && w.Peer != "" {
+		// Only the client is sure to print the result; a server that does not
+		// is not a failure.
+		return 0, text, perr
+	}
+	return gbps, text, nil
+}
+
+func refused(out string) bool {
+	for _, s := range []string{"Couldn't connect", "Unable to init the socket connection", "Connection refused"} {
+		if strings.Contains(out, s) {
+			return true
+		}
+	}
+	return false
+}
+
+var columnSplit = regexp.MustCompile(`\s{2,}`)
+
+// ParseWriteBW finds the average bandwidth in perftest's result table:
+//
+//	#bytes     #iterations    BW peak[Gb/sec]    BW average[Gb/sec]   MsgRate[Mpps]
+//	65536      887036           0.00               96.93               0.184877
+//
+// by the heading's position rather than a fixed column, since versions add
+// columns and the peak reads 0.00 when the test runs for a duration.
+func ParseWriteBW(out string) (float64, error) {
+	lines := strings.Split(out, "\n")
+	for i, l := range lines {
+		if !strings.Contains(l, "BW average") {
+			continue
+		}
+		heads := columnSplit.Split(strings.TrimSpace(l), -1)
+		col := -1
+		for j, h := range heads {
+			if strings.HasPrefix(h, "BW average") {
+				col = j
+			}
+		}
+		for _, d := range lines[i+1:] {
+			f := strings.Fields(d)
+			if len(f) == 0 || strings.HasPrefix(f[0], "-") {
+				continue
+			}
+			if len(f) != len(heads) || col < 0 {
+				return 0, fmt.Errorf("perftest's result table has a shape this does not know: %q / %q", l, d)
+			}
+			v, err := strconv.ParseFloat(f[col], 64)
+			if err != nil {
+				return 0, fmt.Errorf("reading the average bandwidth %q: %w", f[col], err)
+			}
+			return v, nil
+		}
+	}
+	return 0, errors.New("perftest printed no result")
+}
+
+func lastNonEmpty(s string) string {
+	lines := strings.Split(strings.TrimSpace(s), "\n")
+	return strings.TrimSpace(lines[len(lines)-1])
+}

internal/agent/discovery/perftest_test.go

@@ -0,0 +1,49 @@
+package discovery
+
+import (
+	"slices"
+	"testing"
+)
+
+// The client's output of perftest 24.x, with a duration.
+const writeBWClient = `---------------------------------------------------------------------------------------
+                    RDMA_Write BW Test
+ Dual-port       : OFF		Device         : mlx5_0
+ Number of qps   : 1		Transport type : IB
+ Connection type : RC		Using SRQ      : OFF
+ TX depth        : 128
+ CQ Moderation   : 100
+ Mtu             : 4096[B]
+ Link type       : IB
+ Max inline data : 0[B]
+ rdma_cm QPs	 : OFF
+ Data ex. method : Ethernet
+---------------------------------------------------------------------------------------
+ local address: LID 0x05 QPN 0x0112 PSN 0x7b1f02 RKey 0x1fffbd VAddr 0x007f1d2a5f0000
+ remote address: LID 0x09 QPN 0x0113 PSN 0x2c1e44 RKey 0x1ffeaf VAddr 0x007fa4e1a60000
+---------------------------------------------------------------------------------------
+ #bytes     #iterations    BW peak[Gb/sec]    BW average[Gb/sec]   MsgRate[Mpps]
+ 65536      1851214          0.00               388.21		   0.740422
+---------------------------------------------------------------------------------------
+`
+
+func TestTheAverageBandwidthIsReadFromPerftest(t *testing.T) {
+	got, err := ParseWriteBW(writeBWClient)
+	if err != nil || got != 388.21 {
+		t.Errorf("got %v, %v", got, err)
+	}
+	if _, err := ParseWriteBW(" Couldn't connect to 10.0.0.2:18515\n"); err == nil {
+		t.Error("output with no result table gave a number")
+	}
+}
+
+func TestWriteBWArguments(t *testing.T) {
+	ib := WriteBW{HCA: "mlx5_0", Port: 1, GIDIndex: -1, TCPPort: 18515, Seconds: 3}.Args()
+	if slices.Contains(ib, "-x") {
+		t.Errorf("InfiniBand was given a GID index: %v", ib)
+	}
+	roce := WriteBW{HCA: "mlx5_0", Port: 1, GIDIndex: 3, Peer: "10.0.0.2", TCPPort: 18515, Seconds: 3}.Args()
+	if !slices.Contains(roce, "-x") || roce[len(roce)-1] != "10.0.0.2" {
+		t.Errorf("RoCE client: %v", roce)
+	}
+}

internal/agent/discovery/sminfo.go

@@ -0,0 +1,172 @@
+package discovery
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os/exec"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// ErrNoDiags means infiniband-diags is not installed, so the subnet manager
+// cannot be asked who it is.
+var ErrNoDiags = errors.New("sminfo not found: install infiniband-diags")
+
+// smLine is sminfo's one line of answer:
+//
+//	sminfo: sm lid 1 sm guid 0x98039b03009fcfd6, activity count 5452 priority 15 state 3 SMINFO_MASTER
+var smLine = regexp.MustCompile(`sm lid (\d+) sm guid (0x[0-9a-fA-F]+), activity count \d+ priority (\d+) state \d+ (\S+)`)
+
+// ParseSMInfo reads sminfo's output.
+func ParseSMInfo(out string) (*SMInfo, error) {
+	m := smLine.FindStringSubmatch(out)
+	if m == nil {
+		return nil, fmt.Errorf("unrecognised sminfo output: %q", strings.TrimSpace(out))
+	}
+	lid, _ := strconv.Atoi(m[1])
+	prio, _ := strconv.Atoi(m[3])
+	return &SMInfo{GUID: normalizeGUID(m[2]), LID: lid, Priority: prio, State: m[4]}, nil
+}
+
+// QuerySM asks, through one port, which subnet manager is master. It is a
+// management datagram to the SM, not a scan: cheap, but not free, which is
+// why the agent asks once a minute rather than every heartbeat.
+func QuerySM(ctx context.Context, hca string, port int) (*SMInfo, error) {
+	bin, err := exec.LookPath("sminfo")
+	if err != nil {
+		return nil, ErrNoDiags
+	}
+	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	out, err := exec.CommandContext(ctx, bin, "-C", hca, "-P", strconv.Itoa(port)).CombinedOutput()
+	if err != nil {
+		return nil, fmt.Errorf("sminfo on %s/%d: %w: %s", hca, port, err, strings.TrimSpace(string(out)))
+	}
+	return ParseSMInfo(string(out))
+}
+
+// AttachSM fills in the subnet manager each active InfiniBand port sees.
+// RoCE has none. The first error is returned for reporting; the ports it
+// could answer for keep their answer.
+func AttachSM(hcas []HCA, query func(hca string, port int) (*SMInfo, error)) error {
+	var first error
+	for i := range hcas {
+		for j := range hcas[i].Ports {
+			p := &hcas[i].Ports[j]
+			if !p.Active() || p.LinkLayer == LinkEthernet {
+				continue
+			}
+			sm, err := query(hcas[i].Name, p.Num)
+			if err != nil {
+				if first == nil {
+					first = err
+				}
+				continue
+			}
+			p.SM = sm
+		}
+	}
+	return first
+}
+
+// SMRecord is one subnet manager on a fabric, as the subnet administrator
+// lists them: master and standbys alike.
+type SMRecord struct {
+	GUID     string `json:"guid"`
+	LID      int    `json:"lid"`
+	Priority int    `json:"priority"`
+	// State is master, standby, discovering or not active.
+	State string `json:"state"`
+}
+
+// smStates are SMInfo's state numbers.
+var smStates = map[string]string{"0": "not active", "1": "discovering", "2": "standby", "3": "master"}
+
+// smirField is one line of saquery's record dump: "LID.........1".
+var smirField = regexp.MustCompile(`^\s*([A-Za-z_]+)\.{2,}\s*(\S+)`)
+
+// ParseSMIR reads `saquery SMIR`: every subnet manager the fabric's subnet
+// administrator knows of, one "SMInfoRecord dump:" block each.
+func ParseSMIR(out string) ([]SMRecord, error) {
+	var recs []SMRecord
+	var cur *SMRecord
+	for _, line := range strings.Split(out, "\n") {
+		if strings.Contains(line, "SMInfoRecord dump") {
+			recs = append(recs, SMRecord{})
+			cur = &recs[len(recs)-1]
+			continue
+		}
+		m := smirField.FindStringSubmatch(line)
+		if m == nil || cur == nil {
+			continue
+		}
+		switch strings.ToLower(m[1]) {
+		case "lid":
+			cur.LID, _ = strconv.Atoi(m[2])
+		case "guid":
+			cur.GUID = normalizeGUID(m[2])
+		case "priority":
+			cur.Priority, _ = strconv.Atoi(m[2])
+		case "smstate":
+			cur.State = smStates[m[2]]
+			if cur.State == "" {
+				cur.State = m[2]
+			}
+		}
+	}
+	out2 := recs[:0]
+	for _, r := range recs {
+		if r.GUID != "" {
+			out2 = append(out2, r)
+		}
+	}
+	if len(out2) == 0 {
+		return nil, fmt.Errorf("no subnet manager records in saquery output")
+	}
+	return out2, nil
+}
+
+// QuerySMs asks the subnet administrator, through one port, for every subnet
+// manager on the fabric.
+func QuerySMs(ctx context.Context, hca string, port int) ([]SMRecord, error) {
+	bin, err := exec.LookPath("saquery")
+	if err != nil {
+		return nil, ErrNoDiags
+	}
+	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	out, err := exec.CommandContext(ctx, bin, "-C", hca, "-P", strconv.Itoa(port), "SMIR").CombinedOutput()
+	if err != nil {
+		return nil, fmt.Errorf("saquery on %s/%d: %w: %s", hca, port, err, strings.TrimSpace(string(out)))
+	}
+	return ParseSMIR(string(out))
+}
+
+// ScanFabric maps the fabric a port is on with ibnetdiscover: every switch,
+// adapter and link. It can take a while on a large fabric, so it is bounded,
+// and its output is capped: a fabric of thousands of ports is a few
+// megabytes of text.
+func ScanFabric(ctx context.Context, hca string, port int) (string, error) {
+	bin, err := exec.LookPath("ibnetdiscover")
+	if err != nil {
+		return "", ErrNoDiags
+	}
+	ctx, cancel := context.WithTimeout(ctx, 2*time.Minute)
+	defer cancel()
+	out, err := exec.CommandContext(ctx, bin, "-C", hca, "-P", strconv.Itoa(port)).Output()
+	if err != nil {
+		var ee *exec.ExitError
+		if errors.As(err, &ee) {
+			return "", fmt.Errorf("ibnetdiscover on %s/%d: %w: %s", hca, port, err, strings.TrimSpace(string(ee.Stderr)))
+		}
+		return "", fmt.Errorf("ibnetdiscover on %s/%d: %w", hca, port, err)
+	}
+	const limit = 16 << 20
+	if len(out) > limit {
+		return "", fmt.Errorf("ibnetdiscover printed %d MB, more than the %d MB a scan may send", len(out)>>20, limit>>20)
+	}
+	return string(out), nil
+}

internal/agent/discovery/topo.go

@@ -0,0 +1,185 @@
+package discovery
+
+import (
+	"context"
+	"fmt"
+	"os/exec"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// Topology is what `nvidia-smi topo -m` says about how a node's GPUs and
+// network adapters are wired together.
+//
+// Read from nvidia-smi rather than NVML so the portable, cgo-free binary knows
+// it too. Without it that binary saw no NVLink at all: every GPU reported no
+// peers, and a tensor-parallel group was chosen by index on machines where
+// NVLink decides whether it runs at full speed.
+type Topology struct {
+	// NVLink is, per GPU, the GPUs it reaches over NVLink and how many links
+	// are bonded to each.
+	NVLink map[int]map[int]int
+	// NICPath is, per GPU, how far each network adapter is, by its HCA name:
+	// PIX, PXB, PHB, NODE or SYS, nearest first. A GPU should talk to the
+	// fabric through the adapter nearest it; one across the socket costs a
+	// trip over the processor interconnect on every transfer.
+	NICPath map[int]map[string]string
+	// NUMA is the NUMA node each GPU is attached to, where reported.
+	NUMA map[int]int
+}
+
+// PathRank orders the relations nvidia-smi reports, nearest first. Lower is
+// closer; an unknown relation ranks last.
+func PathRank(rel string) int {
+	switch strings.ToUpper(rel) {
+	case "PIX":
+		return 0
+	case "PXB":
+		return 1
+	case "PHB":
+		return 2
+	case "NODE":
+		return 3
+	case "SYS":
+		return 4
+	}
+	return 5
+}
+
+// DiscoverTopology runs `nvidia-smi topo -m`. A node without nvidia-smi has
+// no topology to report, which is not an error.
+func DiscoverTopology(ctx context.Context, binary string) (Topology, error) {
+	if binary == "" {
+		if _, err := exec.LookPath("nvidia-smi"); err != nil {
+			return Topology{}, nil
+		}
+		binary = "nvidia-smi"
+	}
+	out, err := exec.CommandContext(ctx, binary, "topo", "-m").Output()
+	if err != nil {
+		return Topology{}, fmt.Errorf("running %s topo -m: %w", binary, err)
+	}
+	return parseTopo(string(out))
+}
+
+// ParseTopology reads `nvidia-smi topo -m` output.
+func ParseTopology(out string) (Topology, error) { return parseTopo(out) }
+
+var (
+	ansi       = regexp.MustCompile(`\x1b\[[0-9;]*m`)
+	nvLinks    = regexp.MustCompile(`^NV(\d+)$`)
+	nicLegend  = regexp.MustCompile(`^\s*(NIC\d+)\s*:\s*(\S+)\s*$`)
+	gpuColumn  = regexp.MustCompile(`^GPU(\d+)$`)
+	numaColumn = "NUMA Affinity"
+)
+
+// parseTopo reads the matrix. Columns are tab-separated; the header names
+// each one — GPUn, then the adapters, as NICn with a legend below on newer
+// drivers or by HCA name on older ones — then CPU and NUMA affinity.
+func parseTopo(out string) (Topology, error) {
+	out = ansi.ReplaceAllString(out, "")
+	lines := strings.Split(out, "\n")
+
+	legend := map[string]string{}
+	for _, l := range lines {
+		if m := nicLegend.FindStringSubmatch(l); m != nil {
+			legend[m[1]] = m[2]
+		}
+	}
+
+	var header []string
+	start := -1
+	for i, l := range lines {
+		cells := splitTabs(l)
+		if len(cells) > 1 && cells[0] == "" && gpuColumn.MatchString(cells[1]) {
+			header, start = cells, i
+			break
+		}
+	}
+	if start < 0 {
+		return Topology{}, fmt.Errorf("no GPU matrix in nvidia-smi topo output")
+	}
+
+	t := Topology{NVLink: map[int]map[int]int{}, NICPath: map[int]map[string]string{}, NUMA: map[int]int{}}
+	for _, l := range lines[start+1:] {
+		cells := splitTabs(l)
+		if len(cells) < 2 {
+			// The matrix ends at the first blank line, before the legend.
+			if strings.TrimSpace(l) == "" {
+				break
+			}
+			continue
+		}
+		m := gpuColumn.FindStringSubmatch(cells[0])
+		if m == nil {
+			continue // an adapter's row: its view of the GPUs is the same matrix
+		}
+		gpu, _ := strconv.Atoi(m[1])
+		for c := 1; c < len(cells) && c < len(header); c++ {
+			col, v := header[c], strings.TrimSpace(cells[c])
+			switch {
+			case gpuColumn.MatchString(col):
+				peer, _ := strconv.Atoi(gpuColumn.FindStringSubmatch(col)[1])
+				if n := nvLinks.FindStringSubmatch(v); n != nil && peer != gpu {
+					links, _ := strconv.Atoi(n[1])
+					if t.NVLink[gpu] == nil {
+						t.NVLink[gpu] = map[int]int{}
+					}
+					t.NVLink[gpu][peer] = links
+				}
+			case col == numaColumn:
+				if n, err := strconv.Atoi(v); err == nil {
+					t.NUMA[gpu] = n
+				}
+			case col == "CPU Affinity" || col == "GPU NUMA ID" || col == "":
+			default:
+				// An adapter: NICn named by the legend, or an HCA by name.
+				hca := col
+				if name, ok := legend[col]; ok {
+					hca = name
+				}
+				if PathRank(v) < 5 {
+					if t.NICPath[gpu] == nil {
+						t.NICPath[gpu] = map[string]string{}
+					}
+					t.NICPath[gpu][hca] = strings.ToUpper(v)
+				}
+			}
+		}
+	}
+	if len(t.NVLink) == 0 && len(t.NICPath) == 0 && len(t.NUMA) == 0 {
+		return t, fmt.Errorf("the nvidia-smi topo matrix had no rows")
+	}
+	return t, nil
+}
+
+func splitTabs(l string) []string {
+	l = strings.TrimRight(l, "\r")
+	cells := strings.Split(l, "\t")
+	for i := range cells {
+		cells[i] = strings.TrimSpace(cells[i])
+	}
+	return cells
+}
+
+// Apply puts the topology on the GPUs it describes. What a GPU already knows
+// — NVLink peers from NVML, which is the more exact source — is kept.
+func (t Topology) Apply(gpus []GPU) {
+	for i := range gpus {
+		g := &gpus[i]
+		if len(g.NVLinkPeers) == 0 {
+			for peer := range t.NVLink[g.Index] {
+				g.NVLinkPeers = append(g.NVLinkPeers, peer)
+			}
+			sort.Ints(g.NVLinkPeers)
+		}
+		if n, ok := t.NUMA[g.Index]; ok {
+			g.NUMANode = n
+		}
+		if paths := t.NICPath[g.Index]; len(paths) > 0 {
+			g.NICPaths = paths
+		}
+	}
+}

internal/agent/discovery/topo_test.go

@@ -0,0 +1,113 @@
+package discovery
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// row joins cells the way nvidia-smi prints them: tab-separated, each padded.
+func row(cells ...string) string { return strings.Join(cells, "\t") }
+
+// dgxH100 is `nvidia-smi topo -m` on an eight-GPU NVSwitch machine with two
+// adapters, as newer drivers print it: NICn columns and a legend naming them.
+var dgxH100 = strings.Join([]string{
+	row("\x1b[4m", "GPU0", "GPU1", "GPU2", "GPU3", "NIC0", "NIC1", "CPU Affinity", "NUMA Affinity", "GPU NUMA ID\x1b[0m"),
+	row("GPU0", " X ", "NV18", "NV18", "NV18", "PXB", "SYS", "0-55,112-167", "0", "N/A"),
+	row("GPU1", "NV18", " X ", "NV18", "NV18", "PXB", "SYS", "0-55,112-167", "0", "N/A"),
+	row("GPU2", "NV18", "NV18", " X ", "NV18", "SYS", "PXB", "56-111,168-223", "1", "N/A"),
+	row("GPU3", "NV18", "NV18", "NV18", " X ", "SYS", "PIX", "56-111,168-223", "1", "N/A"),
+	row("NIC0", "PXB", "PXB", "SYS", "SYS", " X ", "SYS"),
+	row("NIC1", "SYS", "SYS", "PXB", "PIX", "SYS", " X "),
+	"",
+	"Legend:",
+	"",
+	"  X    = Self",
+	"  SYS  = Connection traversing PCIe as well as the SMP interconnect between NUMA nodes (e.g., QPI/UPI)",
+	"  NV#  = Connection traversing a bonded set of # NVLinks",
+	"",
+	"NIC Legend:",
+	"",
+	"  NIC0: mlx5_0",
+	"  NIC1: mlx5_1",
+	"",
+}, "\n")
+
+func TestNVLinkAndAdapterDistanceAreReadFromTopo(t *testing.T) {
+	topo, err := parseTopo(dgxH100)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := topo.NVLink[0]; !reflect.DeepEqual(got, map[int]int{1: 18, 2: 18, 3: 18}) {
+		t.Errorf("GPU0's NVLink peers = %v", got)
+	}
+	// The legend turns NIC1 into the adapter's own name.
+	if got := topo.NICPath[3]; !reflect.DeepEqual(got, map[string]string{"mlx5_0": "SYS", "mlx5_1": "PIX"}) {
+		t.Errorf("GPU3's adapters = %v", got)
+	}
+	if topo.NUMA[2] != 1 || topo.NUMA[0] != 0 {
+		t.Errorf("NUMA = %v", topo.NUMA)
+	}
+
+	gpus := []GPU{{Index: 0}, {Index: 3}}
+	topo.Apply(gpus)
+	if !reflect.DeepEqual(gpus[0].NVLinkPeers, []int{1, 2, 3}) || gpus[1].NUMANode != 1 ||
+		gpus[1].NICPaths["mlx5_1"] != "PIX" {
+		t.Errorf("applied = %+v", gpus)
+	}
+}
+
+func TestOlderDriversNameAdaptersInTheHeader(t *testing.T) {
+	// No legend: the columns are the adapters' own names, and NVLink between
+	// pairs only, as on an A100 PCIe box with bridges.
+	out := strings.Join([]string{
+		row("", "GPU0", "GPU1", "GPU2", "GPU3", "mlx5_0", "CPU Affinity", "NUMA Affinity"),
+		row("GPU0", " X ", "NV12", "SYS", "SYS", "NODE", "0-31", "0"),
+		row("GPU1", "NV12", " X ", "SYS", "SYS", "NODE", "0-31", "0"),
+		row("GPU2", "SYS", "SYS", " X ", "NV12", "SYS", "32-63", "1"),
+		row("GPU3", "SYS", "SYS", "NV12", " X ", "SYS", "32-63", "1"),
+		row("mlx5_0", "NODE", "NODE", "SYS", "SYS", " X "),
+		"",
+	}, "\n")
+	topo, err := parseTopo(out)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(topo.NVLink[2], map[int]int{3: 12}) || len(topo.NVLink[0]) != 1 {
+		t.Errorf("NVLink = %v", topo.NVLink)
+	}
+	if topo.NICPath[0]["mlx5_0"] != "NODE" {
+		t.Errorf("adapters = %v", topo.NICPath)
+	}
+}
+
+func TestAPCIeMachineHasNoNVLink(t *testing.T) {
+	out := strings.Join([]string{
+		row("", "GPU0", "GPU1", "CPU Affinity", "NUMA Affinity"),
+		row("GPU0", " X ", "PHB", "0-15", "0"),
+		row("GPU1", "PHB", " X ", "0-15", "0"),
+		"",
+	}, "\n")
+	topo, err := parseTopo(out)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(topo.NVLink) != 0 {
+		t.Errorf("NVLink on a PCIe machine: %v", topo.NVLink)
+	}
+}
+
+func TestNVMLPeersAreKeptOverTopo(t *testing.T) {
+	topo, _ := parseTopo(dgxH100)
+	gpus := []GPU{{Index: 0, NVLinkPeers: []int{1}}}
+	topo.Apply(gpus)
+	if !reflect.DeepEqual(gpus[0].NVLinkPeers, []int{1}) {
+		t.Errorf("NVML's answer was replaced: %v", gpus[0].NVLinkPeers)
+	}
+}
+
+func TestSomethingThatIsNotAMatrixIsAnError(t *testing.T) {
+	if _, err := parseTopo("NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver."); err == nil {
+		t.Error("expected an error")
+	}
+}

internal/agent/engines/engine.go

@@ -63,13 +63,28 @@ type ShardSpec struct {
 	HCAs []string
 	// MgmtInterface is the ethernet interface used for bootstrap traffic.
 	MgmtInterface string
+	// GIDIndex is the RoCE v2 GID index for the HCAs, set by the agent when
+	// they are RoCE; nil on InfiniBand, where NCCL needs none.
+	GIDIndex *int
 
 	HTTPPort int
 	Profile  Profile
 
+	// APIKey is what the engine demands of every request. Engines listen on
+	// all of a node's addresses; without a key anybody who can reach the port
+	// talks to the model directly, past the gateway's authentication, quotas
+	// and accounting. Given to the engine in its environment rather than on
+	// its command line, which every user on the node can read.
+	APIKey string `json:"api_key,omitempty"`
+	// Threads is the CPU cores placement reserved for a shard with no GPU,
+	// and so what its engine computes on. Zero leaves it to the engine's own
+	// configuration.
+	Threads int `json:"threads,omitempty"`
+
 	// Pool and Fabric are control plane concepts the agent cannot derive. They
-	// are carried so the agent can report them back after a restart, and are
-	// not used when building a command.
+	// are carried so the agent can report them back after a restart; Fabric
+	// also says, with an "nvl:" prefix, that the replica is inside a
+	// multi-node NVLink domain, which changes NCCL's environment.
 	Pool   string
 	Fabric string
 	// ProfileFP identifies the version of the profile this shard was started
@@ -193,6 +208,10 @@ type Config struct {
 
 // --- shared helpers ---
 
+// NCCLEnv is the environment a shard with this spec is given, for a tool that
+// shows an operator what an engine would see.
+func NCCLEnv(s ShardSpec) map[string]string { return baseEnv(s) }
+
 // baseEnv builds the environment every engine shares.
 //
 // This is the part of §5.3 the plan marks critical. The rules encoded here:
@@ -215,11 +234,24 @@ func baseEnv(s ShardSpec) map[string]string {
 	if len(s.HCAs) > 0 {
 		env["NCCL_IB_HCA"] = strings.Join(s.HCAs, ",")
 		env["NCCL_IB_DISABLE"] = "0"
+		// RoCE: the index of the routable RoCE v2 entry. NCCL's default is a
+		// v1 link-local one on most hosts, and a job on it hangs.
+		if s.GIDIndex != nil {
+			env["NCCL_IB_GID_INDEX"] = strconv.Itoa(*s.GIDIndex)
+		}
 	} else {
 		// Single node, or a node with no fabric. Either way IB is not the path.
 		env["NCCL_IB_DISABLE"] = "1"
 	}
 
+	// Placed inside a multi-node NVLink domain: NCCL is to carry the
+	// replica's collectives over NVLink between its nodes, which it only
+	// does when told to, and needs IMEX for.
+	if s.NNodes > 1 && strings.HasPrefix(s.Fabric, "nvl:") {
+		env["NCCL_MNNVL_ENABLE"] = "1"
+		env["NCCL_CUMEM_ENABLE"] = "1"
+	}
+
 	if s.MgmtInterface != "" {
 		env["NCCL_SOCKET_IFNAME"] = s.MgmtInterface
 		env["GLOO_SOCKET_IFNAME"] = s.MgmtInterface
@@ -228,6 +260,11 @@ func baseEnv(s ShardSpec) map[string]string {
 	// Profile overrides win: they are the escape hatch for the per-cluster
 	// tuning no adapter can guess.
 	for k, v := range s.Profile.Env {
+		// Checked again here, not only where the model was defined: this is
+		// the process about to run as root, whatever sent the profile.
+		if bad, _ := UnsafeEnv(k); bad {
+			continue
+		}
 		env[k] = v
 	}
 	return env

internal/agent/engines/engines_test.go

@@ -3,6 +3,7 @@ package engines
 import (
 	"fmt"
 	"slices"
+	"strconv"
 	"strings"
 	"testing"
 )
@@ -243,14 +244,41 @@ func TestVLLMRayWorkerRunsOnlyRay(t *testing.T) {
 }
 
 func TestVLLMMPMode(t *testing.T) {
+	// vLLM's multi-node launch: every node the same serve with its rank and
+	// the leader's address, workers headless. Workers used to be given the
+	// leader's address as their own VLLM_HOST_IP, and no rank at all.
 	v := &VLLM{cfg: VLLMConfig{LaunchMode: "mp"}}
-	cmd := buildOne(t, v, multiNodeSpec(0))
-	if argValue(cmd.Args, "--distributed-executor-backend") != "mp" {
-		t.Errorf("backend not set: %v", cmd.Args)
+	for _, rank := range []int{0, 1} {
+		cmd := buildOne(t, v, multiNodeSpec(rank))
+		for flag, want := range map[string]string{
+			"--distributed-executor-backend": "mp", "--nnodes": "2",
+			"--node-rank": strconv.Itoa(rank), "--master-addr": "10.0.0.10", "--master-port": "20001",
+		} {
+			if got := argValue(cmd.Args, flag); got != want {
+				t.Errorf("rank %d: %s = %q, want %q (%v)", rank, flag, got, want, cmd.Args)
+			}
+		}
+		if headless := slices.Contains(cmd.Args, "--headless"); headless != (rank > 0) {
+			t.Errorf("rank %d: headless = %v", rank, headless)
+		}
+		if ip, ok := envMap(cmd.Env)["VLLM_HOST_IP"]; ok && ip == "10.0.0.10" && rank > 0 {
+			t.Errorf("a worker was told the leader's address is its own")
+		}
 	}
-	env := envMap(cmd.Env)
-	if env["VLLM_HOST_IP"] != "10.0.0.10" || env["VLLM_PORT"] != "20001" {
-		t.Errorf("dist init not configured: %q %q", env["VLLM_HOST_IP"], env["VLLM_PORT"])
+}
+
+func TestRoCEGetsItsGIDIndex(t *testing.T) {
+	s := multiNodeSpec(0)
+	idx := 3
+	s.GIDIndex = &idx
+	env := envMap(buildOne(t, &VLLM{cfg: VLLMConfig{LaunchMode: "mp"}}, s).Env)
+	if env["NCCL_IB_GID_INDEX"] != "3" {
+		t.Errorf("NCCL_IB_GID_INDEX = %q", env["NCCL_IB_GID_INDEX"])
+	}
+	// InfiniBand needs none, and must not be given one.
+	env = envMap(buildOne(t, &VLLM{cfg: VLLMConfig{LaunchMode: "mp"}}, multiNodeSpec(0)).Env)
+	if _, ok := env["NCCL_IB_GID_INDEX"]; ok {
+		t.Error("an InfiniBand shard was given a GID index")
 	}
 }
 
@@ -423,3 +451,28 @@ func TestQuantizationOf(t *testing.T) {
 		t.Errorf("a dangling flag should yield nothing, got %q", got)
 	}
 }
+
+func TestAReplicaInAnNVLinkDomainIsToldToUseIt(t *testing.T) {
+	s := multiNodeSpec(0)
+	s.Fabric = "nvl:76b1ad76-7c24-4b6b-9f6c-2a1e0d8c11aa/7"
+	env := envMap(buildOne(t, &VLLM{cfg: VLLMConfig{LaunchMode: "mp"}}, s).Env)
+	if env["NCCL_MNNVL_ENABLE"] != "1" {
+		t.Errorf("NCCL_MNNVL_ENABLE = %q", env["NCCL_MNNVL_ENABLE"])
+	}
+	if env := envMap(buildOne(t, &VLLM{cfg: VLLMConfig{LaunchMode: "mp"}}, multiNodeSpec(0)).Env); env["NCCL_MNNVL_ENABLE"] != "" {
+		t.Error("a replica on InfiniBand was told to use multi-node NVLink")
+	}
+}
+
+func TestMultiNodeVLLMDefaultsToItsOwnLaunch(t *testing.T) {
+	// mp is what vLLM documents and needs nothing but vLLM; Ray was the
+	// default and was never checked against a real cluster.
+	cmds, err := (&VLLM{}).Commands(multiNodeSpec(1))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(cmds) != 1 || cmds[0].Name != "vllm" || argValue(cmds[0].Args, "--distributed-executor-backend") != "mp" ||
+		!slices.Contains(cmds[0].Args, "--headless") {
+		t.Errorf("default worker = %+v", cmds)
+	}
+}

internal/agent/engines/llamacpp.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"runtime"
 	"sort"
 	"strconv"
 	"strings"
@@ -21,8 +22,21 @@ type LlamaCppConfig struct {
 	// does not say. llama.cpp defaults to one, which would make every second
 	// request wait behind the first no matter what the router decided.
 	Parallel int `koanf:"parallel"`
+	// Threads is how many CPU threads a shard with no GPU computes on. Zero
+	// takes half this machine's CPUs.
+	//
+	// Not all of them, which is llama.cpp's own default: two busy servers
+	// that each spin on every CPU fight for them, and on an 8-vCPU node
+	// that made 7B generation fall from 10 tokens a second to under 1 each.
+	// At half, one server alone is about a third slower and two together
+	// keep 5.5 each. A node that only ever runs one CPU replica does better
+	// with all of them; say so here.
+	Threads int `koanf:"threads"`
 }
 
+// numCPU is the CPUs this process may run on; a variable for tests.
+var numCPU = runtime.NumCPU
+
 // LlamaCpp builds llama.cpp launch commands.
 //
 // It is the engine that makes a cluster without GPUs useful: llama.cpp runs a
@@ -118,10 +132,26 @@ func (l *LlamaCpp) Commands(s ShardSpec) ([]Command, error) {
 	if len(s.GPUIndices) > 0 && !hasFlag(p.Args, "--n-gpu-layers", "-ngl") {
 		args = append(args, "--n-gpu-layers", "999")
 	}
+	if len(s.GPUIndices) == 0 && !hasFlag(p.Args, "--threads", "-t") {
+		// What placement reserved first: it is what the node's other
+		// replicas were placed around.
+		n := s.Threads
+		if n <= 0 {
+			n = l.cfg.Threads
+		}
+		if n <= 0 {
+			n = max(numCPU()/2, 1)
+		}
+		args = append(args, "--threads", strconv.Itoa(n))
+	}
 	args = append(args, p.Args...)
 
+	env := baseEnv(s)
+	if s.APIKey != "" {
+		env["LLAMA_API_KEY"] = s.APIKey
+	}
 	return []Command{{
-		Name: "llama-server", Path: bin, Args: args, Env: materializeEnv(baseEnv(s)),
+		Name: "llama-server", Path: bin, Args: args, Env: materializeEnv(env),
 	}}, nil
 }
 

internal/agent/engines/llamacpp_test.go

@@ -245,3 +245,64 @@ func TestAMissingPathIsLeftToTheEngine(t *testing.T) {
 		t.Errorf("expected it passed through, got %q %v", got, err)
 	}
 }
+
+func TestLlamaCppIsGivenItsKeyOutOfSightOfTheProcessList(t *testing.T) {
+	// The command line is readable by every user on the node; the
+	// environment of a root process is not.
+	cmds, err := (&LlamaCpp{}).Commands(ShardSpec{HTTPPort: 8080, APIKey: "k1",
+		Profile: Profile{ModelPath: "/m.gguf"}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if slices.Contains(cmds[0].Args, "k1") || slices.Contains(cmds[0].Args, "--api-key") {
+		t.Errorf("the key is on the command line: %v", cmds[0].Args)
+	}
+	if !slices.Contains(cmds[0].Env, "LLAMA_API_KEY=k1") {
+		t.Error("llama-server was not given its key")
+	}
+}
+
+func TestACPUShardLeavesHalfTheMachineForAnother(t *testing.T) {
+	prev := numCPU
+	numCPU = func() int { return 8 }
+	t.Cleanup(func() { numCPU = prev })
+
+	threads := func(l *LlamaCpp, s ShardSpec) (string, bool) {
+		cmds, err := l.Commands(s)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return flagValue(cmds[0].Args, "--threads")
+	}
+	if v, _ := threads(&LlamaCpp{}, llamaSpec(nil)); v != "4" {
+		t.Errorf("--threads %q on 8 CPUs, expected 4", v)
+	}
+	if v, _ := threads(&LlamaCpp{cfg: LlamaCppConfig{Threads: 8}}, llamaSpec(nil)); v != "8" {
+		t.Errorf("--threads %q with 8 configured", v)
+	}
+	if _, ok := threads(&LlamaCpp{}, llamaSpec([]int{0})); ok {
+		t.Error("a GPU shard was given a thread count")
+	}
+	s := llamaSpec(nil)
+	s.Profile.Args = []string{"-t", "2"}
+	cmds, _ := (&LlamaCpp{}).Commands(s)
+	if slices.Contains(cmds[0].Args, "--threads") {
+		t.Error("the profile's own -t was overridden")
+	}
+	numCPU = func() int { return 1 }
+	if v, _ := threads(&LlamaCpp{}, llamaSpec(nil)); v != "1" {
+		t.Errorf("--threads %q on one CPU", v)
+	}
+}
+
+func TestTheCoresPlacementReservedAreTheThreads(t *testing.T) {
+	s := llamaSpec(nil)
+	s.Threads = 3
+	cmds, err := (&LlamaCpp{cfg: LlamaCppConfig{Threads: 8}}).Commands(s)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if v, _ := flagValue(cmds[0].Args, "--threads"); v != "3" {
+		t.Errorf("--threads %q; what placement reserved should win over the node's setting", v)
+	}
+}

internal/agent/engines/probe.go

@@ -202,11 +202,7 @@ func (g *SGLang) Configured() bool { return g.cfg.Python != "" }
 
 // Probe reports whether vLLM is installed.
 func (v *VLLM) Probe(context.Context) (string, error) {
-	bin := v.cfg.Bin
-	if bin == "" {
-		bin = "vllm"
-	}
-	return installedBinary(bin)
+	return installedBinary(v.bin())
 }
 
 // Probe reports the SGLang version.
@@ -215,10 +211,6 @@ func (v *VLLM) Probe(context.Context) (string, error) {
 // asking the shell for "sglang" finds nothing on a machine that can run it
 // perfectly well.
 func (g *SGLang) Probe(ctx context.Context) (string, error) {
-	python := g.cfg.Python
-	if python == "" {
-		python = "python3"
-	}
-	return versionOfModule(ctx, python, "-c",
+	return versionOfModule(ctx, g.python(), "-c",
 		"import sglang, sys; sys.stdout.write(getattr(sglang, '__version__', ''))")
 }

internal/agent/engines/sglang.go

@@ -1,6 +1,9 @@
 package engines
 
-import "strconv"
+import (
+	"strconv"
+	"sync/atomic"
+)
 
 // SGLangConfig locates the SGLang installation.
 type SGLangConfig struct {
@@ -11,7 +14,25 @@ type SGLangConfig struct {
 }
 
 // SGLang builds SGLang launch commands.
-type SGLang struct{ cfg SGLangConfig }
+type SGLang struct {
+	cfg       SGLangConfig
+	installed atomic.Pointer[string]
+}
+
+// UseInstalled points the engine at the interpreter of the environment the
+// agent installed and checked, ahead of the configuration.
+func (g *SGLang) UseInstalled(path string) { g.installed.Store(&path) }
+
+// python is the interpreter to launch SGLang with.
+func (g *SGLang) python() string {
+	if p := g.installed.Load(); p != nil {
+		return *p
+	}
+	if g.cfg.Python != "" {
+		return g.cfg.Python
+	}
+	return "python3"
+}
 
 // Name identifies the engine in the catalog.
 func (*SGLang) Name() string { return "sglang" }
@@ -55,10 +76,7 @@ func (g *SGLang) Commands(s ShardSpec) ([]Command, error) {
 }
 
 func (g *SGLang) serverCommand(s ShardSpec) (Command, error) {
-	python := g.cfg.Python
-	if python == "" {
-		python = "python3"
-	}
+	python := g.python()
 	p := s.Profile
 
 	args := []string{"-m", "sglang.launch_server",
@@ -78,6 +96,11 @@ func (g *SGLang) serverCommand(s ShardSpec) (Command, error) {
 		)
 	}
 	args = append(args, p.Args...)
+	// SGLang reads its key only from the command line, so on a node with
+	// other users it is visible to them in the process list.
+	if s.APIKey != "" && s.Leader() {
+		args = append(args, "--api-key", s.APIKey)
+	}
 
 	return Command{Name: "sglang", Path: python, Args: args, Env: materializeEnv(baseEnv(s))}, nil
 }

internal/agent/engines/unsafeenv.go

@@ -0,0 +1,30 @@
+package engines
+
+import "strings"
+
+// UnsafeEnv reports whether a profile may not set an environment variable,
+// and why.
+//
+// A profile's env is the escape hatch for tuning no adapter can guess —
+// CUDA_*, NCCL_*, VLLM_*, HF_* — and it reaches an engine the agent starts as
+// root. Some variables are not tuning but a way to run other code in that
+// process: the dynamic loader's LD_PRELOAD, Python's PYTHONSTARTUP, a shell's
+// BASH_ENV. Set from a model definition, which an admin API or a config file
+// supplies, they would turn "add a model" into "run this as root on every
+// node". They are refused where a model is defined and again where an engine
+// starts.
+func UnsafeEnv(key string) (bool, string) {
+	k := strings.ToUpper(key)
+	switch {
+	case strings.HasPrefix(k, "LD_"), strings.HasPrefix(k, "DYLD_"):
+		return true, "it changes what the dynamic loader loads"
+	case k == "PATH":
+		return true, "it changes which binaries run"
+	case strings.HasPrefix(k, "PYTHON") && k != "PYTHONUNBUFFERED" && k != "PYTHONHASHSEED":
+		return true, "it changes what Python imports or runs at start"
+	case k == "BASH_ENV" || k == "ENV" || k == "PERL5OPT" || k == "PERL5LIB" ||
+		k == "NODE_OPTIONS" || k == "RUBYOPT" || k == "GCONV_PATH" || k == "OPENSSL_CONF":
+		return true, "it makes an interpreter or library load code"
+	}
+	return false, ""
+}

internal/agent/engines/vllm.go

@@ -3,24 +3,48 @@ package engines
 import (
 	"fmt"
 	"strconv"
+	"sync/atomic"
 )
 
 // VLLMConfig locates the vLLM installation and picks how it is launched.
 type VLLMConfig struct {
 	// Bin is the vllm executable.
 	Bin string `koanf:"bin"`
-	// LaunchMode selects the multi-node mechanism: "ray" or "mp".
+	// LaunchMode selects the multi-node mechanism: "mp", the default, or
+	// "ray".
 	//
-	// Which one works depends on the vLLM version, and the flags have changed
-	// more than once (plan §14). Both paths exist so a cluster can pick the one
-	// its version supports instead of waiting for a code change.
+	// mp is what vLLM documents today — every node runs serve with its rank,
+	// the workers headless — and needs nothing but vLLM. ray is the older way,
+	// kept for a vLLM too old for mp's multi-node flags; it needs Ray on every
+	// node and has not been checked against a real cluster.
 	LaunchMode string `koanf:"launch_mode"`
 	// RayBin is used when LaunchMode is "ray".
 	RayBin string `koanf:"ray_bin"`
 }
 
 // VLLM builds vLLM launch commands.
-type VLLM struct{ cfg VLLMConfig }
+type VLLM struct {
+	cfg       VLLMConfig
+	installed atomic.Pointer[string]
+}
+
+// UseInstalled points the engine at the environment the agent installed and
+// checked. It takes precedence over the configuration, as llama.cpp's does:
+// it is the one seen to run. An operator who wants their own sets the
+// control plane's engines.vllm to "".
+func (v *VLLM) UseInstalled(path string) { v.installed.Store(&path) }
+
+// bin is the vllm to run: the installed one, else the configured one, else
+// whatever PATH has.
+func (v *VLLM) bin() string {
+	if p := v.installed.Load(); p != nil {
+		return *p
+	}
+	if v.cfg.Bin != "" {
+		return v.cfg.Bin
+	}
+	return "vllm"
+}
 
 // Name identifies the engine in the catalog.
 func (*VLLM) Name() string { return "vllm" }
@@ -78,10 +102,7 @@ func (v *VLLM) Commands(s ShardSpec) ([]Command, error) {
 
 // serverCommand produces the vLLM server process.
 func (v *VLLM) serverCommand(s ShardSpec) (Command, error) {
-	bin := v.cfg.Bin
-	if bin == "" {
-		bin = "vllm"
-	}
+	bin := v.bin()
 	p := s.Profile
 
 	args := []string{"serve", p.ModelPath,
@@ -100,16 +121,27 @@ func (v *VLLM) serverCommand(s ShardSpec) (Command, error) {
 
 	if s.NNodes > 1 {
 		switch v.cfg.LaunchMode {
-		case "", "ray":
+		case "ray":
 			// Ray is started separately by the supervisor; vLLM then finds the
 			// cluster through the address in the environment.
 			env["VLLM_HOST_IP"] = s.LeaderAddr
 			env["RAY_ADDRESS"] = fmt.Sprintf("%s:%d", s.LeaderAddr, s.LeaderPort)
 			args = append(args, "--distributed-executor-backend", "ray")
-		case "mp":
-			env["VLLM_HOST_IP"] = s.LeaderAddr
-			env["VLLM_PORT"] = strconv.Itoa(s.LeaderPort)
-			args = append(args, "--distributed-executor-backend", "mp")
+		case "", "mp":
+			// vLLM's own multi-node launch: every node runs the same serve
+			// with its rank and the leader's address, and the workers run
+			// headless — no API server, only their GPUs. VLLM_HOST_IP is
+			// this node's address for vLLM to find itself, so it is left
+			// to vLLM; the leader's, which workers used to be given, made
+			// every worker announce itself as the leader.
+			args = append(args, "--distributed-executor-backend", "mp",
+				"--nnodes", strconv.Itoa(s.NNodes),
+				"--node-rank", strconv.Itoa(s.Rank),
+				"--master-addr", s.LeaderAddr,
+				"--master-port", strconv.Itoa(s.LeaderPort))
+			if !s.Leader() {
+				args = append(args, "--headless")
+			}
 		default:
 			return Command{}, fmt.Errorf("vllm: unknown launch_mode %q (want \"ray\" or \"mp\")", v.cfg.LaunchMode)
 		}
@@ -118,13 +150,16 @@ func (v *VLLM) serverCommand(s ShardSpec) (Command, error) {
 	// Profile arguments last, so an operator can override anything above.
 	args = append(args, p.Args...)
 
+	if s.APIKey != "" {
+		env["VLLM_API_KEY"] = s.APIKey
+	}
 	return Command{Name: "vllm", Path: bin, Args: args, Env: materializeEnv(env)}, nil
 }
 
 // rayCommand returns the command that starts or joins the Ray cluster, or
 // ok=false when the launch mode does not use Ray.
 func (v *VLLM) rayCommand(s ShardSpec) (Command, bool) {
-	if s.NNodes <= 1 || (v.cfg.LaunchMode != "" && v.cfg.LaunchMode != "ray") {
+	if s.NNodes <= 1 || v.cfg.LaunchMode != "ray" {
 		return Command{}, false
 	}
 	bin := v.cfg.RayBin
@@ -134,7 +169,10 @@ func (v *VLLM) rayCommand(s ShardSpec) (Command, bool) {
 
 	args := []string{"start", "--block"}
 	if s.Leader() {
-		args = append(args, "--head", "--port", strconv.Itoa(s.LeaderPort))
+		// Ray's head has no authentication: whoever reaches its port can run
+		// code on the node. Its dashboard, and the job API behind it, is the
+		// easiest way in, and nothing here uses it.
+		args = append(args, "--head", "--port", strconv.Itoa(s.LeaderPort), "--include-dashboard=false")
 	} else {
 		args = append(args, "--address", fmt.Sprintf("%s:%d", s.LeaderAddr, s.LeaderPort))
 	}

internal/agent/fabrics.go

@@ -0,0 +1,345 @@
+package agent
+
+import (
+	"context"
+	"fmt"
+	"os/exec"
+	"slices"
+	"strconv"
+	"strings"
+	"time"
+
+	llmgwv1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/discovery"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/inventory"
+)
+
+// usableFabrics reports the fabrics this node can actually carry traffic on.
+//
+// Loud about what it drops. A fabric silently missing from a registration looks
+// identical to one never configured, and the operator who typed the adapter
+// name is the only person who can fix it — so the reason is logged here, on the
+// machine where both halves are visible, rather than inferred later from a
+// replica that will not converge.
+func (a *Agent) usableFabrics(inv discovery.Inventory) []inventory.FabricAttachment {
+	out := a.checkFabrics(inv.HCAs, true)
+	a.mu.Lock()
+	a.fabricsSent = fabricsFingerprint(out)
+	a.mu.Unlock()
+	return out
+}
+
+// checkFabrics is the declared fabrics this node can carry traffic on, from
+// the adapters as they are now. Loud logs every problem; the heartbeat checks
+// quietly and speaks only when the answer changes.
+func (a *Agent) checkFabrics(hcas []discovery.HCA, loud bool) []inventory.FabricAttachment {
+	declared := map[string][]string{}
+	for _, f := range a.cfg.Fabrics {
+		declared[f.Fabric] = f.HCAs
+	}
+
+	var out []inventory.FabricAttachment
+	for _, c := range discovery.CheckFabrics(declared, hcas) {
+		if loud {
+			for _, p := range c.Problems {
+				a.log.Error("a declared fabric adapter cannot carry traffic",
+					"fabric", c.Fabric, "problem", p)
+			}
+		}
+		if !c.OK() {
+			if loud {
+				a.log.Error("fabric not advertised; no declared adapter on it can carry traffic",
+					"fabric", c.Fabric,
+					"consequence", "no multi-node replica will be placed here")
+			}
+			continue
+		}
+		out = append(out, inventory.FabricAttachment{
+			Fabric: c.Fabric, HCAs: c.Usable, RateGbps: c.RateGbps,
+		})
+	}
+	return out
+}
+
+// fabricsFingerprint is enough to notice a fabric, an adapter or a rate
+// changing.
+func fabricsFingerprint(fs []inventory.FabricAttachment) string {
+	var b strings.Builder
+	for _, f := range fs {
+		fmt.Fprintf(&b, "%s:%s:%d;", f.Fabric, strings.Join(f.HCAs, ","), f.RateGbps)
+	}
+	return b.String()
+}
+
+// sampleIB re-reads the adapters for the heartbeat: every port's state and
+// counters, and the fabrics again when they no longer match what the control
+// plane was told.
+//
+// Every heartbeat, because it is a few small files per port, and because a
+// port that went down used to be invisible until the agent restarted — the
+// node went on being offered multi-node work that would hang on its first
+// collective.
+func (a *Agent) sampleIB(hb *llmgwv1.Heartbeat) {
+	a.mu.Lock()
+	had := len(a.inv.HCAs) > 0
+	a.mu.Unlock()
+	if !had && len(a.cfg.Fabrics) == 0 {
+		return
+	}
+	hcas, err := discovery.DiscoverIB(a.cfg.Discovery.IBRoot)
+	if err != nil {
+		return
+	}
+	a.attachSM(hcas)
+	for _, h := range hcas {
+		for _, p := range h.Ports {
+			ip := &llmgwv1.IBPort{
+				Hca: h.Name, Port: int32(p.Num), State: p.State, PhysState: p.PhysState,
+				RateGbps: int32(p.RateGbps), LinkLayer: string(p.LinkLayer), Counters: p.Counters,
+				NodeGuid: h.NodeGUID, PortGuid: p.PortGUID, Network: p.Network, GidPrefix: p.GIDPrefix,
+			}
+			a.mu.Lock()
+			if p.SM != nil {
+				ip.SmGuid, ip.SmLid, ip.SmPriority, ip.SmState = p.SM.GUID, int32(p.SM.LID), int32(p.SM.Priority), p.SM.State
+			} else {
+				ip.SmError = a.smErr[smKey(h.Name, p.Num)]
+			}
+			for _, r := range a.sms[smKey(h.Name, p.Num)] {
+				ip.SubnetManagers = append(ip.SubnetManagers, &llmgwv1.SubnetManager{
+					Guid: r.GUID, Lid: int32(r.LID), Priority: int32(r.Priority), State: r.State})
+			}
+			ip.SubnetManagersError = a.smsErr[smKey(h.Name, p.Num)]
+			a.mu.Unlock()
+			hb.IbPorts = append(hb.IbPorts, ip)
+		}
+	}
+	a.mu.Lock()
+	a.inv.HCAs = hcas // a reconnect registers what is true now
+	a.mu.Unlock()
+	if len(a.cfg.Fabrics) == 0 {
+		return
+	}
+	now := a.checkFabrics(hcas, false)
+	fp := fabricsFingerprint(now)
+	a.mu.Lock()
+	changed := fp != a.fabricsSent
+	a.fabricsSent = fp
+	a.mu.Unlock()
+	if !changed {
+		return
+	}
+	// Said once, with the reasons, the moment it happens.
+	a.checkFabrics(hcas, true)
+	a.log.Warn("the fabrics this node can carry traffic on changed", "now", fp)
+	hb.FabricsChanged = true
+	for _, f := range now {
+		hb.Fabrics = append(hb.Fabrics, &llmgwv1.FabricAttachment{
+			Fabric: f.Fabric, Hcas: f.HCAs, RateGbps: int32(f.RateGbps),
+		})
+	}
+}
+
+func smKey(hca string, port int) string { return fmt.Sprintf("%s/%d", hca, port) }
+
+// scanFabric is discovery.ScanFabric, replaced in tests.
+var scanFabric = discovery.ScanFabric
+
+// querySMs is discovery.QuerySMs, replaced in tests.
+var querySMs = func(hca string, port int) ([]discovery.SMRecord, error) {
+	return discovery.QuerySMs(context.Background(), hca, port)
+}
+
+func splitSMKey(k string) (string, int) {
+	i := strings.LastIndexByte(k, '/')
+	port, _ := strconv.Atoi(k[i+1:])
+	return k[:i], port
+}
+
+// querySM is discovery.QuerySM, replaced in tests.
+var querySM = func(hca string, port int) (*discovery.SMInfo, error) {
+	return discovery.QuerySM(context.Background(), hca, port)
+}
+
+// attachSM puts on each active InfiniBand port the subnet manager it sees,
+// asking again once a minute and otherwise reusing the last answer.
+func (a *Agent) attachSM(hcas []discovery.HCA) {
+	a.mu.Lock()
+	stale := time.Since(a.smAsked) > time.Minute || a.sm == nil
+	a.mu.Unlock()
+	if stale {
+		sm, errs := map[string]*discovery.SMInfo{}, map[string]string{}
+		_ = discovery.AttachSM(hcas, func(hca string, port int) (*discovery.SMInfo, error) {
+			got, err := querySM(hca, port)
+			if err != nil {
+				errs[smKey(hca, port)] = err.Error()
+				return nil, err
+			}
+			sm[smKey(hca, port)] = got
+			return got, nil
+		})
+		// Every subnet manager on each fabric, through one port per master:
+		// the same list through every port of one fabric is one query too
+		// many for each.
+		sms, smsErr := map[string][]discovery.SMRecord{}, map[string]string{}
+		asked := map[string]bool{}
+		for k, v := range sm {
+			if asked[v.GUID] {
+				continue
+			}
+			asked[v.GUID] = true
+			hca, port := splitSMKey(k)
+			if recs, err := querySMs(hca, port); err != nil {
+				smsErr[k] = err.Error()
+			} else {
+				sms[k] = recs
+			}
+		}
+		a.mu.Lock()
+		for k, v := range sm {
+			if old := a.sm[k]; old != nil && old.GUID != v.GUID {
+				a.log.Warn("the master subnet manager changed", "port", k, "from", old.GUID, "to", v.GUID)
+			}
+		}
+		a.sm, a.smErr, a.smAsked = sm, errs, time.Now()
+		a.sms, a.smsErr = sms, smsErr
+		a.mu.Unlock()
+		return
+	}
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	for i := range hcas {
+		for j := range hcas[i].Ports {
+			if sm := a.sm[smKey(hcas[i].Name, hcas[i].Ports[j].Num)]; sm != nil && hcas[i].Ports[j].Active() {
+				hcas[i].Ports[j].SM = sm
+			}
+		}
+	}
+}
+
+// ensureDiags installs infiniband-diags on a node with adapters and without
+// it. sminfo is what tells which physical fabric a port is on; without it,
+// two separate fabrics given one name cannot be caught. Installed the way
+// engine dependencies are, from the machine's own package sources.
+func (a *Agent) ensureDiags(ctx context.Context) {
+	a.mu.Lock()
+	hasIB := len(a.inv.HCAs) > 0
+	a.mu.Unlock()
+	if !hasIB || a.prov == nil {
+		return
+	}
+	if _, err := exec.LookPath("sminfo"); err == nil {
+		return
+	}
+	a.log.Info("installing infiniband-diags, to tell which fabric each port is on")
+	pkgs := map[string][]string{"deb": {"infiniband-diags"}, "rpm": {"infiniband-diags"}}
+	if err := a.prov.InstallPackages(ctx, pkgs); err != nil {
+		a.log.Warn("could not install infiniband-diags; fabrics cannot be told apart by their subnet manager",
+			"err", err)
+	}
+}
+
+// FeatureFabricTest is the agent answering FabricTestRequest.
+const FeatureFabricTest = "fabric-test"
+
+// runWriteBW is discovery.RunWriteBW, and haveWriteBW whether it is
+// installed; both replaced in tests.
+var (
+	runWriteBW  = discovery.RunWriteBW
+	haveWriteBW = func() bool { _, err := exec.LookPath("ib_write_bw"); return err == nil }
+)
+
+// fabricTest runs this node's side of a bandwidth test with another.
+func (a *Agent) fabricTest(ctx context.Context, req *llmgwv1.FabricTestRequest) *llmgwv1.FabricTestReply {
+	start := time.Now()
+	reply := &llmgwv1.FabricTestReply{RequestId: req.GetRequestId()}
+	defer func() { reply.TookMs = time.Since(start).Milliseconds() }()
+
+	w := discovery.WriteBW{HCA: req.GetHca(), Port: int(req.GetPort()), GIDIndex: -1,
+		TCPPort: int(req.GetTcpPort()), Seconds: int(req.GetSeconds())}
+	if req.GetRole() == "client" {
+		w.Peer = req.GetPeer()
+	}
+	a.mu.Lock()
+	found := false
+	for _, h := range a.inv.HCAs {
+		for _, p := range h.Ports {
+			if h.Name == w.HCA && p.Num == w.Port {
+				found = true
+				// RoCE needs its v2 GID named, as NCCL does; InfiniBand uses the LID.
+				if p.LinkLayer == discovery.LinkEthernet && p.RoCEv2GID >= 0 {
+					w.GIDIndex = p.RoCEv2GID
+				}
+			}
+		}
+	}
+	a.mu.Unlock()
+	if !found {
+		reply.Error = fmt.Sprintf("this node has no port %s/%d", w.HCA, w.Port)
+		return reply
+	}
+	if !haveWriteBW() && a.prov != nil {
+		a.log.Info("installing perftest, for a bandwidth test with another node")
+		pkgs := map[string][]string{"deb": {"perftest"}, "rpm": {"perftest"}}
+		if err := a.prov.InstallPackages(ctx, pkgs); err != nil {
+			reply.Error = "installing perftest: " + err.Error()
+			return reply
+		}
+	}
+	gbps, out, err := runWriteBW(ctx, w)
+	reply.Gbps = gbps
+	reply.Output = tailLines(out, 12)
+	if err != nil {
+		reply.Error = err.Error()
+	}
+	return reply
+}
+
+func tailLines(s string, n int) string {
+	lines := strings.Split(strings.TrimRight(s, "\n"), "\n")
+	if len(lines) > n {
+		lines = lines[len(lines)-n:]
+	}
+	return strings.Join(lines, "\n")
+}
+
+// discoverGPUFabric and discoverIMEX are replaced in tests.
+var (
+	discoverGPUFabric = discovery.DiscoverGPUFabric
+	discoverIMEX      = discovery.DiscoverIMEX
+)
+
+// sampleNVLink reads, once a minute, which NVLink domain each GPU is joined
+// to and whether IMEX is up. nvidia-smi -q takes a second or two, too long
+// for every heartbeat, and a fabric that was joined an hour ago rarely
+// changes in five seconds — but when a fabric manager restarts it does, for
+// every card at once.
+func (a *Agent) sampleNVLink(hb *llmgwv1.Heartbeat) {
+	a.mu.Lock()
+	gpus := slices.Clone(a.inv.GPUs)
+	due := time.Since(a.nvlAsked) > time.Minute
+	if due {
+		a.nvlAsked = time.Now()
+	}
+	a.mu.Unlock()
+	if len(gpus) == 0 || !due {
+		return
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	defer cancel()
+	fab, err := discoverGPUFabric(ctx, a.cfg.Discovery.NvidiaSMI)
+	if err != nil || len(fab) == 0 {
+		return
+	}
+	discovery.ApplyFabric(gpus, fab)
+	for _, g := range gpus {
+		if g.Fabric == nil {
+			continue
+		}
+		hb.GpuFabric = append(hb.GpuFabric, &llmgwv1.GPUFabricState{
+			Index: int32(g.Index), State: g.Fabric.State, Status: g.Fabric.Status,
+			ClusterUuid: g.Fabric.ClusterUUID, CliqueId: g.Fabric.CliqueID, Bandwidth: g.Fabric.Bandwidth,
+		})
+	}
+	m := discoverIMEX(ctx)
+	hb.Imex = &llmgwv1.IMEX{State: m.State, Channels: int32(m.Channels)}
+}

internal/agent/logs.go

@@ -0,0 +1,34 @@
+package agent
+
+import (
+	"slices"
+
+	llmgwv1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1"
+)
+
+// logsReply answers a request for one of this node's logs.
+func (a *Agent) logsReply(req *llmgwv1.LogsRequest) *llmgwv1.LogsReply {
+	n := int(req.GetLines())
+	if n <= 0 {
+		n = 200
+	}
+	n = min(n, agentLogLines)
+	shards := a.sup.IDs()
+	slices.Sort(shards)
+	out := &llmgwv1.LogsReply{
+		RequestId: req.GetRequestId(),
+		Sources:   append([]string{"agent"}, shards...),
+	}
+	switch src := req.GetSource(); src {
+	case "", "agent":
+		out.Lines = a.logRing.tail(n)
+	default:
+		sh, err := a.sup.Get(src)
+		if err != nil {
+			out.Error = "no engine " + src + " runs on this node"
+			return out
+		}
+		out.Lines = sh.Logs(n)
+	}
+	return out
+}

internal/agent/provision.go

@@ -0,0 +1,197 @@
+package agent
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"maps"
+	"slices"
+	"strings"
+	"time"
+
+	llmgwv1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/engines"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/provision"
+)
+
+// engines is what this node can run: what the agent installed and saw run,
+// and what the configuration names and answers. Nothing merely found on the
+// machine — a llama-server on PATH is somebody's, not necessarily one that
+// works, and placing on it is how a replica fails on a node nobody watches.
+func (a *Agent) engines(ctx context.Context) map[string]string {
+	a.engineOnce.Do(func() {
+		vers := a.reg.ProbeConfigured(ctx)
+		a.mu.Lock()
+		a.configuredVers, a.lastEngineProbe = vers, time.Now()
+		a.mu.Unlock()
+		if len(vers) > 0 {
+			a.log.Info("engines named in the configuration",
+				"engines", engines.ProbedNames(vers))
+		}
+	})
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	vers := a.engineReportLocked()
+	// Whatever registration sends is what the control plane now knows, so a
+	// heartbeat repeats it only once it differs.
+	a.enginesSent = enginesFingerprint(vers)
+	return vers
+}
+
+// engineReportLocked merges the two sources. Installed wins: it is the one
+// that was seen to run. Called with mu held.
+func (a *Agent) engineReportLocked() map[string]string {
+	out := maps.Clone(a.configuredVers)
+	if out == nil {
+		out = map[string]string{}
+	}
+	maps.Copy(out, a.installedVers)
+	return out
+}
+
+// provisionEvery is how often installed engines are checked again. A library
+// removed by an unrelated upgrade is found here rather than by the next
+// replica to start.
+const provisionEvery = 10 * time.Minute
+
+// setProvision takes the control plane's list of wanted engines.
+func (a *Agent) setProvision(p *llmgwv1.Provision) {
+	wants := []provision.Want{}
+	for _, e := range p.GetEngines() {
+		wants = append(wants, provision.Want{Engine: e.GetEngine(), Version: e.GetVersion()})
+	}
+	a.mu.Lock()
+	a.provWants = wants
+	a.mu.Unlock()
+	select {
+	case a.provKick <- struct{}{}:
+	default:
+	}
+}
+
+// provisionLoop installs and re-checks the wanted engines, one pass at a time.
+func (a *Agent) provisionLoop(ctx context.Context) {
+	// After a failure the next pass comes sooner, and backs off: a lock held
+	// by a new machine's own updates clears in a minute or two, while ten
+	// minutes' wait left a node idle for no reason.
+	next := provisionEvery
+	retry := time.Minute
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-a.provKick:
+		case <-time.After(next):
+		}
+		a.mu.Lock()
+		wants := slices.Clone(a.provWants)
+		managed := a.provWants != nil
+		a.mu.Unlock()
+		if !managed {
+			continue
+		}
+
+		statuses := a.prov.Converge(ctx, wants)
+		next = provisionEvery
+		for _, st := range statuses {
+			if st.State == provision.Failed {
+				next, retry = retry, min(retry*2, provisionEvery)
+				break
+			}
+		}
+		if next == provisionEvery {
+			retry = time.Minute
+		}
+		installed := map[string]string{}
+		keep := map[string]bool{}
+		for _, st := range statuses {
+			keep[st.Engine] = true
+			if st.State == provision.Ready {
+				a.reg.UseInstalled(st.Engine, st.Binary)
+				installed[st.Engine] = st.Version
+			}
+		}
+		a.mu.Lock()
+		if enginesFingerprint(installed) != enginesFingerprint(a.installedVers) {
+			a.log.Info("engines installed and running", "engines", engines.ProbedNames(installed))
+		}
+		a.installedVers = installed
+		// An engine no longer asked for is no longer reported on.
+		for e := range a.provStatus {
+			if !keep[e] {
+				delete(a.provStatus, e)
+			}
+		}
+		a.mu.Unlock()
+	}
+}
+
+// provisionStatus records a change in one engine's installation.
+func (a *Agent) provisionStatus(st provision.Status) {
+	a.mu.Lock()
+	prev, had := a.provStatus[st.Engine]
+	a.provStatus[st.Engine] = st
+	a.mu.Unlock()
+	if !had || prev.State != st.State || prev.Detail != st.Detail {
+		lvl := slog.LevelInfo
+		if st.State == provision.Failed || st.State == provision.Unsupported {
+			lvl = slog.LevelWarn
+		}
+		a.log.Log(context.Background(), lvl, "engine installation",
+			"engine", st.Engine, "version", st.Version, "variant", st.Variant,
+			"state", st.State, "detail", st.Detail)
+	}
+}
+
+func provisionFingerprint(m map[string]provision.Status) string {
+	var b strings.Builder
+	for _, k := range slices.Sorted(maps.Keys(m)) {
+		st := m[k]
+		fmt.Fprintf(&b, "%s|%s|%s|%s|%s\n", st.Engine, st.Version, st.Variant, st.State, st.Detail)
+	}
+	return b.String()
+}
+
+// engineReprobe is how often the installed engines are looked for again.
+//
+// Minutes, not seconds: an engine is installed by somebody at a keyboard, so a
+// minute's delay in noticing is invisible, while SGLang's probe starts a
+// Python interpreter that imports it.
+const engineReprobe = time.Minute
+
+// reprobeEngines looks for installed engines again when it is time, off the
+// heartbeat goroutine so a slow probe never delays a heartbeat.
+func (a *Agent) reprobeEngines() {
+	a.mu.Lock()
+	due := !a.probingEngines && !a.lastEngineProbe.IsZero() &&
+		time.Since(a.lastEngineProbe) >= engineReprobe
+	if due {
+		a.probingEngines = true
+	}
+	a.mu.Unlock()
+	if !due {
+		return
+	}
+	go func() {
+		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+		defer cancel()
+		vers := a.reg.ProbeConfigured(ctx)
+
+		a.mu.Lock()
+		changed := enginesFingerprint(vers) != enginesFingerprint(a.configuredVers)
+		a.configuredVers, a.lastEngineProbe, a.probingEngines = vers, time.Now(), false
+		a.mu.Unlock()
+		if changed {
+			a.log.Info("engines named in the configuration changed",
+				"engines", engines.ProbedNames(vers))
+		}
+	}()
+}
+
+func enginesFingerprint(vers map[string]string) string {
+	var b strings.Builder
+	for _, k := range slices.Sorted(maps.Keys(vers)) {
+		fmt.Fprintf(&b, "%s=%s\n", k, vers[k])
+	}
+	return b.String()
+}

internal/agent/provision/install.go

@@ -16,6 +16,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"regexp"
 	"strings"
 	"time"
 
@@ -34,6 +35,9 @@ const (
 	Ready       = "ready"
 	Failed      = "failed"
 	Unsupported = "unsupported"
+	// Skipped is an engine this node is not meant to run, such as vLLM on a
+	// machine with no GPU. Nothing is wrong, and nothing is shown as wrong.
+	Skipped = "skipped"
 )
 
 // Status is where one engine's installation stands.
@@ -62,11 +66,22 @@ type Installer struct {
 
 	// Run executes a command; a seam for tests. Nil runs it for real.
 	Run func(ctx context.Context, env []string, name string, args ...string) ([]byte, error)
-	// APIBase and DownloadBase default to GitHub; tests point them at a fake.
+	// FreeSpace reports the gigabytes free under a directory; a seam for
+	// tests. Nil asks the filesystem.
+	FreeSpace func(dir string) (float64, error)
+	// RunStdin is Run with input; a seam for tests. Nil runs it for real.
+	RunStdin func(ctx context.Context, env []string, stdin, name string, args ...string) ([]byte, error)
+	// APIBase and DownloadBase default to GitHub, PyPIBase to PyPI; tests
+	// point them at a fake.
 	APIBase      string
 	DownloadBase string
+	PyPIBase     string
 }
 
+// validVersion is what a version may look like: "b10991", "0.29.0",
+// "0.11.0+cu128". No separators, and not starting with a dot.
+var validVersion = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$`)
+
 // DefaultRoot is where engines are installed when nothing says otherwise.
 const DefaultRoot = "/opt/llmgw/engines"
 
@@ -75,12 +90,16 @@ const DefaultRoot = "/opt/llmgw/engines"
 const marker = ".llmgw-installed"
 
 type markerFile struct {
-	Engine    string            `json:"engine"`
-	Version   string            `json:"version"`
-	Variant   string            `json:"variant"`
-	Binary    string            `json:"binary"`
-	SHA256    map[string]string `json:"sha256"`
-	Installed time.Time         `json:"installed"`
+	Engine  string            `json:"engine"`
+	Version string            `json:"version"`
+	Variant string            `json:"variant"`
+	Binary  string            `json:"binary"`
+	SHA256  map[string]string `json:"sha256,omitempty"`
+	// For a Python engine: what was asked for, PyPI as of when, by which uv.
+	Requirements []string  `json:"requirements,omitempty"`
+	ExcludeNewer string    `json:"exclude_newer,omitempty"`
+	UV           string    `json:"uv,omitempty"`
+	Installed    time.Time `json:"installed"`
 }
 
 // Converge brings every wanted engine to ready, or says why it cannot.
@@ -100,6 +119,15 @@ func (in *Installer) Converge(ctx context.Context, wants []Want) []Status {
 
 func (in *Installer) one(ctx context.Context, w Want) Status {
 	st := Status{Engine: w.Engine, Version: w.Version}
+	// Checked here, on the node, whatever the control plane checked: the
+	// version names a directory under the install root and is passed to a
+	// package manager, and "../x" would put an install — and the RemoveAll
+	// that replaces one — outside it, as root.
+	if !validVersion.MatchString(w.Version) {
+		st.State = Unsupported
+		st.Detail = fmt.Sprintf("%q is not a version this agent will install", w.Version)
+		return st
+	}
 	recipe, ok := Recipes[w.Engine]
 	if !ok {
 		st.State = Unsupported
@@ -110,6 +138,10 @@ func (in *Installer) one(ctx context.Context, w Want) Status {
 	build, err := recipe.Choose(w.Version, in.Host)
 	if err != nil {
 		st.State, st.Detail = Unsupported, err.Error()
+		var nh NotHere
+		if errors.As(err, &nh) {
+			st.State = Skipped
+		}
 		return st
 	}
 	st.Variant = build.Variant
@@ -168,6 +200,9 @@ func (in *Installer) ready(st Status, b Build, bin, version string) Status {
 // Into a scratch directory renamed into place at the end, so a failure halfway
 // leaves nothing that looks installed.
 func (in *Installer) install(ctx context.Context, r Recipe, w Want, b Build, dir string, st *Status) error {
+	if b.Python != "" {
+		return in.installPython(ctx, r, w, b, dir, st)
+	}
 	if err := in.packages(ctx, b.Packages, st); err != nil {
 		return err
 	}
@@ -235,18 +270,32 @@ func (in *Installer) install(ctx context.Context, r Recipe, w Want, b Build, dir
 // running it is the only proof that the rest — the right instruction set, the
 // right driver — is in place.
 func (in *Installer) verify(ctx context.Context, dir string, b Build) (bin, version string, err error) {
-	bin, err = findFile(dir, b.Binary)
-	if err != nil {
-		return "", "", err
-	}
-	if out, err := in.run(ctx, nil, "ldd", bin); err == nil {
-		if missing := lddMissing(string(out)); len(missing) > 0 {
-			return "", "", fmt.Errorf("%s cannot run on this system: %s", b.Binary, strings.Join(missing, "; "))
+	timeout := 60 * time.Second
+	if b.Python != "" {
+		// A script in the environment, not a binary to ldd; and importing
+		// torch and the engine behind it takes a while on a cold disk.
+		bin, timeout = filepath.Join(dir, "bin", b.Binary), 3*time.Minute
+		if _, err := os.Stat(bin); err != nil {
+			return "", "", fmt.Errorf("%s is not in the environment: %w", b.Binary, err)
+		}
+	} else {
+		bin, err = findFile(dir, b.Binary)
+		if err != nil {
+			return "", "", err
+		}
+		if out, err := in.run(ctx, nil, "ldd", bin); err == nil {
+			if missing := lddMissing(string(out)); len(missing) > 0 {
+				return "", "", fmt.Errorf("%s cannot run on this system: %s", b.Binary, strings.Join(missing, "; "))
+			}
 		}
 	}
-	tctx, cancel := context.WithTimeout(ctx, 60*time.Second)
+	args := b.VersionArgs
+	if len(args) == 0 {
+		args = []string{"--version"}
+	}
+	tctx, cancel := context.WithTimeout(ctx, timeout)
 	defer cancel()
-	out, err := in.run(tctx, nil, bin, "--version")
+	out, err := in.run(tctx, nil, bin, args...)
 	if err != nil {
 		return "", "", fmt.Errorf("%s --version failed: %v: %s", b.Binary, err, lastLine(out))
 	}
@@ -290,6 +339,14 @@ func (in *Installer) packages(ctx context.Context, byFamily map[string][]string,
 	return nil
 }
 
+// InstallPackages installs whichever of these packages the machine lacks,
+// from its own package sources, waiting out another package manager's lock.
+// byFamily is keyed by discovery.Host.Family: "deb" or "rpm".
+func (in *Installer) InstallPackages(ctx context.Context, byFamily map[string][]string) error {
+	var st Status
+	return in.packages(ctx, byFamily, &st)
+}
+
 // lockWait bounds how long a package command waits for another to finish.
 const lockWait = 10 * time.Minute
 
@@ -466,6 +523,11 @@ func (in *Installer) download(ctx context.Context, repo, tag, asset, dst, want s
 // untarGz unpacks an archive under dir, refusing anything that would land
 // outside it. A release archive is somebody else's file, and a path of
 // "../../etc/cron.d/x" in it would otherwise be written as root.
+//
+// Every write goes through an os.Root, which refuses to leave dir however the
+// path gets there. Checking names alone was not enough: "a -> ." followed by
+// "a/a/b -> ../.." reads as inside and resolves two levels above it, and a
+// file written through that lands wherever the links point.
 func untarGz(archive, dir string) error {
 	f, err := os.Open(archive) //nolint:gosec // inside the install root
 	if err != nil {
@@ -476,6 +538,11 @@ func untarGz(archive, dir string) error {
 	if err != nil {
 		return err
 	}
+	root, err := os.OpenRoot(dir)
+	if err != nil {
+		return err
+	}
+	defer root.Close()
 	tr := tar.NewReader(gz)
 	for {
 		h, err := tr.Next()
@@ -485,22 +552,22 @@ func untarGz(archive, dir string) error {
 		if err != nil {
 			return err
 		}
-		target, err := within(dir, h.Name)
-		if err != nil {
+		name := filepath.Clean(h.Name)
+		if _, err := within(dir, name); err != nil {
 			return err
 		}
 		switch h.Typeflag {
 		case tar.TypeDir:
-			if err := os.MkdirAll(target, 0o755); err != nil {
+			if err := root.MkdirAll(name, 0o755); err != nil {
 				return err
 			}
 		case tar.TypeReg:
-			if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
+			if err := root.MkdirAll(filepath.Dir(name), 0o755); err != nil {
 				return err
 			}
-			out, err := os.OpenFile(target, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, fs.FileMode(h.Mode)&0o755) //nolint:gosec // checked above
+			out, err := root.OpenFile(name, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, fs.FileMode(h.Mode)&0o755)
 			if err != nil {
-				return err
+				return fmt.Errorf("%s: %w", h.Name, err)
 			}
 			if _, err := io.Copy(out, tr); err != nil { //nolint:gosec // a release archive, size bounded by its checksum
 				out.Close()
@@ -510,19 +577,19 @@ func untarGz(archive, dir string) error {
 				return err
 			}
 		case tar.TypeSymlink:
-			// Libraries are versioned through symlinks, and those are
-			// relative. One pointing anywhere else is refused.
-			if filepath.IsAbs(h.Linkname) {
-				return fmt.Errorf("%s links outside the archive", h.Name)
+			// Libraries are versioned through symlinks to a file beside them —
+			// libllama.so -> libllama.so.0 — and that is all a release needs.
+			// A target with a separator in it could point anywhere once other
+			// links are followed, and a binary found through one would be run
+			// as root, so it is refused rather than reasoned about.
+			if h.Linkname == "" || strings.ContainsAny(h.Linkname, `/\`) || h.Linkname == ".." || h.Linkname == "." {
+				return fmt.Errorf("%s links to %q; only a file beside it is allowed", h.Name, h.Linkname)
 			}
-			if _, err := within(dir, filepath.Join(filepath.Dir(h.Name), h.Linkname)); err != nil {
-				return fmt.Errorf("%s links outside the archive", h.Name)
-			}
-			if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
+			if err := root.MkdirAll(filepath.Dir(name), 0o755); err != nil {
 				return err
 			}
-			_ = os.Remove(target)
-			if err := os.Symlink(h.Linkname, target); err != nil {
+			_ = root.Remove(name)
+			if err := root.Symlink(h.Linkname, name); err != nil {
 				return err
 			}
 		default:
@@ -599,6 +666,13 @@ func (in *Installer) report(st Status) {
 	}
 }
 
+func runWithStdin(ctx context.Context, env []string, stdin, name string, args ...string) ([]byte, error) {
+	cmd := exec.CommandContext(ctx, name, args...) //nolint:gosec // fixed commands and paths we installed
+	cmd.Env = append(os.Environ(), env...)
+	cmd.Stdin = strings.NewReader(stdin)
+	return cmd.CombinedOutput()
+}
+
 func (in *Installer) run(ctx context.Context, env []string, name string, args ...string) ([]byte, error) {
 	if in.Run != nil {
 		return in.Run(ctx, env, name, args...)
@@ -654,5 +728,11 @@ func firstVersionLine(b []byte) string {
 			return strings.TrimSpace(l)
 		}
 	}
+	// vllm --version says the number and nothing else.
+	for _, l := range strings.Split(string(b), "\n") {
+		if l = strings.TrimSpace(l); l != "" && l[0] >= '0' && l[0] <= '9' {
+			return l
+		}
+	}
 	return ""
 }

internal/agent/provision/install_test.go

@@ -265,8 +265,8 @@ func TestTheBuildFollowsTheHardware(t *testing.T) {
 
 func TestAnEngineTheAgentCannotInstallSaysSo(t *testing.T) {
 	in := &Installer{Root: t.TempDir(), Host: ubuntu}
-	got := in.Converge(t.Context(), []Want{{Engine: "vllm", Version: "0.29.0"}})
-	if got[0].State != Unsupported {
+	got := in.Converge(t.Context(), []Want{{Engine: "tgi", Version: "3.0.0"}})
+	if got[0].State != Unsupported || !strings.Contains(got[0].Detail, "install it by hand") {
 		t.Errorf("got %+v", got[0])
 	}
 }
@@ -330,3 +330,61 @@ func TestAPackageManagerBusyWithItsOwnUpdatesIsWaitedFor(t *testing.T) {
 		t.Error("the wait was not reported")
 	}
 }
+
+func TestAVersionThatIsAPathIsRefused(t *testing.T) {
+	// The version names a directory under the install root; "../" would put
+	// an install, and the RemoveAll that replaces one, outside it, as root.
+	in := &Installer{Root: t.TempDir(), Host: ubuntu}
+	for _, v := range []string{"../../etc", "..", ".hidden", "b1/../../x", "", "b1 && rm -rf /"} {
+		got := in.Converge(t.Context(), []Want{{Engine: "llamacpp", Version: v}})
+		if got[0].State != Unsupported {
+			t.Errorf("version %q: %+v", v, got[0])
+		}
+	}
+}
+
+func TestChainedLinksCannotCarryAFileOutOfTheInstall(t *testing.T) {
+	// Each link reads as inside the directory; together they point above it.
+	var buf bytes.Buffer
+	gz := gzip.NewWriter(&buf)
+	tw := tar.NewWriter(gz)
+	_ = tw.WriteHeader(&tar.Header{Name: "a", Linkname: ".", Typeflag: tar.TypeSymlink})
+	_ = tw.WriteHeader(&tar.Header{Name: "a/a/b", Linkname: "../..", Typeflag: tar.TypeSymlink})
+	_ = tw.WriteHeader(&tar.Header{Name: "a/a/b/escaped", Mode: 0o644, Size: 1, Typeflag: tar.TypeReg})
+	_, _ = tw.Write([]byte("x"))
+	_ = tw.Close()
+	_ = gz.Close()
+
+	parent := t.TempDir()
+	dir := filepath.Join(parent, "install")
+	_ = os.MkdirAll(dir, 0o755)
+	archive := filepath.Join(parent, "evil.tar.gz")
+	_ = os.WriteFile(archive, buf.Bytes(), 0o644)
+
+	if err := untarGz(archive, dir); err == nil {
+		t.Error("an archive of chained links was unpacked")
+	}
+	if _, err := os.Stat(filepath.Join(parent, "escaped")); err == nil {
+		t.Fatal("a file was written outside the install directory")
+	}
+}
+
+func TestALibrarysVersionLinkIsStillUnpacked(t *testing.T) {
+	var buf bytes.Buffer
+	gz := gzip.NewWriter(&buf)
+	tw := tar.NewWriter(gz)
+	_ = tw.WriteHeader(&tar.Header{Name: "lib/libllama.so.0", Mode: 0o755, Size: 1, Typeflag: tar.TypeReg})
+	_, _ = tw.Write([]byte("x"))
+	_ = tw.WriteHeader(&tar.Header{Name: "lib/libllama.so", Linkname: "libllama.so.0", Typeflag: tar.TypeSymlink})
+	_ = tw.Close()
+	_ = gz.Close()
+	dir := t.TempDir()
+	archive := filepath.Join(t.TempDir(), "ok.tar.gz")
+	_ = os.WriteFile(archive, buf.Bytes(), 0o644)
+	if err := untarGz(archive, dir); err != nil {
+		t.Fatal(err)
+	}
+	if target, err := os.Readlink(filepath.Join(dir, "lib", "libllama.so")); err != nil || target != "libllama.so.0" {
+		t.Errorf("link %q %v", target, err)
+	}
+}

internal/agent/provision/python.go

@@ -0,0 +1,205 @@
+package provision
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"syscall"
+	"time"
+)
+
+// A Python engine is a virtual environment built by uv: an interpreter uv
+// fetches, and the engine with every dependency from PyPI.
+//
+// Two things make it as trustworthy as an archive checked against its
+// publisher's checksum. The dependencies are resolved as PyPI stood a day
+// after the engine was published (--exclude-newer), so a node built next
+// month gets what one built today got, not whatever a dependency released
+// since — the usual way a working vLLM stops working. And the resolution is
+// written out with every file's sha256 from PyPI and installed with
+// --require-hashes, so a file that does not match what PyPI published is
+// refused. The resolved list is kept in the environment, as the record of
+// exactly what is installed.
+
+// pythonInstallTimeout bounds one installation: several gigabytes, on a
+// network that may be slow, but not forever.
+const pythonInstallTimeout = time.Hour
+
+// lockName is the resolved requirements, kept in the environment.
+const lockName = "llmgw-requirements.txt"
+
+func (in *Installer) installPython(ctx context.Context, r Recipe, w Want, b Build, dir string, st *Status) error {
+	ctx, cancel := context.WithTimeout(ctx, pythonInstallTimeout)
+	defer cancel()
+
+	if err := in.packages(ctx, b.Packages, st); err != nil {
+		return err
+	}
+	if err := os.MkdirAll(in.root(), 0o755); err != nil {
+		return err
+	}
+	if b.FreeGB > 0 {
+		if free, err := in.free(in.root()); err == nil && free < float64(b.FreeGB) {
+			return fmt.Errorf("%s needs about %d GB free under %s and there are %.1f GB",
+				w.Engine, b.FreeGB, in.root(), free)
+		}
+	}
+
+	in.progress(st, "installing uv %s", UVVersion)
+	uv := in.one(ctx, Want{Engine: "uv", Version: UVVersion})
+	if uv.State != Ready {
+		return fmt.Errorf("installing uv, which installs %s: %s", w.Engine, uv.Detail)
+	}
+
+	in.progress(st, "asking PyPI when %s %s was published", r.PyPI, w.Version)
+	published, err := in.published(ctx, r.PyPI, w.Version)
+	if err != nil {
+		return err
+	}
+	asOf := published.Add(24 * time.Hour).UTC().Format(time.RFC3339)
+
+	cache := filepath.Join(in.root(), ".uv-cache")
+	env := []string{
+		"UV_CACHE_DIR=" + cache,
+		"UV_PYTHON_INSTALL_DIR=" + filepath.Join(in.root(), "python"),
+		// Only the interpreter uv fetched: the system's may be the wrong
+		// version, or change under the environment with the next upgrade.
+		"UV_PYTHON_PREFERENCE=only-managed",
+		// Nobody's uv.toml or pip.conf decides what is installed here.
+		"UV_NO_CONFIG=1",
+	}
+	tmp := dir + ".partial"
+	_ = os.RemoveAll(tmp)
+	defer os.RemoveAll(tmp) //nolint:errcheck // gone either way once renamed
+
+	in.progress(st, "creating a Python %s environment for %s", b.Python, w.Engine)
+	// Relocatable, because it is built under one name and renamed into place
+	// once it works: its scripts find their interpreter relative to
+	// themselves rather than by the path they were built at.
+	if out, err := in.run(ctx, env, uv.Binary, "venv", "--relocatable", "--python", b.Python, tmp); err != nil {
+		return fmt.Errorf("uv venv: %v: %s", err, tail(out))
+	}
+	python := filepath.Join(tmp, "bin", "python")
+
+	in.progress(st, "resolving %s against PyPI as of %s", strings.Join(b.Requirements, " "), asOf[:10])
+	lock := filepath.Join(tmp, lockName)
+	args := []string{"pip", "compile", "--python", python, "--exclude-newer", asOf,
+		"--generate-hashes", "--quiet", "--output-file", lock, "-"}
+	if out, err := in.runStdin(ctx, env, strings.Join(b.Requirements, "\n")+"\n", uv.Binary, args...); err != nil {
+		return fmt.Errorf("resolving %s: %v: %s", strings.Join(b.Requirements, " "), err, tail(out))
+	}
+
+	in.progress(st, "downloading and installing %s and its dependencies: several gigabytes, which takes minutes",
+		strings.Join(b.Requirements, " "))
+	if out, err := in.run(ctx, env, uv.Binary, "pip", "install", "--python", python,
+		"--require-hashes", "--no-deps", "-r", lock); err != nil {
+		return fmt.Errorf("installing %s: %v: %s", strings.Join(b.Requirements, " "), err, tail(out))
+	}
+
+	in.progress(st, "checking that %s runs", w.Engine)
+	if _, _, err := in.verify(ctx, tmp, b); err != nil {
+		return err
+	}
+	m, _ := json.MarshalIndent(markerFile{
+		Engine: w.Engine, Version: w.Version, Variant: b.Variant,
+		Binary: filepath.Join("bin", b.Binary), Requirements: b.Requirements,
+		ExcludeNewer: asOf, UV: UVVersion, Installed: time.Now().UTC(),
+	}, "", "  ")
+	if err := os.WriteFile(filepath.Join(tmp, marker), m, 0o644); err != nil { //nolint:gosec // not secret
+		return err
+	}
+	_ = os.RemoveAll(dir)
+	if err := os.Rename(tmp, dir); err != nil {
+		return err
+	}
+	// The cache is as large as the environment. Kept after a failure, so the
+	// next attempt does not download it all again; dropped after success.
+	_ = os.RemoveAll(cache)
+	in.log().Info("installed an engine", "engine", w.Engine, "version", w.Version,
+		"variant", b.Variant, "dir", dir, "as_of", asOf)
+	return nil
+}
+
+// published is when PyPI received a release's last file.
+func (in *Installer) published(ctx context.Context, project, version string) (time.Time, error) {
+	url := strings.TrimSuffix(in.pypiBase(), "/") + "/pypi/" + project + "/" + version + "/json"
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return time.Time{}, err
+	}
+	resp, err := in.client().Do(req)
+	if err != nil {
+		return time.Time{}, fmt.Errorf("asking PyPI for %s %s: %w", project, version, err)
+	}
+	defer resp.Body.Close() //nolint:errcheck // read-only
+	if resp.StatusCode == http.StatusNotFound {
+		return time.Time{}, fmt.Errorf("PyPI has no %s %s", project, version)
+	}
+	if resp.StatusCode != http.StatusOK {
+		return time.Time{}, fmt.Errorf("asking PyPI for %s %s: %s", project, version, resp.Status)
+	}
+	var rel struct {
+		URLs []struct {
+			Uploaded time.Time `json:"upload_time_iso_8601"`
+		} `json:"urls"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&rel); err != nil {
+		return time.Time{}, fmt.Errorf("reading PyPI's answer for %s %s: %w", project, version, err)
+	}
+	var last time.Time
+	for _, u := range rel.URLs {
+		if u.Uploaded.After(last) {
+			last = u.Uploaded
+		}
+	}
+	if last.IsZero() {
+		return time.Time{}, errors.New("PyPI lists no files for " + project + " " + version)
+	}
+	return last, nil
+}
+
+func (in *Installer) free(dir string) (float64, error) {
+	if in.FreeSpace != nil {
+		return in.FreeSpace(dir)
+	}
+	return FreeGB(dir)
+}
+
+func (in *Installer) pypiBase() string {
+	if in.PyPIBase != "" {
+		return in.PyPIBase
+	}
+	return "https://pypi.org"
+}
+
+// runStdin runs a command with input on its standard input.
+func (in *Installer) runStdin(ctx context.Context, env []string, stdin, name string, args ...string) ([]byte, error) {
+	if in.RunStdin != nil {
+		return in.RunStdin(ctx, env, stdin, name, args...)
+	}
+	return runWithStdin(ctx, env, stdin, name, args...)
+}
+
+// FreeGB is the space available to an unprivileged writer under dir.
+func FreeGB(dir string) (float64, error) {
+	var s syscall.Statfs_t
+	if err := syscall.Statfs(dir, &s); err != nil {
+		return 0, err
+	}
+	return float64(s.Bavail) * float64(s.Bsize) / (1 << 30), nil
+}
+
+// tail is the last few lines of a command's output: uv explains a failed
+// resolution over several, and the last alone is rarely the reason.
+func tail(b []byte) string {
+	lines := strings.Split(strings.TrimSpace(string(b)), "\n")
+	if len(lines) > 4 {
+		lines = lines[len(lines)-4:]
+	}
+	return strings.Join(lines, " / ")
+}

internal/agent/provision/python_test.go

@@ -0,0 +1,184 @@
+package provision
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"sync"
+	"testing"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/discovery"
+)
+
+var gpuNode = discovery.Host{OSID: "ubuntu", OSVersion: "24.04", Arch: "amd64",
+	NVIDIADriver: "580.65.06", MinComputeCapability: 8.0}
+
+// fakePython is uv and the environments it builds.
+type fakePython struct {
+	fakeSystem
+	pmu      sync.Mutex
+	commands []string
+	failPip  bool
+}
+
+func (f *fakePython) run(ctx context.Context, env []string, name string, args ...string) ([]byte, error) {
+	line := name + " " + strings.Join(args, " ")
+	f.pmu.Lock()
+	f.commands = append(f.commands, line)
+	f.pmu.Unlock()
+	switch {
+	case strings.HasSuffix(name, "/uv") && len(args) == 1 && args[0] == "--version":
+		return []byte("uv 0.12.20\n"), nil
+	case strings.HasSuffix(name, "/uv") && args[0] == "venv":
+		return nil, os.MkdirAll(filepath.Join(args[len(args)-1], "bin"), 0o755)
+	case strings.HasSuffix(name, "/uv") && args[0] == "pip" && args[1] == "install":
+		if f.failPip {
+			return []byte("error: Hash mismatch for torch\n"), errExit
+		}
+		venv := filepath.Dir(filepath.Dir(args[slices.Index(args, "--python")+1]))
+		return nil, os.WriteFile(filepath.Join(venv, "bin", "vllm"), []byte("#!/bin/sh\n"), 0o755)
+	case strings.HasSuffix(name, "/bin/vllm") && args[0] == "--version":
+		return []byte("0.30.0\n"), nil
+	}
+	return f.fakeSystem.run(ctx, env, name, args...)
+}
+
+func (f *fakePython) runStdin(_ context.Context, _ []string, stdin, name string, args ...string) ([]byte, error) {
+	f.pmu.Lock()
+	f.commands = append(f.commands, name+" "+strings.Join(args, " ")+" <<< "+strings.TrimSpace(stdin))
+	f.pmu.Unlock()
+	out := args[slices.Index(args, "--output-file")+1]
+	return nil, os.WriteFile(out, []byte("vllm==0.30.0 --hash=sha256:ab\n"), 0o644)
+}
+
+func pythonInstaller(t *testing.T, host discovery.Host, sys *fakePython) (*Installer, *release) {
+	uv := newRelease(map[string][]byte{
+		"uv-x86_64-unknown-linux-gnu.tar.gz": tarGz(t,
+			map[string]string{"uv-x86_64-unknown-linux-gnu/uv": "#!/bin/sh\n"}, nil),
+	})
+	gh := uv.serve(t)
+	mux := http.NewServeMux()
+	mux.HandleFunc("/pypi/vllm/0.30.0/json", func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`{"urls":[{"upload_time_iso_8601":"2026-09-22T05:22:21.647189Z"},
+			{"upload_time_iso_8601":"2026-09-22T05:23:10.039243Z"}]}`))
+	})
+	pypi := httptest.NewServer(mux)
+	t.Cleanup(pypi.Close)
+	return &Installer{
+		Root: t.TempDir(), Host: host, Run: sys.run, RunStdin: sys.runStdin,
+		APIBase: gh.URL, DownloadBase: gh.URL, PyPIBase: pypi.URL, HTTP: gh.Client(),
+		FreeSpace: func(string) (float64, error) { return 100, nil },
+	}, uv
+}
+
+func TestVLLMIsInstalledOnAGPUNode(t *testing.T) {
+	sys := &fakePython{fakeSystem: fakeSystem{installed: map[string]bool{}}}
+	in, _ := pythonInstaller(t, gpuNode, sys)
+
+	got := in.Converge(t.Context(), []Want{{Engine: "vllm", Version: "0.30.0"}})
+	if got[0].State != Ready {
+		t.Fatalf("not ready: %+v", got[0])
+	}
+	dir := filepath.Join(in.Root, "vllm", "0.30.0-cu13")
+	if got[0].Binary != filepath.Join(dir, "bin", "vllm") {
+		t.Errorf("binary %s, want the environment's vllm", got[0].Binary)
+	}
+	if !sys.installed["gcc"] {
+		t.Error("gcc, which Triton compiles its launcher with, was not installed")
+	}
+	all := strings.Join(sys.commands, "\n")
+	for _, want := range []string{
+		// PyPI as it stood a day after vLLM's last file, so the dependencies
+		// are the ones it was released against.
+		"--exclude-newer 2026-09-23T05:23:10Z",
+		"--generate-hashes",
+		"--require-hashes",
+		"venv --relocatable --python 3.12",
+	} {
+		if !strings.Contains(all, want) {
+			t.Errorf("no %q in:\n%s", want, all)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(dir, lockName)); err != nil {
+		t.Errorf("the resolved requirements were not kept: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(in.Root, ".uv-cache")); err == nil {
+		t.Error("the download cache was left behind after a successful install")
+	}
+
+	// Checked again on the next pass, not installed again.
+	before := len(sys.commands)
+	if again := in.Converge(t.Context(), []Want{{Engine: "vllm", Version: "0.30.0"}}); again[0].State != Ready {
+		t.Fatalf("second pass: %+v", again[0])
+	}
+	for _, c := range sys.commands[before:] {
+		if strings.Contains(c, "pip install") {
+			t.Errorf("a ready environment was installed again: %s", c)
+		}
+	}
+}
+
+func TestVLLMIsNotForEveryNode(t *testing.T) {
+	cases := []struct {
+		name  string
+		host  discovery.Host
+		state string
+		says  string
+	}{
+		{"no GPU", ubuntu, Skipped, "has none"},
+		{"old driver", discovery.Host{Arch: "amd64", NVIDIADriver: "550.54.15"}, Unsupported, "driver 580"},
+		{"V100", discovery.Host{Arch: "amd64", NVIDIADriver: "580.65.06", MinComputeCapability: 7.0}, Unsupported, "7.5"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			sys := &fakePython{fakeSystem: fakeSystem{installed: map[string]bool{}}}
+			in, uv := pythonInstaller(t, c.host, sys)
+			got := in.Converge(t.Context(), []Want{{Engine: "vllm", Version: "0.30.0"}})
+			if got[0].State != c.state || !strings.Contains(got[0].Detail, c.says) {
+				t.Errorf("got %s %q, want %s saying %q", got[0].State, got[0].Detail, c.state, c.says)
+			}
+			if uv.gets != 0 || len(sys.commands) != 0 {
+				t.Errorf("a node that cannot run it still started installing: %v", sys.commands)
+			}
+		})
+	}
+}
+
+func TestAPythonEngineIsRefusedWithoutTheDiskForIt(t *testing.T) {
+	sys := &fakePython{fakeSystem: fakeSystem{installed: map[string]bool{"gcc": true}}}
+	in, uv := pythonInstaller(t, gpuNode, sys)
+	in.FreeSpace = func(string) (float64, error) { return 12.5, nil }
+	got := in.Converge(t.Context(), []Want{{Engine: "vllm", Version: "0.30.0"}})
+	if got[0].State != Failed || !strings.Contains(got[0].Detail, "12.5 GB") {
+		t.Errorf("got %s %q", got[0].State, got[0].Detail)
+	}
+	if uv.gets != 0 {
+		t.Error("it began downloading anyway")
+	}
+}
+
+func TestAFailedPythonInstallLeavesNothingThatLooksInstalled(t *testing.T) {
+	sys := &fakePython{fakeSystem: fakeSystem{installed: map[string]bool{"gcc": true}}, failPip: true}
+	in, _ := pythonInstaller(t, gpuNode, sys)
+	got := in.Converge(t.Context(), []Want{{Engine: "vllm", Version: "0.30.0"}})
+	if got[0].State != Failed || !strings.Contains(got[0].Detail, "Hash mismatch") {
+		t.Fatalf("got %s %q", got[0].State, got[0].Detail)
+	}
+	entries, _ := os.ReadDir(filepath.Join(in.Root, "vllm"))
+	for _, e := range entries {
+		t.Errorf("left behind: %s", e.Name())
+	}
+}
+
+func TestAVersionPyPIDoesNotHaveIsSaidSo(t *testing.T) {
+	sys := &fakePython{fakeSystem: fakeSystem{installed: map[string]bool{"gcc": true}}}
+	in, _ := pythonInstaller(t, gpuNode, sys)
+	got := in.Converge(t.Context(), []Want{{Engine: "vllm", Version: "9.9.9"}})
+	if got[0].State != Failed || !strings.Contains(got[0].Detail, "PyPI has no vllm 9.9.9") {
+		t.Errorf("got %s %q", got[0].State, got[0].Detail)
+	}
+}

internal/agent/provision/recipe.go

@@ -11,6 +11,7 @@ package provision
 
 import (
 	"fmt"
+	"slices"
 	"strings"
 
 	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/discovery"
@@ -33,23 +34,163 @@ type Build struct {
 	// CPUFlags are extensions the build is slow without. Missing ones are
 	// reported, not refused: slow is still running.
 	CPUFlags []string
+
+	// Python, when set, makes the build a Python environment rather than an
+	// archive: that interpreter version, with Requirements installed from
+	// PyPI by uv. Binary is then looked for in the environment's bin.
+	Python       string
+	Requirements []string
+	// VersionArgs is what Binary is run with to prove the build works, when
+	// --version is not it.
+	VersionArgs []string
+	// FreeGB is the disk space the installation needs before it starts: a
+	// Python engine is several gigabytes, and one that fills the disk halfway
+	// leaves the node worse off than one that never began.
+	FreeGB int
 }
 
 // Recipe knows how to install one engine.
 type Recipe struct {
-	// Repo is the GitHub repository whose releases carry the builds.
+	// Repo is the GitHub repository whose releases carry the builds; empty
+	// for an engine installed from PyPI.
 	Repo string
+	// PyPI is the project an engine installed from PyPI is published as.
+	PyPI string
 	// Choose picks the build for a machine, or says why none fits.
 	Choose func(version string, h discovery.Host) (Build, error)
 }
 
 // Recipes are the engines this agent can install.
 //
-// vLLM and SGLang are not here yet: they are Python environments of several
-// gigabytes rather than an archive, and are installed by hand and named in the
-// agent's configuration until they are.
+// vLLM and SGLang are Python environments of several gigabytes, installed
+// from PyPI by uv, which is itself installed like llama.cpp: a GitHub release
+// checked against its published checksum.
 var Recipes = map[string]Recipe{
 	"llamacpp": {Repo: "ggml-org/llama.cpp", Choose: chooseLlamaCpp},
+	"vllm":     {PyPI: "vllm", Choose: chooseVLLM},
+	"sglang":   {PyPI: "sglang", Choose: chooseSGLang},
+	"uv":       {Repo: "astral-sh/uv", Choose: chooseUV},
+}
+
+// Installable are the engines this agent can install, as it tells the
+// control plane: every recipe but uv, which is a tool for the others.
+func Installable() []string {
+	var out []string
+	for name := range Recipes {
+		if name != "uv" {
+			out = append(out, name)
+		}
+	}
+	slices.Sort(out)
+	return out
+}
+
+// UVVersion is the uv that installs the Python engines.
+const UVVersion = "0.12.20"
+
+// pythonForEngines is the interpreter the Python engines run on. uv fetches
+// it, so the node's own Python — or its absence — does not matter.
+const pythonForEngines = "3.12"
+
+// NotHere is the error a recipe gives for a node the engine is not meant
+// for, as opposed to one it should run on and cannot: vLLM on a machine
+// with no GPU is not a fault, and is not reported as one.
+type NotHere struct{ Reason string }
+
+func (e NotHere) Error() string { return e.Reason }
+
+func chooseUV(version string, h discovery.Host) (Build, error) {
+	var arch string
+	switch h.Arch {
+	case "amd64":
+		arch = "x86_64"
+	case "arm64":
+		arch = "aarch64"
+	default:
+		return Build{}, fmt.Errorf("uv publishes no Linux build for %s", orUnknown(h.Arch))
+	}
+	return Build{
+		Variant: arch,
+		Assets:  []string{"uv-" + arch + "-unknown-linux-gnu.tar.gz"},
+		Binary:  "uv",
+	}, nil
+}
+
+// minDriverForCUDA13 is the oldest NVIDIA driver CUDA 13 runs on. Every vLLM
+// since 0.26 and SGLang 0.5 is built on torch for CUDA 13.
+const minDriverForCUDA13 = 580
+
+// minComputeForCUDA13 is the oldest GPU CUDA 13 supports: Turing. It dropped
+// Volta, so a V100 cannot run these builds at all.
+const minComputeForCUDA13 = 7.5
+
+// cudaGate says whether a node can run an engine built on CUDA 13.
+func cudaGate(engine string, h discovery.Host) error {
+	switch h.Arch {
+	case "amd64", "arm64":
+	default:
+		return fmt.Errorf("%s publishes no Linux build for %s", engine, orUnknown(h.Arch))
+	}
+	if h.NVIDIADriver == "" {
+		return NotHere{engine + " runs on NVIDIA GPUs and this node has none; it serves llama.cpp models"}
+	}
+	if major := leadingInt(h.NVIDIADriver); major > 0 && major < minDriverForCUDA13 {
+		return fmt.Errorf("%s is built for CUDA 13, which needs NVIDIA driver %d or newer; this node has %s",
+			engine, minDriverForCUDA13, h.NVIDIADriver)
+	}
+	if cc := h.MinComputeCapability; cc > 0 && cc < minComputeForCUDA13 {
+		return fmt.Errorf("%s is built for CUDA 13, which supports GPUs of compute capability %.1f and newer; this node has %.1f",
+			engine, minComputeForCUDA13, cc)
+	}
+	return nil
+}
+
+// Python engines need a C compiler at run time: Triton builds a small
+// launcher for its kernels the first time a model loads, and without gcc
+// that load fails long after the installation looked finished.
+var compilerPackages = map[string][]string{"deb": {"gcc"}, "rpm": {"gcc"}}
+
+func chooseVLLM(version string, h discovery.Host) (Build, error) {
+	if err := cudaGate("vLLM", h); err != nil {
+		return Build{}, err
+	}
+	return Build{
+		Variant:      "cu13",
+		Python:       pythonForEngines,
+		Requirements: []string{"vllm==" + version},
+		Binary:       "vllm",
+		Packages:     compilerPackages,
+		FreeGB:       25,
+	}, nil
+}
+
+func chooseSGLang(version string, h discovery.Host) (Build, error) {
+	if err := cudaGate("SGLang", h); err != nil {
+		return Build{}, err
+	}
+	// SGLang is launched as a module, so what the agent is given is the
+	// environment's interpreter, and the proof is importing it.
+	return Build{
+		Variant:      "cu13",
+		Python:       pythonForEngines,
+		Requirements: []string{"sglang==" + version},
+		Binary:       "python",
+		VersionArgs:  []string{"-c", "import sglang; print('sglang', sglang.__version__)"},
+		Packages:     compilerPackages,
+		FreeGB:       25,
+	}, nil
+}
+
+// leadingInt is the number a version string starts with: 580 of "580.65.06".
+func leadingInt(s string) int {
+	n := 0
+	for _, c := range strings.TrimSpace(s) {
+		if c < '0' || c > '9' {
+			break
+		}
+		n = n*10 + int(c-'0')
+	}
+	return n
 }
 
 // cudaForLlamaCpp is the CUDA build taken on an NVIDIA node. The release also

internal/agent/supervisor/health.go

@@ -53,8 +53,8 @@ func NewHTTPHealth(timeout time.Duration, opts ...HTTPHealthOption) *HTTPHealth
 }
 
 // Ready reports whether the engine at baseURL is serving model.
-func (h *HTTPHealth) Ready(ctx context.Context, baseURL, model string) error {
-	if err := h.get(ctx, baseURL+h.healthPath, nil); err != nil {
+func (h *HTTPHealth) Ready(ctx context.Context, baseURL, model, apiKey string) error {
+	if err := h.get(ctx, baseURL+h.healthPath, apiKey, nil); err != nil {
 		return fmt.Errorf("health: %w", err)
 	}
 	if !h.requireName || model == "" {
@@ -66,7 +66,7 @@ func (h *HTTPHealth) Ready(ctx context.Context, baseURL, model string) error {
 			ID string `json:"id"`
 		} `json:"data"`
 	}
-	if err := h.get(ctx, baseURL+h.modelsPath, &list); err != nil {
+	if err := h.get(ctx, baseURL+h.modelsPath, apiKey, &list); err != nil {
 		return fmt.Errorf("models: %w", err)
 	}
 	for _, d := range list.Data {
@@ -77,11 +77,14 @@ func (h *HTTPHealth) Ready(ctx context.Context, baseURL, model string) error {
 	return fmt.Errorf("engine is up but does not serve %q yet", model)
 }
 
-func (h *HTTPHealth) get(ctx context.Context, url string, out any) error {
+func (h *HTTPHealth) get(ctx context.Context, url, apiKey string, out any) error {
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
 	if err != nil {
 		return err
 	}
+	if apiKey != "" {
+		req.Header.Set("Authorization", "Bearer "+apiKey)
+	}
 	resp, err := h.client.Do(req)
 	if err != nil {
 		return err

internal/agent/supervisor/health_test.go

@@ -39,7 +39,7 @@ func engineStub(t *testing.T, healthy bool, models ...string) *httptest.Server {
 
 func TestReadyWhenServingModel(t *testing.T) {
 	srv := engineStub(t, true, "llama-3.3-70b")
-	if err := NewHTTPHealth(time.Second).Ready(t.Context(), srv.URL, "llama-3.3-70b"); err != nil {
+	if err := NewHTTPHealth(time.Second).Ready(t.Context(), srv.URL, "llama-3.3-70b", ""); err != nil {
 		t.Errorf("a serving engine was reported unready: %v", err)
 	}
 }
@@ -48,7 +48,7 @@ func TestNotReadyWhileLoading(t *testing.T) {
 	// The case that matters: the process is up but the weights are not loaded.
 	// Routing on /health alone would send traffic into a loading model.
 	srv := engineStub(t, false, "llama-3.3-70b")
-	err := NewHTTPHealth(time.Second).Ready(t.Context(), srv.URL, "llama-3.3-70b")
+	err := NewHTTPHealth(time.Second).Ready(t.Context(), srv.URL, "llama-3.3-70b", "")
 	if err == nil {
 		t.Fatal("an unhealthy engine was reported ready")
 	}
@@ -61,7 +61,7 @@ func TestNotReadyWhenModelMissing(t *testing.T) {
 	// /health passes but the model is not listed: the engine is up and serving
 	// something else, or still registering.
 	srv := engineStub(t, true, "some-other-model")
-	err := NewHTTPHealth(time.Second).Ready(t.Context(), srv.URL, "llama-3.3-70b")
+	err := NewHTTPHealth(time.Second).Ready(t.Context(), srv.URL, "llama-3.3-70b", "")
 	if err == nil {
 		t.Fatal("a model that is not served was reported ready")
 	}
@@ -73,14 +73,33 @@ func TestNotReadyWhenModelMissing(t *testing.T) {
 func TestModelCheckCanBeSkipped(t *testing.T) {
 	srv := engineStub(t, true)
 	h := NewHTTPHealth(time.Second, WithoutModelCheck())
-	if err := h.Ready(t.Context(), srv.URL, "anything"); err != nil {
+	if err := h.Ready(t.Context(), srv.URL, "anything", ""); err != nil {
 		t.Errorf("the model check was not skipped: %v", err)
 	}
 }
 
 func TestUnreachableEngine(t *testing.T) {
 	h := NewHTTPHealth(200 * time.Millisecond)
-	if err := h.Ready(t.Context(), "http://127.0.0.1:1", "m"); err == nil {
+	if err := h.Ready(t.Context(), "http://127.0.0.1:1", "m", ""); err == nil {
 		t.Error("an unreachable engine was reported ready")
 	}
 }
+
+func TestTheHealthCheckSendsTheEnginesKey(t *testing.T) {
+	// An engine started with a key refuses /v1/models without it, and a
+	// shard that is serving would read as never ready.
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("Authorization") != "Bearer k1" {
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+		_, _ = w.Write([]byte(`{"data":[{"id":"m"}]}`))
+	}))
+	defer srv.Close()
+	if err := NewHTTPHealth(time.Second).Ready(t.Context(), srv.URL, "m", "k1"); err != nil {
+		t.Errorf("with the key: %v", err)
+	}
+	if err := NewHTTPHealth(time.Second).Ready(t.Context(), srv.URL, "m", ""); err == nil {
+		t.Error("without the key the engine refused, and that read as ready")
+	}
+}

internal/agent/supervisor/supervisor.go

@@ -79,7 +79,7 @@ func (c *Config) normalize() {
 // supervisor can be tested without an HTTP engine.
 type HealthChecker interface {
 	// Ready reports whether the shard at baseURL serves model.
-	Ready(ctx context.Context, baseURL, model string) error
+	Ready(ctx context.Context, baseURL, model, apiKey string) error
 }
 
 // Shard is one supervised engine process.
@@ -243,6 +243,16 @@ func (s *Supervisor) launch(ctx context.Context, sh *Shard, cmds []engines.Comma
 	}
 
 	cmd := cmds[len(cmds)-1]
+	// The main process can need the rendezvous point too: a Ray worker's
+	// join is its only process, and started before the head listens it
+	// exits, failing the shard and with it the replica.
+	if cmd.WaitForLeaderPort && !sh.Spec.Leader() {
+		addr := fmt.Sprintf("%s:%d", sh.Spec.LeaderAddr, sh.Spec.LeaderPort)
+		if err := waitForPort(runCtx, addr, s.cfg.RendezvousTimeout); err != nil {
+			cancel()
+			return fmt.Errorf("waiting for %s (%s): %w", addr, cmd.Name, err)
+		}
+	}
 
 	c := exec.CommandContext(runCtx, cmd.Path, cmd.Args...)
 	c.Env = cmd.Env
@@ -401,7 +411,7 @@ func (s *Supervisor) WaitReady(ctx context.Context, sh *Shard, baseURL, model st
 			last := strings.Join(sh.Logs(10), "\n")
 			return fmt.Errorf("shard %s not ready within %v; last output:\n%s", sh.ID, timeout, last)
 		case <-t.C:
-			if err := s.health.Ready(ctx, baseURL, model); err != nil {
+			if err := s.health.Ready(ctx, baseURL, model, sh.Spec.APIKey); err != nil {
 				continue
 			}
 			sh.setState(Ready, nil)

internal/agent/supervisor/supervisor_test.go

@@ -21,7 +21,7 @@ import (
 // scriptedHealth reports ready once the flag is set.
 type scriptedHealth struct{ ready atomic.Bool }
 
-func (h *scriptedHealth) Ready(context.Context, string, string) error {
+func (h *scriptedHealth) Ready(context.Context, string, string, string) error {
 	if h.ready.Load() {
 		return nil
 	}
@@ -243,7 +243,9 @@ func TestWaitReadyTimeoutIncludesLogs(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	time.Sleep(100 * time.Millisecond) // let the line be captured
+	eventually(t, 3*time.Second, "the line was never captured", func() bool {
+		return strings.Contains(strings.Join(sh.Logs(10), "\n"), "CUDA out of memory")
+	})
 
 	err = s.WaitReady(t.Context(), sh, "http://x", "m", 200*time.Millisecond)
 	if err == nil {
@@ -295,7 +297,10 @@ func TestLogsAreCaptured(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	time.Sleep(400 * time.Millisecond)
+	eventually(t, 3*time.Second, "not every line arrived", func() bool {
+		l := strings.Join(sh.Logs(10), "\n")
+		return strings.Contains(l, "line1") && strings.Contains(l, "line2") && strings.Contains(l, "line3")
+	})
 
 	logs := strings.Join(sh.Logs(10), "\n")
 	for _, want := range []string{"line1", "line2", "line3"} {
@@ -372,11 +377,11 @@ func TestStateFileRemovedOnExit(t *testing.T) {
 
 	sh, _ := s.Start(t.Context(), "a", engines.ShardSpec{}, shellCommand("exit 0"))
 	waitState(t, sh, Failed, 3*time.Second)
-	time.Sleep(50 * time.Millisecond)
-
-	if _, err := os.Stat(s.statePath("a")); !os.IsNotExist(err) {
-		t.Error("the state file outlived the process; a later scan would find a dead orphan")
-	}
+	eventually(t, 3*time.Second,
+		"the state file outlived the process; a later scan would find a dead orphan", func() bool {
+			_, err := os.Stat(s.statePath("a"))
+			return os.IsNotExist(err)
+		})
 }
 
 // --- state machine and ring buffer ---
@@ -743,7 +748,9 @@ func TestWaitAliveFailsOnEarlyExit(t *testing.T) {
 	if err := s.WaitAlive(t.Context(), sh); err == nil {
 		t.Fatal("a worker that died immediately was reported ready")
 	}
-	if d := time.Since(start); d > 1500*time.Millisecond {
+	// Below AliveGrace (5s), which is what waiting it out would take; the
+	// headroom is for a loaded runner, where 1.5s was sometimes not enough.
+	if d := time.Since(start); d > 4*time.Second {
 		t.Errorf("waited %v for a process that had already exited", d)
 	}
 }
@@ -794,3 +801,50 @@ func TestAnAdoptedShardCanBecomeReady(t *testing.T) {
 	}
 	_ = s2.Stop(t.Context(), "a")
 }
+
+func TestAWorkersOnlyProcessWaitsForTheLeader(t *testing.T) {
+	// A Ray worker's join is its only process. The wait was honoured only for
+	// sidecars, so the join started at once, found no head, exited, and took
+	// the replica down with it.
+	s, _ := newSupervisor(t)
+	s.cfg.RendezvousTimeout = 5 * time.Second
+
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	port := ln.Addr().(*net.TCPAddr).Port
+	_ = ln.Close()
+	go func() {
+		time.Sleep(400 * time.Millisecond)
+		l, err := net.Listen("tcp", fmt.Sprintf("127.0.0.1:%d", port))
+		if err == nil {
+			t.Cleanup(func() { _ = l.Close() })
+		}
+	}()
+
+	spec := engines.ShardSpec{Rank: 1, LeaderAddr: "127.0.0.1", LeaderPort: port}
+	cmds := []engines.Command{{Name: "join", Path: "/bin/sh", Args: []string{"-c", "sleep 30"},
+		Env: os.Environ(), WaitForLeaderPort: true}}
+	start := time.Now()
+	if _, err := s.Start(t.Context(), "w", spec, cmds); err != nil {
+		t.Fatal(err)
+	}
+	if d := time.Since(start); d < 300*time.Millisecond {
+		t.Errorf("the worker started after %v, before the leader was listening", d)
+	}
+}
+
+// eventually waits for cond, failing with msg if it does not hold within
+// limit. Sleeping a fixed time and then checking measured the machine the
+// test ran on, and a loaded CI runner under the race detector lost that race.
+func eventually(t *testing.T, limit time.Duration, msg string, cond func() bool) {
+	t.Helper()
+	deadline := time.Now().Add(limit)
+	for !cond() {
+		if time.Now().After(deadline) {
+			t.Fatal(msg)
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+}

internal/agent/upgrade.go

@@ -0,0 +1,58 @@
+package agent
+
+import (
+	"context"
+	"os"
+	"runtime"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/release"
+
+	llmgwv1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1"
+)
+
+// upgradeExit is the exit status after an upgrade: non-zero, so systemd's
+// Restart=on-failure starts the new binary, and distinct, so the journal says
+// why the agent went.
+const upgradeExit = 75
+
+// exitForUpgrade ends the process; a variable so a test can see it called
+// rather than have its own process end.
+var exitForUpgrade = func() { os.Exit(upgradeExit) }
+
+// upgradeTarget is the binary an upgrade replaces; a variable so a test
+// replaces a file of its own rather than the test binary running it.
+var upgradeTarget = os.Executable
+
+// upgrade replaces this agent's binary with a release and restarts into it.
+//
+// Engines are not touched: an agent restart leaves them running and adopts
+// them again, which is what makes upgrading a node something that can be done
+// while it serves.
+func (a *Agent) upgrade(ctx context.Context, m *llmgwv1.UpgradeAgent, out chan<- *llmgwv1.AgentMessage) {
+	reply := &llmgwv1.UpgradeReply{RequestId: m.GetRequestId(), Version: m.GetVersion()}
+	send := func() {
+		select {
+		case out <- &llmgwv1.AgentMessage{Msg: &llmgwv1.AgentMessage_Upgrade{Upgrade: reply}}:
+		case <-ctx.Done():
+		}
+	}
+	a.log.Info("upgrading", "to", m.GetVersion(), "from", a.cfg.Version)
+	self, err := upgradeTarget()
+	if err == nil {
+		dctx, cancel := context.WithTimeout(ctx, 10*time.Minute)
+		_, err = release.Install(dctx, nil, m.GetReleases(), m.GetVersion(), runtime.GOOS, runtime.GOARCH, self)
+		cancel()
+	}
+	if err != nil {
+		reply.Error = err.Error()
+		a.log.Error("upgrade failed; still running the old version", "to", m.GetVersion(), "err", err)
+		send()
+		return
+	}
+	send()
+	a.log.Info("upgraded; restarting into the new version", "to", m.GetVersion())
+	// A moment for the reply to leave before the stream goes.
+	time.Sleep(500 * time.Millisecond)
+	exitForUpgrade()
+}

internal/agent/upgrade_test.go

@@ -0,0 +1,78 @@
+package agent
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+	"time"
+
+	llmgwv1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/release"
+)
+
+func TestAnAgentUpgradesItselfAndSaysSoBeforeRestarting(t *testing.T) {
+	body := []byte("the new agent")
+	sum := sha256.Sum256(body)
+	asset := release.AssetName("v9.9.9", runtime.GOOS, runtime.GOARCH)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/v9.9.9/checksums.txt":
+			_, _ = w.Write([]byte(hex.EncodeToString(sum[:]) + "  " + asset + "\n"))
+		case "/v9.9.9/" + asset:
+			_, _ = w.Write(body)
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer srv.Close()
+
+	bin := filepath.Join(t.TempDir(), "llmgw")
+	_ = os.WriteFile(bin, []byte("the old agent"), 0o755)
+	exited := make(chan struct{}, 1)
+	oldTarget, oldExit := upgradeTarget, exitForUpgrade
+	upgradeTarget = func() (string, error) { return bin, nil }
+	exitForUpgrade = func() { exited <- struct{}{} }
+	t.Cleanup(func() { upgradeTarget, exitForUpgrade = oldTarget, oldExit })
+
+	cfg := Config{Server: "127.0.0.1:7443", NodeID: "n1", WeightsCache: t.TempDir(), EnginesDir: t.TempDir()}
+	cfg.Superv.WorkDir = t.TempDir()
+	a, err := New(cfg, nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	out := make(chan *llmgwv1.AgentMessage, 1)
+	go a.upgrade(t.Context(), &llmgwv1.UpgradeAgent{RequestId: "u1", Version: "v9.9.9", Releases: srv.URL}, out)
+
+	select {
+	case m := <-out:
+		if r := m.GetUpgrade(); r.GetRequestId() != "u1" || r.GetError() != "" {
+			t.Fatalf("reply %+v", r)
+		}
+	case <-time.After(10 * time.Second):
+		t.Fatal("no reply")
+	}
+	select {
+	case <-exited:
+	case <-time.After(5 * time.Second):
+		t.Fatal("the agent did not restart into the new binary")
+	}
+	if b, _ := os.ReadFile(bin); string(b) != "the new agent" {
+		t.Errorf("binary holds %q", b)
+	}
+
+	// A version with no release answers with why, and does not restart.
+	go a.upgrade(t.Context(), &llmgwv1.UpgradeAgent{RequestId: "u2", Version: "v9.9.8", Releases: srv.URL}, out)
+	if r := (<-out).GetUpgrade(); r.GetError() == "" {
+		t.Error("an upgrade to a release that does not exist reported success")
+	}
+	select {
+	case <-exited:
+		t.Error("a failed upgrade restarted the agent")
+	case <-time.After(time.Second):
+	}
+}

internal/auth/auth.go

@@ -21,6 +21,9 @@ import (
 type Principal struct {
 	KeyID     string
 	KeyPrefix string
+	// UserID is the person the key belongs to, empty for a key an operator
+	// issued in a project. A personal key has a person and no project.
+	UserID    string
 	ProjectID string
 	TeamID    string
 	OrgID     string
@@ -186,7 +189,7 @@ func (a *Authenticator) resolve(ctx context.Context, hash []byte) (Principal, er
 		return Principal{}, err
 	}
 	return Principal{
-		KeyID: k.ID, KeyPrefix: k.Prefix, ProjectID: eff.ProjectID,
+		KeyID: k.ID, KeyPrefix: k.Prefix, UserID: eff.UserID, ProjectID: eff.ProjectID,
 		TeamID: eff.TeamID, OrgID: eff.OrgID,
 		Band: eff.Band, RoutingProfile: eff.RoutingProfile,
 		Limits: eff,

internal/bench/bench.go

@@ -225,6 +225,7 @@ func runStep(ctx context.Context, client *http.Client, cfg Config, concurrency i
 	)
 
 	sampler := newSampler(cfg.MetricsURL, cfg.Engine)
+	sampler.apiKey = cfg.APIKey
 	sampler.start(ctx)
 
 	start := time.Now()

internal/bench/sampler.go

@@ -19,6 +19,7 @@ import (
 // Optional, because a run pointed at the gateway has no single engine to read.
 type sampler struct {
 	url    string
+	apiKey string
 	engine string
 	client *http.Client
 	cancel context.CancelFunc
@@ -65,6 +66,9 @@ func (s *sampler) sample(ctx context.Context) {
 	if err != nil {
 		return
 	}
+	if s.apiKey != "" {
+		req.Header.Set("Authorization", "Bearer "+s.apiKey)
+	}
 	resp, err := s.client.Do(req)
 	if err != nil {
 		return

internal/cli/agent.go

@@ -163,10 +163,10 @@ func printInventory(inv discovery.Inventory) {
 				g.Index, g.Class(), g.Name, g.MemoryTotalMB, g.ComputeCapability, health)
 		}
 		fmt.Fprintf(w, "  classes: %v\n", inv.Classes())
-		if !discovery.NVMLSupported() {
-			fmt.Fprintln(w, "  NVLink topology unavailable: rebuild with -tags nvml.")
-			fmt.Fprintln(w, "  Without it, placement cannot keep a tensor-parallel group inside")
-			fmt.Fprintln(w, "  one NVLink domain (plan §6.2).")
+		for _, g := range inv.GPUs {
+			if len(g.NVLinkPeers) > 0 {
+				fmt.Fprintf(w, "  GPU %d NVLink peers: %v\n", g.Index, g.NVLinkPeers)
+			}
 		}
 	}
 

internal/cli/backup.go

@@ -0,0 +1,312 @@
+package cli
+
+import (
+	"archive/tar"
+	"compress/gzip"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"net/url"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"slices"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/config"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/version"
+)
+
+// DefaultBackupDir is where backups are written and where the control plane
+// looks for the newest one.
+//
+// Its own directory rather than /var/backups/llmgw, which a PostgreSQL move
+// had already made for its own dumps, owned by postgres and closed to
+// everyone else — so the control plane could not see a backup landing in it.
+const DefaultBackupDir = "/var/backups/llmgw-server"
+
+func newBackupCmd() *cobra.Command {
+	var (
+		configPath string
+		etcDir     string
+		dir        string
+		keep       int
+	)
+	c := &cobra.Command{
+		Use:   "backup",
+		Short: "Write the store and /etc/llmgw to one archive, and keep the last few",
+		Long: "Everything a control plane cannot be rebuilt without: the store — keys,\n" +
+			"people, quotas, usage, the models added at runtime, the secret engine\n" +
+			"keys derive from — and /etc/llmgw, which holds the configuration, the\n" +
+			"store's address and the certificate authority's key.\n\n" +
+			"The archive holds that key, so it is written readable by root only. It\n" +
+			"is on the same disk as what it backs up: copy it elsewhere, or it does\n" +
+			"not survive the loss of this machine.\n\n" +
+			"Run daily by llmgw-backup.timer (`llmgw server backup`). The control plane publishes the time of\n" +
+			"the newest archive as llmgw_backup_last_success_timestamp_seconds, and\n" +
+			"BackupTooOld fires when it is more than a day old.",
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			cfg, err := config.Load(configPath)
+			if err != nil {
+				return err
+			}
+			path, err := writeBackup(cmd.Context(), cfg.Auth.Store, etcDir, dir)
+			if err != nil {
+				return err
+			}
+			if why := unlistable(dir); why != "" {
+				fmt.Fprintf(cmd.ErrOrStderr(), "warning: %s; the control plane will report no backup "+
+					"and BackupTooOld will fire\n", why)
+			}
+			removed, err := pruneBackups(dir, keep)
+			if err != nil {
+				return err
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "wrote %s", path)
+			if removed > 0 {
+				fmt.Fprintf(cmd.OutOrStdout(), "; removed %d older", removed)
+			}
+			fmt.Fprintln(cmd.OutOrStdout())
+			return nil
+		},
+	}
+	c.Flags().StringVar(&configPath, "config", "/etc/llmgw/server.yaml", "the control plane's configuration")
+	c.Flags().StringVar(&etcDir, "etc", "/etc/llmgw", "configuration directory to include")
+	c.Flags().StringVar(&dir, "dir", DefaultBackupDir, "where archives are written")
+	c.Flags().IntVar(&keep, "keep", 14, "how many archives to keep")
+	return c
+}
+
+const backupPrefix = "llmgw-backup-"
+
+// writeBackup writes one archive and returns its path. Written beside its
+// final name and renamed, so a backup interrupted halfway is never the newest
+// one the control plane reports.
+func writeBackup(ctx context.Context, storeAddr, etcDir, dir string) (string, error) {
+	// Listable by anyone, so the control plane — not root — can see when the
+	// newest archive was written. The archives themselves are root's alone.
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return "", err
+	}
+	host, _ := os.Hostname()
+	name := backupPrefix + host + "-" + time.Now().UTC().Format("20060102T150405Z") + ".tar.gz"
+	final := filepath.Join(dir, name)
+	part := final + ".part"
+
+	f, err := os.OpenFile(part, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o600)
+	if err != nil {
+		return "", err
+	}
+	ok := false
+	defer func() {
+		if !ok {
+			_ = os.Remove(part)
+		}
+	}()
+	gz := gzip.NewWriter(f)
+	tw := tar.NewWriter(gz)
+
+	manifest := fmt.Sprintf("llmgw %s\nhost %s\ntime %s\n", version.Version, host,
+		time.Now().UTC().Format(time.RFC3339))
+	if err := addBytes(tw, "MANIFEST", []byte(manifest)); err != nil {
+		return "", err
+	}
+	if storeAddr != "" {
+		if err := addStore(ctx, tw, storeAddr, dir); err != nil {
+			return "", fmt.Errorf("the store: %w", err)
+		}
+	}
+	if err := addTree(tw, etcDir, "etc/llmgw"); err != nil {
+		return "", fmt.Errorf("%s: %w", etcDir, err)
+	}
+	if err := errors.Join(tw.Close(), gz.Close(), f.Sync(), f.Close()); err != nil {
+		return "", err
+	}
+	if err := os.Rename(part, final); err != nil {
+		return "", err
+	}
+	ok = true
+	return final, nil
+}
+
+// addStore dumps the store into the archive.
+func addStore(ctx context.Context, tw *tar.Writer, addr, scratch string) error {
+	addr, err := store.ResolveAddress(addr)
+	if err != nil {
+		return err
+	}
+	// Inside a directory only its owner can enter. The archive directory is
+	// listable on purpose, and VACUUM INTO creates its file with the default
+	// mode: made there directly, a full copy of the store — password hashes,
+	// the engine-key secret — sat readable by any local user for as long as
+	// the backup took.
+	tmpDir, err := os.MkdirTemp(scratch, ".store-")
+	if err != nil {
+		return err
+	}
+	defer os.RemoveAll(tmpDir)
+	tmpPath := filepath.Join(tmpDir, "store")
+
+	name := "store.sqlite"
+	if store.IsPostgres(addr) {
+		name = "store.pgdump"
+		if err := pgDump(ctx, addr, tmpPath); err != nil {
+			return err
+		}
+	} else {
+		db, err := store.Open(ctx, addr)
+		if err != nil {
+			return err
+		}
+		err = db.SnapshotTo(ctx, tmpPath)
+		_ = db.Close()
+		if err != nil {
+			return err
+		}
+	}
+	return addFile(tw, tmpPath, name)
+}
+
+// pgDump runs pg_dump in its custom format, which pg_restore can restore
+// selectively. The connection is given through the environment, not the
+// command line: a DSN carries the password, and every user on the machine
+// can read another process's arguments.
+func pgDump(ctx context.Context, dsn, out string) error {
+	u, err := url.Parse(dsn)
+	if err != nil {
+		return fmt.Errorf("the store address is not a URL")
+	}
+	env := os.Environ()
+	set := func(k, v string) {
+		if v != "" {
+			env = append(env, k+"="+v)
+		}
+	}
+	set("PGHOST", u.Hostname())
+	set("PGPORT", u.Port())
+	set("PGUSER", u.User.Username())
+	if pw, ok := u.User.Password(); ok {
+		set("PGPASSWORD", pw)
+	}
+	set("PGDATABASE", strings.TrimPrefix(u.Path, "/"))
+	set("PGSSLMODE", u.Query().Get("sslmode"))
+	cmd := exec.CommandContext(ctx, "pg_dump", "--format=custom", "--no-owner", "--file="+out) //nolint:gosec // fixed binary, our own file
+	cmd.Env = env
+	if b, err := cmd.CombinedOutput(); err != nil {
+		return fmt.Errorf("pg_dump: %v: %s", err, strings.TrimSpace(string(b)))
+	}
+	return nil
+}
+
+func addTree(tw *tar.Writer, root, as string) error {
+	return filepath.WalkDir(root, func(p string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		rel, _ := filepath.Rel(root, p)
+		name := filepath.ToSlash(filepath.Join(as, rel))
+		info, err := d.Info()
+		if err != nil {
+			return err
+		}
+		switch {
+		case d.IsDir():
+			return tw.WriteHeader(&tar.Header{Name: name + "/", Mode: int64(info.Mode().Perm()),
+				Typeflag: tar.TypeDir, ModTime: info.ModTime()})
+		case info.Mode().IsRegular():
+			return addFile(tw, p, name)
+		}
+		return nil // sockets, links: not configuration
+	})
+}
+
+func addFile(tw *tar.Writer, path, name string) error {
+	f, err := os.Open(path) //nolint:gosec // files we chose to back up
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	info, err := f.Stat()
+	if err != nil {
+		return err
+	}
+	if err := tw.WriteHeader(&tar.Header{Name: name, Mode: int64(info.Mode().Perm()),
+		Size: info.Size(), ModTime: info.ModTime(), Typeflag: tar.TypeReg}); err != nil {
+		return err
+	}
+	_, err = io.Copy(tw, f)
+	return err
+}
+
+func addBytes(tw *tar.Writer, name string, b []byte) error {
+	if err := tw.WriteHeader(&tar.Header{Name: name, Mode: 0o600, Size: int64(len(b)),
+		ModTime: time.Now(), Typeflag: tar.TypeReg}); err != nil {
+		return err
+	}
+	_, err := tw.Write(b)
+	return err
+}
+
+// pruneBackups keeps the newest keep archives. Only files this command
+// wrote are considered, so nothing else in the directory is ever removed.
+func pruneBackups(dir string, keep int) (int, error) {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return 0, err
+	}
+	var names []string
+	for _, e := range entries {
+		if n := e.Name(); strings.HasPrefix(n, backupPrefix) && strings.HasSuffix(n, ".tar.gz") {
+			names = append(names, n)
+		}
+	}
+	// The name carries a UTC timestamp, so name order is age order.
+	slices.Sort(names)
+	removed := 0
+	for len(names) > max(keep, 1) {
+		if err := os.Remove(filepath.Join(dir, names[0])); err != nil {
+			return removed, err
+		}
+		names = names[1:]
+		removed++
+	}
+	return removed, nil
+}
+
+// NewestBackup is the modification time of the newest complete archive in
+// dir, or zero when there is none.
+func NewestBackup(dir string) time.Time {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return time.Time{}
+	}
+	var newest time.Time
+	for _, e := range entries {
+		if n := e.Name(); !strings.HasPrefix(n, backupPrefix) || !strings.HasSuffix(n, ".tar.gz") {
+			continue
+		}
+		if info, err := e.Info(); err == nil && info.ModTime().After(newest) {
+			newest = info.ModTime()
+		}
+	}
+	return newest
+}
+
+// unlistable says why the control plane, which does not run as root, could
+// not see the archives in dir, or "" when it can.
+func unlistable(dir string) string {
+	info, err := os.Stat(dir)
+	if err != nil {
+		return err.Error()
+	}
+	if info.Mode().Perm()&0o005 != 0o005 {
+		return fmt.Sprintf("%s is %v, so only its owner can list it", dir, info.Mode().Perm())
+	}
+	return ""
+}

internal/cli/backup_test.go

@@ -0,0 +1,141 @@
+package cli
+
+import (
+	"archive/tar"
+	"compress/gzip"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
+)
+
+func TestABackupHoldsTheStoreAndTheConfiguration(t *testing.T) {
+	tmp := t.TempDir()
+	dbPath := filepath.Join(tmp, "store.db")
+	db, err := store.Open(t.Context(), dbPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	secret, err := db.ClusterSecret(t.Context(), "engine-key")
+	if err != nil {
+		t.Fatal(err)
+	}
+	_ = db.Close()
+
+	etc := filepath.Join(tmp, "etc")
+	_ = os.MkdirAll(filepath.Join(etc, "pki"), 0o700)
+	_ = os.WriteFile(filepath.Join(etc, "server.yaml"), []byte("listen: :8080\n"), 0o644)
+	_ = os.WriteFile(filepath.Join(etc, "pki", "ca-key.pem"), []byte("KEY"), 0o600)
+
+	out := filepath.Join(tmp, "backups")
+	path, err := writeBackup(t.Context(), dbPath, etc, out)
+	if err != nil {
+		t.Fatal(err)
+	}
+	info, _ := os.Stat(path)
+	if info.Mode().Perm() != 0o600 {
+		t.Errorf("the archive holds the CA's key and is %v", info.Mode().Perm())
+	}
+
+	files := map[string][]byte{}
+	f, _ := os.Open(path)
+	defer f.Close()
+	gz, err := gzip.NewReader(f)
+	if err != nil {
+		t.Fatal(err)
+	}
+	tr := tar.NewReader(gz)
+	for {
+		h, err := tr.Next()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			t.Fatal(err)
+		}
+		b, _ := io.ReadAll(tr)
+		files[h.Name] = b
+	}
+	for _, want := range []string{"MANIFEST", "store.sqlite", "etc/llmgw/server.yaml", "etc/llmgw/pki/ca-key.pem"} {
+		if _, ok := files[want]; !ok {
+			t.Errorf("%s is not in the archive", want)
+		}
+	}
+
+	// And the store in it is a working store, with what was in it.
+	restored := filepath.Join(tmp, "restored.db")
+	_ = os.WriteFile(restored, files["store.sqlite"], 0o600)
+	rdb, err := store.Open(t.Context(), restored)
+	if err != nil {
+		t.Fatalf("the backed-up store does not open: %v", err)
+	}
+	defer rdb.Close()
+	if got, _ := rdb.ClusterSecret(t.Context(), "engine-key"); got != secret {
+		t.Error("the restored store lost the engine key secret; every engine would be locked out")
+	}
+}
+
+func TestOldBackupsArePrunedAndTheNewestIsFound(t *testing.T) {
+	dir := t.TempDir()
+	for i, stamp := range []string{"20260101T000000Z", "20260102T000000Z", "20260103T000000Z"} {
+		p := filepath.Join(dir, backupPrefix+"h-"+stamp+".tar.gz")
+		_ = os.WriteFile(p, []byte("x"), 0o600)
+		mt := time.Date(2026, 1, 1+i, 0, 0, 0, 0, time.UTC)
+		_ = os.Chtimes(p, mt, mt)
+	}
+	_ = os.WriteFile(filepath.Join(dir, "someone-elses-file"), []byte("x"), 0o600)
+	_ = os.WriteFile(filepath.Join(dir, backupPrefix+"h-20260104T000000Z.tar.gz.part"), []byte("x"), 0o600)
+
+	removed, err := pruneBackups(dir, 2)
+	if err != nil || removed != 1 {
+		t.Fatalf("removed %d, %v", removed, err)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "someone-elses-file")); err != nil {
+		t.Error("a file the backup did not write was removed")
+	}
+	newest := NewestBackup(dir)
+	if !newest.Equal(time.Date(2026, 1, 3, 0, 0, 0, 0, time.UTC)) {
+		t.Errorf("newest %v; an interrupted .part must not count", newest)
+	}
+	if !NewestBackup(filepath.Join(dir, "none")).IsZero() {
+		t.Error("a missing directory reported a backup")
+	}
+}
+
+func TestABackupDirectoryTheControlPlaneCannotListIsSaid(t *testing.T) {
+	dir := t.TempDir()
+	_ = os.Chmod(dir, 0o700)
+	if unlistable(dir) == "" {
+		t.Error("a directory only its owner can list was taken as visible")
+	}
+	_ = os.Chmod(dir, 0o755)
+	if why := unlistable(dir); why != "" {
+		t.Errorf("a listable directory: %s", why)
+	}
+}
+
+func TestNoScratchCopyOfTheStoreIsLeftBehind(t *testing.T) {
+	// The snapshot is made before it is archived. Made straight into the
+	// listable archive directory, it was readable by anyone for that time.
+	tmp := t.TempDir()
+	dbPath := filepath.Join(tmp, "store.db")
+	db, err := store.Open(t.Context(), dbPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_ = db.Close()
+	out := filepath.Join(tmp, "backups")
+	if _, err := writeBackup(t.Context(), dbPath, t.TempDir(), out); err != nil {
+		t.Fatal(err)
+	}
+	entries, _ := os.ReadDir(out)
+	for _, e := range entries {
+		if strings.HasPrefix(e.Name(), ".store") {
+			t.Errorf("a scratch copy of the store was left behind: %s", e.Name())
+		}
+	}
+}

internal/cli/bench.go

@@ -41,6 +41,11 @@ func newBenchCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
 			cfg.MetricsURL = metrics
 			cfg.Engine = engine
 			cfg.APIKey = key
+			// A replica's engine demands its own key. Asked for rather than
+			// typed: the admin API knows which replica answers at the target.
+			if cfg.APIKey == "" {
+				cfg.APIKey = replicaKey(cmd, client, target)
+			}
 			if len(steps) > 0 {
 				cfg.Concurrency = steps
 			}
@@ -227,3 +232,18 @@ func ms(d time.Duration) string {
 		return d.Round(10 * time.Millisecond).String()
 	}
 }
+
+// replicaKey is the engine key of the replica at target, or "" when target is
+// not a replica (the gateway, say) or the admin API cannot be asked.
+func replicaKey(cmd *cobra.Command, client func() *ctlClient, target string) string {
+	var reps []adminapi.ReplicaView
+	if err := client().get(cmd.Context(), "/api/v1/replicas", &reps); err != nil {
+		return ""
+	}
+	for _, rep := range reps {
+		if sameEndpoint(rep.Endpoint, target) {
+			return rep.EngineKey
+		}
+	}
+	return ""
+}

internal/cli/ctl.go

@@ -67,7 +67,9 @@ func (c *ctlClient) do(ctx context.Context, method, path string, body, out any)
 	if err != nil {
 		return err
 	}
-	if body != nil {
+	// On every change, body or not: the admin listener refuses anything else,
+	// because a browser can send a bodiless POST across origins unasked.
+	if method != http.MethodGet {
 		req.Header.Set("Content-Type", "application/json")
 	}
 	// Who made the change, kept with a stored model so a catalog that grew
@@ -81,7 +83,10 @@ func (c *ctlClient) do(ctx context.Context, method, path string, body, out any)
 	}
 	defer resp.Body.Close()
 
-	if resp.StatusCode != http.StatusOK {
+	// Any 2xx. The API answers a change it has queued rather than made — a
+	// restart — with 202, and treating that as a failure printed
+	// "Error: 202 Accepted" over a request that had worked.
+	if resp.StatusCode < 200 || resp.StatusCode > 299 {
 		var e struct {
 			Error string `json:"error"`
 		}
@@ -117,9 +122,11 @@ func newCtlCmd() *cobra.Command {
 	cmd.AddCommand(
 		newNodesCmd(client, &asJSON),
 		newLogsCmd(client, &asJSON),
+		newRequestCmd(client, &asJSON),
 		newModelsCmd(client, &asJSON),
 		newReplicasCmd(client, &asJSON),
 		newExplainCmd(client, &asJSON),
+		newFabricTestCmd(client, &asJSON),
 		newNodeStateCmd(client, "cordon", "cordoned",
 			"Stop placing new work on a node; what runs there keeps running"),
 		newNodeStateCmd(client, "uncordon", "ready",
@@ -132,6 +139,10 @@ func newCtlCmd() *cobra.Command {
 		newStatusCmd(client, &asJSON),
 		newModelCmd(client),
 		newScaleCmd(client),
+		newResourcesCmd(client),
+		newRestartCmd(client),
+		newRetryCmd(client),
+		newUpgradeCmd(client),
 		newEngineCheckCmd(),
 		newToolCheckCmd(),
 		newWeightsCmd(client, &asJSON),
@@ -199,7 +210,8 @@ func newNodesCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
 					said = true
 				}
 				for _, p := range n.Provision {
-					if p.State == "ready" {
+					// Skipped is vLLM on a node with no GPU: as it should be.
+					if p.State == "ready" || p.State == "skipped" {
 						continue
 					}
 					fmt.Printf("\n%s: %s %s %s: %s", n.ID, p.Engine, p.Version, p.State, p.Detail)
@@ -240,6 +252,10 @@ func newNodesCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
 // actually served, never what is merely catalogued.
 func modelStatus(m adminapi.ModelView) string {
 	switch {
+	case m.Parked:
+		return "parked"
+	case m.Unplaceable:
+		return "cannot place"
 	case m.Min == 0 && m.Total == 0:
 		return "stopped"
 	case m.Ready >= m.Min && m.Min > 0:
@@ -308,17 +324,27 @@ func newModelsCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
 			}
 
 			w := tab()
-			fmt.Fprintln(w, "MODEL\tSERVING\tREPLICAS\tSTATUS\tALIASES\tPROFILES\tFALLBACKS")
+			fmt.Fprintln(w, "MODEL\tSERVING\tREPLICAS\tSTATUS\tRESERVES\tALIASES\tPROFILES\tFALLBACKS")
+			var warnings []string
 			for _, m := range models {
 				serving := "no"
 				if m.Ready > 0 {
 					serving = "yes"
 				}
-				fmt.Fprintf(w, "%s\t%s\t%d/%d\t%s\t%s\t%s\t%s\n",
-					m.Name, serving, m.Ready, m.Min, modelStatus(m),
+				fmt.Fprintf(w, "%s\t%s\t%d/%d\t%s\t%s\t%s\t%s\t%s\n",
+					m.Name, serving, m.Ready, m.Min, modelStatus(m), reserves(m),
 					join(m.Aliases), join(m.Profiles), join(m.Fallbacks))
+				for _, x := range m.Warnings {
+					warnings = append(warnings, m.Name+": "+x)
+				}
 			}
-			return w.Flush()
+			if err := w.Flush(); err != nil {
+				return err
+			}
+			for _, x := range warnings {
+				fmt.Println("warning:", x)
+			}
+			return nil
 		},
 	}
 }
@@ -366,6 +392,9 @@ func newReplicasCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
 				if r.Stale {
 					state += " (stale profile)"
 				}
+				if r.Restart != "" {
+					state += " (restart " + r.Restart + ")"
+				}
 				fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n",
 					r.ID, r.Model, state, r.Pool, join(nodes),
 					(time.Duration(r.AgeSec) * time.Second).String(),
@@ -493,3 +522,22 @@ func dash(s string) string {
 	}
 	return s
 }
+
+// reserves is what one replica of a model holds of a node, with what it was
+// measured using beside it: "6G 2c (5.1G used)".
+func reserves(m adminapi.ModelView) string {
+	if m.MemoryGB == 0 && m.CPUCores == 0 {
+		return "-"
+	}
+	out := fmt.Sprintf("%dG", m.MemoryGB)
+	if m.CPUCores > 0 {
+		out += fmt.Sprintf(" %dc", m.CPUCores)
+	}
+	if m.MeasuredMemoryGB > 0 {
+		out += fmt.Sprintf(" (%.1fG used)", m.MeasuredMemoryGB)
+	}
+	if len(m.Warnings) > 0 {
+		out += " !"
+	}
+	return out
+}

internal/cli/ctl_fabrictest.go

@@ -0,0 +1,75 @@
+package cli
+
+import (
+	"encoding/json"
+	"fmt"
+	"text/tabwriter"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+)
+
+func newFabricTestCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
+	var (
+		fabric  string
+		seconds int
+	)
+	c := &cobra.Command{
+		Use:   "fabric-test NODE-A NODE-B",
+		Short: "Measure RDMA bandwidth between two nodes, rail by rail",
+		Long: `Runs ib_write_bw from each of NODE-A's adapters on a fabric to the same
+adapter on NODE-B — mlx5_0 to mlx5_0, and so on, the way NCCL pairs them —
+one rail at a time, and grades each against its link's rate: ok at 80% or
+more, slow at 50%, fail below or when nothing got through.
+
+Every check on one node can pass while two nodes still cannot reach each
+other: a cable into the wrong switch, a partition key, a RoCE network with no
+route. A replica spanning them then hangs on its first all-reduce. Run this
+before placing one.
+
+It goes through the agents, so it needs no ssh between nodes. perftest is
+installed on a node the first time it is asked. The traffic is real and
+takes a few seconds a rail; run it when the fabric is quiet.`,
+		Example: `  llmgw ctl fabric-test gpu01 gpu02
+  llmgw ctl fabric-test gpu01 gpu02 --fabric ib-compute --seconds 10`,
+		Args: cobra.ExactArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			body, _ := json.Marshal(map[string]any{"a": args[0], "b": args[1], "fabric": fabric, "seconds": seconds})
+			cl := client()
+			// Rails one after another, each for its seconds and a settle; the
+			// client's usual timeout is for questions, not measurements.
+			cl.http.Timeout = 30 * time.Minute
+			var v adminapi.FabricTestView
+			if err := cl.post(cmd.Context(), "/api/v1/fabric-test", body, &v); err != nil {
+				return err
+			}
+			if *asJSON {
+				return json.NewEncoder(cmd.OutOrStdout()).Encode(v)
+			}
+			out := cmd.OutOrStdout()
+			fmt.Fprintf(out, "%s → %s on %s, %s\n\n", v.A, v.B, v.Fabric, v.Took)
+			w := tabwriter.NewWriter(out, 0, 0, 2, ' ', 0)
+			fmt.Fprintln(w, "RAIL\tLINK\tMEASURED\tVERDICT\tDETAIL")
+			for _, r := range v.Rails {
+				link := "-"
+				if r.RateGbps > 0 {
+					link = fmt.Sprintf("%d Gb/s", r.RateGbps)
+				}
+				fmt.Fprintf(w, "%s → %s\t%s\t%.1f Gb/s\t%s\t%s\n", r.A, r.B, link, r.Gbps, r.Verdict, r.Detail)
+			}
+			_ = w.Flush()
+			for _, n := range v.Notes {
+				fmt.Fprintf(out, "\nnote: %s\n", n)
+			}
+			if !v.OK {
+				return fmt.Errorf("not every rail passed")
+			}
+			return nil
+		},
+	}
+	c.Flags().StringVar(&fabric, "fabric", "", "the fabric to test (default: the one the two nodes share)")
+	c.Flags().IntVar(&seconds, "seconds", 3, "how long each rail runs, up to 30")
+	return c
+}

internal/cli/ctl_request.go

@@ -0,0 +1,45 @@
+package cli
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/url"
+
+	"github.com/spf13/cobra"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+)
+
+func newRequestCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
+	return &cobra.Command{
+		Use:   "request ID",
+		Short: "What one request went through: replica, queue, first token, tokens",
+		Long: "Every response carries its id in X-Request-Id, and a client may send its\n" +
+			"own. Given one, this says which replica answered, how long admission held\n" +
+			"it, how long the first token took and what it cost — the answer to \"why\n" +
+			"was this slow\". The access log has the same fields under \"request\".",
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			var v adminapi.RequestView
+			if err := client().get(cmd.Context(), "/api/v1/requests/"+url.PathEscape(args[0]), &v); err != nil {
+				return err
+			}
+			if *asJSON {
+				return json.NewEncoder(cmd.OutOrStdout()).Encode(v)
+			}
+			model := v.Model
+			if v.ServedModel != "" && v.ServedModel != v.Model {
+				model += " (served by " + v.ServedModel + ")"
+			}
+			out := cmd.OutOrStdout()
+			fmt.Fprintf(out, "request   %s at %s\n", v.RequestID, v.At.UTC().Format("2006-01-02 15:04:05Z"))
+			fmt.Fprintf(out, "model     %s\n", model)
+			fmt.Fprintf(out, "replica   %s\n", or(v.Replica, "- (none answered)"))
+			fmt.Fprintf(out, "status    %d\n", v.Status)
+			fmt.Fprintf(out, "time      %d ms total: %d queued, %d to the first token\n", v.LatencyMs, v.QueueMs, v.TTFTMs)
+			fmt.Fprintf(out, "tokens    %d in, %d out\n", v.PromptTokens, v.CompletionTokens)
+			fmt.Fprintf(out, "who       key %s, project %s%s\n", v.KeyID, v.ProjectID, prefixed(", user ", v.UserID))
+			return nil
+		},
+	}
+}

internal/cli/ctl_restart.go

@@ -0,0 +1,75 @@
+package cli
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+)
+
+func newRestartCmd(client func() *ctlClient) *cobra.Command {
+	var (
+		models []string
+		all    bool
+	)
+	c := &cobra.Command{
+		Use:   "restart [REPLICA...]",
+		Short: "Replace replicas with new ones, starting each replacement before stopping the old",
+		Long: "How a running engine picks up what only applies at start: an engine key,\n" +
+			"an edited profile, a new engine version.\n\n" +
+			"Each replacement is placed beside the replica it replaces, and the old one\n" +
+			"keeps serving until the new one is ready. Replicas of one model are\n" +
+			"replaced one at a time. Where nothing else has room for a second copy —\n" +
+			"the usual case on a small CPU fleet — the old one is stopped after the\n" +
+			"drain grace period (5 minutes by default) and the new one starts in its\n" +
+			"place; a model with only that replica is unserved while it loads.\n\n" +
+			"  llmgw ctl restart qwen2.5-7b-3f2a91c0\n" +
+			"  llmgw ctl restart --model qwen2.5-7b\n" +
+			"  llmgw ctl restart --all",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if len(args) == 0 && len(models) == 0 && !all {
+				return errors.New("name replicas, --model, or --all")
+			}
+			body, _ := json.Marshal(adminapi.RestartRequest{Replicas: args, Models: models, All: all})
+			var res adminapi.RestartResult
+			if err := client().post(cmd.Context(), "/api/v1/restart", body, &res); err != nil {
+				return err
+			}
+			fmt.Printf("%d replica(s) queued for restart; watch with: llmgw ctl replicas\n", len(res.Queued))
+			return nil
+		},
+	}
+	c.Flags().StringArrayVar(&models, "model", nil, "every replica of this model; repeatable")
+	c.Flags().BoolVar(&all, "all", false, "every ready replica in the cluster")
+	return c
+}
+
+func newRetryCmd(client func() *ctlClient) *cobra.Command {
+	return &cobra.Command{
+		Use:   "retry MODEL",
+		Short: "Try a parked model again, and clear its backoff",
+		Long: "A model whose replicas fail every time they start is parked after five\n" +
+			"failures in a row: it is not placed again until its definition changes\n" +
+			"or this is run. Run it once the cause — the weights, the engine, the\n" +
+			"profile — has been dealt with; `llmgw ctl status` lists parked models with\n" +
+			"their last error.",
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			var res struct {
+				WasParked bool `json:"was_parked"`
+			}
+			if err := client().post(cmd.Context(), "/api/v1/models/"+args[0]+"/retry", []byte(`{}`), &res); err != nil {
+				return err
+			}
+			if res.WasParked {
+				fmt.Printf("%s unparked; it is placed on the next pass\n", args[0])
+			} else {
+				fmt.Printf("%s was not parked; its backoff is cleared\n", args[0])
+			}
+			return nil
+		},
+	}
+}

internal/cli/ctl_status_test.go

@@ -0,0 +1,24 @@
+package cli
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestAQueuedChangeIsNotReportedAsAnError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusAccepted)
+		_, _ = w.Write([]byte(`{"queued":["r1"]}`))
+	}))
+	defer srv.Close()
+	var out struct {
+		Queued []string `json:"queued"`
+	}
+	if err := newCtlClient(srv.URL).post(t.Context(), "/api/v1/restart", []byte(`{}`), &out); err != nil {
+		t.Fatalf("202 read as a failure: %v", err)
+	}
+	if len(out.Queued) != 1 {
+		t.Errorf("the body of a 202 was not read: %+v", out)
+	}
+}

internal/cli/ctl_upgrade.go

@@ -0,0 +1,197 @@
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"runtime"
+	"slices"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/release"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/version"
+)
+
+func newUpgradeCmd(client func() *ctlClient) *cobra.Command {
+	var (
+		nodes     []string
+		skipCP    bool
+		releases  string
+		perNode   time.Duration
+		serverSvc string
+	)
+	c := &cobra.Command{
+		Use:   "upgrade VERSION",
+		Short: "Upgrade this control plane, then every node, one at a time",
+		Long: "Moves the cluster to a release: v0.10.4, or a candidate like v0.10.4-rc.2.\n\n" +
+			"This machine first — run it with sudo on the control plane, since it\n" +
+			"replaces /usr/local/bin/llmgw and restarts llmgw-server. Then each node, in\n" +
+			"turn: its agent fetches the release for its own platform, checks it\n" +
+			"against the release's checksums, swaps it in and restarts. Engines keep\n" +
+			"serving through all of it and are adopted again; no ssh into the nodes is\n" +
+			"needed.\n\n" +
+			"A node counts as done when it is back on the new version, ready, with as\n" +
+			"many ready replicas as before. One that is not within --timeout stops the\n" +
+			"upgrade there, so a bad release reaches one node rather than all of them.\n" +
+			"Nodes already on the version are skipped, so running it again resumes.",
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			v := args[0]
+			if !release.Tag.MatchString(v) {
+				return fmt.Errorf("%q is not a release version (v1.2.3 or v1.2.3-rc.4)", v)
+			}
+			out := cmd.OutOrStdout()
+			ctx := cmd.Context()
+			if !skipCP {
+				if err := upgradeControlPlane(ctx, out, client, v, releases, serverSvc); err != nil {
+					return err
+				}
+			}
+			return upgradeNodes(ctx, out, client, v, nodes, perNode)
+		},
+	}
+	c.Flags().StringSliceVar(&nodes, "nodes", nil, "only these nodes (default: all)")
+	c.Flags().BoolVar(&skipCP, "skip-control-plane", false, "leave this machine as it is and upgrade only nodes")
+	c.Flags().StringVar(&releases, "releases", release.DefaultBase, "where release binaries are fetched from, for this machine")
+	c.Flags().DurationVar(&perNode, "timeout", 3*time.Minute, "how long a node may take to come back")
+	c.Flags().StringVar(&serverSvc, "service", "llmgw-server", "this machine's systemd unit")
+	return c
+}
+
+func upgradeControlPlane(ctx context.Context, out io.Writer, client func() *ctlClient, v, releases, svc string) error {
+	if version.Version == v {
+		fmt.Fprintf(out, "this machine already runs %s\n", v)
+		return nil
+	}
+	if os.Geteuid() != 0 {
+		return errors.New("replacing this machine's binary needs root: run it with sudo, " +
+			"or pass --skip-control-plane to upgrade only the nodes")
+	}
+	self, err := os.Executable()
+	if err != nil {
+		return err
+	}
+	fmt.Fprintf(out, "== this machine: %s -> %s\n", version.Version, v)
+	backup, err := release.Install(ctx, nil, releases, v, runtime.GOOS, runtime.GOARCH, self)
+	if err != nil {
+		return err
+	}
+	fmt.Fprintf(out, "   installed, checksum verified; the old binary is %s\n", backup)
+	var before []adminapi.NodeView
+	_ = client().get(ctx, "/api/v1/nodes", &before)
+	if b, err := exec.CommandContext(ctx, "systemctl", "restart", svc).CombinedOutput(); err != nil { //nolint:gosec // fixed command
+		return fmt.Errorf("restarting %s: %v: %s", svc, err, strings.TrimSpace(string(b)))
+	}
+	fmt.Fprintf(out, "   %s restarted; waiting for its nodes to reconnect\n", svc)
+	// Back when the admin API answers and every node that was ready is ready
+	// again: agents reconnect within seconds of the control plane returning.
+	want := 0
+	for _, n := range before {
+		if n.State == "ready" {
+			want++
+		}
+	}
+	deadline := time.Now().Add(2 * time.Minute)
+	for {
+		var now []adminapi.NodeView
+		if err := client().get(ctx, "/api/v1/nodes", &now); err == nil {
+			ready := 0
+			for _, n := range now {
+				if n.State == "ready" {
+					ready++
+				}
+			}
+			if ready >= want {
+				fmt.Fprintf(out, "   back: %d of %d nodes ready\n", ready, len(now))
+				return nil
+			}
+		}
+		if time.Now().After(deadline) {
+			return fmt.Errorf("%s did not come back with its %d nodes within two minutes; "+
+				"see journalctl -u %s, and %s holds the previous binary", svc, want, svc, backup)
+		}
+		time.Sleep(2 * time.Second)
+	}
+}
+
+func upgradeNodes(ctx context.Context, out io.Writer, client func() *ctlClient, v string, only []string, perNode time.Duration) error {
+	var nodes []adminapi.NodeView
+	if err := client().get(ctx, "/api/v1/nodes", &nodes); err != nil {
+		return err
+	}
+	slices.SortFunc(nodes, func(a, b adminapi.NodeView) int { return strings.Compare(a.ID, b.ID) })
+	done, skipped := 0, 0
+	for _, n := range nodes {
+		if len(only) > 0 && !slices.Contains(only, n.ID) {
+			continue
+		}
+		if n.AgentVersion == v {
+			skipped++
+			continue
+		}
+		start := time.Now()
+		before := readyReplicasOn(ctx, client, n.ID)
+		fmt.Fprintf(out, "== %s: %s -> %s\n", n.ID, n.AgentVersion, v)
+		body, _ := json.Marshal(adminapi.UpgradeRequest{Version: v})
+		if err := client().post(ctx, "/api/v1/nodes/"+n.ID+"/upgrade", body, nil); err != nil {
+			return fmt.Errorf("%s: %w\nstopped here; `llmgw ctl logs %s` says more", n.ID, err, n.ID)
+		}
+		fmt.Fprintf(out, "   new binary in place; waiting for it to come back with its %d replica(s)\n", before)
+		deadline := time.Now().Add(perNode)
+		for {
+			var now []adminapi.NodeView
+			_ = client().get(ctx, "/api/v1/nodes", &now)
+			var cur adminapi.NodeView
+			for _, x := range now {
+				if x.ID == n.ID {
+					cur = x
+				}
+			}
+			after := readyReplicasOn(ctx, client, n.ID)
+			if cur.AgentVersion == v && cur.State == "ready" && after >= before {
+				fmt.Fprintf(out, "   done in %s: ready, replicas %d/%d\n",
+					time.Since(start).Round(time.Second), after, before)
+				done++
+				break
+			}
+			if time.Now().After(deadline) {
+				return fmt.Errorf("%s did not come back within %s (version %q, state %q, replicas %d/%d)\n"+
+					"stopped here, before the next node; `llmgw ctl logs %s` says why, and the node "+
+					"keeps its previous binary beside the new one", n.ID, perNode, cur.AgentVersion,
+					cur.State, after, before, n.ID)
+			}
+			time.Sleep(2 * time.Second)
+		}
+	}
+	fmt.Fprintf(out, "%d node(s) upgraded to %s, %d already on it\n", done, v, skipped)
+	return nil
+}
+
+// readyReplicasOn counts the ready replicas with a shard on a node.
+func readyReplicasOn(ctx context.Context, client func() *ctlClient, node string) int {
+	var reps []adminapi.ReplicaView
+	if err := client().get(ctx, "/api/v1/replicas", &reps); err != nil {
+		return 0
+	}
+	n := 0
+	for _, r := range reps {
+		if r.State != "ready" {
+			continue
+		}
+		for _, s := range r.Shards {
+			if s.Node == node {
+				n++
+				break
+			}
+		}
+	}
+	return n
+}

internal/cli/ctl_upgrade_test.go

@@ -0,0 +1,88 @@
+package cli
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+)
+
+// fakeFleet is an admin API whose nodes come back on the version they are told
+// to upgrade to — except those listed in stuck.
+type fakeFleet struct {
+	mu       sync.Mutex
+	versions map[string]string
+	stuck    map[string]bool
+	told     []string
+}
+
+func (f *fakeFleet) server(t *testing.T) *httptest.Server {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		switch {
+		case r.URL.Path == "/api/v1/nodes":
+			var out []adminapi.NodeView
+			for id, v := range f.versions {
+				out = append(out, adminapi.NodeView{ID: id, State: "ready", AgentVersion: v})
+			}
+			_ = json.NewEncoder(w).Encode(out)
+		case r.URL.Path == "/api/v1/replicas":
+			var out []adminapi.ReplicaView
+			for id := range f.versions {
+				out = append(out, adminapi.ReplicaView{ID: "r-" + id, State: "ready",
+					Shards: []adminapi.ShardView{{Node: id}}})
+			}
+			_ = json.NewEncoder(w).Encode(out)
+		case strings.HasSuffix(r.URL.Path, "/upgrade"):
+			id := strings.TrimSuffix(strings.TrimPrefix(r.URL.Path, "/api/v1/nodes/"), "/upgrade")
+			var req adminapi.UpgradeRequest
+			_ = json.NewDecoder(r.Body).Decode(&req)
+			f.told = append(f.told, id)
+			if !f.stuck[id] {
+				f.versions[id] = req.Version
+			}
+			_, _ = w.Write([]byte(`{}`))
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func TestAnUpgradeGoesNodeByNodeAndSkipsTheDone(t *testing.T) {
+	f := &fakeFleet{versions: map[string]string{"a": "v1.0.0", "b": "v1.0.1", "c": "v1.0.0"}}
+	srv := f.server(t)
+	var out bytes.Buffer
+	err := upgradeNodes(t.Context(), &out, func() *ctlClient { return newCtlClient(srv.URL) }, "v1.0.1", nil, 5*time.Second)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Join(f.told, ",") != "a,c" {
+		t.Errorf("told %v; b was already on the version", f.told)
+	}
+	if !strings.Contains(out.String(), "2 node(s) upgraded to v1.0.1, 1 already on it") {
+		t.Errorf("output:\n%s", out.String())
+	}
+}
+
+func TestAnUpgradeStopsAtTheFirstNodeThatDoesNotComeBack(t *testing.T) {
+	// A bad release reaches one node, not all of them.
+	f := &fakeFleet{versions: map[string]string{"a": "v1.0.0", "b": "v1.0.0"}, stuck: map[string]bool{"a": true}}
+	srv := f.server(t)
+	var out bytes.Buffer
+	err := upgradeNodes(t.Context(), &out, func() *ctlClient { return newCtlClient(srv.URL) }, "v1.0.1", nil, 3*time.Second)
+	if err == nil || !strings.Contains(err.Error(), "a did not come back") {
+		t.Fatalf("err %v", err)
+	}
+	if len(f.told) != 1 {
+		t.Errorf("went on to %v after a node failed to come back", f.told)
+	}
+}

internal/cli/dispatcherref_test.go

@@ -5,6 +5,7 @@ import (
 
 	"gitea.mynodes.xyz/ilker/llmgw/internal/control"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/control/agentsvc"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/fabrictest"
 )
 
 func TestTheForwardingDispatcherCarriesEveryCapability(t *testing.T) {
@@ -23,10 +24,17 @@ func TestTheForwardingDispatcherCarriesEveryCapability(t *testing.T) {
 		t.Error("dispatcherRef drops WeightRemover, so the control plane cannot reclaim disk")
 	}
 
+	if _, ok := ref.(fabrictest.Asker); !ok {
+		t.Error("dispatcherRef drops the bandwidth test, so ctl fabric-test cannot reach the agents")
+	}
+
 	// And the thing it forwards to must have it, or the forwarding has nothing
 	// to reach.
 	var svc any = &agentsvc.Service{}
 	if _, ok := svc.(control.WeightRemover); !ok {
 		t.Error("the agent service does not implement WeightRemover")
 	}
+	if _, ok := svc.(fabrictest.Asker); !ok {
+		t.Error("the agent service does not implement the bandwidth test")
+	}
 }

internal/cli/doctor.go

@@ -0,0 +1,185 @@
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"sort"
+	"strings"
+	"text/tabwriter"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/discovery"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/config"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/doctor"
+)
+
+func newDoctorCmd() *cobra.Command {
+	var (
+		opts    doctor.Options
+		asJSON  bool
+		verbose bool
+	)
+	cmd := &cobra.Command{
+		Use:   "doctor",
+		Short: "Check this node's GPUs, NVLink, InfiniBand and engines for what llmgw needs",
+		Long: `Reads this node's GPUs, their NVLink and PCIe topology, its InfiniBand and
+RoCE ports, the kernel modules RDMA needs, the agent's configuration and
+whether vLLM can be installed here, and says what is wrong and how to fix
+it — most serious first.
+
+Run it on a node before it joins, and whenever a multi-node replica will not
+come up. --json writes everything it read as well as what it concluded; send
+that file when the report is not enough to go on.`,
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			doctor.SetConfigLoader(config.LoadAgent)
+			if opts.VLLMVersion == "" {
+				opts.VLLMVersion = config.DefaultEngines["vllm"]
+			}
+			ctx, cancel := context.WithTimeout(cmd.Context(), 60*time.Second)
+			defer cancel()
+			facts := doctor.Collect(ctx, opts)
+			findings := doctor.Evaluate(facts)
+			if asJSON {
+				enc := json.NewEncoder(os.Stdout)
+				enc.SetIndent("", "  ")
+				return enc.Encode(struct {
+					Findings []doctor.Finding `json:"findings"`
+					Facts    doctor.Facts     `json:"facts"`
+				}{findings, facts})
+			}
+			printDoctor(os.Stdout, facts, findings, verbose)
+			for _, f := range findings {
+				if f.Level == doctor.Fail {
+					return fmt.Errorf("%d problem(s) need fixing", countLevel(findings, doctor.Fail))
+				}
+			}
+			return nil
+		},
+	}
+	f := cmd.Flags()
+	f.StringVar(&opts.ConfigPath, "config", "", "agent configuration (default /etc/llmgw/agent.yaml when present)")
+	f.StringVar(&opts.IBRoot, "ib-root", discovery.SysfsRoot, "sysfs InfiniBand directory")
+	f.StringVar(&opts.NvidiaSMI, "nvidia-smi", "", "path to nvidia-smi")
+	f.StringVar(&opts.VLLMVersion, "vllm", "", "the vLLM version to check for (default: the one this llmgw installs)")
+	f.BoolVar(&asJSON, "json", false, "write every fact and finding as JSON, to send back")
+	f.BoolVar(&verbose, "verbose", false, "also print the raw nvidia-smi topology")
+	return cmd
+}
+
+func countLevel(fs []doctor.Finding, l doctor.Level) int {
+	n := 0
+	for _, f := range fs {
+		if f.Level == l {
+			n++
+		}
+	}
+	return n
+}
+
+func printDoctor(out io.Writer, f doctor.Facts, findings []doctor.Finding, verbose bool) {
+	fmt.Fprintf(out, "%s · %s %s %s · driver %s\n\n", f.Hostname, f.Host.OSID, f.Host.OSVersion,
+		f.Host.Arch, orDash(f.Host.NVIDIADriver))
+
+	for _, x := range findings {
+		fmt.Fprintf(out, "%-4s  %-6s  %s\n", x.Level, x.Area, x.Message)
+		if x.Fix != "" && (x.Level == doctor.Fail || x.Level == doctor.Warn) {
+			fmt.Fprintf(out, "              → %s\n", x.Fix)
+		}
+	}
+
+	w := tabwriter.NewWriter(out, 0, 0, 2, ' ', 0)
+	if len(f.GPUs) > 0 {
+		fmt.Fprintln(w, "\nGPU\tNAME\tNUMA\tNVLINK PEERS\tNEAREST ADAPTER")
+		for _, g := range f.GPUs {
+			fmt.Fprintf(w, "%d\t%s\t%d\t%s\t%s\n", g.Index, g.Name, g.NUMANode,
+				orDash(ints(g.NVLinkPeers)), orDash(nearest(g.NICPaths)))
+		}
+	}
+	if len(f.HCAs) > 0 {
+		fmt.Fprintln(w, "\nADAPTER\tSTATE\tPHYS\tRATE\tLINK\tNUMA\tROCE GID\tERRORS")
+		for _, h := range f.HCAs {
+			for _, p := range h.Ports {
+				gid := "-"
+				if p.RoCEv2GID >= 0 {
+					gid = fmt.Sprint(p.RoCEv2GID)
+				}
+				fmt.Fprintf(w, "%s/%d\t%s\t%s\t%d Gb/s\t%s\t%d\t%s\t%s\n", h.Name, p.Num, p.State,
+					orDash(p.PhysState), p.RateGbps, p.LinkLayer, h.NUMANode, gid, orDash(errorsOf(p.Counters)))
+			}
+		}
+	}
+	_ = w.Flush()
+
+	for _, fabric := range sortedKeys(f.NCCL) {
+		fmt.Fprintf(out, "\nA shard on %s is given:\n", fabric)
+		env := f.NCCL[fabric]
+		for _, k := range sortedKeys(env) {
+			fmt.Fprintf(out, "  %s=%s\n", k, env[k])
+		}
+	}
+	if len(f.Engines) > 0 {
+		fmt.Fprintln(out, "\nEngines:")
+		for _, k := range sortedKeys(f.Engines) {
+			fmt.Fprintf(out, "  %s: %s\n", k, f.Engines[k])
+		}
+	}
+	if verbose && f.TopoRaw != "" {
+		fmt.Fprintf(out, "\nnvidia-smi topo -m:\n%s\n", f.TopoRaw)
+	}
+	fmt.Fprintf(out, "\n%d failed, %d warnings. `llmgw doctor --json > report.json` keeps everything read, to send back.\n",
+		countLevel(findings, doctor.Fail), countLevel(findings, doctor.Warn))
+}
+
+func nearest(paths map[string]string) string {
+	best, rel := "", ""
+	for h, r := range paths {
+		if best == "" || discovery.PathRank(r) < discovery.PathRank(rel) ||
+			(discovery.PathRank(r) == discovery.PathRank(rel) && h < best) {
+			best, rel = h, r
+		}
+	}
+	if best == "" {
+		return ""
+	}
+	return best + " (" + rel + ")"
+}
+
+func errorsOf(c map[string]uint64) string {
+	var out []string
+	for _, k := range sortedKeys(c) {
+		if c[k] > 0 && k != "port_xmit_data" && k != "port_rcv_data" {
+			out = append(out, fmt.Sprintf("%s=%d", k, c[k]))
+		}
+	}
+	return strings.Join(out, " ")
+}
+
+func ints(v []int) string {
+	s := make([]string, len(v))
+	for i, x := range v {
+		s[i] = fmt.Sprint(x)
+	}
+	return strings.Join(s, ",")
+}
+
+func orDash(s string) string {
+	if s == "" {
+		return "-"
+	}
+	return s
+}
+
+func sortedKeys[V any](m map[string]V) []string {
+	out := make([]string, 0, len(m))
+	for k := range m {
+		out = append(out, k)
+	}
+	sort.Strings(out)
+	return out
+}

internal/cli/keys.go

@@ -6,6 +6,7 @@ import (
 	"encoding/base32"
 	"errors"
 	"fmt"
+	"math"
 	"strings"
 	"text/tabwriter"
 	"time"
@@ -84,7 +85,7 @@ func newKeyInitCmd(open opener) *cobra.Command {
 }
 
 func newKeyCreateCmd(open opener) *cobra.Command {
-	var project, band, profile, baseURL string
+	var project, band, profile, baseURL, forUser string
 	var expires, claimTTL time.Duration
 	var claim bool
 
@@ -107,7 +108,24 @@ func newKeyCreateCmd(open opener) *cobra.Command {
 			}
 			defer s.Close()
 
-			secret, k, err := store.NewKey(randomID("key"), args[0], project)
+			// Three kinds: an operator's key in a project, a person's key in a
+			// project they are a member of, and a person's personal key.
+			var owner store.User
+			if forUser != "" {
+				if owner, err = resolveUser(cmd.Context(), s, forUser); err != nil {
+					return err
+				}
+			}
+			var p store.ProjectPath
+			if project != "" || forUser == "" {
+				if p, err = resolveProject(cmd.Context(), s, project); err != nil {
+					return err
+				}
+			}
+			if p.ID == "" {
+				p.Path = "personal, " + owner.Email
+			}
+			secret, k, err := store.NewKey(randomID("key"), args[0], p.ID)
 			if err != nil {
 				return err
 			}
@@ -116,9 +134,16 @@ func newKeyCreateCmd(open opener) *cobra.Command {
 			if expires > 0 {
 				k.ExpiresAt = k.CreatedAt.Add(expires)
 			}
-			if err := s.CreateKey(cmd.Context(), k); err != nil {
-				return fmt.Errorf("creating the key (does project %q exist? run `llmgw keys init`): %w",
-					project, err)
+			if owner.ID != "" {
+				err = s.CreateUserKey(cmd.Context(), owner.ID, k)
+			} else {
+				err = s.CreateKey(cmd.Context(), k)
+			}
+			if errors.Is(err, store.ErrNotMember) {
+				return fmt.Errorf("%s is not a member of %s; `llmgw users join` first", owner.Email, p.Path)
+			}
+			if err != nil {
+				return fmt.Errorf("creating the key in %s: %w", p.Path, err)
 			}
 
 			// The one output that matters goes to stdout and everything else to
@@ -141,13 +166,13 @@ func newKeyCreateCmd(open opener) *cobra.Command {
 				link := strings.TrimRight(baseURL, "/") + "/claim/" + token
 				fmt.Fprintln(out, link)
 				cmd.PrintErrf("\nid       %s\nproject  %s\nexpires  %s\n",
-					k.ID, k.ProjectID, time.Now().Add(orDefault(claimTTL, store.ClaimTTL)).Format(time.RFC3339))
+					k.ID, p.Path, time.Now().Add(orDefault(claimTTL, store.ClaimTTL)).Format(time.RFC3339))
 				cmd.PrintErrln("\nSend the link. It works once, and the key is shown only to whoever opens it.")
 				return nil
 			}
 
 			fmt.Fprintln(out, secret)
-			cmd.PrintErrf("\nid       %s\nproject  %s\n", k.ID, k.ProjectID)
+			cmd.PrintErrf("\nid       %s\nproject  %s\n", k.ID, p.Path)
 			if !k.ExpiresAt.IsZero() {
 				cmd.PrintErrf("expires  %s\n", k.ExpiresAt.Format(time.RFC3339))
 			}
@@ -155,7 +180,10 @@ func newKeyCreateCmd(open opener) *cobra.Command {
 			return nil
 		},
 	}
-	cmd.Flags().StringVar(&project, "project", "default", "project the key belongs to")
+	cmd.Flags().StringVar(&project, "project", "",
+		"project the key belongs to: id, path (Acme/platform/gateway) or unique name")
+	cmd.Flags().StringVar(&forUser, "for", "",
+		"a person the key belongs to (id or email); without --project it is their personal key")
 	cmd.Flags().StringVar(&band, "band", "", "admission band; empty inherits")
 	cmd.Flags().StringVar(&profile, "profile", "", "routing profile; empty inherits")
 	cmd.Flags().DurationVar(&expires, "expires-in", 0, "lifetime; 0 never expires")
@@ -174,9 +202,10 @@ func orDefault(d, fallback time.Duration) time.Duration {
 
 func newKeyListCmd(open opener) *cobra.Command {
 	var project string
+	var all bool
 	cmd := &cobra.Command{
 		Use:   "list",
-		Short: "List a project's keys",
+		Short: "List a project's keys, or with --all every key and whose it is",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			s, err := open(cmd.Context())
@@ -185,12 +214,35 @@ func newKeyListCmd(open opener) *cobra.Command {
 			}
 			defer s.Close()
 
-			keys, err := s.Keys(cmd.Context(), project)
+			if all {
+				rows, err := s.AllKeys(cmd.Context())
+				if err != nil {
+					return err
+				}
+				w := tabwriter.NewWriter(cmd.OutOrStdout(), 0, 0, 2, ' ', 0)
+				fmt.Fprintln(w, "ID\tNAME\tKEY\tPROJECT\tOWNER\tSTATE\tLAST USED")
+				now := time.Now()
+				for _, r := range rows {
+					where := r.ProjectPath
+					if where == "" {
+						where = "personal"
+					}
+					fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\t%s\t%s\n", r.ID, r.Name, r.Prefix,
+						where, dash(r.OwnerEmail), keyState(r.Key, now), ago(r.LastUsedAt, now))
+				}
+				return w.Flush()
+			}
+
+			p, err := resolveProject(cmd.Context(), s, project)
+			if err != nil {
+				return err
+			}
+			keys, err := s.Keys(cmd.Context(), p.ID)
 			if err != nil {
 				return err
 			}
 			if len(keys) == 0 {
-				fmt.Fprintf(cmd.OutOrStdout(), "no keys in project %q\n", project)
+				fmt.Fprintf(cmd.OutOrStdout(), "no keys in %s\n", p.Path)
 				return nil
 			}
 
@@ -204,7 +256,8 @@ func newKeyListCmd(open opener) *cobra.Command {
 			return w.Flush()
 		},
 	}
-	cmd.Flags().StringVar(&project, "project", "default", "project to list")
+	cmd.Flags().StringVar(&project, "project", "", "project to list: id, path or unique name")
+	cmd.Flags().BoolVar(&all, "all", false, "every key in every project, with its owner")
 	return cmd
 }
 
@@ -234,8 +287,9 @@ func newKeyRevokeCmd(open opener) *cobra.Command {
 
 func newLimitsCmd(open opener) *cobra.Command {
 	var scope, id, period string
+	var perMember bool
 	var rpm, tpm int
-	var budget int64
+	var budget float64
 	var models []string
 
 	cmd := &cobra.Command{
@@ -252,7 +306,47 @@ func newLimitsCmd(open opener) *cobra.Command {
 			}
 			defer s.Close()
 
-			l := store.Limits{Scope: store.Scope(scope), ScopeID: id}
+			scopeID := id
+			switch store.Scope(scope) {
+			case store.ScopeOrg:
+				o, err := resolveOrg(cmd.Context(), s, id)
+				if err != nil {
+					return err
+				}
+				scopeID = o.ID
+			case store.ScopeTeam:
+				t, err := resolveTeam(cmd.Context(), s, id)
+				if err != nil {
+					return err
+				}
+				scopeID = t.ID
+			case store.ScopeProject:
+				p, err := resolveProject(cmd.Context(), s, id)
+				if err != nil {
+					return err
+				}
+				scopeID = p.ID
+			case store.ScopeUser:
+				u, err := resolveUser(cmd.Context(), s, id)
+				if err != nil {
+					return err
+				}
+				scopeID = u.ID
+			case store.ScopeKey:
+				if id == "" {
+					return errors.New("--scope key needs --id, the key's id")
+				}
+			default:
+				return fmt.Errorf("--scope is org, team, project, user or key, not %q", scope)
+			}
+			level := store.Scope(scope)
+			if perMember {
+				// Written on the scope, applied to each member separately.
+				if level = store.MemberScope(level); level == "" {
+					return errors.New("--per-member is for --scope org, team or project")
+				}
+			}
+			l := store.Limits{Scope: level, ScopeID: scopeID}
 			if cmd.Flags().Changed("rpm") {
 				l.RPM = &rpm
 			}
@@ -260,7 +354,10 @@ func newLimitsCmd(open opener) *cobra.Command {
 				l.TPM = &tpm
 			}
 			if cmd.Flags().Changed("budget") {
-				l.Budget = &budget
+				// Whole units, as the quotas page takes them; stored as
+				// micro-units so repeated addition does not drift.
+				micros := int64(math.Round(budget * 1e6))
+				l.Budget = &micros
 				l.BudgetPeriod = store.Period(period)
 			}
 			if cmd.Flags().Changed("models") {
@@ -274,15 +371,17 @@ func newLimitsCmd(open opener) *cobra.Command {
 			if err := s.PutLimits(cmd.Context(), l); err != nil {
 				return err
 			}
-			fmt.Fprintf(cmd.OutOrStdout(), "limits set on %s %s\n", scope, id)
+			fmt.Fprintf(cmd.OutOrStdout(), "limits set on %s %s\n", level, scopeID)
 			return nil
 		},
 	}
-	cmd.Flags().StringVar(&scope, "scope", "project", "org | team | project | key")
-	cmd.Flags().StringVar(&id, "id", "default", "id at that scope")
+	cmd.Flags().StringVar(&scope, "scope", "project", "org | team | project | user | key")
+	cmd.Flags().BoolVar(&perMember, "per-member", false,
+		"with org, team or project: a limit for each member there, not one shared by all")
+	cmd.Flags().StringVar(&id, "id", "", "which one: id, path or unique name (a key's id for --scope key)")
 	cmd.Flags().IntVar(&rpm, "rpm", 0, "requests per minute")
 	cmd.Flags().IntVar(&tpm, "tpm", 0, "tokens per minute")
-	cmd.Flags().Int64Var(&budget, "budget", 0, "budget per period, in micro-units")
+	cmd.Flags().Float64Var(&budget, "budget", 0, "budget per period, in whole units as the quotas page shows them")
 	cmd.Flags().StringVar(&period, "period", "month", "day | month")
 	cmd.Flags().StringSliceVar(&models, "models", nil, "allowed models; empty allows none")
 	return cmd

internal/cli/memory.go

@@ -42,7 +42,12 @@ func newMemoryCmd(open opener) *cobra.Command {
 			if off {
 				keep = 0
 			}
-			if err := s.SetMemoryRetention(cmd.Context(), project, keep); err != nil {
+			p, err := resolveProject(cmd.Context(), s, project)
+			if err != nil {
+				return err
+			}
+			project = p.Path
+			if err := s.SetMemoryRetention(cmd.Context(), p.ID, keep); err != nil {
 				return err
 			}
 			if keep == 0 {
@@ -55,7 +60,7 @@ func newMemoryCmd(open opener) *cobra.Command {
 			return nil
 		},
 	}
-	cmd.Flags().StringVar(&project, "project", "default", "project id")
+	cmd.Flags().StringVar(&project, "project", "", "project: id, path or unique name")
 	cmd.Flags().IntVar(&hours, "retain-hours", 0, "how long a note is kept after it was last written")
 	cmd.Flags().BoolVar(&off, "off", false, "stop keeping notes for this project")
 	return cmd

internal/cli/mirror.go

@@ -4,8 +4,11 @@ import (
 	"encoding/json"
 	"fmt"
 	"log/slog"
+	"net"
 	"net/http"
+	"net/netip"
 	"os"
+	"slices"
 	"strings"
 	"time"
 
@@ -44,6 +47,7 @@ func newMirrorCmd() *cobra.Command {
 		newMirrorUnusedCmd(&dir),
 		newMirrorRemoveCmd(&dir),
 		newMirrorServeCmd(&dir),
+		newMirrorInitCmd(&dir),
 	)
 	return c
 }
@@ -229,6 +233,8 @@ func newMirrorRemoveCmd(dir *string) *cobra.Command {
 func newMirrorServeCmd(dir *string) *cobra.Command {
 	var listen, apiListen, base string
 	var tlsc tlsconf.Config
+	var allow, clients []string
+	var allowPrivate bool
 
 	c := &cobra.Command{
 		Use:   "serve",
@@ -254,10 +260,16 @@ func newMirrorServeCmd(dir *string) *cobra.Command {
 			if err := tlsc.Validate(); err != nil {
 				return err
 			}
+			if len(clients) > 0 && !tlsc.Enabled() {
+				return fmt.Errorf("--api-client names a certificate, and needs --tls-ca, --tls-cert and --tls-key")
+			}
 
 			out := cmd.OutOrStdout()
 			log := slog.Default()
 			mgr := mirror.NewManager(*dir, log)
+			if allowPrivate {
+				mgr.AllowPrivateSources()
+			}
 			api := mirror.NewAPI(mgr, strings.TrimSuffix(base, "/"))
 
 			// http.Dir refuses paths that escape the root, which is the whole
@@ -268,9 +280,13 @@ func newMirrorServeCmd(dir *string) *cobra.Command {
 				Handler:           readOnly(withManifest(*dir, http.FileServer(http.Dir(*dir)))),
 				ReadHeaderTimeout: 10 * time.Second,
 			}
+			allowed, err := parseAllow(allow)
+			if err != nil {
+				return err
+			}
 			admin := &http.Server{
 				Addr:              apiListen,
-				Handler:           api.Handler(),
+				Handler:           onlyClients(clients, apiGate(tlsc.Enabled(), allowed, api.Handler())),
 				ReadHeaderTimeout: 10 * time.Second,
 			}
 
@@ -279,14 +295,23 @@ func newMirrorServeCmd(dir *string) *cobra.Command {
 			fmt.Fprintf(out, "serving %s on %s\n", *dir, listen)
 
 			go func() { errs <- fmt.Errorf("serving the API: %w", serveAPI(admin, tlsc)) }()
-			if tlsc.Enabled() {
+			switch {
+			case tlsc.Enabled():
 				fmt.Fprintf(out, "management API on %s, mutual TLS against %s\n", apiListen, tlsc.CA)
-			} else {
-				// Said plainly rather than left to be discovered. An API that
-				// can delete models and start downloads, open to anyone who can
-				// reach the port, is a choice the operator should have made
-				// rather than inherited from a default.
-				fmt.Fprintf(out, "management API on %s, UNAUTHENTICATED — keep it on a trusted network\n", apiListen)
+				if len(clients) == 0 {
+					// The same root signs every node's certificate, so without a
+					// name any node could delete models here.
+					log.Warn("the management API takes any certificate from " + tlsc.CA +
+						", every node's included; name the control plane's with --api-client")
+				}
+			case len(allowed) > 0:
+				fmt.Fprintf(out, "management API on %s, for %s and this machine only\n", apiListen, strings.Join(allow, ", "))
+			default:
+				// This machine only, which was once "anyone": an API that can
+				// delete models and start downloads, open to every node that
+				// could reach the port, is a choice the operator should make
+				// with --api-allow rather than inherit.
+				fmt.Fprintf(out, "management API on %s, for this machine only (--api-allow to add the control plane)\n", apiListen)
 			}
 			fmt.Fprintf(out, "catalog sources should point at %s\n", base)
 
@@ -300,6 +325,12 @@ func newMirrorServeCmd(dir *string) *cobra.Command {
 	c.Flags().StringVar(&apiListen, "api-listen", ":8082", "address to serve the management API on")
 	c.Flags().StringVar(&base, "base", "http://localhost:8081",
 		"the address nodes use to reach this mirror, as it should appear in catalog sources")
+	c.Flags().StringArrayVar(&allow, "api-allow", nil,
+		"an address or network the management API answers, besides this machine; repeatable (default: this machine only)")
+	c.Flags().StringArrayVar(&clients, "api-client", nil,
+		"with mutual TLS, the common name of a certificate the management API answers; repeatable (default: any from --tls-ca)")
+	c.Flags().BoolVar(&allowPrivate, "allow-private-sources", false,
+		"let downloads reach loopback, private and link-local addresses")
 	c.Flags().StringVar(&tlsc.CA, "tls-ca", "", "CA bundle that management clients must present a certificate from")
 	c.Flags().StringVar(&tlsc.Cert, "tls-cert", "", "this mirror's certificate")
 	c.Flags().StringVar(&tlsc.Key, "tls-key", "", "this mirror's private key")
@@ -398,3 +429,78 @@ func versionPath(p string) (model, version string, ok bool) {
 	}
 	return parts[0], parts[1], true
 }
+
+// parseAllow reads addresses and networks: 10.0.0.140, 10.0.0.0/24.
+func parseAllow(list []string) ([]netip.Prefix, error) {
+	var out []netip.Prefix
+	for _, s := range list {
+		for _, one := range strings.Split(s, ",") {
+			one = strings.TrimSpace(one)
+			if one == "" {
+				continue
+			}
+			if p, err := netip.ParsePrefix(one); err == nil {
+				out = append(out, p.Masked())
+				continue
+			}
+			a, err := netip.ParseAddr(one)
+			if err != nil {
+				return nil, fmt.Errorf("--api-allow %q is not an address or a network", one)
+			}
+			out = append(out, netip.PrefixFrom(a.Unmap(), a.Unmap().BitLen()))
+		}
+	}
+	return out, nil
+}
+
+// apiGate decides who reaches the management API. With mutual TLS the
+// certificate decides, narrowed by --api-allow when given. Without it, only
+// this machine and the addresses allowed: nothing allowed used to mean anyone,
+// and every node that could reach the port could delete models.
+func apiGate(mtls bool, allowed []netip.Prefix, next http.Handler) http.Handler {
+	if mtls && len(allowed) == 0 {
+		return next
+	}
+	return onlyFrom(allowed, next)
+}
+
+// onlyClients answers only certificates with one of these common names, when
+// any are given. The handshake has already checked the certificate against
+// the root; this narrows which of the root's certificates may manage.
+func onlyClients(names []string, next http.Handler) http.Handler {
+	if len(names) == 0 {
+		return next
+	}
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.TLS == nil || len(r.TLS.VerifiedChains) == 0 ||
+			!slices.Contains(names, r.TLS.VerifiedChains[0][0].Subject.CommonName) {
+			http.Error(w, "this mirror is managed by its control plane only", http.StatusForbidden)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+// onlyFrom answers only this machine and the addresses allowed: the management
+// API can delete models and start downloads, and a mirror on its own machine
+// is reached over the network by one control plane and no one else.
+func onlyFrom(allowed []netip.Prefix, next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		host, _, err := net.SplitHostPort(r.RemoteAddr)
+		a, perr := netip.ParseAddr(host)
+		if err != nil || perr != nil {
+			http.Error(w, "forbidden", http.StatusForbidden)
+			return
+		}
+		a = a.Unmap()
+		ok := a.IsLoopback()
+		for _, p := range allowed {
+			ok = ok || p.Contains(a)
+		}
+		if !ok {
+			http.Error(w, "this mirror is managed by its control plane only", http.StatusForbidden)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}

internal/cli/mirror_gate_test.go

@@ -0,0 +1,66 @@
+package cli
+
+import (
+	"crypto/tls"
+	"crypto/x509"
+	"crypto/x509/pkix"
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"testing"
+)
+
+func TestTheMirrorAPIAnswersOnlyThisMachineUnlessTold(t *testing.T) {
+	ok := http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {})
+	call := func(h http.Handler, from string) int {
+		r := httptest.NewRequest("DELETE", "/v1/models/m/v", nil)
+		r.RemoteAddr = from + ":5000"
+		w := httptest.NewRecorder()
+		h.ServeHTTP(w, r)
+		return w.Code
+	}
+	cp := []netip.Prefix{netip.MustParsePrefix("10.0.0.140/32")}
+
+	// Nothing allowed and no TLS used to mean anyone: every node could delete
+	// models.
+	if got := call(apiGate(false, nil, ok), "10.0.0.141"); got != http.StatusForbidden {
+		t.Errorf("a node reached an unconfigured mirror API: %d", got)
+	}
+	if got := call(apiGate(false, nil, ok), "127.0.0.1"); got != http.StatusOK {
+		t.Errorf("the mirror's own machine was refused: %d", got)
+	}
+	if got := call(apiGate(false, cp, ok), "10.0.0.140"); got != http.StatusOK {
+		t.Errorf("the allowed control plane was refused: %d", got)
+	}
+	if got := call(apiGate(false, cp, ok), "10.0.0.141"); got != http.StatusForbidden {
+		t.Errorf("a node outside the allowlist got through: %d", got)
+	}
+	// With mutual TLS the certificate decides.
+	if got := call(apiGate(true, nil, ok), "10.0.0.141"); got != http.StatusOK {
+		t.Errorf("mTLS without an allowlist refused a client: %d", got)
+	}
+}
+
+func TestOnlyANamedCertificateManagesTheMirror(t *testing.T) {
+	ok := http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {})
+	with := func(cn string) *http.Request {
+		r := httptest.NewRequest("GET", "/", nil)
+		if cn != "" {
+			r.TLS = &tls.ConnectionState{VerifiedChains: [][]*x509.Certificate{{{Subject: pkix.Name{CommonName: cn}}}}}
+		}
+		return r
+	}
+	h := onlyClients([]string{"control-plane"}, ok)
+	for cn, want := range map[string]int{"control-plane": 200, "node01": 403, "": 403} {
+		w := httptest.NewRecorder()
+		h.ServeHTTP(w, with(cn))
+		if w.Code != want {
+			t.Errorf("%q: %d, expected %d", cn, w.Code, want)
+		}
+	}
+	w := httptest.NewRecorder()
+	onlyClients(nil, ok).ServeHTTP(w, with("node01"))
+	if w.Code != 200 {
+		t.Error("no names given narrowed it anyway")
+	}
+}

internal/cli/mirrorinit.go

@@ -0,0 +1,125 @@
+package cli
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"os"
+	"runtime"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/mirror"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/tlsconf"
+)
+
+// mirror init sets a machine up as the cluster's model mirror, on its own:
+// the bytes for every node on :8081, the management API on :8082 for the
+// control plane alone. server init does the same beside the control plane;
+// this is for when the mirror wants its own disk.
+
+func newMirrorInitCmd(dir *string) *cobra.Command {
+	var (
+		controlPlanes []string
+		base          string
+	)
+	cmd := &cobra.Command{
+		Use:   "init",
+		Short: "Set this machine up as the cluster's model mirror and start it",
+		Long: `Creates the llmgw user and the mirror's directory, and a systemd unit that
+serves the model files to every node on :8081 and the management API on
+:8082, and starts it.
+
+The management API can fetch and delete models, so it answers this machine
+and the control planes given with --control-plane, and nobody else. Then on
+the control plane:
+
+  sudo llmgw server init --mirror http://<this machine>:8082
+
+Safe to run again: it changes only what differs.`,
+		Example: `  sudo llmgw mirror init --control-plane 10.0.0.10`,
+		Args:    cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			if runtime.GOOS != "linux" {
+				return fmt.Errorf("mirror init sets up a Linux machine; this is %s", runtime.GOOS)
+			}
+			if os.Geteuid() != 0 {
+				return errors.New("mirror init creates a user, writes /etc and starts a service: run it as root")
+			}
+			if len(controlPlanes) == 0 {
+				return errors.New("--control-plane: which control plane manages this mirror (its address)")
+			}
+			if _, err := parseAllow(controlPlanes); err != nil {
+				return err
+			}
+			return mirrorInit(cmd.Context(), cmd.OutOrStdout(), *dir, base, controlPlanes)
+		},
+	}
+	cmd.Flags().StringArrayVar(&controlPlanes, "control-plane", nil,
+		"address of the control plane that manages this mirror; repeatable")
+	cmd.Flags().StringVar(&base, "base", "",
+		"the address nodes fetch from, http://host:8081 (default: this machine's first address)")
+	return cmd
+}
+
+func mirrorInit(ctx context.Context, out io.Writer, dir, base string, controlPlanes []string) error {
+	in := &serverInit{user: "llmgw", stateDir: "/var/lib/llmgw", out: out}
+	if err := in.ensureUser(ctx); err != nil {
+		return err
+	}
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return err
+	}
+	if err := in.chown(dir, true); err != nil {
+		return err
+	}
+	addr := ""
+	if ips := localAddrs(); len(ips) > 0 {
+		addr = ips[0].String()
+	}
+	if base == "" {
+		if addr == "" {
+			return errors.New("this machine has no address to give nodes; give one with --base")
+		}
+		base = "http://" + net.JoinHostPort(addr, "8081")
+	}
+	unit := mirrorUnitFor(dir, ":8082", base, controlPlanes,
+		"'llmgw mirror init'. Bytes on :8081 for every node; the\n# management API on :8082, for the control plane only.")
+	changed, err := in.writeUnit(mirrorUnitPath, unit)
+	if err != nil {
+		return err
+	}
+	for _, args := range [][]string{{"daemon-reload"}, {"enable", "--now", "llmgw-mirror"}} {
+		if err := in.systemctl(ctx, args...); err != nil {
+			return err
+		}
+	}
+	if changed {
+		if err := in.systemctl(ctx, "restart", "llmgw-mirror"); err != nil {
+			return err
+		}
+		in.done("model mirror in %s: files on :8081 at %s, management on :8082 for %s", dir, base, strings.Join(controlPlanes, ", "))
+	} else {
+		in.kept("model mirror in %s", dir)
+	}
+	m, err := mirror.NewClient("http://127.0.0.1:8082", tlsconf.Config{}, 5*time.Second)
+	if err != nil {
+		return err
+	}
+	if err := waitFor(ctx, 30*time.Second, "the mirror to answer", func() (bool, error) {
+		return m.Health(ctx) == nil, nil
+	}); err != nil {
+		return err
+	}
+	in.kept("answering")
+	api := "http://<this machine>:8082"
+	if addr != "" {
+		api = "http://" + net.JoinHostPort(addr, "8082")
+	}
+	fmt.Fprintf(out, "\nThe mirror is up. On the control plane:\n\n  sudo llmgw server init --mirror %s\n\n", api)
+	return nil
+}

internal/cli/model.go

@@ -3,6 +3,7 @@ package cli
 import (
 	"encoding/json"
 	"fmt"
+	"os"
 	"os/user"
 	"time"
 
@@ -28,7 +29,8 @@ func newModelCmd(client func() *ctlClient) *cobra.Command {
 		Use:   "model",
 		Short: "Add or remove models while the cluster is running",
 	}
-	c.AddCommand(newModelAddCmd(client), newModelRemoveCmd(client), newModelPlanCmd(client))
+	c.AddCommand(newModelAddCmd(client), newModelRemoveCmd(client), newModelPlanCmd(client),
+		newModelServeCmd(client))
 	return c
 }
 
@@ -126,6 +128,10 @@ func newModelRemoveCmd(client func() *ctlClient) *cobra.Command {
 
 // actor names who made a change, for the audit trail on a stored model.
 func actor() string {
+	// Under sudo, the person who ran it rather than root.
+	if u := os.Getenv("SUDO_USER"); u != "" && os.Geteuid() == 0 {
+		return u
+	}
 	if u, err := user.Current(); err == nil && u.Username != "" {
 		return u.Username
 	}
@@ -186,3 +192,44 @@ func newScaleCmd(client func() *ctlClient) *cobra.Command {
 		"how long an on-demand model stays up unasked-for; zero takes the cluster default")
 	return c
 }
+
+func newResourcesCmd(client func() *ctlClient) *cobra.Command {
+	var memory, cores int
+	var profile string
+	c := &cobra.Command{
+		Use:   "resources <model> --memory GB [--cores N]",
+		Short: "Set what a model reserves of a node: memory, and CPU cores",
+		Long: "--memory is the host RAM a replica needs: for a model with no GPU, its\n" +
+			"weights, KV cache and engine together. Placement reserves it on the node,\n" +
+			"so a node holds only as many replicas as it has memory for.\n\n" +
+			"--cores is the CPU cores a replica with no GPU computes on. They are\n" +
+			"reserved the same way, and become the engine's thread count, so two\n" +
+			"replicas on one node stop competing for the same cores. Zero reserves\n" +
+			"none and leaves the thread count to the node.\n\n" +
+			"Running replicas keep what they were started with; `llmgw ctl restart\n" +
+			"--model M` moves them to the new figures.",
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if !cmd.Flags().Changed("memory") {
+				return fmt.Errorf("--memory is required")
+			}
+			body, err := json.Marshal(adminapi.ResourcesRequest{Profile: profile, MemoryGB: memory, CPUCores: cores})
+			if err != nil {
+				return err
+			}
+			var m catalog.Model
+			if err := client().post(cmd.Context(), "/api/v1/models/"+args[0]+"/resources", body, &m); err != nil {
+				return err
+			}
+			for _, p := range m.Profiles {
+				fmt.Fprintf(cmd.OutOrStdout(), "%s/%s: %d GB memory, %d cores\n", m.Name, p.Name, p.MinMemoryGB, p.CPUCores)
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "Running replicas keep their old figures until restarted: llmgw ctl restart --model %s\n", m.Name)
+			return nil
+		},
+	}
+	c.Flags().IntVar(&memory, "memory", 0, "host RAM a replica needs, in GB")
+	c.Flags().IntVar(&cores, "cores", 0, "CPU cores a replica with no GPU computes on; 0 reserves none")
+	c.Flags().StringVar(&profile, "profile", "", "one profile; every profile when left out")
+	return c
+}

internal/cli/model_serve.go

@@ -0,0 +1,81 @@
+package cli
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/modelserve"
+)
+
+func newModelServeCmd(client func() *ctlClient) *cobra.Command {
+	var (
+		req      modelserve.Request
+		onDemand bool
+	)
+	c := &cobra.Command{
+		Use:   "serve OWNER/REPO",
+		Short: "Take a model from the registry to a replica that answers, in one command",
+		Long: "Picks the GGUF file (--quant, Q4_K_M by default, or --file), has the mirror\n" +
+			"fetch it and checks what arrived against the registry's checksum, checks\n" +
+			"that the nodes' llama.cpp can load it and sizes its memory from its own\n" +
+			"header, adds it to the catalog, waits for a replica, and asks it to say\n" +
+			"hello. Each step is shown as it happens; the first that fails stops it.\n\n" +
+			"  llmgw ctl model serve bartowski/Qwen2.5-3B-Instruct-GGUF\n" +
+			"  llmgw ctl model serve Qwen/Qwen2.5-7B-Instruct-GGUF --quant Q5_K_M --name qwen-7b\n" +
+			"  llmgw ctl model serve owner/big-GGUF --on-demand",
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			req.Repo = args[0]
+			if onDemand {
+				req.Replicas = 0
+			}
+			body, _ := json.Marshal(req)
+			var job modelserve.Job
+			if err := client().post(cmd.Context(), "/api/v1/models/serve", body, &job); err != nil {
+				return err
+			}
+			out := cmd.OutOrStdout()
+			fmt.Fprintf(out, "job %s\n", job.ID)
+			shown := map[string]string{}
+			for {
+				for _, s := range job.Steps {
+					line := s.State + " " + s.Detail
+					if shown[s.Name] == line {
+						continue
+					}
+					shown[s.Name] = line
+					mark := map[string]string{modelserve.Running: "..", modelserve.Done: "ok",
+						modelserve.Failed: "!!"}[s.State]
+					fmt.Fprintf(out, "%-3s %-11s %s\n", mark, s.Name, s.Detail)
+				}
+				switch job.State {
+				case modelserve.Done:
+					fmt.Fprintf(out, "\n%s is served.\n", job.Model)
+					return nil
+				case modelserve.Failed:
+					return errors.New(job.Error)
+				}
+				time.Sleep(2 * time.Second)
+				if err := client().get(cmd.Context(), "/api/v1/jobs/"+job.ID, &job); err != nil {
+					return err
+				}
+			}
+		},
+	}
+	f := c.Flags()
+	f.StringVar(&req.Quant, "quant", "", "the quantisation to serve (default Q4_K_M)")
+	f.StringVar(&req.File, "file", "", "the file to serve, instead of choosing by --quant")
+	f.StringVar(&req.Name, "name", "", "the catalog name (default: from the repository)")
+	f.StringSliceVar(&req.Aliases, "alias", nil, "other names clients may use; repeatable")
+	f.StringVar(&req.Description, "description", "", "what it is for, shown to clients in /v1/models")
+	f.IntVar(&req.Replicas, "replicas", 1, "how many replicas to run")
+	f.BoolVar(&onDemand, "on-demand", false, "run none until first asked for")
+	f.IntVar(&req.CtxPool, "ctx-pool", 16384, "llama.cpp's --ctx-size, shared by its parallel slots")
+	f.IntVar(&req.CPUCores, "cores", 0, "CPU cores a replica computes on; 0 takes half the smallest node it fits")
+	f.IntVar(&req.ContextLength, "context-length", 4096, "what one request may use")
+	return c
+}

internal/cli/node.go

@@ -0,0 +1,440 @@
+package cli
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"slices"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/config"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/onboard"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/version"
+)
+
+func newNodeCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "node",
+		Short: "Add machines to the cluster",
+	}
+	cmd.AddCommand(newNodeAddCmd(), newNodeRemoveCmd())
+	return cmd
+}
+
+func newNodeRemoveCmd() *cobra.Command {
+	var admin, serverCfg string
+	cmd := &cobra.Command{
+		Use:   "remove <node>",
+		Short: "Forget a node that is gone for good",
+		Long: `For a machine retired, or rebuilt under another name, which would otherwise
+stay listed as lost until the control plane restarts.
+
+Only a node that is not there is removed: stop its agent first, and wait for
+it to be lost, a minute later. Its certificate stays valid, since the
+authority keeps no revocation list: a machine that still has it can join
+again, which is how a node rebuilt under the same name comes back.`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			na := nodeAdd{admin: admin, serverCfg: serverCfg}
+			var out map[string]string
+			if err := na.adminAPI().delete(cmd.Context(), "/api/v1/nodes/"+args[0], &out); err != nil {
+				return err
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "%s removed\n", args[0])
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&admin, "admin", "", "the control plane's admin API (default: from server.yaml, else 127.0.0.1:9090)")
+	cmd.Flags().StringVar(&serverCfg, "config", "/etc/llmgw/server.yaml", "the control plane's configuration")
+	return cmd
+}
+
+// nodeAdd is what `llmgw node add` was asked to do.
+type nodeAdd struct {
+	opts      onboard.Options
+	fabrics   []string
+	servers   []string
+	admin     string
+	waitAll   bool
+	noWait    bool
+	plain     bool
+	serverCfg string
+	// named are the fabric names given in this run, by what the adapters
+	// report the fabric to be.
+	named map[string]string
+}
+
+func newNodeAddCmd() *cobra.Command {
+	var na nodeAdd
+	cmd := &cobra.Command{
+		Use:   "add [user@]address...",
+		Short: "Make a machine a node: check it, give it an identity, start its agent",
+		Long: `Run on the machine holding the certificate authority — the control plane,
+after 'llmgw server init' — as root. It logs in to the machine with ssh,
+as you would by hand, and:
+
+  1. installs llmgw there: the release for its architecture, checksum verified
+  2. runs 'llmgw doctor' there, and stops if it finds a problem
+  3. issues the node's certificate and installs it
+  4. writes agent.yaml and the systemd unit, and starts the agent
+  5. waits for the node to join and install llama.cpp
+
+The node's id is its hostname, and the address its agent dials is this
+machine's on the route to it, unless --node or --server say otherwise.
+Nothing else needs giving, except --fabric for InfiniBand or RoCE: which
+fabric an adapter is on has a name only you can choose, and it must be the
+same on every node attached to it. Doctor suggests one when it sees adapters.
+
+Several addresses add several nodes, one after another; a fabric named for
+one is recognised on the next and not asked again.
+
+The user needs sudo on the machine without a password. Run it again at any
+time: the node gets a fresh certificate and configuration, and its running
+engines are kept.`,
+		Example: `  sudo llmgw node add 10.0.0.21
+  sudo llmgw node add ubuntu@10.0.0.21 ubuntu@10.0.0.22 ubuntu@10.0.0.23
+  sudo llmgw node add ubuntu@gpu01 --fabric ib-a:mlx5_0,mlx5_1,mlx5_2,mlx5_3`,
+		Args: cobra.MinimumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return na.run(cmd.Context(), args, cmd.OutOrStdout())
+		},
+	}
+	f := cmd.Flags()
+	f.StringVar(&na.opts.Node, "node", "", "node id (default: the machine's hostname)")
+	f.StringVar(&na.opts.User, "ssh-user", "", "user to log in as (default: the one before @ in the address, else whoever ran sudo, else you)")
+	f.StringArrayVar(&na.servers, "server", nil, "control plane address the agent dials, https://host:7443; repeatable for failover (default: this machine)")
+	f.StringArrayVar(&na.fabrics, "fabric", nil, "InfiniBand or RoCE fabric and its adapters, name:mlx5_0,mlx5_1; repeatable")
+	f.StringVar(&na.opts.MgmtAddr, "mgmt-addr", "", "address engines are reached at (default: found by the agent)")
+	f.StringVar(&na.opts.MgmtIface, "mgmt-if", "", "interface NCCL bootstraps over (default: the one holding that address)")
+	f.StringVar(&na.opts.LlamaCppBin, "llamacpp-bin", "", "a llama-server you installed, instead of the one the agent installs")
+	f.StringVar(&na.opts.VLLMBin, "vllm-bin", "", "a vllm you installed; also set engines.vllm: \"\" in server.yaml")
+	f.StringVar(&na.opts.SGLangPython, "sglang-python", "", "python of an SGLang virtualenv you installed")
+	f.StringVar(&na.opts.NvidiaSMI, "nvidia-smi", "", "where nvidia-smi is, when it is not on PATH")
+	f.StringVar(&na.opts.IBRoot, "ib-root", "", "the sysfs InfiniBand directory, when not /sys/class/infiniband")
+	f.StringVar(&na.opts.PKI, "pki", defaultPKIDir, "directory holding the certificate authority")
+	f.StringVar(&na.opts.Releases, "releases", "https://gitea.mynodes.xyz/ilker/llmgw/releases/download", "where release files are downloaded from")
+	f.BoolVar(&na.opts.IgnoreChecks, "ignore-checks", false, "add the node even when doctor finds a problem")
+	f.StringVar(&na.admin, "admin", "", "the control plane's admin API, to watch the node join (default: from server.yaml, else 127.0.0.1:9090)")
+	f.StringVar(&na.serverCfg, "config", "/etc/llmgw/server.yaml", "the control plane's configuration, for the admin API's address")
+	f.BoolVar(&na.waitAll, "wait", false, "wait for every engine, vLLM included, not only llama.cpp")
+	f.BoolVar(&na.noWait, "no-wait", false, "do not wait for the node to join")
+	f.BoolVar(&na.plain, "plain", false, "plain output, even in a terminal")
+	return cmd
+}
+
+// prepare works out what every node added in this run shares.
+func (na *nodeAdd) prepare() error {
+	o := &na.opts
+	for _, s := range na.fabrics {
+		fab, err := onboard.ParseFabric(s)
+		if err != nil {
+			return err
+		}
+		if len(fab.HCAs) == 0 {
+			return fmt.Errorf("--fabric %s names no adapters: give them as %s:mlx5_0,mlx5_1", s, fab.Name)
+		}
+		o.Fabrics = append(o.Fabrics, fab)
+	}
+	for _, s := range na.servers {
+		for _, one := range strings.Split(s, ",") {
+			if one = strings.TrimSpace(one); one != "" {
+				o.Servers = append(o.Servers, one)
+			}
+		}
+	}
+	o.Version = version.Version
+	if o.Binary == "" {
+		exe, err := os.Executable()
+		if err != nil {
+			return err
+		}
+		o.Binary = exe
+	}
+	onboard.AgentUnit = agentUnit
+	na.named = map[string]string{}
+	return nil
+}
+
+// target is the options for one address, [user@]host.
+func (na *nodeAdd) target(addr string) onboard.Options {
+	o := na.opts
+	o.Fabrics = slices.Clone(na.opts.Fabrics)
+	o.Addr = addr
+	if user, host, ok := strings.Cut(addr, "@"); ok {
+		o.User, o.Addr = user, host
+	}
+	if o.User == "" {
+		// Under sudo, the person who ran it — their account is usually the
+		// one that exists on the nodes too. root's own keys still do the
+		// logging in, since that is who is running ssh.
+		o.User = os.Getenv("SUDO_USER")
+	}
+	return o
+}
+
+// rememberFabrics wraps the question of which fabric a node's adapters are
+// on, so a name given for one node is used for the next whose adapters
+// report the same fabric, without asking again. ask nil is a script, which
+// is asked nothing and gets only what an earlier answer said.
+func (na *nodeAdd) rememberFabrics(ask func([]onboard.Fabric) []onboard.Fabric) func([]onboard.Fabric) []onboard.Fabric {
+	return func(s []onboard.Fabric) []onboard.Fabric {
+		var known []onboard.Fabric
+		all := true
+		for i, f := range s {
+			if name, ok := na.named[f.Key]; ok && f.Key != "" && f.Key != "unknown" {
+				f.Name = name
+				s[i].Name = name
+				known = append(known, f)
+			} else {
+				all = false
+			}
+		}
+		if all || ask == nil {
+			return known
+		}
+		got := ask(s)
+		for _, f := range got {
+			if f.Key != "" && f.Key != "unknown" {
+				na.named[f.Key] = f.Name
+			}
+		}
+		return got
+	}
+}
+
+func (na *nodeAdd) run(ctx context.Context, addrs []string, out io.Writer) error {
+	if len(addrs) > 1 && na.opts.Node != "" {
+		return errors.New("--node names one node; give one address with it")
+	}
+	if err := na.prepare(); err != nil {
+		return err
+	}
+	tui := !na.plain && isTerminal(out)
+	type outcome struct {
+		addr, node string
+		err        error
+	}
+	var results []outcome
+	for i, addr := range addrs {
+		o := na.target(addr)
+		title := "llmgw · adding " + o.Addr
+		if len(addrs) > 1 {
+			title += fmt.Sprintf(" (%d of %d)", i+1, len(addrs))
+		}
+		var node string
+		var err error
+		if tui {
+			node, err = na.runTUI(ctx, o, title)
+		} else {
+			node, err = na.runPlain(ctx, o, title, out)
+		}
+		results = append(results, outcome{addr, node, err})
+		if ctx.Err() != nil {
+			break
+		}
+	}
+	if len(addrs) == 1 {
+		return results[0].err
+	}
+	fmt.Fprintln(out)
+	failed := 0
+	for _, r := range results {
+		if r.err != nil {
+			failed++
+			fmt.Fprintf(out, "  FAIL  %-20s %s\n", r.addr, r.err)
+		} else {
+			fmt.Fprintf(out, "  ok    %-20s %s\n", r.addr, r.node)
+		}
+	}
+	if failed > 0 {
+		return fmt.Errorf("%d of %d not added; running the same command again finishes them and leaves the rest as they are", failed, len(addrs))
+	}
+	return nil
+}
+
+func (na *nodeAdd) runPlain(ctx context.Context, o onboard.Options, title string, out io.Writer) (string, error) {
+	p := &plainProgress{out: out}
+	fmt.Fprintf(out, "%s\n", title)
+	o.AskFabrics = na.rememberFabrics(nil)
+	res, err := onboard.New(o, p.event).Run(ctx)
+	if err != nil {
+		return "", err
+	}
+	if na.noWait {
+		fmt.Fprintf(out, "\n%s is added. 'llmgw ctl nodes' shows it once it joins.\n\n", res.Node)
+		return res.Node, nil
+	}
+	if err := na.watch(ctx, res.Node, p.event); err != nil {
+		return res.Node, err
+	}
+	fmt.Fprintf(out, "\n%s is in the cluster.\n\n", res.Node)
+	return res.Node, nil
+}
+
+// adminAPI is the control plane's admin API, from its configuration when
+// this machine has it.
+func (na *nodeAdd) adminAPI() *ctlClient {
+	addr := na.admin
+	if addr == "" {
+		addr = "127.0.0.1:9090"
+		if cfg, err := config.Load(na.serverCfg); err == nil && cfg.AdminListen != "" {
+			addr = cfg.AdminListen
+			if strings.HasPrefix(addr, ":") {
+				addr = "127.0.0.1" + addr
+			}
+		}
+	}
+	return newCtlClient(addr)
+}
+
+// errNoAdmin is the watch giving up because the admin API is not here, which
+// is not a failure of onboarding.
+var errNoAdmin = errors.New("no admin API")
+
+// watch follows the node from the control plane: joining, then installing
+// its engines. llama.cpp is waited for, since without it the node serves
+// nothing; vLLM takes minutes more and is waited for only with --wait.
+func (na *nodeAdd) watch(ctx context.Context, node string, emit func(onboard.Event)) error {
+	client := na.adminAPI()
+	var nodes []adminapi.NodeView
+	if err := client.get(ctx, "/api/v1/nodes", &nodes); err != nil {
+		emit(onboard.Event{Step: onboard.StepJoin, Level: onboard.Warn,
+			Detail: "cannot reach the control plane's admin API here, so the node's joining is not followed",
+			Fix:    "llmgw ctl nodes on the control plane shows it"})
+		return nil
+	}
+	emit(onboard.Event{Step: onboard.StepJoin, Level: onboard.Running, Detail: "waiting for " + node + " to join"})
+	var view adminapi.NodeView
+	started := time.Now()
+	err := waitFor(ctx, 2*time.Minute, node+" to join", func() (bool, error) {
+		if err := client.get(ctx, "/api/v1/nodes", &nodes); err != nil {
+			return false, nil
+		}
+		for _, n := range nodes {
+			if n.ID == node && heardSince(n, started) {
+				view = n
+				return true, nil
+			}
+		}
+		return false, nil
+	})
+	if err != nil {
+		return fmt.Errorf("%s did not join: its agent's log says why (journalctl -u llmgw-agent on the node); a certificate whose name differs from the node id is refused", node)
+	}
+	emit(onboard.Event{Step: onboard.StepJoin, Level: onboard.Done, Detail: node + " joined: " + describeNode(view)})
+
+	emit(onboard.Event{Step: onboard.StepEngines, Level: onboard.Running, Detail: "installing engines"})
+	seen := map[string]string{}
+	limit := 20 * time.Minute
+	if na.waitAll {
+		limit = time.Hour
+	}
+	err = waitFor(ctx, limit, "the engines on "+node, func() (bool, error) {
+		if err := client.get(ctx, "/api/v1/nodes", &nodes); err != nil {
+			return false, nil
+		}
+		for _, n := range nodes {
+			if n.ID != node {
+				continue
+			}
+			finished := true
+			for _, p := range n.Provision {
+				line := p.State + " " + p.Detail
+				if seen[p.Engine] != line {
+					seen[p.Engine] = line
+					emit(engineEvent(p.Engine, p.Version, p.State, p.Detail))
+				}
+				switch p.State {
+				case "installing":
+					if p.Engine == "llamacpp" || na.waitAll {
+						finished = false
+					}
+				case "failed":
+					if p.Engine == "llamacpp" {
+						return false, fmt.Errorf("llama.cpp did not install: %s", p.Detail)
+					}
+				}
+			}
+			return finished && len(n.Provision) > 0, nil
+		}
+		return false, nil
+	})
+	if err != nil {
+		return err
+	}
+	msg := "engines ready"
+	if v, ok := seen["vllm"]; ok && strings.HasPrefix(v, "installing") && !na.waitAll {
+		msg = "llama.cpp ready; vLLM is still installing, which takes a few minutes more (watch /admin, or add --wait)"
+	}
+	emit(onboard.Event{Step: onboard.StepEngines, Level: onboard.Done, Detail: msg})
+	return nil
+}
+
+// heardSince reports whether the node has been heard from since t, by the
+// agent just started. A node added again is already listed, from its agent
+// before the restart, and a cordoned one is not "ready": neither says whether
+// the new agent connected.
+func heardSince(n adminapi.NodeView, t time.Time) bool {
+	switch n.State {
+	case "unreachable", "lost", "unknown":
+		return false
+	}
+	ago, err := time.ParseDuration(n.LastSeenAgo)
+	if err != nil {
+		return false
+	}
+	// A second's margin: the age is rounded to one.
+	return ago+time.Second < time.Since(t)
+}
+
+func engineEvent(engine, version, state, detail string) onboard.Event {
+	level := onboard.Info
+	switch state {
+	case "failed", "unsupported":
+		level = onboard.Warn
+	}
+	return onboard.Event{Step: onboard.StepEngines, Level: level,
+		Detail: fmt.Sprintf("%s %s: %s%s", engine, version, state, prefixed(": ", detail))}
+}
+
+func prefixed(p, s string) string {
+	if s == "" {
+		return ""
+	}
+	return p + s
+}
+
+func describeNode(n adminapi.NodeView) string {
+	parts := []string{}
+	if n.GPUTotal > 0 {
+		parts = append(parts, fmt.Sprintf("%d GPU(s) %s", n.GPUTotal, strings.Join(n.Classes, ", ")))
+	} else {
+		parts = append(parts, "no GPU")
+	}
+	if len(n.Fabrics) > 0 {
+		parts = append(parts, "fabrics "+strings.Join(n.Fabrics, ", "))
+	}
+	return strings.Join(parts, ", ")
+}
+
+// plainProgress prints events as lines, for a log or a pipe.
+type plainProgress struct {
+	out io.Writer
+}
+
+func (p *plainProgress) event(e onboard.Event) {
+	mark := map[string]string{
+		onboard.Running: "  ..  ", onboard.Done: "  ok  ", onboard.Info: "      ",
+		onboard.Warn: "  !!  ", onboard.Fail: "  FAIL",
+	}[e.Level]
+	fmt.Fprintf(p.out, "%s %-13s %s\n", mark, e.Step, e.Detail)
+	if e.Fix != "" {
+		fmt.Fprintf(p.out, "       %-13s → %s\n", "", e.Fix)
+	}
+}

internal/cli/org.go

@@ -0,0 +1,361 @@
+package cli
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+
+	"github.com/spf13/cobra"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
+)
+
+func newOrgCmd() *cobra.Command {
+	var sf storeFlags
+	cmd := &cobra.Command{
+		Use:   "org",
+		Short: "Organizations, teams and projects: see, add, rename, move, remove",
+		Long: "The tenancy tree an account lives in. A person is in a project, a project\n" +
+			"in a team, a team in an organization, and limits can be set on any of them.\n\n" +
+			"Anything that takes one of them accepts its id, its path\n" +
+			"(\"Acme/platform/gateway\") or its name when that name is unique.",
+	}
+	sf.bind(cmd)
+	open := func(cmd *cobra.Command) (*store.DB, error) { return sf.open(cmd) }
+	cmd.AddCommand(newOrgTreeCmd(open), newOrgAddCmd(open), newOrgRenameCmd(open),
+		newOrgMoveCmd(open), newOrgRemoveCmd(open))
+	return cmd
+}
+
+type dbOpener func(*cobra.Command) (*store.DB, error)
+
+func newOrgTreeCmd(open dbOpener) *cobra.Command {
+	var people bool
+	cmd := &cobra.Command{
+		Use:   "tree",
+		Short: "Show the whole tree, with how many accounts and keys each project has",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			s, err := open(cmd)
+			if err != nil {
+				return err
+			}
+			defer s.Close()
+			tree, err := s.Tree(cmd.Context())
+			if err != nil {
+				return err
+			}
+			var members map[string][]string
+			var alone []store.User
+			if people {
+				users, err := s.Users(cmd.Context(), "")
+				if err != nil {
+					return err
+				}
+				all, err := s.AllMemberships(cmd.Context())
+				if err != nil {
+					return err
+				}
+				email := map[string]string{}
+				for _, u := range users {
+					email[u.ID] = u.Email + "  " + string(u.State)
+					if u.IsAdmin {
+						email[u.ID] += "  admin"
+					}
+				}
+				members = map[string][]string{}
+				in := map[string]bool{}
+				for _, m := range all {
+					members[string(m.Scope)+":"+m.ScopeID] = append(members[string(m.Scope)+":"+m.ScopeID], email[m.UserID])
+					in[m.UserID] = true
+				}
+				for _, u := range users {
+					if !in[u.ID] {
+						alone = append(alone, u)
+					}
+				}
+			}
+			printTree(cmd.OutOrStdout(), tree, members)
+			if people && len(alone) > 0 {
+				fmt.Fprintf(cmd.OutOrStdout(), "\non their own\n")
+				for _, u := range alone {
+					fmt.Fprintf(cmd.OutOrStdout(), "  %s  %s  %s\n", u.Email, u.State, u.ID)
+				}
+			}
+			return nil
+		},
+	}
+	cmd.Flags().BoolVar(&people, "people", false, "list the accounts in each project")
+	return cmd
+}
+
+func printTree(w io.Writer, tree []store.TreeOrg, members map[string][]string) {
+	if len(tree) == 0 {
+		fmt.Fprintln(w, "no organizations yet; `llmgw org add org <name>` starts one")
+		return
+	}
+	list := func(indent, key string) {
+		for _, m := range members[key] {
+			fmt.Fprintf(w, "%s%s\n", indent, m)
+		}
+	}
+	for _, o := range tree {
+		fmt.Fprintf(w, "%s  (%s)%s\n", o.Name, o.ID, membersNote(o.Members))
+		list("    · ", "org:"+o.ID)
+		if len(o.Teams) == 0 {
+			fmt.Fprintln(w, "    no teams")
+		}
+		for _, t := range o.Teams {
+			fmt.Fprintf(w, "  %s  (%s)%s\n", t.Name, t.ID, membersNote(t.Members))
+			list("      · ", "team:"+t.ID)
+			if len(t.Projects) == 0 {
+				fmt.Fprintln(w, "      no projects")
+			}
+			for _, p := range t.Projects {
+				fmt.Fprintf(w, "    %s  (%s)  %s, %s\n", p.Name, p.ID,
+					countOf(p.Users, "member"), keysOf(p))
+				list("        · ", "project:"+p.ID)
+			}
+		}
+	}
+}
+
+func membersNote(n int) string {
+	if n == 0 {
+		return ""
+	}
+	return "  " + countOf(n, "member")
+}
+
+func keysOf(p store.TreeProject) string {
+	s := countOf(p.ActiveKeys, "key")
+	if revoked := p.Keys - p.ActiveKeys; revoked > 0 {
+		s += fmt.Sprintf(" (+%d revoked)", revoked)
+	}
+	return s
+}
+
+func countOf(n int, noun string) string {
+	if n == 1 {
+		return "1 " + noun
+	}
+	return fmt.Sprintf("%d %ss", n, noun)
+}
+
+func levelArg(arg string) (string, error) {
+	switch arg {
+	case "org", "organization":
+		return "org", nil
+	case "team", "project":
+		return arg, nil
+	}
+	return "", fmt.Errorf("%q is not org, team or project", arg)
+}
+
+func newOrgAddCmd(open dbOpener) *cobra.Command {
+	var in string
+	cmd := &cobra.Command{
+		Use:   "add <org|team|project> <name>",
+		Short: "Add an organization, a team to one, or a project to a team",
+		Example: "  llmgw org add org Acme\n" +
+			"  llmgw org add team platform --in Acme\n" +
+			"  llmgw org add project gateway --in Acme/platform",
+		Args: cobra.ExactArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			level, err := levelArg(args[0])
+			if err != nil {
+				return err
+			}
+			s, err := open(cmd)
+			if err != nil {
+				return err
+			}
+			defer s.Close()
+			ctx := cmd.Context()
+			var id, where string
+			switch level {
+			case "org":
+				id, err = s.CreateOrg(ctx, args[1])
+			case "team":
+				var o store.Org
+				if o, err = resolveOrg(ctx, s, in); err == nil {
+					id, err = s.CreateTeam(ctx, o.ID, args[1])
+					where = " in " + o.Name
+				}
+			case "project":
+				var t store.TeamPath
+				if t, err = resolveTeam(ctx, s, in); err == nil {
+					id, err = s.CreateProject(ctx, t.ID, args[1])
+					where = " in " + t.OrgName + " / " + t.Name
+				}
+			}
+			if errors.Is(err, store.ErrDuplicateName) {
+				return fmt.Errorf("there is already a %s named %q there", level, args[1])
+			}
+			if err != nil {
+				return err
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "%s %s%s  (%s)\n", level, args[1], where, id)
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&in, "in", "", "the organization a team goes in, or the team a project goes in")
+	return cmd
+}
+
+func newOrgRenameCmd(open dbOpener) *cobra.Command {
+	return &cobra.Command{
+		Use:     "rename <org|team|project> <which> <new name>",
+		Short:   "Rename an organization, team or project; ids and everything under it stay",
+		Example: "  llmgw org rename project Acme/platform/gateway api-gateway",
+		Args:    cobra.ExactArgs(3),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			level, err := levelArg(args[0])
+			if err != nil {
+				return err
+			}
+			s, err := open(cmd)
+			if err != nil {
+				return err
+			}
+			defer s.Close()
+			id, err := resolveLevel(cmd.Context(), s, level, args[1])
+			if err != nil {
+				return err
+			}
+			switch level {
+			case "org":
+				err = s.RenameOrg(cmd.Context(), id, args[2])
+			case "team":
+				err = s.RenameTeam(cmd.Context(), id, args[2])
+			case "project":
+				err = s.RenameProject(cmd.Context(), id, args[2])
+			}
+			if errors.Is(err, store.ErrDuplicateName) {
+				return fmt.Errorf("there is already a %s named %q beside it", level, args[2])
+			}
+			if err != nil {
+				return err
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "%s %s is now %q\n", level, id, args[2])
+			return nil
+		},
+	}
+}
+
+func newOrgMoveCmd(open dbOpener) *cobra.Command {
+	var to string
+	cmd := &cobra.Command{
+		Use:   "move <team|project> <which> --to <parent>",
+		Short: "Put a team in another organization, or a project in another team",
+		Long: "Everything under it moves too: projects, accounts and keys. From then on it\n" +
+			"inherits the new parent's limits. Usage already recorded is not rewritten.",
+		Example: "  llmgw org move project Acme/platform/gateway --to Scania/ml\n" +
+			"  llmgw org move team platform --to Scania",
+		Args: cobra.ExactArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			s, err := open(cmd)
+			if err != nil {
+				return err
+			}
+			defer s.Close()
+			ctx := cmd.Context()
+			switch args[0] {
+			case "team":
+				t, err := resolveTeam(ctx, s, args[1])
+				if err != nil {
+					return err
+				}
+				o, err := resolveOrg(ctx, s, to)
+				if err != nil {
+					return err
+				}
+				if err := s.MoveTeam(ctx, t.ID, o.ID); err != nil {
+					return dupAs(err, "team", t.Name)
+				}
+				fmt.Fprintf(cmd.OutOrStdout(), "team %s is now in %s\n", t.Name, o.Name)
+			case "project":
+				p, err := resolveProject(ctx, s, args[1])
+				if err != nil {
+					return err
+				}
+				t, err := resolveTeam(ctx, s, to)
+				if err != nil {
+					return err
+				}
+				if err := s.MoveProject(ctx, p.ID, t.ID); err != nil {
+					return dupAs(err, "project", p.Path)
+				}
+				fmt.Fprintf(cmd.OutOrStdout(), "%s is now in %s / %s\n", p.Path, t.OrgName, t.Name)
+			default:
+				return fmt.Errorf("only a team or a project moves; to move an account, `llmgw users move`")
+			}
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&to, "to", "", "the organization or team it goes to")
+	_ = cmd.MarkFlagRequired("to")
+	return cmd
+}
+
+func dupAs(err error, level, name string) error {
+	if errors.Is(err, store.ErrDuplicateName) {
+		return fmt.Errorf("the destination already has a %s named like %s", level, name)
+	}
+	return err
+}
+
+func newOrgRemoveCmd(open dbOpener) *cobra.Command {
+	return &cobra.Command{
+		Use:   "remove <org|team|project> <which>",
+		Short: "Remove an organization, team or project that nothing is in",
+		Long: "Only something empty is removed: an organization with no teams, a team with\n" +
+			"no projects, a project with no accounts and no keys. A project that ever had\n" +
+			"a key keeps it, revoked, because usage history refers to it; rename such a\n" +
+			"project instead. Its limits go with it.",
+		Args: cobra.ExactArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			level, err := levelArg(args[0])
+			if err != nil {
+				return err
+			}
+			s, err := open(cmd)
+			if err != nil {
+				return err
+			}
+			defer s.Close()
+			id, err := resolveLevel(cmd.Context(), s, level, args[1])
+			if err != nil {
+				return err
+			}
+			switch level {
+			case "org":
+				err = s.DeleteOrg(cmd.Context(), id)
+			case "team":
+				err = s.DeleteTeam(cmd.Context(), id)
+			case "project":
+				err = s.DeleteProject(cmd.Context(), id)
+			}
+			if err != nil {
+				return fmt.Errorf("%s %s was not removed: %w", level, args[1], err)
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "%s %s removed\n", level, id)
+			return nil
+		},
+	}
+}
+
+func resolveLevel(ctx context.Context, s *store.DB, level, arg string) (string, error) {
+	switch level {
+	case "org":
+		o, err := resolveOrg(ctx, s, arg)
+		return o.ID, err
+	case "team":
+		t, err := resolveTeam(ctx, s, arg)
+		return t.ID, err
+	default:
+		p, err := resolveProject(ctx, s, arg)
+		return p.ID, err
+	}
+}

internal/cli/org_test.go

@@ -0,0 +1,133 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
+)
+
+// run executes the CLI against one store file and returns stdout.
+func run(t *testing.T, db string, args ...string) (string, error) {
+	t.Helper()
+	cmd := Root()
+	var out, errOut bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&errOut)
+	// --config pointed nowhere, so a server.yaml on the test machine is never read.
+	cmd.SetArgs(append(args, "--store", db, "--config", ""))
+	err := cmd.ExecuteContext(context.Background())
+	return out.String(), err
+}
+
+func mustRun(t *testing.T, db string, args ...string) string {
+	t.Helper()
+	out, err := run(t, db, args...)
+	if err != nil {
+		t.Fatalf("%v: %v", args, err)
+	}
+	return out
+}
+
+func TestTheTreeIsManagedByNameNotId(t *testing.T) {
+	db := filepath.Join(t.TempDir(), "s.db")
+	mustRun(t, db, "org", "add", "org", "Acme")
+	mustRun(t, db, "org", "add", "org", "Scania")
+	mustRun(t, db, "org", "add", "team", "platform", "--in", "Acme")
+	mustRun(t, db, "org", "add", "team", "platform", "--in", "Scania")
+
+	// "platform" is in both, so a project needs the path.
+	_, err := run(t, db, "org", "add", "project", "gateway", "--in", "platform")
+	if err == nil || !strings.Contains(err.Error(), "more than one team") {
+		t.Fatalf("an ambiguous name was accepted: %v", err)
+	}
+	mustRun(t, db, "org", "add", "project", "gateway", "--in", "acme/Platform")
+	mustRun(t, db, "org", "add", "project", "research", "--in", "Scania / platform")
+
+	mustRun(t, db, "users", "create", "ayse@example.com", "--password", "correct horse battery", "--project", "Acme/platform/gateway")
+	mustRun(t, db, "keys", "create", "laptop", "--project", "gateway")
+
+	out := mustRun(t, db, "org", "tree", "--people")
+	for _, want := range []string{"Acme", "gateway", "1 member, 1 key", "ayse@example.com"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("tree lacks %q:\n%s", want, out)
+		}
+	}
+
+	out = mustRun(t, db, "users", "join", "ayse@example.com", "--project", "research")
+	if !strings.Contains(out, "Scania / platform / research") {
+		t.Errorf("join said: %s", out)
+	}
+	mustRun(t, db, "users", "leave", "ayse@example.com", "--project", "Acme/platform/gateway")
+	// She now uses the gateway through research alone; a personal key is hers.
+	mustRun(t, db, "keys", "create", "mine", "--for", "ayse@example.com")
+	if out := mustRun(t, db, "keys", "list", "--all"); !strings.Contains(out, "personal") {
+		t.Errorf("a personal key is not listed as one:\n%s", out)
+	}
+	if _, err := run(t, db, "keys", "create", "x", "--for", "ayse@example.com", "--project", "gateway"); err == nil {
+		t.Error("a key was made for her in a project she left")
+	}
+
+	mustRun(t, db, "org", "rename", "project", "research", "lab")
+	mustRun(t, db, "org", "move", "project", "Acme/platform/gateway", "--to", "Scania/platform")
+
+	// gateway still has the operator's key, so it stays.
+	if _, err := run(t, db, "org", "remove", "project", "gateway"); err == nil {
+		t.Error("a project with a key was removed")
+	}
+	mustRun(t, db, "org", "remove", "team", "Acme/platform")
+	mustRun(t, db, "org", "remove", "org", "Acme")
+
+	s, err := store.Open(context.Background(), db)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer s.Close()
+	paths, _ := s.AllProjects(context.Background())
+	var got []string
+	for _, p := range paths {
+		got = append(got, p.Path)
+	}
+	if strings.Join(got, "|") != "Scania / platform / gateway|Scania / platform / lab" {
+		t.Errorf("projects = %v", got)
+	}
+}
+
+func TestOneProjectNeedsNoFlag(t *testing.T) {
+	db := filepath.Join(t.TempDir(), "s.db")
+	mustRun(t, db, "org", "add", "org", "Acme")
+	mustRun(t, db, "org", "add", "team", "platform")
+	mustRun(t, db, "org", "add", "project", "gateway")
+	mustRun(t, db, "keys", "create", "laptop")
+	if out := mustRun(t, db, "keys", "list"); !strings.Contains(out, "laptop") {
+		t.Errorf("list: %s", out)
+	}
+	mustRun(t, db, "org", "add", "project", "search", "--in", "platform")
+	if _, err := run(t, db, "keys", "create", "other"); err == nil ||
+		!strings.Contains(err.Error(), "which project?") {
+		t.Errorf("two projects and no flag: %v", err)
+	}
+}
+
+func TestKeyBudgetsAreWholeUnits(t *testing.T) {
+	db := filepath.Join(t.TempDir(), "s.db")
+	mustRun(t, db, "org", "add", "org", "Acme")
+	mustRun(t, db, "org", "add", "team", "platform")
+	mustRun(t, db, "org", "add", "project", "gateway")
+	mustRun(t, db, "keys", "limits", "--scope", "project", "--id", "gateway", "--budget", "12.5")
+
+	s, err := store.Open(context.Background(), db)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer s.Close()
+	all, _ := s.AllLimits(context.Background())
+	for _, l := range all {
+		if l.Budget == nil || *l.Budget != 12_500_000 {
+			t.Errorf("budget stored as %v micro-units", l.Budget)
+		}
+	}
+}

internal/cli/resolve.go

@@ -0,0 +1,131 @@
+package cli
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
+)
+
+// The tree can be built from the web, which mints ids like proj-3kq7..., or
+// from `keys init`, which makes slugs. A command that wanted the id made the
+// operator copy one off a page, and every --project defaulted to "default",
+// which a tree built from the web does not have. These take what a person
+// would type instead: an id, a path, or a name that is unique.
+
+// normPath lowercases a path and spaces its separators the way the store joins
+// them, so "acme/platform/gateway" matches "Acme / platform / gateway".
+func normPath(p string) string {
+	parts := strings.Split(p, "/")
+	for i := range parts {
+		parts[i] = strings.ToLower(strings.TrimSpace(parts[i]))
+	}
+	return strings.Join(parts, " / ")
+}
+
+type candidate struct{ id, path string }
+
+// pick finds the one candidate an argument names.
+func pick(kind, arg string, all []candidate) (candidate, error) {
+	if arg == "" {
+		if len(all) == 1 {
+			return all[0], nil
+		}
+		if len(all) == 0 {
+			return candidate{}, fmt.Errorf("there is no %s yet; create one with `llmgw org add %s`", kind, kind)
+		}
+		return candidate{}, fmt.Errorf("which %s? give an id, a path or a name:\n%s", kind, listCandidates(all))
+	}
+	for _, c := range all {
+		if c.id == arg {
+			return c, nil
+		}
+	}
+	want := normPath(arg)
+	var matches []candidate
+	for _, c := range all {
+		full := normPath(c.path)
+		segs := strings.Split(full, " / ")
+		if full == want || segs[len(segs)-1] == want {
+			matches = append(matches, c)
+		}
+	}
+	switch len(matches) {
+	case 1:
+		return matches[0], nil
+	case 0:
+		return candidate{}, fmt.Errorf("no %s %q; there is:\n%s", kind, arg, listCandidates(all))
+	default:
+		return candidate{}, fmt.Errorf("%q names more than one %s; give its path:\n%s",
+			arg, kind, listCandidates(matches))
+	}
+}
+
+func listCandidates(cs []candidate) string {
+	var b strings.Builder
+	for _, c := range cs {
+		fmt.Fprintf(&b, "  %-40s %s\n", c.path, c.id)
+	}
+	return strings.TrimRight(b.String(), "\n")
+}
+
+func resolveProject(ctx context.Context, s *store.DB, arg string) (store.ProjectPath, error) {
+	all, err := s.AllProjects(ctx)
+	if err != nil {
+		return store.ProjectPath{}, err
+	}
+	cs := make([]candidate, len(all))
+	for i, p := range all {
+		cs[i] = candidate{p.ID, p.Path}
+	}
+	c, err := pick("project", arg, cs)
+	return store.ProjectPath{ID: c.id, Path: c.path}, err
+}
+
+func resolveTeam(ctx context.Context, s *store.DB, arg string) (store.TeamPath, error) {
+	all, err := s.AllTeams(ctx)
+	if err != nil {
+		return store.TeamPath{}, err
+	}
+	cs := make([]candidate, len(all))
+	for i, t := range all {
+		cs[i] = candidate{t.ID, t.OrgName + " / " + t.Name}
+	}
+	c, err := pick("team", arg, cs)
+	if err != nil {
+		return store.TeamPath{}, err
+	}
+	for _, t := range all {
+		if t.ID == c.id {
+			return t, nil
+		}
+	}
+	return store.TeamPath{}, store.ErrNotFound
+}
+
+func resolveOrg(ctx context.Context, s *store.DB, arg string) (store.Org, error) {
+	all, err := s.AllOrgs(ctx)
+	if err != nil {
+		return store.Org{}, err
+	}
+	cs := make([]candidate, len(all))
+	for i, o := range all {
+		cs[i] = candidate{o.ID, o.Name}
+	}
+	c, err := pick("org", arg, cs)
+	return store.Org{ID: c.id, Name: c.path}, err
+}
+
+// resolveUser takes an account's id or its email.
+func resolveUser(ctx context.Context, s *store.DB, arg string) (store.User, error) {
+	if u, err := s.UserByID(ctx, arg); err == nil {
+		return u, nil
+	}
+	u, err := s.UserByEmail(ctx, arg)
+	if errors.Is(err, store.ErrNotFound) {
+		return u, fmt.Errorf("no account with id or email %q; `llmgw users list` shows them", arg)
+	}
+	return u, err
+}