v0.13.0

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

.gitea/workflows/ci.yml

@@ -39,6 +39,16 @@ jobs:
       - name: Build
         run: go build ./...
 
+      # The Terraform provider is a module of its own, which ./... above does
+      # not reach. Its tests check its client against docs/admin-api.openapi.json,
+      # so a change to the admin API that breaks the provider fails here. The
+      # acceptance tests (TF_ACC=1) are left out: they need Terraform itself.
+      - name: Test the Terraform provider
+        working-directory: terraform-provider-llmgw
+        run: |
+          go vet ./...
+          go test ./...
+
       # The NVML backend needs cgo and cannot run without a driver, but it must
       # at least keep compiling: it is the only source of NVLink topology and a
       # break would otherwise surface on a GPU node, far from here.

.gitea/workflows/release.yml

@@ -93,6 +93,31 @@ jobs:
           ./dist/llmgw-${version}-linux-amd64 --version
           cat dist/checksums.txt
 
+      # Signed, so a machine that trusts the key built into it installs
+      # nothing the server alone could have put there. `release sign` checks
+      # the signature against that key before writing it, so a secret that
+      # does not match trusted.pub stops the release too.
+      - name: Sign the checksums
+        env:
+          RELEASE_SIGNING_KEY: ${{ secrets.RELEASE_SIGNING_KEY }}
+        run: |
+          set -euo pipefail
+          version="${GITHUB_REF_NAME:-$(git describe --tags --always)}"
+          if [ -z "${RELEASE_SIGNING_KEY:-}" ]; then
+            # Builds that carry a trusted key install only signed releases:
+            # publishing an unsigned one would be a release no upgraded
+            # machine accepts, so it stops here instead.
+            if [ -s internal/release/trusted.pub ]; then
+              echo "internal/release/trusted.pub holds a key, and the RELEASE_SIGNING_KEY secret is not set:"
+              echo "add it under Settings -> Secrets, or this release could not be installed anywhere."
+              exit 1
+            fi
+            echo "no RELEASE_SIGNING_KEY secret and no trusted key; releases are not signed"
+            exit 0
+          fi
+          ./dist/llmgw-${version}-linux-amd64 release sign dist/checksums.txt
+          echo "signed: dist/checksums.txt.sig"
+
       - name: Attach to the release
         env:
           TOKEN: ${{ secrets.GITEA_TOKEN }}

.gitignore

@@ -5,3 +5,7 @@
 *.db-shm
 .DS_Store
 coverage.out
+# The provider built in place, and what Terraform leaves beside an example.
+/terraform-provider-llmgw/terraform-provider-llmgw
+/terraform-provider-llmgw/examples/.terraform*
+/terraform-provider-llmgw/examples/terraform.tfstate*

BACKLOG.md

@@ -0,0 +1,907 @@
+# Backlog
+
+What a review of the code on 2026-10-04 (commit c2238ab) found should be done
+next: security fixes first, then guardrails, then features. Written for
+whoever implements it — a person or a model — without the review in hand.
+Every item names the files it touches and what "done" is. Paths are relative
+to the repository root. Sizes: S about a week, M two to four weeks, L more.
+
+Conventions this codebase keeps, which every item here must keep too:
+- A change is refused before anything is written (validate, then persist).
+- Nothing on the serving path logs prompt text, keys or passwords.
+- Each item gets unit tests beside the code (`*_test.go`), and the TUI
+  (`internal/cli/tui_*.go`), `docs/console.md` and `CHANGELOG.md` are
+  updated when behaviour an operator sees changes.
+- `go test ./...`, `go vet ./...` and `govulncheck ./...` pass. No release is
+  cut and nothing is deployed to the PoC cluster without being told to.
+
+---
+
+## A. Security — do first
+
+**Status (2026-10-04): done and merged.** A1–A9, A6b included — etcd and
+Patroni's API on TLS, the PoC moved in maintenance mode without a failover.
+Deliberately narrower than written: the admin API is a token on loopback
+rather than a unix socket (A5); thread ids are bounded and documented as
+project-wide rather than scoped per user (A8); Python engines resolve with an
+explicit PyTorch index and a PEP 751 lock rather than locks shipped per engine
+version (A8). All of A is live on the PoC.
+
+### A1. Toolchain (S, hours)
+`govulncheck` finds 11 standard-library vulnerabilities reachable from this
+code at Go 1.26.3 (net/http, crypto/x509, os.Root, net/textproto). Raise the
+`go` directive in `go.mod` to 1.26.6 or later, rebuild, run `govulncheck
+./...` until it reports none reachable. Add `govulncheck` to the Makefile's
+check target.
+
+### A2. Release signing is effectively off (S)
+- `internal/release/trusted.pub` is empty, so `TrustedKey()` returns "" and
+  `release.go:103` skips signature verification. Ship a real public key;
+  make a missing or invalid signature fatal. Drop the `LLMGW_RELEASE_KEY`
+  environment override, or honour it only in `-tags dev` builds.
+- `internal/onboard/onboard.go:365`: the node-side download checks only a
+  same-origin `checksums.txt`. Verify the signature there too (simplest:
+  have the node run `llmgw` itself to fetch and verify once it has any
+  binary), and `shellQuote` the `Releases` URL, which is interpolated into
+  single quotes unescaped.
+- `internal/agent/upgrade.go:44`: accept only `https://` release bases.
+- Done when: a tampered binary or checksums file is refused by self-upgrade,
+  node onboarding and agent upgrade, with a test for each.
+
+### A3. Agent port without TLS is anonymous and plaintext (S)
+`internal/cli/server.go:423` serves h2c on `:7443` when `agent_tls` is not
+configured; `agentsvc` then accepts any node id. Refuse to start control
+mode without TLS unless `agent_tls.insecure: true` is set explicitly; when
+insecure, bind `agent_listen` to 127.0.0.1 and log a warning at startup and
+in `llmgw doctor`. Keep `server init` writing TLS as it does.
+
+### A4. Model profiles reach root on every node (M)
+Profile `args` and `env` from a model definition are appended to the engine
+command unchecked (`internal/agent/engines/llamacpp.go:170`, `vllm.go:151`,
+`sglang.go:98`); `internal/agent/engines/unsafeenv.go` is a denylist that
+misses `NCCL_NET_PLUGIN`, `NCCL_TUNER_PLUGIN`, `NCCL_PROFILER_PLUGIN`,
+`CUDA_INJECTION64_PATH`, `NVTX_INJECTION64_PATH`, `TRITON_*` paths; engines
+run as root.
+- Replace the env denylist with an allowlist (CUDA_/NCCL_ tuning keys minus
+  anything ending in `_PLUGIN` or containing `INJECTION`, `VLLM_*`,
+  `HF_*` minus path keys, `OMP_*`, `GGML_*`). Apply at catalog validation
+  (`internal/control/catalog/catalog.go`, where `UnsafeEnv` is called) and
+  again in the agent.
+- Deny engine flags that write files or run code: `--trust-remote-code`,
+  `--log-file`, `--slot-save-path`, `--chat-template` with a path,
+  `--host`, `--api-key`, `--port`; vLLM/SGLang equivalents. Allowlist is
+  better than denylist if the flag set is enumerable per engine.
+- Run engines as an unprivileged user with the video/render groups
+  (`internal/agent/supervisor`, systemd unit in
+  `internal/cli/serverinit_cluster.go:52`). Weights cache must be readable
+  by it.
+- Done when: a profile with `--trust-remote-code` or `NCCL_NET_PLUGIN` is
+  refused at `ctl model add` and at the agent; `ps` shows engines not as
+  root.
+
+### A5. Admin API trusts any local process (M)
+`internal/cli/server.go:357` serves the admin API and pprof on
+`127.0.0.1:9090` with no authentication; `adminapi.actorOf`
+(`internal/control/adminapi/api.go:1613`) takes the actor from the
+client-sent `X-Llmgw-Actor` header.
+- Serve the admin API on a unix socket (`/run/llmgw/admin.sock`, 0660,
+  group `llmgw-admin`) by default, keeping TCP as an option that requires
+  a bearer token read from a root-only file (`/etc/llmgw/secrets/admin-token`).
+- Take the actor from `SO_PEERCRED` (uid → username) on the socket, or from
+  the token's name; ignore the header.
+- Refuse `admin_listen` on a non-loopback address unless `admin_insecure:
+  true`.
+- Put pprof behind its own `debug.pprof: true` setting, off by default.
+- `ctlClient` (`internal/cli/ctl.go`), the console and `node add` must work
+  over the socket; `sudo llmgw` already runs as root.
+
+### A6. Patroni REST and etcd are unauthenticated and plaintext (M)
+`internal/pgha/config.go:99` writes a `restapi:` with no `authentication`
+and `:54` etcd over `http://` with no client auth; `hba.go:56` PATCHes
+Patroni's config unauthenticated. Anyone reaching :8008 or :2379 owns the
+store.
+- Generate a Patroni REST username/password at setup, store it in
+  `/etc/llmgw/secrets/`, write `restapi.authentication` and
+  `restapi.certfile/cafile` from the cluster CA; send it from
+  `internal/pgha/hba.go` and `status.go`.
+- etcd: client and peer TLS from the cluster CA with `--client-cert-auth`.
+- Document, and have `server init` write, nftables rules limiting
+  2379/2380/8008/5432 to member addresses (see A9).
+- Done when: an unauthenticated `curl :8008/config` is refused and the
+  store status in the console still works.
+
+### A7. PostgreSQL traffic is plaintext (S)
+`internal/pgha/config.go:168` and `internal/cli/serverinit_postgres.go:330`
+use `sslmode=disable`; HBA lines are `host`. Enable server TLS in Patroni's
+postgresql parameters with a certificate from the cluster CA, write
+`hostssl` lines, use `sslmode=verify-full&sslrootcert=/etc/llmgw/ca.pem`.
+Existing clusters: `llmgw server` must keep working against a store that
+has not been migrated, with a warning.
+
+### A8. Smaller fixes, each S or less
+- **Capacity fallback skips the allowlist.** `internal/router/router.go:700`
+  builds `[canonical]+entry.Fallbacks` without `permits`. Filter the chain
+  with `r.permits(p, model)`; price against the model that served.
+- **Suspended users keep working API keys.** `store.(*DB).Resolve`
+  (`internal/store/memberships.go`) never joins `users.state`;
+  `Authenticator.Invalidate()` is never called. Reject keys whose owner is
+  not active; call `Invalidate` on revoke, suspend, limit change.
+- **Join codes never expire server-side.** `internal/join/join.go:103`
+  checks expiry only in `Parse`; `admit` (`:212`) does not. Check it there;
+  bind the listener to the chosen address, not `:7444` on all interfaces;
+  use the peer's address rather than the claimed `hello.Addr`, and show the
+  joiner's address for the operator to confirm before secrets are sent.
+- **Leftover sudoers grant.** `internal/onboard/gossh.go:248` writes
+  `NOPASSWD:ALL` and removes it only in `Close()` (`:271`). Write the grant
+  with a self-removal (`at`/systemd-run timer, 30 min) so a crash leaves
+  nothing; wipe password buffers after use. In `ssh.go:39` pass `--` before
+  the target.
+- **Auth cache and pre-auth DoS.** `internal/auth/auth.go:127`: unbounded
+  map, one DB query per bogus well-formed key. Bounded LRU, negative cache
+  with short TTL, per-IP token bucket before the DB.
+- **HTTP server hardening.** `server.go:351-360`, the h2c agent server,
+  both mirror servers: set `ReadHeaderTimeout` (exists), `IdleTimeout`,
+  `MaxHeaderBytes`, a body-read deadline, `netutil.LimitListener`; connect
+  `WithReadMaxBytes` on the agent stream.
+- **Login/signup abuse.** Default `signup_open: false`; per-IP token buckets
+  on `/login` and `/signup`; bounded wait for argon2 slots; CSRF token on
+  the login form; the per-address throttle must not lock the real owner
+  out (use IP+address pairs).
+- **Trusted proxies.** `internal/web/account.go:557`, `landing.go:60` honour
+  `X-Forwarded-Proto/Host` from anyone; add `router.trusted_proxies` and
+  only then trust them; `Cache-Control: no-store` on `/setup/*`.
+- **Certificate revocation.** `DELETE /api/v1/nodes/{id}` only drops
+  inventory; add a revoked-CN/serial list in the store checked in
+  `agentsvc` `Connect` and mirror `onlyClients`; `serverinit_cluster`
+  always passes `--api-client`.
+- **Engine exposure.** Engines bind `0.0.0.0` (`llamacpp.go:102`,
+  `vllm.go:109`): bind the management address. SGLang receives its key on
+  the command line (`sglang.go:102`): pass it by env or file.
+- **Backups.** `internal/cli/backup.go`: encrypt archives to an `age`
+  recipient from `backup.recipient` in server.yaml; keep the directory 0700.
+- **Python dependency confusion.** `internal/agent/provision/python.go:121`
+  uses `--extra-index-url` with `unsafe-best-match`. Pin torch to the
+  PyTorch index explicitly (uv `[[index]] explicit = true`), `first-index`,
+  hash-pinned lockfiles per engine version.
+- **Control-plane SSRF.** `internal/sourcecheck/sourcecheck.go:39` and
+  `gguf.FromURL` use the default client; reuse the mirror's
+  `fetchClient(false)` (private-address filter) and refuse a proxy unless
+  configured; block NAT64/6to4-embedded private addresses in
+  `internal/mirror/safefetch.go`.
+- **Low:** `agentsvc/service.go:430` indexes `n.GPUs[0]` without a length
+  check (CPU-only node panics the handler); thread ids are client-chosen
+  with no length cap and shared per project (`router/threads.go`) — cap
+  length, document, offer per-user scoping; `/v1/models` lists models the
+  key may not use (`handlers.go:799`); sessions have no idle timeout and
+  `PurgeSessions`/`PurgeClaims` are never called — add a janitor; add a CSP
+  header and set `htmx.config.allowEval=false`; cap GGUF array nesting
+  depth in `internal/gguf/gguf.go`; mirror `.source` sidecars are served by
+  the public file server — exclude dotfiles from `:8081`; prune
+  `modelserve.jobs` and the mirror `running` map; KaTeX → 0.16.21+.
+
+### A9. Firewall (S)
+No machine in a default install has a firewall. Have `server init`, `node
+add` and `server add` write an nftables ruleset: ssh open; `:8080` open;
+`:7443` and `:9091` open to the cluster's networks; `:9100` to the
+monitoring host; `:2379/2380/8008/5432` to store members and control
+planes; mirror `:8081` to the cluster, `:8082` to control planes; `:9090`
+Prometheus and `:3000` Grafana to operators. `llmgw doctor` reports a
+missing ruleset. Make it skippable with `--no-firewall`.
+
+---
+
+## B. Guardrails (M–L, build in this order)
+
+**Status (2026-10-04, branch `guardrails-b`):** B1–B4 done, and tried live on
+the PoC. That found four bugs, all fixed with tests:
+- a shadow default merged with an attached policy of unwritten mode left it
+  in shadow;
+- a streamed word held back at one release was dropped at the next;
+- llama.cpp continues a conversation ending on the answer, so Llama Guard's
+  verdict on answers is now asked with its own prompt as a completion;
+- a judge model was named in a client's "no endpoint" error.
+
+The PoC runs `observe` (shadow) for everyone, and Llama Guard 3 1B
+(`llama-guard-3-1b`, CPU, on cuda01) as a judge, which blocks a harmful
+request in ~0.7s and a harmful answer in ~1.4s there. Still left: see each
+item.
+
+Today nothing on the request path reads, classifies, redacts or filters
+message text in either direction (confirmed; the only "moderation" hit is a
+comment in `internal/router/budget_fallback.go:20`). Existing controls are
+about who, how much and how fast: allowlists (`router/handlers.go:450`),
+RPM/TPM/budget (`internal/accounting`), context precheck
+(`router/context_limit.go`), admission bands (`router/admission`),
+timeouts (`router/proxy/proxy.go:26-57`). Gaps to close on the way: no
+default output cap when the client omits `max_tokens`; `catalog.Capabilities`
+is advertised but never enforced; tool results are trusted input.
+
+### B1. Hooks in the proxy and router (S)
+**Done (branch `guardrails-b`):** `internal/guard` holds the interface;
+proxy `Filter`/`StreamFilter`; the input hook runs after `loadThread` (the
+simpler choice); error codes, headers, Responses `incomplete`, usage columns
+`guard_*`. Moved to B2: holding `delta.tool_calls` until they are whole and
+reading their arguments — that is the tool policy's filter, not the proxy's.
+
+- `internal/router/proxy/proxy.go`: add optional `InputRewrite func(body
+  []byte) ([]byte, Verdict)` on the request and two output hooks: `Filter`
+  for `relayBuffered` (between `ReadAll` and `WriteHeader`) and
+  `StreamFilter{OnEvent(data) (emit []string, stop bool); OnEnd()}` for
+  `relayStream`, called where each whole SSE event is assembled
+  (`eventBuffer`, before `io.WriteString` at `:343`). Nil hooks cost
+  nothing.
+- `internal/router/handlers.go`: call the input policy after the allowlist
+  and limits and before admission (around `:395`); the principal, scopes
+  and the model that will serve are known there. Thread history is spliced
+  later (`:416`): scan stored turns when written, or move the hook after
+  `loadThread` (decide; the second is simpler).
+- Blocking conventions: input → 400 `invalid_request_error` with
+  `code: "content_policy_violation"` (today `writeError` always sends
+  `code: null`); output non-stream → 200 with `finish_reason:
+  "content_filter"` and empty/redacted content; output stream → a final
+  chunk `{"choices":[{"index":0,"delta":{},"finish_reason":"content_filter"}]}`,
+  then `data: [DONE]`, then cancel upstream. Headers `x-llmgw-guard:
+  blocked|redacted|flagged` and `x-llmgw-guard-policy` set before the proxy
+  writes headers.
+- `internal/router/responses.go`: map `content_filter` to
+  `response.incomplete` with `incomplete_details.reason: "content_filter"`
+  (today it always emits `response.completed`, `:525`).
+- Tool calls: hold `delta.tool_calls` until `finish_reason: "tool_calls"`,
+  then validate; `replyDelta` (`reply.go:33`) must also read
+  `tool_calls[].function.arguments`.
+- Accounting: a blocked input is recorded like `RecordRefused` (nothing
+  charged); a blocked output is charged (the GPU was used). `store.Usage`
+  gains `GuardAction`, `GuardPolicy`, `GuardCategory`, `GuardMs`.
+
+### B2. Package `internal/guard` (M)
+**Mostly done (branch `guardrails-b`):** policies in server.yaml with
+attachments in the store (`ctl guard attach`), narrowed by the limits' rule;
+`guard/detect` (validated PII, secrets, injection through normalisation and
+decoding); redaction with consistent placeholders before prefix routing;
+tool allow/deny/strip, call count and argument schemas; capabilities and
+structured output (opt-in); default `max_tokens`; pinned system prompt and
+dropping the client's; `no_store` (threads, notes, prefix tree, external
+models); shadow mode. **Left:** a `guard_events` table — the usage row's
+`guard_*` columns carry action/policy/category/time, not rule and stage;
+language identification; the re-identification map that restores
+redacted values in answers.
+
+- `Policy`, `Effective` resolution over the tenancy tree with the same
+  narrowing rule as limits (`internal/store/sqlite.go:383-416` `tighten`):
+  deny sets union, allow sets intersect, `mode` takes the strictest of
+  `enforce > shadow > off`, `fail` takes `closed > open`, `no_store` at any
+  level wins, thresholds take the minimum.
+- Store: `guard_policies(scope, scope_id, policy json)` and
+  `guard_events(request_id, scopes, policy, rule, category, action, stage,
+  score, judge_ms, shadow)` — ids, categories, offsets and lengths only,
+  never text. Migrations for sqlite and postgres. Pruned with
+  `usage_retention`.
+- `guard/detect`: regex/keyword sets; PII with validators — email, phone,
+  IBAN (mod-97), card (Luhn), TCKN (checksum), IP, secrets (`sk-`, AWS,
+  JWT, PEM); normaliser (NFKC, strip zero-width/bidi, homoglyph fold,
+  base64/hex/URL decode to depth 2); injection heuristics (role-switch
+  phrases, fake chat-template tokens, long base64, invisible Unicode) —
+  default action `flag`; language id.
+- Redaction rewrites `messages[].content` in the upstream body with
+  placeholders (`[EMAIL_1]`) via the same `map[string]json.RawMessage`
+  round-trip `withModel`/`spliceThread` use; an optional re-identification
+  map lives only in request memory and restores originals in the output.
+  Redact before prefix routing so `PromptPrefix` hashes the redacted text.
+- `guard/toolpolicy`: tool name allow/deny (strip or 400), JSON-Schema
+  validation of assembled arguments against the declared `parameters`,
+  argument regex rules, `max_calls_per_turn`. Enforce
+  `Capabilities.Tools`/`Vision` here: a `tools` array or image parts to a
+  model without the capability → 400.
+- `guard/structured`: validate `response_format.json_schema` on the final
+  text → `content_filter`, or flag in shadow.
+- Output constraints: inject a default `max_tokens` when absent (from the
+  policy or `MaxOutput`), language check, structured check.
+- System-prompt pinning per project: prepend before `checkContextFits` and
+  before `spliceThread`; optionally drop client `system`/`developer`
+  roles; exclude the pin from stored thread turns; apply to Responses
+  `instructions` in `toChat`.
+- `no_store`: `loadThread` and `PutNote` refuse; `captureBytes()` returns 0;
+  skip the prefix-tree observe (`router.go:840`); disable External
+  fallbacks for the scope (filter in `dispatch` and `budgetFallback`).
+
+### B3. Judge model on the cluster (M)
+**Done (branch `guardrails-b`):** `role: guard` + `guard.format`; hidden and
+refused to clients and fallbacks; critical by default, never on demand;
+`Router.Judge` past admission/accounting/guardrails; llamaguard3,
+shieldgemma and json parsers; 5-minute cache; latency budget then
+fail open/closed; streamed answers read every 600 characters, or held with
+buffer_all. Simpler than written: the input judge runs after admission, not
+alongside it, and shadow mode judges synchronously within the budget rather
+than after the response. Not enforced: two replicas on different nodes —
+documented, left to `scaling.min`.
+
+- `catalog.Model.Role: "guard"` plus `Guard{Format: llamaguard3 |
+  shieldgemma | json, Categories}`. Guard models are hidden from
+  `/v1/models`, the chat picker and allowlists; placed like any model,
+  class `critical`, `scaling.min ≥ 1`, at least 2 replicas on different
+  nodes.
+- `guard/judge`: calls the guard model through the router's own `dispatch`
+  with an internal principal and its own admission band (never the
+  tenant's queue); parsers per format (Llama Guard `safe`/`unsafe\nS1,S10`;
+  ShieldGemma yes/no probability → per-tenant thresholds; generic JSON
+  verdict); verdict cache keyed by hash of normalised new turns (5 min);
+  `latency_budget` (default 250 ms) then `fail` open/closed; input judge
+  runs in parallel with admission queueing.
+- Streaming strategy: default sentence-buffered scanning (regex/PII per
+  sentence or ~200 chars before release; judge every 400–800 chars on the
+  cumulative tail; final judge at end); `buffer_all` for `fail: closed`
+  scopes. Document that released text cannot be retracted.
+- Shadow mode runs everything asynchronously after the response
+  (`context.WithoutCancel`, like `saveThread`) and only records.
+
+### B4. Config, metrics, UI (S)
+**Done (branch `guardrails-b`):** library in server.yaml, attachments via
+`ctl guard`, the console's **Guardrails…** with "applies from" marks, and
+the portal's `/admin/guard`; the metrics and alerts below (judge latency
+labelled by model only at the judge; the check latency by stage); `ctl
+request` shows the verdict; the chat page says "stopped by policy"; the
+profile lists effective policies; docs/guardrails.md and data.md written;
+the access log carries action, stage and policy only. Attaching from the
+portal is not done — the page shows; the console and ctl change.
+
+- Gateway-level policy library in `server.yaml` under `guard:` (see the
+  YAML in the review, reproduced in `docs/guardrails.md` to be written);
+  attachments to scopes in the store via `llmgw keys guard`, the console
+  ("Guardrails…" beside "Limits…" in `internal/cli/tui_people.go`, with
+  "inherited from team:X" badges) and the portal.
+- Metrics in `router/metrics.go` style:
+  `llmgw_guard_checks_total{stage,policy,action,category,mode}`,
+  `llmgw_guard_latency_seconds{stage,judge_model}`,
+  `llmgw_guard_judge_errors_total{reason}`, `llmgw_guard_fail_open_total`,
+  `llmgw_guard_stream_stops_total`, `llmgw_guard_redactions_total{kind}`,
+  `llmgw_tenant_guard_blocks_total{tenant}`. Alerts: fail-open > 1% for 5m,
+  judge p95 over budget, judge has no ready replicas, per-tenant block rate
+  > 3× its 7-day baseline, any `secret` detected in output.
+- Portal `/admin/guard`: violations by tenant/category/policy over time,
+  shadow vs enforce, judge health, recent events by request id; `ctl
+  request <id>` shows the verdict; chat page renders `content_filter` as
+  "stopped by policy X"; `/me` lists effective policies.
+- Update `docs/data.md`: the judge sees all text but in-cluster; External
+  fallbacks send prompts outside the cluster (the current "nothing leaves
+  the cluster" is wrong); `no_store` semantics.
+- Never log: prompt/completion text, PII values, the re-identification
+  map, judge inputs or rationale that quotes input. Check `accessLog`'s
+  `err` field and span errors.
+
+---
+
+## C. Features, ranked by value × feasibility
+
+1. **Done (branch `features-c`):** `audit_events`, written by the admin
+   API middleware and the /admin pages (with each change's result), `ctl
+   audit`, the console's Audit view; staff roles viewer / operator /
+   billing / admin. Left: before/after values (the request's fields are
+   recorded, not the state they replaced); a tenant-admin role that changes
+   its own organization (managers still only view it); hiding the forms a
+   viewer cannot submit. **Audit log and roles (M).** Today "audit" is slog lines
+   (`internal/web/admin_users.go:403-480`) and roles are the `IsAdmin` flag
+   plus an org "manager" who can view. Add `audit_events` (who, what,
+   before/after, source) written by the `adminAction`/`tenancyAction`
+   wrappers and by every admin-API mutation; roles viewer / operator /
+   tenant-admin / billing; `ctl audit`. Depends on A5 for a real actor.
+2. **Done (branch `features-c`):** OIDC sign-in (`auth.oidc`, PKCE,
+   verified email, roles and memberships from groups, `no_passwords`) and
+   SCIM 2.0 (`/scim/v2` Users and Groups). Left: the sign-in cookie is
+   signed with a per-process key, so with two control planes behind a
+   balancer the callback must reach the one that started it (sticky
+   sessions) until the key comes from the store. **OIDC/SSO login (M), then SCIM (M).** `internal/account/service.go`,
+   `internal/web/account.go`; map IdP groups to org/team/admin.
+3. **Done (branch `features-c`):** key lifetime limits (gateway, org, team,
+   project), `keys rotate --overlap`, kinds and expiry in `keys list`.
+   **Service accounts and key lifecycle (S).** Per-org maximum key TTL,
+   `keys rotate` with overlap, last-used shown, project-owned service keys
+   listed apart. `internal/cli/keys.go`, `internal/store/keys.go`,
+   `internal/auth/auth.go`.
+4. **Done (branch `features-c`):** CSV export from the rollups (API, ctl,
+   console). Left: Parquet, and a scheduled push to S3/SFTP. **Usage export (S).** CSV/Parquet by org/team/project/model/period from
+   the rollups (`internal/store/usageseries.go`), `GET
+   /api/v1/usage/export`, optional scheduled push to S3/SFTP.
+5. **Done (branch `features-c`):** `notify.webhooks` (model parked, node
+   lost, budget spent, update available; signed JSON or Slack; retries,
+   hourly de-duplication), `ctl notify test`, Alertmanager receiver
+   templates. Left: `server init` and the console do not yet ask for a
+   receiver — the templates are filled in by hand; each control plane sends
+   budget events on its own, so two behind a balancer may both send one.
+   **Alerting out of the box (S).** `deploy/monitoring/alertmanager.yml`
+   ships `receiver: none`; add Slack/email/webhook/PagerDuty receiver
+   templates driven by `server init` or the console; llmgw-native webhooks
+   for model parked, budget spent, update available (from the reconciler
+   and `modelserve`).
+6. **Done (branch `features-c2`):** `metadata`, `x-llmgw-tags` and `user`
+   on the usage record (migration 0023), `ctl request` shows them,
+   `router.tag_labels` metrics with 100 values per tag. Left: export and
+   `ctl usage` by tag or end user (the hourly and daily sums do not carry
+   tags; it would read the request records, within their retention).
+   **Request metadata and tags (S).** Accept `metadata`/`user` from the
+   body or `x-llmgw-tags`; store on the usage row; tenant metric labels
+   behind an allowlist. `router/handlers.go` parse, `accounting/recorder.go`.
+7. **Done (branch `features-c2`):** `ctl model canary/promote/canaries`,
+   session-sticky split with `x-llmgw-variant` pins, rollback on error rate
+   or TTFT, `canary_rolled_back` notification, console menu. Left: A/B
+   between two different models (the split is between a model and its
+   newer weights); the comparison is per control plane and lives in memory,
+   so a restart begins it again; a key-level pin.
+   **Canary and weighted A/B between model revisions (M).**
+   `control/modelserve/updates.go` `replace` swaps every replica; add
+   weighted routing across two revisions/aliases (scheduler filter, alias
+   resolution in `router/router.go:569`), a header/key pin, automatic
+   rollback on error-rate or TTFT regression from per-replica metrics.
+8. **Done (branch `features-c2`):** `/v1/files` and `/v1/batches`
+   (OpenAI's shape), worker under a store lease, lines kept as served,
+   lowest band, usage tagged `batch=<id>`, output and error files with
+   retention, `no_store` refused. Left: the Responses API (`/v1/responses`)
+   as a batch endpoint; the console and `ctl` do not list batches (an
+   operator sees them through usage tags); a file is one row in the store,
+   so a store backup carries batch files with it.
+   **Batch API and Files (M–L).** `/v1/files`, `/v1/batches`, JSONL
+   storage, a worker feeding the bronze band, accounting. New
+   `internal/router/batch`.
+9. **Done (branch `features-c2`):** `keys requests` (retention, sample),
+   kept after redaction, `ctl request --body/--replay`, console, pruning.
+   Left: a streamed answer is kept as its text, not its chunks; replay is
+   one request at a time (a set of them against a model is item 21's eval).
+   **Request/response logging and replay (M).** Opt-in per project with
+   retention like threads; sampled or full; redaction hooks from B;
+   `ctl request <id> --body`; replay against another model.
+10. **Done (branch `features-c2`):** Responses `text.format`,
+    `input_image`, `previous_response_id` (thread in the id); rerank and
+    score passthrough; transcription and translation as multipart;
+    `/v1/moderations` by the judge. Left: audio is charged no tokens (an
+    engine's duration usage is not read); `input_image` by `file_id`;
+    moderation scores are 0 or 1, as a judge says yes or no.
+    **OpenAI compatibility gaps (S–M each).** Responses: `text.format` →
+    `response_format`, `input_image`, `previous_response_id` via threads
+    (`router/responses.go`). Rerank/score passthrough for vLLM,
+    `/v1/audio/transcriptions` for a whisper engine, `/v1/moderations`
+    mapped to the guard model.
+11. **Done (branch `features-c2`):** `/v1/messages` and `count_tokens`,
+    streamed and not, tools, images, `x-api-key`, Anthropic error shape.
+    Left: extended thinking (a reasoning model's thoughts are not mapped to
+    thinking blocks); prompt caching; the account page's "Connect your
+    editor" does not offer Claude Code yet.
+    **Anthropic `/v1/messages` (M).** Translate like `responses.go`.
+12. **Done (branch `features-c2`):** `server restore` (dry run, version
+    check, decryption, modes and owners, SQLite and PostgreSQL),
+    `backup_copy_to` (directory or ssh), the drill in docs/install.md.
+    Left: restoring a replicated store's members (restore into the primary;
+    Patroni replicates it); the console's Back up now does not offer
+    restore; an ssh copy holds the archive in memory while it sends it.
+    **`server restore` (S).** Restore is manual shell today
+    (`docs/install.md:1187`); add the command with version check, dry run,
+    off-host copy target; a documented DR drill.
+13. **Done (branch `features-c2`):** TPOT, inter-token and tokens/s
+    histograms by model, pool and tenant; `slo` pressure in admission's
+    saturation; `llmgw_model_slo_seconds` and `llmgw-slo` alerts. Left: the
+    p99 is per control plane, from its own requests; an SLO per band or per
+    tenant; placement does not yet add replicas for an SLO (item 14).
+    **SLO-based admission and token-level metrics (S–M).** TPOT and
+    inter-token histograms, output tokens/s per model and tenant in
+    `router/metrics.go`; use `catalog.SLO` in `admission/saturation.go`.
+14. **Done (branch `features-c2`):** `scaling.schedule` (days, from, to,
+    min, max; past midnight), `scaling.prewarm`, `control.timezone`;
+    queue-depth scaling was there already. Left: `ctl scale` sets min and
+    max only (a schedule is set in the definition); scaling for an SLO
+    rather than for queue depth.
+    **Scheduled and warm-pool autoscaling (S–M).** Time-of-day min/max,
+    pre-warm, queue-depth scaling in `catalog.Scaling`,
+    `control/reconciler/demand.go`, `headroom.go`.
+15. **Done (branch `features-c2`):** `env:` and `vault:` references
+    wherever a secret file is named (store address, api_key_file, OIDC,
+    SCIM, webhooks), Vault KV with token or AppRole, `secrets.master_key`
+    sealing cluster_secrets (Vault transit or a local key). Left: the
+    certificate authority's key is still a file in /etc/llmgw (signing in
+    Vault's PKI engine instead is its own change); rotating the master key;
+    `backup_copy_key` and `admin_token_file` are files only.
+    **Secrets management (S–M).** Vault/KMS for `api_key_file`, the DSN, the
+    CA key, `cluster_secrets` (`store/secrets.go`, `store/seal.go`);
+    envelope-encrypt them in backups (with A8 backups).
+16. **Done (branch `features-c2`):** `users forget` (pseudonymised usage
+    and sums, kept requests, files, batches, limits and audit names), `keys
+    residency --in-cluster` (asked-for, fallback and canary). Left: an
+    export of everything held about a person (article 15); residency by
+    region between several clusters; backups keep what was forgotten until
+    they age out.
+    **GDPR and residency (S).** "Forget user" anonymises `user_id` in usage
+    and rollups and erases threads/memory (`store/hierarchy.go:241` leaves
+    it today); per-project "never route to an External provider".
+17. **Done (branch `features-c2`):** exact-match answer cache per project (`keys
+    cache --ttl/--any/--off`, console **Cache answers…**, `projects`
+    columns, 30-second setting cache), reproducible answers only unless
+    `--any`, LRU in memory bounded by `router.cache.max_bytes` and
+    `max_entry_bytes`, streamed answers kept and replayed as chunks,
+    `x-llmgw-cache` and `Cache-Control: no-cache`, guardrails before a hit
+    and the output policy on it, `no_store` and threads bypass, a hit
+    recorded as `cache_hit` with no tokens and no cost (migration 0027),
+    metrics, docs. Left: semantic (embedding-similarity) caching through the
+    embeddings models; a cache shared across control planes (each process
+    keeps its own, deliberately: a shared one would write every answer to
+    the store); a hit still waits its turn in admission, because the
+    guardrails judge the request after admission and the key is the request
+    they let through; logprobs in a streamed answer leave it unkept; `users
+    forget` does not reach into the cache (answers age out by the TTL); no
+    listing or flushing of what is cached (`--off` stops it being served at
+    once, the memory is freed by TTL and LRU).
+    **Response/semantic cache (M).** Exact-match first, per project,
+    opt-in, TTL; semantic via the embeddings models later. Before
+    `dispatch` in `router/handlers.go`.
+18. **Done (branch `features-c2`):** offline bundles — `llmgw bundle create`
+    (releases with signed checksums, every llama.cpp build per arch/variant
+    with GitHub's checksums, starter/judge and named Hugging Face model
+    files pinned and checked; directory or tar; manifest sha256), `bundle
+    import` (checked, all-or-nothing, into the mirror under `_llmgw/`),
+    `bundle trust`, `bundle show --verify`;
+    `offline.mirror`/`offline.checksums` in server.yaml, with nodes
+    installing llama.cpp from the mirror against checksums the control plane
+    sends over the agent stream (proto `EngineWant.offline_*`), releases
+    defaulting to the mirror for `node add`, `ctl upgrade` and agent
+    upgrades, update checks off; `server init --bundle` and the setup form's
+    bundle fields; docs/data.md's offline claim corrected; install.md
+    "Offline sites". A Helm chart for the control plane
+    (`deploy/helm/llmgw`, one replica, SQLite PVC or external PostgreSQL,
+    Secrets, Services, Ingress, ServiceMonitor) with
+    `deploy/container/Dockerfile` and docs/kubernetes.md; GPU nodes stay
+    outside Kubernetes by design. Left: vLLM/SGLang offline (a wheelhouse of
+    several GB per CUDA build and a uv `--find-links` install path); the
+    NVML release binary and uv in bundles; the setup wizard's preflight
+    still fails a machine without internet; `join`'s printed `curl` from the
+    mirror checks nothing; models in a bundle are single files (no whole-
+    repository safetensors sets yet); the chart runs one replica (a standby
+    is never ready, so HA in Kubernetes needs a different readiness design),
+    has not been installed on a real cluster, and ships no agent DaemonSet;
+    no published container image.
+    **Kubernetes/Helm and an air-gapped bundle (M).** `deploy/`,
+    `agent/provision`; `docs/data.md` claims offline operation but install
+    assumes the internet.
+19. **Done (branch `features-c2`):** `adminapi.Routes` and
+    `internal/docgen/openapi` generating `docs/admin-api.openapi.json` (3.1,
+    bearer security, every route, query parameters, schemas from the Go
+    types with their comments), served embedded at `GET
+    /api/v1/openapi.json`, kept true by a route-table test and a staleness
+    test; validated with openapi-spec-validator and openapi-generator-cli.
+    `GET /api/v1/models/{name}`. `docs/admin-api.md`. `terraform-provider-
+    llmgw/` (terraform-plugin-framework): `llmgw_model`, `llmgw_quota`,
+    `llmgw_guard_attachment`, data sources `llmgw_models` and `llmgw_nodes`;
+    client tests against a fake admin API and the OpenAPI document;
+    acceptance tests with Terraform and OpenTofu against the fake; one
+    apply, empty plan, in-place change and destroy against a real `llmgw
+    server` run by hand. Left: organizations, teams, projects, people and
+    keys are not in the admin API (they are `llmgw org`/`users`/`keys`
+    against the store), so not in the provider; a model's definition beyond
+    scaling, class, owner and adapters is changed by replacing it (the API
+    has no edit, and `resources` is not used yet); `canary`, `slo`,
+    `scaling.schedule` and `prewarm`, `guard` role and `origin` are not in
+    `llmgw_model`; models cannot be imported; the provider is not published
+    to a registry and has no release build; the acceptance tests are not run
+    in CI (they need Terraform); the document's schemas mark nothing
+    required and give no enums; `catalog.SLO`'s fields have no JSON tags, so
+    they are `TTFTp99` and `TPOTp99` on the wire.
+    **OpenAPI for the admin API, Terraform provider (M).** Generate from
+    `adminapi/api.go` routes via `docgen`.
+20. **Done (branch `features-c2`):** spans for the reconcile pass (begun only
+    when a pass does something), placement with its answer or rejections,
+    scale-up/down, drain, stop, eviction, preemption, reaping, restarts and
+    lost nodes; a `replica start` span from placement to serving whose
+    context travels to the agent in the start command
+    (`ControlMessage.trace`), where weights fetch, engine launch, rendezvous
+    and readiness wait continue the trace; stops, drains, adoption and
+    engine installs; modelserve jobs as a trace with a span per step linked
+    to the replica's start; an agent `tracing` block; docs in install.md's
+    "Tracing". Left: the router's span for a request does not link to the
+    replica it was sent to's start; heartbeats, fabric scans, logs and agent
+    upgrades are not traced; the supervisor has no restart span because it
+    never restarts an engine itself (a restart is the reconciler's `restart
+    replica` and reaches a node as a stop and a start); canary and promote
+    jobs, which landed on `features-c2` after this was branched, are traced
+    only through the shared step recording (as `<kind> model`), unchecked by
+    a test.
+    **Tracing beyond the router (S).** Spans for reconciler, placement,
+    agent start (`obs/trace.go`, `control/reconciler`, `agent/supervisor`).
+21. **Done (branch `features-c2`):** `internal/bench/eval` (suites in YAML or
+    JSON lines; exact, contains, regex, number, a JSON Schema subset, and a
+    judge model with a rubric; weights and a threshold), run on the control
+    plane through `Router.Replay`; `llmgw ctl eval MODEL --suite FILE|NAME`,
+    `--history`, `--run`, `--suites`; runs and their cases kept (migration
+    0028, `eval_runs` and `eval_cases`); `model update`/`promote --eval
+    SUITE --min-score N`, a model's standing gate (`ctl model gate`, `eval:`
+    in the catalog) — a promote asks the canary first, an update tries the
+    new weights as a 0% canary and promotes or removes it; the console's
+    model menu; `arithmetic` and `json-format` in `deploy/eval/`, carried in
+    the binary. Left: the suite of a model's standing gate is read by name
+    on the control plane at the time of the update, so two control planes
+    need the same `control.eval_dir`; a gated update needs room for one more
+    replica while it runs (there is no in-place gate, and a declared model
+    in server.yaml cannot be updated at all); no comparison against the old
+    weights' score (the gate is an absolute threshold, not "no worse than
+    before"); a run is not stopped once started (Esc in the console only
+    stops watching it), and the in-memory progress of a run lives on the
+    control plane that started it; runs are never pruned; the JSON Schema
+    support is a subset (no `$ref`, `oneOf`, `not`, `uniqueItems`); judge
+    cases go through the same concurrency as the model's, and a judge's
+    answers are not kept, only its score and reason; a gateway without a
+    control plane cannot run suites (there is no mode that asks through the
+    client API with a key).
+    **Eval harness (M).** `llmgw eval` extending `internal/bench` with
+    quality suites gating `model update`.
+22. **Done (branch `features-c2`):** MIG instances discovered on both paths
+    (nvidia-smi `-L` + `-q -x`; NVML through an interface with a faithful
+    fake) and reported instead of their card, each with its MIG UUID, own
+    memory and class `<card class>-mig-<profile>`; device numbers 1000 + 100
+    × card + instance, shown as `card/migN`; placement on MIG classes;
+    tp/pp/gpus/nodes above 1 on a MIG class refused in catalog validation
+    and again in placement; `CUDA_VISIBLE_DEVICES=MIG-<uuid>` for vLLM and
+    llama.cpp (no Vulkan device variable on MIG); per-instance memory and
+    processes in heartbeats and the GPU check, card sensors under each
+    instance, utilisation absent rather than zero; doctor MIG findings (`mig
+    -lgi`/`-lci` parsed); `ctl nodes`, console, `ctl status`, `ctl model
+    plan`/`serve` by class; docs/install.md MIG section. Written and tested
+    against fakes only — untested on real MIG hardware. Left: run it on an
+    A100/H100 in MIG mode (check `-L`/`-q -x`/`mig -lgi`/`-lci` and NVML MIG
+    device names against the parsers, and that `CUDA_VISIBLE_DEVICES=MIG-…`
+    reaches vLLM's workers through Ray); instances changed while the agent
+    runs are only seen when it restarts (no rescan); llmgw does not create
+    or reshape instances (no mig-parted integration); quotas count an
+    instance as one GPU, the same as a whole card; SGLang on MIG not
+    checked; device numbers assume fewer than 100 instances per card and
+    that instance numbers stay put while shards run on them.
+    **MIG (M–L).** Treat a MIG slice as a GPU class in
+    `agent/discovery/gpu_nvml.go` and `control/placement`.
+23. **Done (branch `features-c2`):** engine `trtllm`
+    (`internal/agent/engines/trtllm.go`): `trtllm-serve` through a launcher
+    of llmgw's that demands the replica's key (trtllm-serve has none) and
+    writes the options file that turns on `/prometheus/metrics` and the
+    iteration statistics; the scrape contract for it
+    (`scrape.TRTLLMMapping`, with a per-engine metrics path); found, not
+    installed — `engines.trtllm.python` in `agent.yaml`, probed from the
+    package's metadata; catalog validation (GPU class, one node, no GGUF
+    source, the flags a profile may not give); `ctl engine-check trtllm`,
+    which asks `trtllm-serve serve --help` through its module. Ollama/GGUF
+    import: `mirror import-ollama` (manifest parsing, blob digest check,
+    projector beside the model, all or nothing, a model definition printed),
+    `mirror import` for any local file, and the console's **I** on the
+    Mirror view. Left: TensorRT-LLM has not run on real hardware — the first
+    node with one should run `engine-check` and serve a model before anyone
+    relies on it; no installer for it; no multi-node TensorRT-LLM replica
+    (it needs an MPI or Slurm launch from one node); Triton Inference Server
+    as an engine is not done; trtllm's queue gauges are set per iteration,
+    so an idle engine shows its last batch until the next request;
+    `--num_serve_frontends` is refused because extra front ends would not
+    demand the key. The Ollama import runs on the mirror machine only — the
+    mirror's API takes no files, so an Ollama elsewhere means copying the
+    blob or running the import there; Ollama models kept as separate tensors
+    or as several weight layers, and its LoRA adapters, are refused or left
+    with a sentence; files an import run with `sudo` writes are root's, as
+    `mirror add`'s are.
+    **More engines (M each).** TensorRT-LLM/Triton adapter; Ollama/GGUF
+    import. `agent/engines/engine.go` interface and the metric contract in
+    `router/scrape`.
+24. **Done (branch `features-c2`), all six parts.** Lower: precise KV-index routing (plan phase 6), LoRA affinity for
+    vLLM, multi-cluster federation via External providers, facility-aware
+    placement (`docs/facility-aware-placement.md`), portal i18n, SDK/docs
+    portal.
+    What was built, and what is left:
+    - 24 (portal i18n): built — English/Turkish catalogue with fallback, per-
+      language templates, cookie/Accept-Language/`landing.language` choice
+      and a footer switcher, Turkish numbers and dates, every template and
+      handler message translated, tests that no template text stays English;
+      left — errors built with fmt.Errorf in other packages (store, catalog,
+      mirror, adminapi) still English on Turkish pages, percent sign
+      placement is mixed (%50 on limits, 93% on cluster pages), RFC3339
+      footer timestamps and plain-text http.Error bodies untranslated, the
+      /docs documents themselves English, a per-person language column
+      (cookie only today).
+    - 24 (SDK/docs portal): built — /docs renders the embedded manual (goldmark,
+      GFM, heading anchors, links rewritten, no script; public,
+      `landing.docs_sign_in` to require a session), and docs/clients.md
+      shows the official OpenAI/Anthropic SDKs against llmgw. Left: the
+      console's generated "Commands" page is not in the portal (it is built
+      from the cobra tree, which internal/web cannot see); no search across
+      documents.
+    - [~] 24. Precise KV index (tier 2) — built: vLLM KV events via the agent
+      (loopback ZMQ, pure-Go zmq4, msgpack in both of vLLM's encodings)
+      forwarded as net block-hash changes over the agent stream; router
+      index, tokenize via the replica's `/tokenize`, sha256_cbor block-hash
+      chain checked against cbor2/hashlib golden values; scorer by leading-
+      block share with tier 1 fallback; opt-in `kv_events` per profile;
+      metrics; docs. Left: validation against a real vLLM (event shape, hash
+      agreement, `/tokenize` matching the served prompt, cost of
+      tokenizing); vLLM's replay endpoint instead of resetting on a gap;
+      data-parallel ranks (one publisher each, ports offset); hybrid models'
+      cache groups and CPU-offloaded blocks; LoRA/multimodal/cache_salt
+      requests (extra keys); a router-only deployment (no agents)
+      subscribing directly; standby control planes have no index until they
+      lead; a per-replica fallback when only some candidates have an index;
+      caching tokenizations of repeated prompts.
+    - **24 LoRA affinity (branch `features-c2`):** built `max_loaded_adapters`
+      (catalog), vLLM adapter support at start and on demand
+      (`engines/lora.go`, `vllm.go`), the agent linking fetched adapters as
+      `llmgw-lora/<name>` in the engines' working directory, the router's
+      adapter tracker (`router/lora.go`: loads/unloads with the engine key,
+      LRU eviction never of an adapter in use, one load per adapter per
+      replica, `/v1/models` sync, 404 reload) and the `adapter-affinity`
+      scheduler filter in the chat, batch and long-context profiles, with
+      metrics and docs; tested against a fake of vLLM's HTTP interface.
+      **Left:** never run against a real vLLM — in particular that vLLM
+      resolves the relative `llmgw-lora/<name>` path against its working
+      directory on every node (multi-node too) and that unloading an adapter
+      mid-request is harmless; the agent still fetches every adapter at
+      replica start, so a new adapter needs a restart (fetching on first
+      load would need an agent command and a proto change); load timeout and
+      resync interval are constants, not config; SGLang's runtime LoRA API
+      is not driven; no per-replica "adapters held" view in the console or
+      admin API; the debug profile has no affinity.
+    - 24. Multi-cluster federation — built: peers via `ctl federation` kept in
+      the store, their models as PEER/MODEL synced from /v1/models
+      (withdrawn-while-referenced), /ready health with latency and routing
+      withdrawal, `ctl model fallbacks` for overflow, hop header loop
+      refusal, residency/no_store hold, optional attribution tags, console
+      view, metrics, docs. Left: server.yaml-declared models cannot name a
+      peer model as a fallback (config catalog is validated before peers are
+      read); per-peer CA / mTLS for peers behind a private CA; transitive
+      federation (A→B→C models) deliberately not offered; latency is /ready
+      RTT only (no per-request peer TTFT used in routing or weighting); the
+      peer's adapters are not imported (listed as aliases); no console form
+      to add/remove peers (CLI only); key file must exist on every control
+      plane.
+    - 24 (facility) — built: location labels (`ctl label`, agent.yaml),
+      spreading across racks/PDUs, `keep_within`, held domains with drain
+      (`ctl facility hold/release`, kept in the store), power caps from
+      `facility.budgets` against declared/derived/measured draw, shown in
+      explain-placement, `ctl nodes`, `ctl facility`, the console and the
+      API. Left: temperature conditions with hysteresis and their
+      enforcement (steps 3–4), a Prometheus/DCIM source, power headroom as a
+      rack-levelling score, spreading multi-node replicas across racks,
+      `llmgw_domain_*` metrics and alerts (near cap, over cap, stale data),
+      shedding and tokens per watt (step 5), and a drained node's state
+      surviving a restart.
+
+---
+
+## E. Every setting takes effect when it is changed (2026-10-05)
+
+Asked for after a site visit: an upgrade left server.yaml without guardrails,
+a node on another subnet stayed lost until firewall_networks was edited by
+hand, and nothing in server.yaml, agent.yaml or a generated unit applies until
+somebody restarts the right service on every machine. The rule from here on:
+**a file holds only what one machine needs to start; everything else is the
+cluster's, kept in the store, changed through ctl, the console or the web,
+audited, and in force on every control plane within seconds.**
+
+### E1. Cluster settings in the store (L) — done 2026-10-05
+Live on the PoC (140, 150): imported as version 1; a guard change applied on
+both without a restart; a router change restarted the standby at once and the
+leader 30s later with /health answering throughout; rollback did the same.
+- Table `cluster_settings` (versioned YAML document, who and why). The
+  cluster-wide part of server.yaml lives there; server.yaml keeps the
+  per-machine keys only (listeners, TLS paths, store DSN, secrets, tracing,
+  monitoring, mirror.api/tls, backup_dir/key, endpoints).
+- First start against a store with no document imports the file's cluster
+  keys (and the baseline guard policy when there is none); after that those
+  keys in a file are ignored, with a warning.
+- Each control plane polls the document's version and its own server.yaml's
+  hash. A change is validated, then applied: `guard` live, the rest by a
+  graceful restart of the process (standbys first, the leader last), which
+  systemd brings back. No "restart now?" anywhere.
+- `llmgw ctl config show|history|get|set|unset|edit|rollback`; the console's
+  settings screen edits the store for cluster keys; admin API
+  `GET/PUT /api/v1/settings`, `/history`, `/rollback`.
+- A standby that becomes leader re-reads the catalog, engine choices and
+  facility state from the store (it kept what it read at start).
+- Retires `appendGuardIfMissing` (server init): the import does it.
+
+### E2. Generated files from settings (L) — firewall on/off done 2026-10-06
+`firewall.enabled` in the cluster's settings reaches nodes over the agent
+stream and control planes through llmgw-firewall-sync.path. Left: the mirror
+machine and store members, the allowed set from membership, the other files.
+
+Every machine runs the agent (root) with roles — node, control plane, mirror,
+store member — and the agent renders and applies what was written once by
+init: the llmgw nft table, the mirror's unit flags, keepalived, etcd and
+Patroni configuration. The firewall's allowed set is the cluster's membership
+(every node, control plane, mirror and store member) plus
+`firewall.extra` from the store; 7443 stays open (mTLS). A node added or
+removed changes every machine's rules. Retires `firewall.Admit` and
+`firewall_networks` in server.yaml (imported into the store).
+
+### E3. agent.yaml down to bootstrap (M)
+agent.yaml keeps the control planes' addresses, its certificate and its id.
+Labels, fabrics, engines, heartbeat and supervisor settings move to the
+store per node and reach the agent over its stream; a change to the file is
+noticed and the agent restarts itself.
+
+### E4. Web settings page (S)
+The same document, edited on /admin/settings, for whoever has no terminal.
+
+---
+
+## F. Company documents: knowledge bases (RAG), then adapters (2026-10-08)
+
+A company wants a model to answer from its own documents. Retrieval is the
+tool for *knowledge* (sources shown, re-indexed in minutes, access per
+tenant); LoRA training is for *behaviour* (vocabulary, format) and has no
+access control — whatever goes into weights reaches everyone who may use the
+adapter. RAG first. Decisions taken: access per collection (no per-document
+ACL yet); a personal key or session names a project or team and gets that
+chain only, never the union of its person's memberships; PostgreSQL store
+only, off on SQLite with a sentence saying why.
+
+### F1. Store: collections, grants, chunks (M)
+- `pgvector` ≥ 0.8 installed on every Patroni member by `server init`
+  (`internal/cli/serverinit_postgres.go`), `CREATE EXTENSION` in the
+  migration; the SQLite migration has no tables, and the store reports the
+  feature unavailable.
+- Tables: `kb_collections` (id, org_id, owner `team:…`/`project:…`/`user:…`,
+  name, embed_model, dims, created_at), `kb_grants` (scope, scope_id,
+  collection, perm read|write — like `guard_attachments`), `kb_documents`
+  (name, digest, bytes, state, chunk count), `kb_chunks` (org_id,
+  collection, doc_id, ord, body, tsv, embedding) `PARTITION BY LIST
+  (org_id)`, a partition per organization, HNSW and GIN indexes per
+  partition.
+- Row-level security on `kb_chunks` against `current_setting('llmgw.org')`
+  and `llmgw.collections`, retrieval through its own role.
+- Rules, refused before anything is written: a grant never crosses
+  organizations; owner and grants resolve to existing scopes; deleting a
+  project/team/org and `users forget` delete their collections (`forget.go`).
+- Done: store tests on PostgreSQL, including an RLS test that a query
+  without the settings returns no rows.
+
+### F2. Ingest (M)
+- `llmgw ctl kb create|list|delete|grant|revoke|docs`, `ctl kb add
+  <collection> <files…>`, admin API under `/api/v1/kb`, audit events.
+- Text from PDF (text layer), DOCX, HTML, Markdown, plain text — in Go, no
+  Python. Split on headings/paragraphs, ~500 tokens with overlap. Embedded
+  through the router at the bronze band, accounted to the collection's
+  owner. One transaction per document; same digest skipped, changed digest
+  replaces. OCR out of scope.
+- Console: a Knowledge screen (collections, documents, grants; add, grant,
+  revoke, delete); `docs/console.md`, `docs/knowledge.md`.
+
+### F3. Retrieval on the request path (M)
+- `llmgw.knowledge: [collections]` in the body (stripped before the
+  engine), or default collections per project/key.
+- Allowed set from the caller's chain (§7.9.2), cached like limits; grants
+  add up down the tree. Personal keys and sessions need `x-llmgw-project`
+  (or the playground's picker) naming a scope the person is a member of.
+- A collection not allowed answers 404, exactly as a missing one.
+- Hybrid search with the filter inside the query (`hnsw.iterative_scan`,
+  `WHERE org_id = $1 AND collection = ANY($2)`), full-text arm merged by
+  reciprocal rank, `/v1/rerank` when a reranker is in the catalog. Top
+  chunks into a system message with document and position;
+  `x-llmgw-sources` lists them.
+- Leaks closed: answer-cache key includes the allowed set; per-organization
+  `cache_salt` on RAG requests; injected passages under `no_store` and the
+  guard's prompt-injection check; returned doc ids in the audit.
+- Done: router tests that tenant B never receives tenant A's chunks
+  (including via cache), that a personal key without a project is refused,
+  metrics (retrieval latency, chunks returned), docs.
+
+### F4. Adapter training (L, after F1–F3)
+A run-to-completion job placed by the control plane like a replica and
+supervised by the agent like an engine, in a Python environment the agent
+installs (TRL + PEFT, QLoRA). Data: Q/A pairs generated from a collection by
+a cluster model through `/v1/batches`, reviewed by people. Output to the
+mirror, into the model's `adapters`, through canary and a quality suite.
+Runs when the scaling schedule frees a GPU; 8–14B dense bases on one card.
+Never train on a collection some users of the adapter may not read.
+
+---
+
+## D. Facts worth knowing before starting
+
+- Admin API: `127.0.0.1:9090`, no auth, `ctlClient` in `internal/cli/ctl.go`.
+  Metrics on `:9091` with `/prometheus/targets` beside them.
+- Store: `internal/store`, migrations under `internal/store/migrations/{sqlite,postgres}`;
+  the PoC runs PostgreSQL under Patroni.
+- The console (`sudo llmgw`) is `internal/cli/tui_console.go` with actions
+  in `tui_actions.go`; every operator-visible change needs a row action or
+  a form there, and a line in `docs/console.md`.
+- Tests of the console use a fake admin API (`internal/cli/tui_actions_test.go`,
+  `adminStub`); tests of serving use fakes in
+  `internal/control/modelserve/modelserve_test.go`.
+- `go generate ./...` regenerates `docs/reference.md` and
+  `internal/docgen/reference_gen.go` whenever a config struct changes; the
+  docgen test fails otherwise.

Makefile

@@ -2,7 +2,7 @@ MODULE  := gitea.mynodes.xyz/ilker/llmgw
 VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo dev)
 LDFLAGS := -X '$(MODULE)/internal/version.Version=$(VERSION)'
 
-.PHONY: build test race lint fmt clean rename proto proto-tools
+.PHONY: build test race lint fmt vuln check clean rename proto proto-tools
 
 build:
 	go build -ldflags "$(LDFLAGS)" -o bin/llmgw ./cmd/llmgw
@@ -20,6 +20,17 @@ fmt:
 	go fmt ./...
 	go vet ./...
 
+# Known vulnerabilities reachable from this code, in the standard library and
+# in dependencies. A toolchain left behind is the commonest cause: the go
+# directive in go.mod is what fixes it.
+vuln:
+	go run golang.org/x/vuln/cmd/govulncheck@latest ./...
+
+# What has to pass before a change is merged.
+check: test
+	go vet ./...
+	$(MAKE) vuln
+
 # Regenerate the agent protocol. Generated code is committed, so this only
 # needs running when api/proto changes.
 proto: proto-tools

README.md

@@ -8,15 +8,17 @@ OpenAI-compatible endpoint. Design document: [llmgw-plan.md](llmgw-plan.md).
 
 ## Getting started
 
-Starting from nothing — no packages installed, no drivers, no nodes — follow
-[docs/install.md](docs/install.md): it builds a control plane, adds a node and
-serves a model, and says plainly which parts llmgw does not install for you.
+On the machine that will be the control plane, with the release binary
+installed:
 
-| Guide | For |
-|---|---|
-| [docs/install.md](docs/install.md) | Standing up a cluster from scratch |
-| [docs/node-onboarding.md](docs/node-onboarding.md) | Adding nodes to one that exists |
-| [docs/onboarding.md](docs/onboarding.md) | Giving people accounts and keys |
+```sh
+sudo llmgw
+```
+
+The setup screens install one machine or three (high availability), check
+them first, and leave a model answering. After that the same command opens
+the console. [docs/quick-install.md](docs/quick-install.md) has the six steps
+from empty servers to a first request; everything else is below.
 
 ## Status
 
@@ -33,6 +35,8 @@ Releases track the roadmap phases; see [CHANGELOG.md](CHANGELOG.md).
 | 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 |
+| v0.11.0 | — | High availability from setup, the setup and console screens, usage sums and per-tenant alerts | released |
 | v1.0.0 | 5 | Tenancy, prefix affinity, benchmarking | planned |
 
 As of v0.6.0 a cluster runs unattended: agents report their hardware, the
@@ -40,12 +44,47 @@ control plane places replicas — including ones larger than a single machine
 models load when someone asks for them and stop when nobody does, and keys,
 budgets and rate limits decide who may use any of it.
 
-Before v1.0.0: tracing, reference documentation, and filtering on `ctl nodes`
-and `ctl replicas` for fleets too large to read a whole table of. Two items
-that were on this list are not gaps: a model falls through to its fallbacks
-when there is no capacity as well as when a budget is spent, and routing
-profiles are chosen by the key rather than by a request header on purpose —
-a header would let any client promote itself into the top priority band.
+Since v0.11.0, not yet released (see [CHANGELOG.md](CHANGELOG.md),
+"Unreleased"):
+
+- **Security hardening** — signed releases only, a token on the admin API,
+  engines not run as root, TLS for the agent port, etcd and Patroni, a
+  firewall for llmgw's internal ports, encrypted backups, bounded
+  connections, sign-in throttling, a Content-Security-Policy.
+- **Guardrails** — policies that check requests and answers (PII, secrets,
+  prompt injection, deny patterns, a judge model such as Llama Guard), in
+  observe or enforce mode, attached to any part of the tenancy tree:
+  [docs/guardrails.md](docs/guardrails.md).
+- **Administration** — an audit log of every change (`ctl audit`), staff
+  roles (viewer, operator, billing, admin), single sign-on through OpenID
+  Connect and provisioning through SCIM 2.0, key lifetime limits and
+  rotation with overlap (`keys ttl`, `keys rotate`), usage export as CSV
+  (`ctl usage export`).
+- **Notifications** — webhooks, signed or Slack-shaped, for a model parked,
+  a node lost, a budget spent and new weights published (`notify.webhooks`,
+  `ctl notify test`), and Alertmanager receiver templates.
+- **Traffic and models** — request tags, canaries of new weights with
+  automatic rollback, quality suites gating updates, a response cache,
+  kept and replayed requests, batches, Anthropic's Messages API, more of
+  OpenAI's (structured output, images, rerank, audio, moderations),
+  scaling by the clock, SLO-aware admission, TensorRT-LLM, MIG, models
+  imported from Ollama, routing by what each vLLM replica's cache holds,
+  LoRA adapters loaded on demand, other llmgw clusters as providers, and
+  placement that knows racks, PDUs and power caps.
+- **Operations** — `server restore` and off-machine backup copies, secrets
+  in Vault, forgetting a person and keeping a project's requests in the
+  cluster, offline installs from a bundle, a Helm chart, tracing from the
+  control plane to the engines, the admin API in OpenAPI with a Terraform
+  provider, and the portal in English and Turkish with its docs at /docs.
+
+Every one of these is in the console as well as on the command line:
+[docs/console.md](docs/console.md).
+
+What is still ahead is in [BACKLOG.md](BACKLOG.md). Two things that look like
+gaps are not: a model falls through to its fallbacks when there is no
+capacity as well as when a budget is spent, and routing profiles are chosen
+by the key rather than by a request header on purpose — 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
@@ -58,29 +97,57 @@ them. On such a machine, run `llmgw doctor --json` first and keep the report;
 
 ## Documentation
 
-- [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
+Every page is also in the binary: `llmgw docs`, or **Manual** in the console.
+
+**Installing**
+
+- [docs/quick-install.md](docs/quick-install.md) — from empty servers to a
+  first request, in six steps: start here
+- [docs/install.md](docs/install.md) — the same with every option explained,
+  and running the cluster after: monitoring, notifications, single sign-on,
+  the firewall, upgrades, backups
+- [docs/node-onboarding.md](docs/node-onboarding.md) — adding nodes to a
+  cluster that exists
+- [docs/kubernetes.md](docs/kubernetes.md) — the control plane on
+  Kubernetes with the Helm chart, and why GPU nodes stay outside it
 - [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
+
+**Running it**
+
+- [docs/console.md](docs/console.md) — the console that bare `llmgw` opens:
+  every view, and the command each of its actions runs
+- [docs/onboarding.md](docs/onboarding.md) — accounts, keys, limits, staff
+  roles and single sign-on
+- [docs/clients.md](docs/clients.md) — using the gateway from code with the
+  official OpenAI and Anthropic SDKs, and llmgw's extensions
+- [docs/guardrails.md](docs/guardrails.md) — checking requests and answers:
+  policies, detectors, a judge model, and where each applies
 - [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
-  what leaves the machine; written for a security review
+
+**Reference**
+
 - [docs/reference.md](docs/reference.md) — every configuration key, generated
   from the structs and checked by a test, so it cannot describe a setting that
   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),
-  [docs/onboarding.md](docs/onboarding.md) — adding machines, and adding people
+- [docs/data.md](docs/data.md) — what llmgw stores, what it does not, and
+  what leaves the machine; written for a security review
+- [docs/admin-api.md](docs/admin-api.md) and its OpenAPI document — the
+  admin API, for scripts; [terraform-provider-llmgw/](terraform-provider-llmgw/)
+  manages models, quotas and guardrails with Terraform or OpenTofu
+- [deploy/](deploy/) — [a mirror](deploy/mirror/) on its own machine,
+  [Caddy and nginx](deploy/proxy/) in front of the client port, [two control
+  planes](deploy/ha/) behind a balancer, and [Prometheus, Alertmanager and
+  Grafana](deploy/monitoring/)
+
+**Working on llmgw**
+
+- [docs/development.md](docs/development.md) — built from source on one
+  workstation, no systemd and no `sudo`
+- [llmgw-plan.md](llmgw-plan.md) — the design; [BACKLOG.md](BACKLOG.md) —
+  what is next
 
 ## Building
 
@@ -100,8 +167,12 @@ 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
+llmgw ctl audit --since 24h          # who changed what
+llmgw ctl usage export --from 2026-09-01 --to 2026-10-01 --by project,model
 ```
 
+Bare `llmgw` opens the console, which does all of this from one screen.
+
 `ctl` talks to the admin port (`:9090` by default), not the client-facing one.
 Add `--json` to any command for machine-readable output.
 

api/proto/llmgw/v1/agent.proto

@@ -27,9 +27,36 @@ message AgentMessage {
     FabricScanReply fabric_scan = 5;
     FabricTestReply fabric_test = 6;
     UpgradeReply upgrade = 7;
+    KVEvents kv_events = 8;
   }
 }
 
+// KVEvents is a change to what one vLLM replica's prefix cache holds, read
+// by the agent from the engine's KV cache events and sent on for the router's
+// precise index (plan §7.5 tier 2).
+//
+// A net effect since the last one, not the events themselves: a block stored
+// and evicted between two sends is not worth the bytes. On every new stream
+// the agent first sends each replica in full, with clear_first set, because a
+// control plane that has just started or taken over knows nothing.
+message KVEvents {
+  string replica_id = 1;
+  // block_size is how many tokens make one of the replica's blocks.
+  int32 block_size = 2;
+  // clear_first says to forget what was known of the replica before applying the
+  // rest: its cache was cleared, its engine restarted, events were lost, or
+  // this is the first piece of a full copy.
+  bool clear_first = 3;
+  // stored and removed are block hashes as vLLM publishes them: the low 64
+  // bits of the sha256_cbor digest.
+  repeated fixed64 stored = 4;
+  repeated fixed64 removed = 5;
+  // problem, when set, is why the replica's events cannot be used — most
+  // likely an engine hashing another way than llmgw configured. Its index is
+  // empty while it stands.
+  string problem = 6;
+}
+
 // ControlMessage is anything the control plane tells a node.
 message ControlMessage {
   oneof msg {
@@ -43,7 +70,45 @@ message ControlMessage {
     FabricScanRequest fabric_scan = 8;
     FabricTestRequest fabric_test = 9;
     UpgradeAgent upgrade = 10;
+    ControlPlanes control_planes = 11;
+    Firewall firewall = 13;
+    RestartAgent restart_agent = 14;
   }
+  // trace is the W3C trace context (traceparent, and tracestate when there
+  // is one) of the control plane's span that sent this command, so what the
+  // agent does for it — fetching weights, launching the engine, waiting for
+  // it to answer — lands in the same trace. Empty when the control plane is
+  // not tracing, and ignored by an agent that is not.
+  map<string, string> trace = 12;
+}
+
+// RestartAgent has the agent start again, as llmgw restart asks of every
+// node: its engines keep serving and are taken over again.
+message RestartAgent {
+  string reason = 1;
+}
+
+// Firewall is whether llmgw's firewall is kept on the node — its nftables
+// table, which lets the cluster's networks alone reach the engines' ports and
+// the node exporter — sent when an agent registers and whenever the
+// cluster's settings change it (firewall.enabled).
+message Firewall {
+  bool enabled = 1;
+  // networks are let in besides those the node reaches the control planes
+  // on: firewall_networks, networks or single addresses.
+  repeated string networks = 2;
+  // engine_ports_from and engine_ports_to are the engines' ports
+  // (control.port_range).
+  int32 engine_ports_from = 3;
+  int32 engine_ports_to = 4;
+}
+
+// ControlPlanes is every control plane an agent may dial, sent by the leader
+// when an agent registers and whenever the list changes. The agent keeps it
+// beside its configuration, so a second control plane added after the node
+// was onboarded is one it fails over to without anybody editing the node.
+message ControlPlanes {
+  repeated string servers = 1;
 }
 
 // Register is the first message on every stream. It carries the node's full
@@ -208,6 +273,11 @@ message RunningShard {
   // restart could not be compared with the catalog — which is exactly when the
   // catalog is most likely to have been edited.
   string profile_fp = 15;
+
+  // compute is where its engine said it put the model when it became ready,
+  // kept by the agent across its own restarts: a control plane that takes
+  // over, or restarts, learns it here.
+  Compute compute = 16;
 }
 
 message GPU {
@@ -243,6 +313,25 @@ message GPU {
   string cluster_uuid = 19;
   string clique_id = 20;
   string fabric_bandwidth = 21;
+  // mig is set when this is a MIG instance rather than a whole card. index
+  // is then 1000 + 100 × card + device, uuid the instance's (MIG-…), and
+  // memory the instance's share; utilization_percent stays zero, because no
+  // driver measures it per instance.
+  MIGDevice mig = 22;
+}
+
+// MIGDevice is which card a MIG instance is carved from, and how.
+message MIGDevice {
+  int32 parent_index = 1;
+  string parent_uuid = 2;
+  // parent_memory_total_mb is the whole card's: the class is named from it.
+  int32 parent_memory_total_mb = 3;
+  // device is the instance's number on its card, as nvidia-smi -L lists it.
+  int32 device = 4;
+  // profile is NVIDIA's name for the slice, like 3g.40gb.
+  string profile = 5;
+  int32 gpu_instance = 6;
+  int32 compute_instance = 7;
 }
 
 message FabricAttachment {
@@ -285,6 +374,54 @@ message NodeLoad {
   int64 memory_used_bytes = 6;
   int64 memory_available_bytes = 7;
   repeated ShardLoad shards = 8;
+  // What the machine's own sensors say; zero is not measured. cpu_temp_c is
+  // the hottest CPU sensor, cpu_power_w the CPU packages' draw from RAPL,
+  // inlet_temp_c the board's inlet or ambient sensor where it has one.
+  double cpu_temp_c = 9;
+  double cpu_power_w = 10;
+  double inlet_temp_c = 11;
+  repeated GPUSensor gpus = 12;
+}
+
+// GPUSensor is one card's heat, power, and what is holding it back.
+message GPUSensor {
+  int32 index = 1;
+  double temp_c = 2;
+  double memory_temp_c = 3;
+  double power_w = 4;
+  double power_limit_w = 5;
+  // throttle names what is holding the clocks down now: sw_power_cap,
+  // hw_slowdown, sw_thermal, hw_thermal, power_brake.
+  repeated string throttle = 6;
+  // How busy the card is, sampled with the rest, rather than read once at
+  // registration. -1 is not reported by the driver. memory_total_mb is set
+  // by every agent that sends these, so zero there is an older agent.
+  double utilization_percent = 7;
+  double memory_utilization_percent = 8;
+  double memory_used_mb = 9;
+  double memory_total_mb = 10;
+  double sm_clock_mhz = 11;
+  // ecc_uncorrected counts uncorrected ECC errors since the driver loaded.
+  double ecc_uncorrected = 12;
+  // What wears the card out, read every minute; has_wear says these are
+  // present. Counts of -1 are not reported for this card.
+  bool has_wear = 13;
+  int64 pcie_replays = 14;
+  int64 retired_pages_sbe = 15;
+  int64 retired_pages_dbe = 16;
+  bool retirement_pending = 17;
+  int64 remapped_rows_correctable = 18;
+  int64 remapped_rows_uncorrectable = 19;
+  bool remap_pending = 20;
+  bool remap_failure = 21;
+  int64 nvlink_crc_errors = 22;
+  int64 nvlink_replay_errors = 23;
+  int64 nvlink_recovery_errors = 24;
+  // xid_errors are the driver's error events since the agent started.
+  int64 xid_errors = 25;
+  int32 last_xid = 26;
+  string last_xid_text = 27;
+  int64 last_xid_unix = 28;
 }
 
 // ShardLoad is one engine process group's use.
@@ -426,6 +563,15 @@ message Heartbeat {
   IMEX imex = 17;
   // cpu_count as in Register, for a VM given more CPUs while it runs.
   int32 cpu_count = 18;
+
+  // gpu_foreign_memory_mb, indexed by GPU, is what processes that are not
+  // this agent's shards hold on each card, read afresh every heartbeat. What
+  // keeps a card out of placement for another tenant is decided from this
+  // rather than from registration: a card that had something else on it when
+  // the agent started is not taken forever, and one that gains a tenant later
+  // is not handed out. Empty from an agent that does not measure it, or from
+  // one that could not this time.
+  repeated int32 gpu_foreign_memory_mb = 19;
 }
 
 // Provision is the software a node should have: which engines, at which
@@ -446,6 +592,18 @@ message Provision {
 message EngineWant {
   string engine = 1;  // "llamacpp"
   string version = 2; // "b10991"
+  // variant is the build to install, when one is chosen for the node rather
+  // than left to its hardware: "cu13", "cu129". Empty is the agent's choice.
+  string variant = 3;
+  // offline_base, on a cluster with no way to the internet, is where this
+  // engine version's files are on its mirror:
+  // http://mirror:8081/_llmgw/engines/llamacpp/b10991. Set, the node never
+  // asks the engine's publisher.
+  string offline_base = 4;
+  // offline_sha256 is each of those files' checksum by name, from the
+  // bundle the control plane trusts — not from the mirror, which serves
+  // every node over plain HTTP.
+  map<string, string> offline_sha256 = 5;
 }
 
 // ProvisionStatus is where one engine's installation stands on a node.
@@ -459,6 +617,18 @@ message ProvisionStatus {
   string detail = 5;
 }
 
+// Compute is where an engine runs its model, as it said when it loaded it.
+message Compute {
+  // backend is "CUDA", "Vulkan", "Metal" or "CPU".
+  string backend = 1;
+  // devices are the devices it named: "CUDA0: Quadro RTX 6000 (7.5)".
+  repeated string devices = 2;
+  // layers_offloaded of layers_total went to the devices; both 0 when the
+  // engine did not say.
+  int32 layers_offloaded = 3;
+  int32 layers_total = 4;
+}
+
 // ShardStatus reports a shard's lifecycle transition.
 message ShardStatus {
   string node_id = 1;
@@ -480,6 +650,10 @@ message ShardStatus {
   // going to look.
   FetchProgress fetch = 8;
 
+  // compute is what the engine says it computes on, read from its own output
+  // as it became ready: sent with STATE_READY when the engine says.
+  Compute compute = 9;
+
   enum State {
     STATE_UNSPECIFIED = 0;
     STATE_PENDING = 1;
@@ -553,6 +727,12 @@ message EngineProfile {
   map<string, string> env = 9;
   string model_path = 10;
   string served_model_name = 11;
+  // adapters are LoRA adapters loaded beside the model, in order: the index
+  // is the id a request applies one by.
+  repeated LoraAdapter adapters = 12;
+  // kv_events has a vLLM engine publish its KV cache events to the agent, for
+  // the router's precise index.
+  bool kv_events = 13;
 }
 
 // RemoveWeights deletes cached model files a node no longer needs.
@@ -685,3 +865,10 @@ message UpgradeReply {
   string version = 2;
   string error = 3;
 }
+
+// LoraAdapter is one adapter: the name clients ask for it by, and its source,
+// which the agent fetches as it does the model's weights.
+message LoraAdapter {
+  string name = 1;
+  string source = 2;
+}

cmd/llmgw/main.go

@@ -5,6 +5,8 @@ package main
 import (
 	"fmt"
 	"os"
+	// Time zones for scaling schedules, on a machine without the tz database.
+	_ "time/tzdata"
 
 	"gitea.mynodes.xyz/ilker/llmgw/internal/cli"
 )

deploy/container/Dockerfile

@@ -0,0 +1,40 @@
+# The llmgw control plane as a container image, for deploy/helm/llmgw.
+#
+# The project publishes binaries, not an image, so this is built where the
+# image is to live:
+#
+#   docker build -f deploy/container/Dockerfile --build-arg VERSION=v0.11.1 \
+#     -t registry.internal/llmgw:v0.11.1 .
+#   docker push registry.internal/llmgw:v0.11.1
+#
+# The binary is static (CGO_ENABLED=0, as every release is), so the image is
+# that one file on a base with nothing else in it: no shell, no package
+# manager. `kubectl exec ... -- llmgw ctl status` still works, because it
+# runs the binary rather than a shell.
+#
+# Only the control plane runs from it. An agent installs engines on its
+# machine, manages its GPUs and supervises processes there as root, which is
+# what a container is built to prevent: docs/kubernetes.md.
+
+FROM golang:1.26 AS build
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+ARG VERSION=dev
+RUN CGO_ENABLED=0 go build -trimpath \
+      -ldflags "-s -w -X gitea.mynodes.xyz/ilker/llmgw/internal/version.Version=${VERSION}" \
+      -o /out/llmgw ./cmd/llmgw && \
+    mkdir -p /out/state
+
+FROM gcr.io/distroless/static-debian12:nonroot
+COPY --from=build /out/llmgw /usr/local/bin/llmgw
+# The chart mounts server.yaml, the certificates and the token under
+# /etc/llmgw, and the SQLite store, when it is one, under /var/lib/llmgw —
+# owned by the user the server runs as, so a volume Docker fills from the
+# image is writable without Kubernetes' fsGroup.
+COPY --from=build --chown=65532:65532 /out/state /var/lib/llmgw
+USER 65532:65532
+EXPOSE 8080 7443 9091
+ENTRYPOINT ["/usr/local/bin/llmgw"]
+CMD ["server", "--config", "/etc/llmgw/server.yaml"]

deploy/eval/arithmetic.yaml

@@ -0,0 +1,58 @@
+# Arithmetic a small instruction model gets right: sums, products and a
+# little reading, each answer scored by the last number in it. A quantisation
+# that has gone wrong, or a chat template that no longer matches the
+# weights, shows up here as a falling score long before anyone notices it in
+# conversation.
+#
+#   llmgw ctl eval MODEL --suite arithmetic
+#   llmgw ctl model update MODEL --eval arithmetic --min-score 0.8
+#
+# Copy it into control.eval_dir (/etc/llmgw/eval) to change it; a suite
+# there of the same name replaces this one.
+name: arithmetic
+description: Sums, products and word problems, each scored by the number in its answer.
+threshold: 0.7
+system: You are a careful calculator. Answer with the number only, without words or units.
+max_tokens: 64
+cases:
+  - id: add-small
+    prompt: What is 17 + 25?
+    number: 42
+  - id: add-carry
+    prompt: What is 389 + 476?
+    number: 865
+  - id: subtract
+    prompt: What is 1000 - 357?
+    number: 643
+  - id: subtract-negative
+    prompt: What is 12 - 30?
+    number: -18
+  - id: multiply
+    prompt: What is 12 * 12?
+    number: 144
+  - id: multiply-larger
+    prompt: What is 23 * 17?
+    number: 391
+    weight: 2
+  - id: divide
+    prompt: What is 144 / 6?
+    number: 24
+  - id: decimal
+    prompt: What is 2.5 * 4?
+    number: 10
+  - id: percent
+    prompt: What is 15% of 200?
+    number: 30
+  - id: words-apples
+    prompt: Ana has 7 apples and buys 5 more, then gives 3 away. How many apples does she have?
+    number: 9
+    weight: 2
+  - id: words-time
+    prompt: A train leaves at 14:00 and the trip takes 150 minutes. How many hours does the trip take?
+    number: 2.5
+    tolerance: 0.01
+    weight: 2
+  - id: order-of-operations
+    prompt: What is 2 + 3 * 4?
+    number: 14
+    weight: 2

deploy/eval/json-format.yaml

@@ -0,0 +1,94 @@
+# Following a format: asked for JSON of a given shape, does the model give
+# it — the thing an application parsing its answers depends on, and the
+# first to go when a chat template drifts. Each answer is read as JSON (a
+# code fence or a sentence around it is forgiven) and held to a schema.
+#
+#   llmgw ctl eval MODEL --suite json-format
+#
+# Copy it into control.eval_dir (/etc/llmgw/eval) to change it; a suite
+# there of the same name replaces this one.
+name: json-format
+description: Answers asked for as JSON of a given shape, held to a schema.
+threshold: 0.7
+system: You answer with a single JSON value and nothing else.
+max_tokens: 200
+cases:
+  - id: person
+    prompt: >-
+      Give a JSON object for a person named Ada Lovelace, born in 1815, with the
+      keys "name" (a string) and "born" (a number).
+    json_schema:
+      type: object
+      required: [name, born]
+      properties:
+        name: {type: string, pattern: "Ada"}
+        born: {type: integer, minimum: 1815, maximum: 1815}
+
+  - id: list-of-colours
+    prompt: Give a JSON array of exactly three colour names, as strings.
+    json_schema:
+      type: array
+      minItems: 3
+      maxItems: 3
+      items: {type: string, minLength: 1}
+
+  - id: boolean-answer
+    prompt: >-
+      Is water wet? Answer as a JSON object with one key, "answer", whose
+      value is true or false.
+    json_schema:
+      type: object
+      required: [answer]
+      properties:
+        answer: {type: boolean}
+
+  - id: nested
+    prompt: >-
+      Give a JSON object describing a book: "title" (a string), "author" (an
+      object with "first" and "last", both strings) and "pages" (a whole number
+      above zero). Use any book.
+    json_schema:
+      type: object
+      required: [title, author, pages]
+      properties:
+        title: {type: string, minLength: 1}
+        author:
+          type: object
+          required: [first, last]
+          properties:
+            first: {type: string}
+            last: {type: string}
+        pages: {type: integer, exclusiveMinimum: 0}
+    weight: 2
+
+  - id: enum-choice
+    prompt: >-
+      Classify the sentence "I love this product!" as positive, negative or
+      neutral. Answer as a JSON object {"sentiment": "..."} using one of those
+      three words in lower case.
+    json_schema:
+      type: object
+      required: [sentiment]
+      properties:
+        sentiment: {enum: [positive]}
+    weight: 2
+
+  - id: numbers
+    prompt: 'Give a JSON object {"sum": N} where N is the sum of 4, 5 and 6.'
+    json_schema:
+      type: object
+      required: [sum]
+      properties:
+        sum: {const: 15}
+
+  - id: no-extra-keys
+    prompt: >-
+      Give a JSON object with exactly two keys, "city" and "country", for
+      Paris. No other keys.
+    json_schema:
+      type: object
+      required: [city, country]
+      additionalProperties: false
+      properties:
+        city: {type: string}
+        country: {type: string}

deploy/examples/server.yaml

@@ -17,8 +17,10 @@ agent_listen: ":7443"
 
 # Mutual TLS on the agent port (plan §5.6). With it, a node's identity is taken
 # from its certificate's common name and an agent claiming a different node id
-# is refused. Without it the port is plaintext HTTP/2 and anyone who can reach
-# it can claim to be any node, so it must stay on a trusted network.
+# is refused. Without it the port would be plaintext HTTP/2 and anyone who can
+# reach it could claim to be any node, so the control plane refuses to start
+# unless `agent_insecure: true` is set — and then listens on loopback unless
+# agent_listen names an address. That is for one machine or a test.
 #
 # These certificates come from llmgw's own authority, not a public one: public
 # authorities stopped issuing the clientAuth usage, so no Let's Encrypt
@@ -92,6 +94,11 @@ agent_listen: ":7443"
 #   flush_interval: 200ms
 #   batch_size: 500
 #   buffer_size: 8192
+#
+#   # How long the record of each request is kept (what `ctl request` reads).
+#   # Charts, totals and budgets come from five-minute sums that are kept, so
+#   # this only bounds the table that grows by a row a request. 0 keeps all.
+#   usage_retention: 2160h   # 90 days
 
 router:
   scrape_interval: 2s
@@ -152,6 +159,12 @@ router:
   # back to a client that did not ask for it.
   inject_usage: true
   max_body_bytes: 33554432
+  # Memory for the answers of projects that reuse them (llmgw keys cache),
+  # all together; the least recently used go first. Nothing is reused until a
+  # project turns it on.
+  # cache:
+  #   max_bytes: 134217728     # 128 MB
+  #   max_entry_bytes: 1048576 # 1 MB
 
   timeouts:
     dial: 5s

deploy/ha/README.md

@@ -85,3 +85,63 @@ auth:
 
 See [docs/install.md](../../docs/install.md) for moving an existing
 installation onto PostgreSQL without reissuing every key.
+
+## The store itself: PostgreSQL under Patroni
+
+Two control planes on one PostgreSQL have moved the single point of failure,
+not removed it. Patroni keeps PostgreSQL on two machines, one streaming to the
+other, and promotes the standby when the primary is lost. It keeps its leader
+lock in etcd, and etcd decides only with a majority — so three members, not
+two: two machines that lose sight of each other must not both decide they are
+the primary. The third member can be any machine that is up; it holds a vote,
+not data.
+
+On the reference cluster:
+
+| machine | etcd | PostgreSQL |
+|---|---|---|
+| llmgw-ctl (control plane) | member | — |
+| llmgw-pg01 | member | Patroni |
+| llmgw-ctl02 (second control plane) | member | Patroni |
+
+`llmgw server init --patroni user@host --patroni user@host` sets all of it up
+over ssh and moves the store in — see [install.md](../../docs/install.md).
+It looks before it acts at every step, so it is also how an existing cluster
+is checked: run against one that is up, it changes nothing. What it writes
+is in `etcd.default.example` (one member's `/etc/default/etcd`) and
+`patroni.yml.example` (one node's `/etc/patroni/config.yml`), for anyone
+doing it by hand; passwords are generated into `/root/llmgw-pg` on each
+database machine.
+
+**Give llmgw every member, and ask for the writable one:**
+
+```
+postgres://llmgw:…@10.0.0.149:5432,10.0.0.150:5432/llmgw?sslmode=disable&target_session_attrs=read-write
+```
+
+The driver connects to whichever member accepts writes, and reconnects to the
+new one after a failover. No floating address or HAProxy is needed for that.
+`llmgw server backup` reads the same address and dumps from a standby when
+there is one.
+
+Measured on the reference cluster, with the gateway serving throughout:
+
+- **Planned switchover** (`patronictl switchover`): the control plane logged
+  one failed lease renewal, reconnected to the new primary, and kept its
+  leadership; nothing else noticed.
+- **The primary's machine switched off**: the standby was promoted 24 seconds
+  later — the 30-second TTL in `patroni.yml` — and the control plane rode it
+  out without losing leadership or a replica. Started again, the old primary
+  rejoined as a standby by itself.
+
+**Watching it.** For a store of several hosts the control plane reads the
+cluster from each member's Patroni (port 8008) and publishes
+`llmgw_store_member{member,host,role,state}`, `llmgw_store_replica_lag_bytes`
+and `llmgw_store_patroni_up`; a host of the address that the cluster no longer
+lists is a member in state `missing`. `llmgw ctl status` prints it as one
+line, and `deploy/monitoring/llmgw-rules.yml` alerts on no leader, a member
+not streaming or missing, and a standby too far behind to be promoted.
+
+Not done here, and worth doing in production: a watchdog (`softdog`) so a
+primary that has lost the lock but not died cannot keep accepting writes, TLS
+on etcd and between PostgreSQL members, and more than one standby.

deploy/ha/etcd.default.example

@@ -0,0 +1,10 @@
+# llmgw: one member of the three that hold Patroni's leader lock (140, 149, 150).
+ETCD_NAME=llmgw-pg01
+ETCD_DATA_DIR=/var/lib/etcd/default
+ETCD_LISTEN_PEER_URLS=http://10.0.0.149:2380
+ETCD_LISTEN_CLIENT_URLS=http://10.0.0.149:2379,http://127.0.0.1:2379
+ETCD_INITIAL_ADVERTISE_PEER_URLS=http://10.0.0.149:2380
+ETCD_ADVERTISE_CLIENT_URLS=http://10.0.0.149:2379
+ETCD_INITIAL_CLUSTER=llmgw-ctl=http://10.0.0.140:2380,llmgw-pg01=http://10.0.0.149:2380,llmgw-ctl02=http://10.0.0.150:2380
+ETCD_INITIAL_CLUSTER_STATE=new
+ETCD_INITIAL_CLUSTER_TOKEN=llmgw-patroni

deploy/ha/patroni.yml.example

@@ -0,0 +1,68 @@
+# llmgw: the control planes' store, kept by Patroni on llmgw-pg01 and
+# llmgw-ctl02, with the leader lock in etcd on 140, 149 and 150.
+scope: llmgw
+namespace: /service/
+name: llmgw-pg01
+
+restapi:
+  listen: 10.0.0.149:8008
+  connect_address: 10.0.0.149:8008
+
+etcd3:
+  hosts: 10.0.0.140:2379,10.0.0.149:2379,10.0.0.150:2379
+
+bootstrap:
+  dcs:
+    ttl: 30
+    loop_wait: 10
+    retry_timeout: 10
+    maximum_lag_on_failover: 1048576
+    postgresql:
+      use_pg_rewind: true
+      use_slots: true
+      parameters:
+        wal_level: replica
+        hot_standby: "on"
+        max_wal_senders: 10
+        max_replication_slots: 10
+        wal_keep_size: 1GB
+        wal_log_hints: "on"
+        password_encryption: scram-sha-256
+  initdb:
+    - encoding: UTF8
+    - data-checksums
+
+postgresql:
+  listen: 127.0.0.1,10.0.0.149:5432
+  connect_address: 10.0.0.149:5432
+  data_dir: /var/lib/postgresql/16/llmgw
+  bin_dir: /usr/lib/postgresql/16/bin
+  pgpass: /var/lib/postgresql/.pgpass_patroni
+  authentication:
+    superuser:
+      username: postgres
+      password: "<from /root/llmgw-pg>"
+    replication:
+      username: replicator
+      password: "<from /root/llmgw-pg>"
+    rewind:
+      username: postgres
+      password: "<from /root/llmgw-pg>"
+  parameters:
+    unix_socket_directories: /var/run/postgresql
+  pg_hba:
+    - local all all peer
+    - host all all 127.0.0.1/32 scram-sha-256
+    - host replication replicator 10.0.0.149/32 scram-sha-256
+    - host replication replicator 10.0.0.150/32 scram-sha-256
+    - host all postgres 10.0.0.149/32 scram-sha-256
+    - host all postgres 10.0.0.150/32 scram-sha-256
+    - host llmgw llmgw 10.0.0.140/32 scram-sha-256
+    - host llmgw llmgw 10.0.0.149/32 scram-sha-256
+    - host llmgw llmgw 10.0.0.150/32 scram-sha-256
+
+tags:
+  nofailover: false
+  noloadbalance: false
+  clonefrom: false
+  nosync: false

deploy/helm/llmgw/Chart.yaml

@@ -0,0 +1,17 @@
+apiVersion: v2
+name: llmgw
+description: >-
+  The llmgw control plane — the OpenAI-compatible gateway, the router and the
+  scheduler that places models on GPU and CPU nodes. The nodes themselves run
+  outside Kubernetes; see docs/kubernetes.md.
+type: application
+# The chart's own version; appVersion is the llmgw release the image holds.
+version: 0.1.0
+appVersion: "v0.11.1"
+home: https://gitea.mynodes.xyz/ilker/llmgw
+sources:
+  - https://gitea.mynodes.xyz/ilker/llmgw
+keywords:
+  - llm
+  - gateway
+  - inference

deploy/helm/llmgw/templates/NOTES.txt

@@ -0,0 +1,27 @@
+The llmgw control plane is starting as {{ include "llmgw.fullname" . }}.
+
+The admin API listens on the pod's loopback only. To reach it from here:
+
+  kubectl -n {{ .Release.Namespace }} port-forward statefulset/{{ include "llmgw.fullname" . }} 9090:9090 &
+  export LLMGW_ADMIN_TOKEN=$(kubectl -n {{ .Release.Namespace }} get secret {{ include "llmgw.adminSecret" . }} \
+    -o jsonpath='{.data.{{ if .Values.adminToken.existingSecret }}{{ .Values.adminToken.secretKey }}{{ else }}admin-token{{ end }}}' | base64 -d)
+  llmgw ctl status
+
+The first administrator:
+
+  kubectl -n {{ .Release.Namespace }} exec -it statefulset/{{ include "llmgw.fullname" . }} -- \
+    llmgw users create you@example.com --password '<a password>'
+  kubectl -n {{ .Release.Namespace }} exec -it statefulset/{{ include "llmgw.fullname" . }} -- \
+    llmgw users role you@example.com admin
+
+Agents connect to the {{ include "llmgw.fullname" . }}-agents Service on port {{ .Values.agentService.port }}:
+
+  kubectl -n {{ .Release.Namespace }} get service {{ include "llmgw.fullname" . }}-agents
+
+Its address must be in the certificate in {{ .Values.agentTLS.existingSecret }}. Nodes join from
+the machine holding llmgw's authority:
+
+  sudo llmgw node add ubuntu@gpu01 --server https://<that address>:{{ .Values.agentService.port }} \
+    --pki ./pki --admin 127.0.0.1:9090
+
+docs/kubernetes.md has the rest, and why the nodes stay outside Kubernetes.

deploy/helm/llmgw/templates/_helpers.tpl

@@ -0,0 +1,74 @@
+{{/* The release's name for everything the chart makes. */}}
+{{- define "llmgw.fullname" -}}
+{{- if contains .Chart.Name .Release.Name -}}
+{{- .Release.Name | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+{{- end -}}
+
+{{- define "llmgw.selectorLabels" -}}
+app.kubernetes.io/name: {{ .Chart.Name }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end -}}
+
+{{- define "llmgw.labels" -}}
+{{ include "llmgw.selectorLabels" . }}
+app.kubernetes.io/version: {{ .Values.image.tag | default .Chart.AppVersion | quote }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" }}
+{{- end -}}
+
+{{- define "llmgw.image" -}}
+{{- if not .Values.image.repository -}}
+{{- fail "image.repository: the image built from deploy/container/Dockerfile, pushed where the cluster can pull it (the project publishes binaries, not an image)" -}}
+{{- end -}}
+{{- printf "%s:%s" .Values.image.repository (.Values.image.tag | default .Chart.AppVersion) -}}
+{{- end -}}
+
+{{- define "llmgw.adminSecret" -}}
+{{- .Values.adminToken.existingSecret | default (printf "%s-admin" (include "llmgw.fullname" .)) -}}
+{{- end -}}
+
+{{/*
+server.yaml: what the chart decides — listeners, where the certificates,
+the token and the store are mounted — laid over .Values.config. The chart's
+keys win, because each names a port or a path the pod is built around.
+*/}}
+{{- define "llmgw.serverConfig" -}}
+{{- $store := "/var/lib/llmgw/llmgw.db" -}}
+{{- if eq .Values.store.type "postgres" -}}
+{{- $store = "@/etc/llmgw/store/dsn" -}}
+{{- end -}}
+{{- $base := dict
+  "listen" ":8080"
+  "admin_listen" "127.0.0.1:9090"
+  "metrics_listen" ":9091"
+  "agent_listen" ":7443"
+  "admin_token_file" "/etc/llmgw/admin/admin-token"
+  "agent_tls" (dict "ca" "/etc/llmgw/tls/ca.pem" "cert" "/etc/llmgw/tls/server.pem" "key" "/etc/llmgw/tls/server-key.pem")
+  "auth" (dict "store" $store)
+-}}
+{{- if .Values.offlineChecksums.configMap -}}
+{{- $_ := set $base "offline" (dict "checksums" "/etc/llmgw/offline/offline.sha256") -}}
+{{- end -}}
+{{- $cfg := mustMergeOverwrite (deepCopy (.Values.config | default dict)) $base -}}
+# Made by the llmgw Helm chart from its values. Every key: docs/reference.md
+{{ toYaml $cfg }}
+{{- end -}}
+
+{{/* Refuses values that would make a pod that cannot work. */}}
+{{- define "llmgw.validate" -}}
+{{- if not (has .Values.store.type (list "sqlite" "postgres")) -}}
+{{- fail (printf "store.type %q: sqlite or postgres" .Values.store.type) -}}
+{{- end -}}
+{{- if ne (int .Values.replicas) 1 -}}
+{{- fail "replicas: this chart runs one control plane; values.yaml says why" -}}
+{{- end -}}
+{{- if and (eq .Values.store.type "postgres") (not .Values.store.postgres.existingSecret) -}}
+{{- fail "store.postgres.existingSecret: a Secret holding the PostgreSQL address" -}}
+{{- end -}}
+{{- if not .Values.agentTLS.existingSecret -}}
+{{- fail "agentTLS.existingSecret: a Secret with ca.pem, server.pem and server-key.pem from llmgw's authority (see values.yaml)" -}}
+{{- end -}}
+{{- end -}}

deploy/helm/llmgw/templates/configmap.yaml

@@ -0,0 +1,10 @@
+{{- include "llmgw.validate" . -}}
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ include "llmgw.fullname" . }}
+  labels:
+    {{- include "llmgw.labels" . | nindent 4 }}
+data:
+  server.yaml: |
+    {{- include "llmgw.serverConfig" . | nindent 4 }}

deploy/helm/llmgw/templates/ingress.yaml

@@ -0,0 +1,37 @@
+{{- if .Values.ingress.enabled }}
+# The OpenAI-compatible API, the portal and the chat page on port 8080. Never
+# the agent port: its mutual TLS cannot pass through an HTTP proxy.
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: {{ include "llmgw.fullname" . }}
+  labels:
+    {{- include "llmgw.labels" . | nindent 4 }}
+  {{- with .Values.ingress.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  {{- with .Values.ingress.className }}
+  ingressClassName: {{ . }}
+  {{- end }}
+  {{- with .Values.ingress.tls }}
+  tls:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+  rules:
+    {{- range .Values.ingress.hosts }}
+    - host: {{ .host | quote }}
+      http:
+        paths:
+          {{- range .paths }}
+          - path: {{ .path }}
+            pathType: {{ .pathType }}
+            backend:
+              service:
+                name: {{ include "llmgw.fullname" $ }}
+                port:
+                  name: api
+          {{- end }}
+    {{- end }}
+{{- end }}

deploy/helm/llmgw/templates/secret-admin.yaml

@@ -0,0 +1,19 @@
+{{- if not .Values.adminToken.existingSecret }}
+{{- $name := include "llmgw.adminSecret" . }}
+{{- $token := randAlphaNum 64 }}
+{{- /* Kept across upgrades: a new token on every upgrade would lock out every console holding the old one. */}}
+{{- with lookup "v1" "Secret" .Release.Namespace $name }}
+{{- $token = index .data "admin-token" | b64dec }}
+{{- end }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ $name }}
+  labels:
+    {{- include "llmgw.labels" . | nindent 4 }}
+  annotations:
+    helm.sh/resource-policy: keep
+type: Opaque
+data:
+  admin-token: {{ $token | b64enc | quote }}
+{{- end }}

deploy/helm/llmgw/templates/servicemonitor.yaml

@@ -0,0 +1,21 @@
+{{- if .Values.serviceMonitor.enabled }}
+# For the Prometheus Operator: the metrics port, which serves metrics and
+# nothing else. deploy/monitoring holds the rules and dashboards that read them.
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: {{ include "llmgw.fullname" . }}
+  labels:
+    {{- include "llmgw.labels" . | nindent 4 }}
+    {{- with .Values.serviceMonitor.labels }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+spec:
+  selector:
+    matchLabels:
+      {{- include "llmgw.selectorLabels" . | nindent 6 }}
+  endpoints:
+    - port: metrics
+      path: /metrics
+      interval: {{ .Values.serviceMonitor.interval }}
+{{- end }}

deploy/helm/llmgw/templates/services.yaml

@@ -0,0 +1,70 @@
+# The API and the metrics, for the cluster and an Ingress.
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "llmgw.fullname" . }}
+  labels:
+    {{- include "llmgw.labels" . | nindent 4 }}
+  {{- with .Values.service.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  type: {{ .Values.service.type }}
+  selector:
+    {{- include "llmgw.selectorLabels" . | nindent 4 }}
+  ports:
+    - name: api
+      port: {{ .Values.service.port }}
+      targetPort: api
+    - name: metrics
+      port: {{ .Values.service.metricsPort }}
+      targetPort: metrics
+---
+# Where agents on the nodes connect. Mutual TLS ends in the pod: whatever is
+# in between must pass TCP through untouched.
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "llmgw.fullname" . }}-agents
+  labels:
+    {{- include "llmgw.labels" . | nindent 4 }}
+  {{- with .Values.agentService.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  type: {{ .Values.agentService.type }}
+  {{- if and (eq .Values.agentService.type "LoadBalancer") .Values.agentService.loadBalancerIP }}
+  loadBalancerIP: {{ .Values.agentService.loadBalancerIP }}
+  {{- end }}
+  {{- with .Values.agentService.loadBalancerSourceRanges }}
+  loadBalancerSourceRanges:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+  {{- if has .Values.agentService.type (list "LoadBalancer" "NodePort") }}
+  externalTrafficPolicy: {{ .Values.agentService.externalTrafficPolicy }}
+  {{- end }}
+  selector:
+    {{- include "llmgw.selectorLabels" . | nindent 4 }}
+  ports:
+    - name: agents
+      port: {{ .Values.agentService.port }}
+      targetPort: agents
+---
+# The StatefulSet's own, giving each pod a stable name.
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "llmgw.fullname" . }}-headless
+  labels:
+    {{- include "llmgw.labels" . | nindent 4 }}
+spec:
+  clusterIP: None
+  publishNotReadyAddresses: true
+  selector:
+    {{- include "llmgw.selectorLabels" . | nindent 4 }}
+  ports:
+    - name: api
+      port: 8080
+      targetPort: api

deploy/helm/llmgw/templates/statefulset.yaml

@@ -0,0 +1,181 @@
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: {{ include "llmgw.fullname" . }}
+  labels:
+    {{- include "llmgw.labels" . | nindent 4 }}
+spec:
+  # One control plane: Kubernetes replaces it within seconds when it goes,
+  # and the agents reconnect on their own. See replicas in values.yaml.
+  replicas: 1
+  serviceName: {{ include "llmgw.fullname" . }}-headless
+  selector:
+    matchLabels:
+      {{- include "llmgw.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+      labels:
+        {{- include "llmgw.selectorLabels" . | nindent 8 }}
+        {{- with .Values.podLabels }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+      annotations:
+        # server.yaml is read at start: a changed one restarts the pod.
+        checksum/config: {{ include "llmgw.serverConfig" . | sha256sum }}
+        {{- with .Values.podAnnotations }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+    spec:
+      {{- with .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      # Agents reconnect within seconds of a control plane going; a long
+      # grace period only delays the one that replaces it.
+      terminationGracePeriodSeconds: 30
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 65532
+        runAsGroup: 65532
+        fsGroup: 65532
+        seccompProfile:
+          type: RuntimeDefault
+      containers:
+        - name: llmgw
+          image: {{ include "llmgw.image" . }}
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          args: ["server", "--config", "/etc/llmgw/server.yaml"]
+          env:
+            # For `kubectl exec ... -- llmgw ctl`, which reads the token
+            # from here; the server reads admin_token_file.
+            - name: LLMGW_ADMIN_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "llmgw.adminSecret" . }}
+                  key: {{ if .Values.adminToken.existingSecret }}{{ .Values.adminToken.secretKey }}{{ else }}admin-token{{ end }}
+          ports:
+            - name: api
+              containerPort: 8080
+            - name: agents
+              containerPort: 7443
+            - name: metrics
+              containerPort: 9091
+          # Up is /health. Ready is /leader: a control plane holds the
+          # agents' connections and places models only once it leads — on
+          # PostgreSQL, once the lease of the one it replaced has run out. A
+          # cluster with no node yet is still ready: /ready would wait for a
+          # replica, and nodes could then never connect.
+          startupProbe:
+            httpGet: {path: /health, port: api}
+            periodSeconds: 5
+            failureThreshold: 60
+          livenessProbe:
+            httpGet: {path: /health, port: api}
+            periodSeconds: 10
+            failureThreshold: 6
+          readinessProbe:
+            httpGet: {path: /leader, port: api}
+            periodSeconds: 5
+            failureThreshold: 2
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop: ["ALL"]
+          resources:
+            {{- toYaml .Values.resources | nindent 12 }}
+          volumeMounts:
+            - name: config
+              mountPath: /etc/llmgw/server.yaml
+              subPath: server.yaml
+              readOnly: true
+            - name: agent-tls
+              mountPath: /etc/llmgw/tls
+              readOnly: true
+            - name: admin-token
+              mountPath: /etc/llmgw/admin
+              readOnly: true
+            {{- if eq .Values.store.type "postgres" }}
+            - name: store
+              mountPath: /etc/llmgw/store
+              readOnly: true
+            {{- end }}
+            {{- if .Values.offlineChecksums.configMap }}
+            - name: offline
+              mountPath: /etc/llmgw/offline
+              readOnly: true
+            {{- end }}
+            - name: data
+              mountPath: /var/lib/llmgw
+            - name: tmp
+              mountPath: /tmp
+      volumes:
+        - name: config
+          configMap:
+            name: {{ include "llmgw.fullname" . }}
+        - name: agent-tls
+          secret:
+            secretName: {{ .Values.agentTLS.existingSecret }}
+            defaultMode: 0440
+            items:
+              - {key: ca.pem, path: ca.pem}
+              - {key: server.pem, path: server.pem}
+              - {key: server-key.pem, path: server-key.pem}
+        - name: admin-token
+          secret:
+            secretName: {{ include "llmgw.adminSecret" . }}
+            defaultMode: 0440
+            items:
+              - key: {{ if .Values.adminToken.existingSecret }}{{ .Values.adminToken.secretKey }}{{ else }}admin-token{{ end }}
+                path: admin-token
+        {{- if eq .Values.store.type "postgres" }}
+        - name: store
+          secret:
+            secretName: {{ .Values.store.postgres.existingSecret }}
+            defaultMode: 0440
+            items:
+              - key: {{ .Values.store.postgres.secretKey }}
+                path: dsn
+        {{- end }}
+        {{- if .Values.offlineChecksums.configMap }}
+        - name: offline
+          configMap:
+            name: {{ .Values.offlineChecksums.configMap }}
+            items:
+              - key: {{ .Values.offlineChecksums.key }}
+                path: offline.sha256
+        {{- end }}
+        - name: tmp
+          emptyDir: {}
+        {{- if eq .Values.store.type "postgres" }}
+        # The store is PostgreSQL; nothing here outlives the pod.
+        - name: data
+          emptyDir: {}
+        {{- end }}
+      {{- with .Values.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+  {{- if eq .Values.store.type "sqlite" }}
+  volumeClaimTemplates:
+    - metadata:
+        name: data
+        labels:
+          {{- include "llmgw.selectorLabels" . | nindent 10 }}
+      spec:
+        accessModes: ["ReadWriteOnce"]
+        {{- with .Values.store.sqlite.storageClass }}
+        storageClassName: {{ . }}
+        {{- end }}
+        resources:
+          requests:
+            storage: {{ .Values.store.sqlite.size }}
+  {{- end }}

deploy/helm/llmgw/values.yaml

@@ -0,0 +1,132 @@
+# The llmgw control plane in Kubernetes. docs/kubernetes.md says what this
+# runs, what it does not, and how nodes outside the cluster join it.
+
+image:
+  # Where you pushed the image built from deploy/container/Dockerfile. The
+  # project publishes binaries, not an image, so this has no default.
+  repository: ""
+  # Empty takes the chart's appVersion.
+  tag: ""
+  pullPolicy: IfNotPresent
+imagePullSecrets: []
+
+# One control plane, always. Two against PostgreSQL would elect a leader and
+# keep a standby, but a standby serves nothing and is never ready, so a
+# rollout would wait on it for ever. Until the chart handles that, it runs
+# one: Kubernetes replaces it within seconds when it goes, and the agents
+# reconnect on their own.
+replicas: 1
+
+store:
+  # sqlite: a file on a PersistentVolumeClaim, for one replica.
+  # postgres: a PostgreSQL you run, its address in a Secret.
+  type: sqlite
+  sqlite:
+    size: 10Gi
+    storageClass: ""
+  postgres:
+    # A Secret holding the address, postgres://user:password@host:5432/llmgw?sslmode=verify-full
+    existingSecret: ""
+    secretKey: dsn
+
+# The agent port's certificate. It comes from llmgw's own authority, not a
+# public one — agents present certificates from the same authority — so it
+# is made outside the cluster, where the authority's key stays:
+#
+#   llmgw ctl cert init-ca --dir ./pki
+#   llmgw ctl cert issue-server llmgw-ctl --host <agent address> --dir ./pki --out ./pki
+#   kubectl create secret generic llmgw-agent-tls \
+#     --from-file=ca.pem=pki/ca.pem \
+#     --from-file=server.pem=pki/server.pem \
+#     --from-file=server-key.pem=pki/server-key.pem
+#
+# --host is every address agents dial: agentService's load balancer address
+# or DNS name.
+agentTLS:
+  existingSecret: ""
+
+# The admin API's token (llmgw ctl, the console). Empty makes one, kept in a
+# Secret across upgrades.
+adminToken:
+  existingSecret: ""
+  secretKey: admin-token
+
+# server.yaml beyond what the chart sets (listeners, TLS, store, admin
+# token): any key of docs/reference.md, laid over the chart's. An offline
+# cluster sets offline.mirror here, and offlineChecksums below.
+config:
+  control:
+    enabled: true
+  auth:
+    enabled: true
+    signup_open: false
+    default_rpm: 60
+    default_tpm: 200000
+    default_price:
+      prompt_per_1k: 1000
+      completion_per_1k: 1000
+    max_key_ttl: 2160h
+  # mirror:
+  #   api: https://models.internal:8082
+  # offline:
+  #   mirror: http://models.internal:8081
+  # firewall_networks: ["10.42.0.0/16"]   # the pods' network, so nodes' engines answer the router
+
+# On an offline cluster, a ConfigMap or Secret holding the engine checksums
+# 'llmgw bundle trust' writes (offline.sha256), mounted where offline.checksums
+# points. Empty mounts none.
+offlineChecksums:
+  configMap: ""
+  key: offline.sha256
+
+# The OpenAI-compatible API and the metrics, inside the cluster.
+service:
+  type: ClusterIP
+  port: 8080
+  metricsPort: 9091
+  annotations: {}
+
+# Where agents connect, with mutual TLS. Nodes run outside the cluster, so
+# this is a load balancer by default; the TLS ends in the pod, never at a
+# proxy in between.
+agentService:
+  type: LoadBalancer
+  port: 7443
+  annotations: {}
+  loadBalancerIP: ""
+  loadBalancerSourceRanges: []
+  # Keeps the agents' addresses as they are, which the node's identity does
+  # not need but the logs and the audit read better with.
+  externalTrafficPolicy: Local
+
+ingress:
+  enabled: false
+  className: ""
+  annotations: {}
+  hosts:
+    - host: llm.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+  tls: []
+  #  - secretName: llm-example-com
+  #    hosts: [llm.example.com]
+
+# A ServiceMonitor for the Prometheus Operator, scraping the metrics port.
+serviceMonitor:
+  enabled: false
+  interval: 30s
+  labels: {}
+
+resources:
+  requests:
+    cpu: 500m
+    memory: 512Mi
+  limits:
+    memory: 2Gi
+
+nodeSelector: {}
+tolerations: []
+affinity: {}
+podAnnotations: {}
+podLabels: {}

deploy/mirror/README.md

@@ -25,6 +25,13 @@ An HTTP server serving a directory. That is the whole design.
       model.safetensors
 ```
 
+At an offline site the mirror also holds what the nodes would otherwise fetch
+from the internet — llmgw's releases and the llama.cpp builds — under
+`_llmgw/releases/` and `_llmgw/engines/`, put there by `llmgw bundle import`
+(docs/install.md, "Offline sites"). They are not models: `mirror list` and
+`mirror unused` pass over them, and a node checks each against what the
+control plane says it must be, not against anything the mirror says.
+
 The date in the path is the point of the layout, not decoration. A model
 repository that changes upstream changes what you are running, and the first
 sign is a prompt that worked last week answering differently this week with
@@ -65,9 +72,13 @@ hand it certificates:
 llmgw mirror serve --dir /srv/models --base http://models.internal:8081 \
   --tls-ca /etc/llmgw/ca.pem \
   --tls-cert /etc/llmgw/mirror.pem \
-  --tls-key /etc/llmgw/mirror-key.pem
+  --tls-key /etc/llmgw/mirror-key.pem \
+  --api-client control-plane
 ```
 
+`--api-client` is required with `--tls-ca`: it names the one certificate the
+API answers, because the CA signs every node's certificate as well.
+
 That is the same CA the agents already use, so the certificates come from the
 authority you have:
 

deploy/monitoring/README.md

@@ -66,6 +66,8 @@ install -m 0644 grafana/datasource.yaml   /etc/grafana/provisioning/datasources/
 install -m 0644 grafana/dashboards.yaml   /etc/grafana/provisioning/dashboards/llmgw.yaml
 install -m 0644 -o grafana -g grafana grafana/llmgw-overview.json \
     /var/lib/grafana/dashboards/llmgw.json
+install -m 0644 -o grafana -g grafana grafana/llmgw-tenants.json \
+    /var/lib/grafana/dashboards/llmgw-tenants.json
 systemctl restart grafana-server
 ```
 

deploy/monitoring/alertmanager.yml

@@ -1,10 +1,11 @@
 # Alertmanager for the llmgw cluster.
 #
-# Nothing is sent anywhere yet, on purpose. Where an alert should go — an
+# Nothing is sent anywhere until a receiver is chosen, on purpose. 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 group and fire here and are
-# visible at :9093 and in Prometheus; add a receiver below to make them travel.
+# visible at :9093 and in Prometheus; uncomment a receiver template below and
+# name it on the route to make them travel.
 global:
   resolve_timeout: 5m
 
@@ -31,6 +32,53 @@ route:
 receivers:
   - name: none
 
+  # Receiver templates. Uncomment one, fill in where it goes, and name it in
+  # `receiver:` above — on the route, the critical branch, or both. Secrets go
+  # in files Alertmanager reads (the *_file settings), mode 0640 owned by
+  # root:prometheus, not in this file. `amtool check-config` before a restart.
+  #
+  # Slack (an incoming webhook):
+  # - name: slack
+  #   slack_configs:
+  #     - api_url_file: /etc/prometheus/slack-webhook-url
+  #       channel: '#llmgw'
+  #       send_resolved: true
+  #       title: '{{ .Status | toUpper }}: {{ .CommonLabels.alertname }}'
+  #       text: >-
+  #         {{ range .Alerts }}{{ .Annotations.summary }}
+  #         {{ .Annotations.description }}
+  #         {{ end }}
+  #
+  # E-mail (through a relay that takes authenticated submission):
+  # - name: email
+  #   email_configs:
+  #     - to: ops@example.com
+  #       from: llmgw-alerts@example.com
+  #       smarthost: smtp.example.com:587
+  #       auth_username: llmgw-alerts@example.com
+  #       auth_password_file: /etc/prometheus/smtp-password
+  #       send_resolved: true
+  #
+  # PagerDuty (Events API v2), for the critical branch — what should wake
+  # someone:
+  # - name: pagerduty
+  #   pagerduty_configs:
+  #     - routing_key_file: /etc/prometheus/pagerduty-routing-key
+  #       severity: '{{ .CommonLabels.severity }}'
+  #       description: '{{ .CommonAnnotations.summary }}'
+  #
+  # A webhook of your own (Alertmanager's JSON, version 4):
+  # - name: webhook
+  #   webhook_configs:
+  #     - url_file: /etc/prometheus/alert-webhook-url
+  #       send_resolved: true
+  #       max_alerts: 20
+  #
+  # The gateway itself also sends a few events straight to webhooks, with no
+  # Prometheus in between — a model parked, a node lost, a budget spent, new
+  # weights published: `notify.webhooks` in server.yaml (docs/install.md,
+  # "Being told").
+
 inhibit_rules:
   # A node that is down explains every replica on it. Reporting both says the
   # same thing twice and buries whichever is the actual cause.

deploy/monitoring/grafana/llmgw-overview.json

@@ -487,6 +487,427 @@
         "defaults": {},
         "overrides": []
       }
+    },
+    {
+      "type": "row",
+      "title": "GPUs",
+      "id": 14,
+      "gridPos": {
+        "x": 0,
+        "y": 30,
+        "w": 24,
+        "h": 1
+      },
+      "collapsed": false,
+      "panels": []
+    },
+    {
+      "type": "timeseries",
+      "title": "GPU busy, by card",
+      "description": "Share of each sample period a kernel was running, sampled every heartbeat.",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "gridPos": {
+        "x": 0,
+        "y": 31,
+        "w": 12,
+        "h": 7
+      },
+      "id": 15,
+      "targets": [
+        {
+          "expr": "llmgw_gpu_utilization_percent",
+          "legendFormat": "{{node}} gpu {{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent",
+          "min": 0,
+          "max": 100
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "GPU memory in use, by card",
+      "description": "Framebuffer in use. Engines reserve most of it at start.",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "gridPos": {
+        "x": 12,
+        "y": 31,
+        "w": 12,
+        "h": 7
+      },
+      "id": 16,
+      "targets": [
+        {
+          "expr": "llmgw_gpu_memory_used_bytes / llmgw_gpu_memory_total_bytes",
+          "legendFormat": "{{node}} gpu {{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit",
+          "min": 0,
+          "max": 1
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "GPU memory bandwidth busy, by card",
+      "description": "Decode is bound by memory: high here with compute low is a card waiting on memory.",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "gridPos": {
+        "x": 0,
+        "y": 38,
+        "w": 12,
+        "h": 7
+      },
+      "id": 17,
+      "targets": [
+        {
+          "expr": "llmgw_gpu_memory_utilization_percent",
+          "legendFormat": "{{node}} gpu {{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percent",
+          "min": 0,
+          "max": 100
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "GPU temperature",
+      "description": "Throttling usually starts in the high 80s.",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "gridPos": {
+        "x": 12,
+        "y": 38,
+        "w": 12,
+        "h": 7
+      },
+      "id": 18,
+      "targets": [
+        {
+          "expr": "llmgw_gpu_temperature_celsius",
+          "legendFormat": "{{node}} gpu {{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "celsius"
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "GPU power against its limit",
+      "description": "1 is the enforced limit; a card held there is power-capped.",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "gridPos": {
+        "x": 0,
+        "y": 45,
+        "w": 12,
+        "h": 7
+      },
+      "id": 19,
+      "targets": [
+        {
+          "expr": "llmgw_gpu_power_watts / llmgw_gpu_power_limit_watts",
+          "legendFormat": "{{node}} gpu {{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit",
+          "min": 0,
+          "max": 1.1
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "GPU clock",
+      "description": "A clock held low under load is the card throttled; see the next panel for why.",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "gridPos": {
+        "x": 12,
+        "y": 45,
+        "w": 12,
+        "h": 7
+      },
+      "id": 20,
+      "targets": [
+        {
+          "expr": "llmgw_gpu_sm_clock_mhz",
+          "legendFormat": "{{node}} gpu {{gpu}}",
+          "refId": "A"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "rotmhz"
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "What holds GPUs back",
+      "description": "Cards throttled now, by reason, and uncorrected ECC errors since the driver loaded.",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "gridPos": {
+        "x": 0,
+        "y": 52,
+        "w": 24,
+        "h": 7
+      },
+      "id": 21,
+      "targets": [
+        {
+          "expr": "sum by (reason) (llmgw_gpu_throttled)",
+          "legendFormat": "throttled: {{reason}}",
+          "refId": "A"
+        },
+        {
+          "expr": "sum by (node, gpu) (llmgw_gpu_ecc_errors)",
+          "legendFormat": "ECC errors {{node}} gpu {{gpu}}",
+          "refId": "B"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short"
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "Output tokens/s per GPU, by model",
+      "description": "What each model gets out of each card it holds.",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "gridPos": {
+        "x": 0,
+        "y": 59,
+        "w": 12,
+        "h": 7
+      },
+      "id": 22,
+      "targets": [
+        {
+          "expr": "sum by (model) (rate(llmgw_tokens_total{direction=\"completion\"}[5m])) / count by (model) (llmgw_gpu_assigned)",
+          "legendFormat": "{{model}}",
+          "refId": "A"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short"
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "Output tokens per watt-hour, by model",
+      "description": "Tokens for the energy the model's cards draw.",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "gridPos": {
+        "x": 12,
+        "y": 59,
+        "w": 12,
+        "h": 7
+      },
+      "id": 23,
+      "targets": [
+        {
+          "expr": "sum by (model) (rate(llmgw_tokens_total{direction=\"completion\"}[5m])) * 3600 / sum by (model) (llmgw_gpu_power_watts * on (node, gpu) group_left (model) llmgw_gpu_assigned)",
+          "legendFormat": "{{model}}",
+          "refId": "A"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short"
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "GPU wear",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "id": 24,
+      "description": "What wears cards out: XID errors in the last 15 minutes, memory rows remapped, PCIe retries an hour. Anything above zero here is worth a look on that card's node page.",
+      "gridPos": {
+        "x": 0,
+        "y": 66,
+        "w": 24,
+        "h": 7
+      },
+      "targets": [
+        {
+          "expr": "increase(llmgw_gpu_xid_errors[15m]) > 0",
+          "legendFormat": "XID {{node}} gpu {{gpu}}",
+          "refId": "A"
+        },
+        {
+          "expr": "sum by (node, gpu) (llmgw_gpu_remapped_rows) > 0",
+          "legendFormat": "rows remapped {{node}} gpu {{gpu}}",
+          "refId": "B"
+        },
+        {
+          "expr": "increase(llmgw_gpu_pcie_replays[1h]) > 0",
+          "legendFormat": "PCIe retries/h {{node}} gpu {{gpu}}",
+          "refId": "C"
+        },
+        {
+          "expr": "increase(llmgw_gpu_nvlink_errors[1h]) > 0",
+          "legendFormat": "NVLink {{kind}}/h {{node}} gpu {{gpu}}",
+          "refId": "D"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short"
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "list",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "multi"
+        }
+      }
     }
   ]
 }

deploy/monitoring/grafana/llmgw-tenants.json

@@ -0,0 +1,650 @@
+{
+  "uid": "llmgw-tenants",
+  "title": "llmgw \u2014 tenants",
+  "schemaVersion": 39,
+  "version": 1,
+  "editable": true,
+  "time": {
+    "from": "now-24h",
+    "to": "now"
+  },
+  "refresh": "1m",
+  "tags": [
+    "llmgw"
+  ],
+  "description": "Requests, tokens, failures, refusals and first-token time per tenant \u2014 the level router.tenant_label names \u2014 and every budget's share spent.",
+  "templating": {
+    "list": [
+      {
+        "name": "tenant",
+        "label": "Tenant",
+        "type": "query",
+        "datasource": {
+          "type": "prometheus",
+          "uid": "llmgw-prom"
+        },
+        "query": {
+          "query": "label_values(llmgw_tenant_requests_total, tenant)",
+          "refId": "tenant"
+        },
+        "definition": "label_values(llmgw_tenant_requests_total, tenant)",
+        "multi": true,
+        "includeAll": true,
+        "allValue": ".*",
+        "current": {
+          "text": "All",
+          "value": "$__all"
+        },
+        "refresh": 2,
+        "sort": 1
+      }
+    ]
+  },
+  "panels": [
+    {
+      "id": 1,
+      "title": "Requests a second",
+      "type": "stat",
+      "description": "Across the tenants chosen above.",
+      "gridPos": {
+        "x": 0,
+        "y": 0,
+        "w": 6,
+        "h": 4
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum(rate(llmgw_tenant_requests_total{tenant=~\"$tenant\"}[5m]))",
+          "legendFormat": "",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "reqps"
+        },
+        "overrides": []
+      },
+      "options": {
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "textMode": "auto",
+        "colorMode": "value"
+      }
+    },
+    {
+      "id": 2,
+      "title": "Failing",
+      "type": "stat",
+      "description": "Requests that failed, not counting refusals by a limit.",
+      "gridPos": {
+        "x": 6,
+        "y": 0,
+        "w": 6,
+        "h": 4
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum(rate(llmgw_tenant_requests_total{tenant=~\"$tenant\",outcome=\"error\"}[5m])) / sum(rate(llmgw_tenant_requests_total{tenant=~\"$tenant\"}[5m]))",
+          "legendFormat": "",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit",
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "orange",
+                "value": 0.02
+              },
+              {
+                "color": "red",
+                "value": 0.05
+              }
+            ]
+          }
+        },
+        "overrides": []
+      },
+      "options": {
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "textMode": "auto",
+        "colorMode": "value"
+      }
+    },
+    {
+      "id": 3,
+      "title": "Refused by a limit",
+      "type": "stat",
+      "description": "Rate, token and budget limits; 429 to the caller.",
+      "gridPos": {
+        "x": 12,
+        "y": 0,
+        "w": 6,
+        "h": 4
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum(rate(llmgw_tenant_requests_total{tenant=~\"$tenant\",outcome=\"limited\"}[5m])) / sum(rate(llmgw_tenant_requests_total{tenant=~\"$tenant\"}[5m]))",
+          "legendFormat": "",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit",
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "orange",
+                "value": 0.02
+              },
+              {
+                "color": "red",
+                "value": 0.1
+              }
+            ]
+          }
+        },
+        "overrides": []
+      },
+      "options": {
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "textMode": "auto",
+        "colorMode": "value"
+      }
+    },
+    {
+      "id": 4,
+      "title": "First token, p95",
+      "type": "stat",
+      "description": "What people wait for before anything appears.",
+      "gridPos": {
+        "x": 18,
+        "y": 0,
+        "w": 6,
+        "h": 4
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "histogram_quantile(0.95, sum by (le) (rate(llmgw_tenant_ttft_seconds_bucket{tenant=~\"$tenant\"}[5m])))",
+          "legendFormat": "",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "s",
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "orange",
+                "value": 3
+              },
+              {
+                "color": "red",
+                "value": 10
+              }
+            ]
+          }
+        },
+        "overrides": []
+      },
+      "options": {
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "textMode": "auto",
+        "colorMode": "value"
+      }
+    },
+    {
+      "id": 5,
+      "title": "Requests by tenant",
+      "type": "timeseries",
+      "description": "Stacked, so the top edge is the whole of it.",
+      "gridPos": {
+        "x": 0,
+        "y": 4,
+        "w": 12,
+        "h": 9
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum by (tenant) (rate(llmgw_tenant_requests_total{tenant=~\"$tenant\"}[5m]))",
+          "legendFormat": "{{tenant}}",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "reqps",
+          "custom": {
+            "stacking": {
+              "mode": "normal"
+            },
+            "fillOpacity": 30
+          }
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "right",
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      }
+    },
+    {
+      "id": 6,
+      "title": "Tokens by tenant",
+      "type": "timeseries",
+      "description": "Prompt and completion together: what was consumed.",
+      "gridPos": {
+        "x": 12,
+        "y": 4,
+        "w": 12,
+        "h": 9
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum by (tenant) (rate(llmgw_tenant_tokens_total{tenant=~\"$tenant\"}[5m]))",
+          "legendFormat": "{{tenant}}",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "short",
+          "custom": {
+            "stacking": {
+              "mode": "normal"
+            },
+            "fillOpacity": 30
+          }
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "right",
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      }
+    },
+    {
+      "id": 7,
+      "title": "Refused by a limit, by tenant",
+      "type": "timeseries",
+      "description": "The share of each tenant's requests a limit turned away.",
+      "gridPos": {
+        "x": 0,
+        "y": 13,
+        "w": 12,
+        "h": 8
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum by (tenant) (rate(llmgw_tenant_requests_total{tenant=~\"$tenant\",outcome=\"limited\"}[5m])) / sum by (tenant) (rate(llmgw_tenant_requests_total{tenant=~\"$tenant\"}[5m]))",
+          "legendFormat": "{{tenant}}",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit"
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "right",
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      }
+    },
+    {
+      "id": 8,
+      "title": "Failing, by tenant",
+      "type": "timeseries",
+      "description": "One tenant alone failing is usually what it sends; all of them together is a model.",
+      "gridPos": {
+        "x": 12,
+        "y": 13,
+        "w": 12,
+        "h": 8
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sum by (tenant) (rate(llmgw_tenant_requests_total{tenant=~\"$tenant\",outcome=\"error\"}[5m])) / sum by (tenant) (rate(llmgw_tenant_requests_total{tenant=~\"$tenant\"}[5m]))",
+          "legendFormat": "{{tenant}}",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit"
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "right",
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      }
+    },
+    {
+      "id": 9,
+      "title": "First token p95, by tenant",
+      "type": "timeseries",
+      "description": "",
+      "gridPos": {
+        "x": 0,
+        "y": 21,
+        "w": 12,
+        "h": 8
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "histogram_quantile(0.95, sum by (tenant, le) (rate(llmgw_tenant_ttft_seconds_bucket{tenant=~\"$tenant\"}[10m])))",
+          "legendFormat": "{{tenant}}",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "s"
+        },
+        "overrides": []
+      },
+      "options": {
+        "legend": {
+          "displayMode": "table",
+          "placement": "right",
+          "calcs": [
+            "mean",
+            "max"
+          ]
+        },
+        "tooltip": {
+          "mode": "multi",
+          "sort": "desc"
+        }
+      }
+    },
+    {
+      "id": 10,
+      "title": "Budgets spent this period",
+      "type": "bargauge",
+      "description": "Every organization, team, project and person with a budget. Requests are refused at 100%.",
+      "gridPos": {
+        "x": 12,
+        "y": 21,
+        "w": 12,
+        "h": 8
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sort_desc(llmgw_budget_spent_ratio)",
+          "legendFormat": "{{scope}} {{name}} ({{period}})",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          }
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "unit": "percentunit",
+          "min": 0,
+          "max": 1,
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "orange",
+                "value": 0.8
+              },
+              {
+                "color": "red",
+                "value": 1
+              }
+            ]
+          }
+        },
+        "overrides": []
+      },
+      "options": {
+        "displayMode": "gradient",
+        "orientation": "horizontal",
+        "reduceOptions": {
+          "calcs": [
+            "lastNotNull"
+          ]
+        },
+        "showUnfilled": true
+      }
+    },
+    {
+      "id": 11,
+      "title": "Who used most, last 24 hours",
+      "type": "table",
+      "description": "Spend in money is on the people page's usage tab, which reads it from the store.",
+      "gridPos": {
+        "x": 0,
+        "y": 29,
+        "w": 24,
+        "h": 8
+      },
+      "datasource": {
+        "type": "prometheus",
+        "uid": "llmgw-prom"
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "expr": "sort_desc(sum by (tenant) (increase(llmgw_tenant_requests_total{tenant=~\"$tenant\"}[24h])))",
+          "legendFormat": "requests",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          },
+          "format": "table",
+          "instant": true
+        },
+        {
+          "refId": "B",
+          "expr": "sum by (tenant) (increase(llmgw_tenant_tokens_total{tenant=~\"$tenant\"}[24h]))",
+          "legendFormat": "tokens",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          },
+          "format": "table",
+          "instant": true
+        },
+        {
+          "refId": "C",
+          "expr": "sum by (tenant) (increase(llmgw_tenant_requests_total{tenant=~\"$tenant\",outcome=\"limited\"}[24h]))",
+          "legendFormat": "limited",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "llmgw-prom"
+          },
+          "format": "table",
+          "instant": true
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {},
+        "overrides": []
+      },
+      "options": {
+        "showHeader": true
+      },
+      "transformations": [
+        {
+          "id": "merge",
+          "options": {}
+        },
+        {
+          "id": "organize",
+          "options": {
+            "excludeByName": {
+              "Time": true
+            },
+            "renameByName": {
+              "Value #A": "Requests",
+              "Value #B": "Tokens",
+              "Value #C": "Refused by a limit"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}

deploy/monitoring/llmgw-rules.yml

@@ -156,6 +156,18 @@ groups:
             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: ModelUpdateAvailable
+        expr: llmgw_model_update_available == 1
+        for: 1h
+        labels: { severity: info }
+        annotations:
+          summary: "{{ $labels.repo }} has new weights for {{ $labels.model }}"
+          description: >-
+            The registry repository the model was served from has published
+            different files under the same names. `llmgw ctl model updates`
+            lists what changed; `llmgw ctl model update {{ $labels.model }}`
+            moves it to them, and `llmgw ctl model rollback` goes back.
+
       - alert: PoolSaturated
         expr: llmgw_pool_saturation > 1
         for: 5m
@@ -200,6 +212,94 @@ groups:
             is skipped by placement rather than failing, so this is quiet until
             somebody wonders why a model will not land there.
 
+  - name: llmgw-gpus
+    rules:
+      - alert: GPUThermalThrottling
+        expr: llmgw_gpu_throttled{reason=~"sw_thermal|hw_thermal|hw_slowdown"} == 1
+        for: 10m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.node }} GPU {{ $labels.gpu }} is slowed by heat ({{ $labels.reason }})"
+          description: >-
+            Ten minutes held back by temperature: every replica on the card is
+            slower than its measurements say. Usually airflow, a fan, or the
+            room — the node page shows the card's temperature over time.
+
+      - alert: GPUUncorrectedECCErrors
+        expr: llmgw_gpu_ecc_errors > 0
+        for: 1m
+        labels: { severity: critical }
+        annotations:
+          summary: "{{ $labels.node }} GPU {{ $labels.gpu }} has {{ $value }} uncorrected ECC errors"
+          description: >-
+            Uncorrected memory errors since the driver loaded: what runs on the
+            card may be computing on corrupted memory. Drain the node
+            (llmgw ctl drain) and have the card looked at.
+
+      - alert: GPUXidError
+        expr: increase(llmgw_gpu_xid_errors[15m]) > 0
+        for: 0m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.node }} GPU {{ $labels.gpu }} logged an XID error"
+          description: >-
+            The driver reported an error on the card (its code is
+            llmgw_gpu_last_xid, and the node page says it in words). 79 is a
+            card fallen off the bus, 48 and 63/64 memory errors, 74 NVLink,
+            94/95 contained and uncontained ECC errors: those need the card
+            looked at. Others are often an engine's own fault, and pass.
+
+      - alert: GPUOutOfSpareRows
+        expr: llmgw_gpu_remap_failure == 1
+        for: 1m
+        labels: { severity: critical }
+        annotations:
+          summary: "{{ $labels.node }} GPU {{ $labels.gpu }} has no spare memory rows left"
+          description: >-
+            The card cannot remap another failing row. Drain the node and
+            have the card replaced.
+
+      - alert: GPUNeedsReset
+        expr: llmgw_gpu_remap_pending == 1 or llmgw_gpu_retirement_pending == 1
+        for: 5m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.node }} GPU {{ $labels.gpu }} has memory repairs waiting for a reset"
+          description: >-
+            Rows remapped or pages retired take effect only after the card is
+            reset. Drain the node (llmgw ctl drain), reset or reboot, and bring
+            it back.
+
+      - alert: GPUPCIeRetriesClimbing
+        expr: increase(llmgw_gpu_pcie_replays[1h]) > 100
+        for: 0m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.node }} GPU {{ $labels.gpu }}: {{ $value }} PCIe retries in an hour"
+          description: >-
+            The card's link to the host is retrying. A riser, the slot or a
+            cable is the usual cause, and transfers to the card slow down.
+
+      - alert: GPUNVLinkErrorsClimbing
+        expr: increase(llmgw_gpu_nvlink_errors{kind="crc"}[1h]) > 10
+        for: 0m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.node }} GPU {{ $labels.gpu }}: NVLink CRC errors climbing"
+          description: >-
+            Errors on the card's NVLink links: tensor-parallel replicas on it
+            slow down, and a link that keeps failing takes a replica with it.
+
+      - alert: GPUHot
+        expr: llmgw_gpu_temperature_celsius > 87
+        for: 10m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.node }} GPU {{ $labels.gpu }} at {{ $value }} °C"
+          description: >-
+            Ten minutes above 87 °C, where most data-centre cards begin to
+            throttle.
+
   - name: monitoring-host
     rules:
       - alert: MonitoringDiskFilling
@@ -262,3 +362,225 @@ groups:
             Working as designed when the cluster is full: the lowest band is
             held first. Worth knowing about because the callers being refused
             do not know why.
+
+  # Per tenant: the level router.tenant_label names (a team by default), and
+  # every organization, team, project and person given a budget.
+  - name: llmgw-tenants
+    rules:
+      - alert: BudgetMostlySpent
+        expr: llmgw_budget_spent_ratio >= 0.8 and llmgw_budget_spent_ratio < 1
+        for: 5m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.scope }} {{ $labels.name }} has spent {{ $value | humanizePercentage }} of its {{ $labels.period }}ly budget"
+          description: >-
+            Its requests are refused once it reaches all of it, until the
+            period turns. Raise it on the people page, or tell them now
+            rather than when they are refused.
+
+      - alert: BudgetSpent
+        expr: llmgw_budget_spent_ratio >= 1
+        for: 1m
+        labels: { severity: critical }
+        annotations:
+          summary: "{{ $labels.scope }} {{ $labels.name }} has spent its {{ $labels.period }}ly budget"
+          description: >-
+            Every request under it is refused with 429 until the period
+            turns, unless a cheaper model is named as its fallback.
+
+      - alert: TenantHittingLimits
+        expr: >-
+          sum by (tenant) (rate(llmgw_tenant_requests_total{outcome="limited"}[10m]))
+          / sum by (tenant) (rate(llmgw_tenant_requests_total[10m])) > 0.1
+        for: 10m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $value | humanizePercentage }} of {{ $labels.tenant }}'s requests are refused by a limit"
+          description: >-
+            A rate, token or budget limit is turning their traffic away. Either
+            the limit is too low for what they now do, or something of theirs
+            is looping.
+
+      - alert: TenantErrors
+        expr: >-
+          sum by (tenant) (rate(llmgw_tenant_requests_total{outcome="error"}[10m]))
+          / sum by (tenant) (rate(llmgw_tenant_requests_total[10m])) > 0.05
+          and sum by (tenant) (rate(llmgw_tenant_requests_total[10m])) > 0.05
+        for: 10m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $value | humanizePercentage }} of {{ $labels.tenant }}'s requests fail"
+          description: >-
+            Not counting refusals by a limit. If every tenant fails alike it
+            is a model (ModelFailing); one alone is usually what they send —
+            prompts past the context, a model they may not use.
+
+      - alert: TenantTrafficSpike
+        expr: >-
+          sum by (tenant) (rate(llmgw_tenant_requests_total[30m]))
+          > 3 * sum by (tenant) (rate(llmgw_tenant_requests_total[7d]))
+          and sum by (tenant) (rate(llmgw_tenant_requests_total[30m])) > 0.2
+        for: 15m
+        labels: { severity: info }
+        annotations:
+          summary: "{{ $labels.tenant }} is sending three times its weekly average"
+          description: >-
+            A new workload, a batch job, or a client retrying in a loop. Only
+            for a tenant sending more than one request every five seconds, so
+            a quiet team starting work in the morning does not page anybody.
+
+      - alert: TenantSlowFirstToken
+        expr: >-
+          histogram_quantile(0.95,
+            sum by (tenant, le) (rate(llmgw_tenant_ttft_seconds_bucket[15m]))) > 10
+          and sum by (tenant) (rate(llmgw_tenant_ttft_seconds_count[15m])) > 0.02
+        for: 15m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.tenant }} waits {{ $value | humanizeDuration }} for a first token at p95"
+          description: >-
+            What their people feel. Compare with SlowFirstToken per model: if
+            only this tenant is slow, it is the models it uses or its queue
+            band, not the cluster.
+  # The store, when it is a replicated cluster under Patroni (llmgw server
+  # init --patroni). Published only for a store of several hosts.
+  - name: llmgw-store
+    rules:
+      - alert: StoreHasNoLeader
+        expr: llmgw_store_patroni_up == 1 and on() count(llmgw_store_member{role="leader"}) == 0
+        for: 1m
+        labels: { severity: critical }
+        annotations:
+          summary: "The store's cluster has no primary"
+          description: >-
+            Every write fails — keys, usage, budgets, leadership. Patroni
+            promotes a standby within its 30-second TTL; a minute without one
+            means it cannot: etcd has lost its majority, or no standby is fit.
+            `patronictl -c /etc/patroni/config.yml list` on a member says which.
+
+      - alert: StorePatroniUnreachable
+        expr: llmgw_store_patroni_up == 0
+        for: 2m
+        labels: { severity: warning }
+        annotations:
+          summary: "No member of the store's cluster answers on its Patroni port"
+          description: >-
+            The control plane reads the cluster's state from port 8008 on each
+            member. The database may still be serving; nothing here can tell.
+
+      - alert: StoreReplicaNotStreaming
+        expr: llmgw_store_member{role!="leader", state!="streaming"} == 1
+        for: 5m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.member }} is {{ $labels.state }}, not streaming from the primary"
+          description: >-
+            A standby that is not streaming is not a standby: if the primary
+            is lost now, there is nothing to promote. "missing" is a host of
+            the store address the cluster no longer lists — usually a machine
+            that is down.
+
+      - alert: StoreReplicaBehind
+        expr: llmgw_store_replica_lag_bytes > 64 * 1024 * 1024 or llmgw_store_replica_lag_bytes == -1
+        for: 10m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.member }} is {{ $value | humanize1024 }}B behind the primary"
+          description: >-
+            Patroni will not promote a standby more than 1 MB behind, so a
+            failover now would find none fit. -1 is a lag Patroni cannot read.
+
+  - name: llmgw-guard
+    rules:
+      - alert: GuardFailingOpen
+        expr: >-
+          sum(rate(llmgw_guard_fail_open_total[5m]))
+            / clamp_min(sum(rate(llmgw_guard_checks_total[5m])), 1e-9) > 0.01
+        for: 5m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $value | humanizePercentage }} of judged traffic is served unjudged"
+          description: >-
+            A guard policy's judge model is not answering within its latency
+            budget, and the policy fails open: requests go through flagged
+            "judge unavailable" instead of being judged.
+            llmgw_guard_judge_errors_total says whether it is timing out or
+            not there; `llmgw ctl replicas` whether the judge has replicas.
+
+      - alert: GuardJudgeSlow
+        expr: >-
+          histogram_quantile(0.95, sum by (le, judge_model) (rate(llmgw_guard_judge_latency_seconds_bucket[5m]))) > 0.25
+        for: 10m
+        labels: { severity: warning }
+        annotations:
+          summary: "Judge {{ $labels.judge_model }} answers in {{ $value | humanizeDuration }} at p95"
+          description: >-
+            Over the default latency budget: every judged request waits this
+            long, and those over their policy's budget are served unjudged or
+            refused. Give the judge more replicas, or faster ones.
+
+      - alert: GuardJudgeUnavailable
+        expr: sum by (reason) (rate(llmgw_guard_judge_errors_total{reason!="timeout"}[5m])) > 0
+        for: 5m
+        labels: { severity: critical }
+        annotations:
+          summary: "The guardrails cannot ask their judge ({{ $labels.reason }})"
+          description: >-
+            no_judge: a policy names a model that is not in the catalog with
+            role: guard. unavailable: it has no replica answering. format: it
+            answers in a form its guard.format does not read.
+
+      - alert: GuardBlocksSpiking
+        expr: >-
+          sum by (tenant) (rate(llmgw_tenant_guard_blocks_total[1h]))
+            > 3 * sum by (tenant) (rate(llmgw_tenant_guard_blocks_total[7d]))
+          and sum by (tenant) (increase(llmgw_tenant_guard_blocks_total[1h])) > 10
+        for: 15m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.tenant }} is being blocked three times as often as usual"
+          description: >-
+            A tenant's requests or answers are blocked by the guardrails
+            more than three times their weekly rate. Someone probing, a
+            client sending data it should not, or a policy that changed.
+            The /admin/guard page lists the recent ones by request.
+
+      - alert: GuardSecretInAnswer
+        expr: sum(increase(llmgw_guard_checks_total{stage="output",category="secret",action!="allowed"}[5m])) > 0
+        labels: { severity: critical }
+        annotations:
+          summary: "A model put a credential in an answer"
+          description: >-
+            An answer contained something shaped like a key or a private key.
+            It was stopped or rewritten if the policy enforces; either way a
+            model has seen it, in its prompt or its training. The usage rows
+            with guard_category secret say which request.
+
+  - name: llmgw-slo
+    rules:
+      - alert: ModelTTFTOverSLO
+        expr: >-
+          histogram_quantile(0.99, sum by (le, model) (rate(llmgw_ttft_seconds_bucket[10m])))
+            > on (model) group_left llmgw_model_slo_seconds{kind="ttft_p99"}
+        for: 15m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.model }} answers its first token past its SLO at p99"
+          description: >-
+            The p99 time to the first token over ten minutes is past the
+            model's slo.ttft_p99. Admission already holds the lower bands back
+            while it is; this says it has lasted. More replicas, or less
+            traffic in the bands above.
+
+      - alert: ModelTPOTOverSLO
+        expr: >-
+          histogram_quantile(0.99, sum by (le, model) (rate(llmgw_tpot_seconds_bucket[10m])))
+            > on (model) group_left llmgw_model_slo_seconds{kind="tpot_p99"}
+        for: 15m
+        labels: { severity: warning }
+        annotations:
+          summary: "{{ $labels.model }} produces tokens slower than its SLO at p99"
+          description: >-
+            The p99 time per output token is past slo.tpot_p99: replicas are
+            batching more than they can decode quickly, or a slower card is
+            serving. llmgw_output_tokens_per_second by pool says which.

deploy/monitoring/prometheus.yml

@@ -27,6 +27,17 @@ scrape_configs:
         labels:
           instance: control-plane
 
+  # Every machine of the cluster, for its node exporter: network and disk
+  # traffic, filesystems, CPU time. The control plane lists them — nodes,
+  # itself, the store's members — so a node added is a node scraped with
+  # nothing edited here, and each carries its llmgw id as the node label.
+  # `llmgw node add` installs the exporter; on a machine added before that,
+  # apt-get install prometheus-node-exporter.
+  - job_name: nodes
+    http_sd_configs:
+      - url: http://10.0.0.140:9091/prometheus/targets
+        refresh_interval: 1m
+
   - job_name: prometheus
     static_configs:
       - targets: ['localhost:9090']

docs.go

@@ -0,0 +1,103 @@
+// Package llmgw holds what the binary carries besides code: its manual, the
+// description of its admin API, and the example quality suites.
+package llmgw
+
+import (
+	"embed"
+	"io/fs"
+	"sort"
+	"strings"
+)
+
+// Docs is the documentation, read on any machine by `llmgw docs` and the
+// console's manual without a checkout or the internet.
+//
+//go:embed README.md CHANGELOG.md docs/*.md
+var Docs embed.FS
+
+// Doc is one page of the manual.
+type Doc struct {
+	// Key is what `llmgw docs KEY` takes, and the page's address under /docs/
+	// on the gateway.
+	Key string
+	// Path is the file in Docs.
+	Path string
+	// Title is the document's first heading.
+	Title string
+}
+
+// Source is the document's markdown.
+func (d Doc) Source() string {
+	b, err := fs.ReadFile(Docs, d.Path)
+	if err != nil {
+		return "# " + d.Path + "\n\nNot in this build."
+	}
+	return string(b)
+}
+
+// docOrder is the documents in the order someone new reads them. Here rather
+// than with either reader, because the console's manual and the gateway's
+// docs portal both list them, and two lists drift.
+var docOrder = []string{"console", "quick-install", "install", "node-onboarding", "onboarding",
+	"clients", "guardrails", "choosing-models", "fabrics", "facility-aware-placement", "data",
+	"reference", "development"}
+
+// Manual is every document, in reading order: those docOrder names, then any
+// other under docs/ alphabetically, so a new one is never missing, then the
+// README and the changes.
+func Manual() []Doc {
+	var out []Doc
+	seen := map[string]bool{}
+	add := func(key, path string) {
+		if seen[key] {
+			return
+		}
+		b, err := fs.ReadFile(Docs, path)
+		if err != nil {
+			return
+		}
+		seen[key] = true
+		out = append(out, Doc{Key: key, Path: path, Title: titleOf(string(b), path)})
+	}
+	for _, k := range docOrder {
+		add(k, "docs/"+k+".md")
+	}
+	entries, _ := fs.ReadDir(Docs, "docs")
+	var rest []string
+	for _, e := range entries {
+		if strings.HasSuffix(e.Name(), ".md") {
+			rest = append(rest, strings.TrimSuffix(e.Name(), ".md"))
+		}
+	}
+	sort.Strings(rest)
+	for _, k := range rest {
+		add(k, "docs/"+k+".md")
+	}
+	add("readme", "README.md")
+	add("changes", "CHANGELOG.md")
+	return out
+}
+
+// titleOf is a document's first top-level heading, or its path when it has
+// none.
+func titleOf(src, path string) string {
+	for _, l := range strings.Split(src, "\n") {
+		if strings.HasPrefix(l, "# ") {
+			return strings.TrimSpace(strings.TrimPrefix(l, "# "))
+		}
+	}
+	return path
+}
+
+// AdminOpenAPI is the admin API described in OpenAPI 3.1, generated from its
+// route table by `go generate` in internal/docgen and served at
+// /api/v1/openapi.json, so a client can be pointed at the server it talks to.
+//
+//go:embed docs/admin-api.openapi.json
+var AdminOpenAPI []byte
+
+// EvalSuites are the example quality suites under deploy/eval, which the
+// control plane runs by name when its eval directory has none of the name.
+//
+//go:embed deploy/eval/*.yaml
+var EvalSuites embed.FS

docs/admin-api.md

@@ -0,0 +1,160 @@
+# The admin API
+
+Written for whoever automates a cluster rather than typing at it: how to reach
+the control plane's management API, what it asks of a request, and where its
+description is.
+
+`llmgw ctl` and the console are clients of this API and nothing more, so
+anything they do can be done with `curl`, a generated client or the
+[Terraform provider](../terraform-provider-llmgw/README.md). It adds and
+removes models, scales them, cordons and upgrades nodes, sets capacity
+quotas, attaches guardrail policies, and reads the fleet, usage and the audit
+log.
+
+## Reaching it
+
+The API is under `/api/v1` on the admin listener, `admin_listen` in
+`/etc/llmgw/server.yaml`: `127.0.0.1:9090` unless changed. It is on loopback
+on purpose. The same listener serves pprof when it is turned on, and the
+server refuses to start with it on any other address unless
+`admin_remote: true` — the token would cross the network in clear.
+
+From another machine, tunnel to it rather than moving it:
+
+```sh
+ssh -N -L 9090:127.0.0.1:9090 admin@control-plane &
+curl -s -H "Authorization: Bearer $LLMGW_ADMIN_TOKEN" http://127.0.0.1:9090/api/v1/summary
+```
+
+With `admin_remote: true` and `admin_listen: 10.0.0.5:9090`, call that address
+directly — on a network you trust, or behind a TLS proxy that keeps the
+`Host` header an address.
+
+## The token
+
+Every path under `/api` needs the admin token as a bearer token:
+
+```
+Authorization: Bearer 6f1c…
+```
+
+The server writes it the first time it starts, 0600, to
+`/var/lib/llmgw/admin-token` under its systemd unit (`admin_token_file`
+moves it; a server run by hand keeps it in `secrets/admin-token` beside its
+configuration). `llmgw ctl` reads it from there, which is why it runs with
+sudo, or from `LLMGW_ADMIN_TOKEN`. To give it to automation:
+
+```sh
+sudo cat /var/lib/llmgw/admin-token
+```
+
+The token is the whole of the API's authorisation: whoever holds it can do
+everything the API does. Keep it where you keep other root credentials.
+
+## What a request must look like
+
+Besides the token, the listener refuses three things before a handler sees
+them, as defences against a browser being turned against it:
+
+- **A name in `Host`.** The listener answers to an address or `localhost`,
+  not a DNS name, so a page on some other site cannot reach it by rebinding
+  a name to 127.0.0.1. Call it as `http://127.0.0.1:9090`, not
+  `http://cp.example.com:9090`; behind a proxy, have the proxy send an
+  address.
+- **A cross-site request.** One whose `Origin` is another host, or whose
+  `Sec-Fetch-Site` says another site sent it.
+- **A change that is not JSON.** Every method but `GET` and `HEAD` must carry
+  `Content-Type: application/json`, even a `DELETE` or a `POST` with no body.
+  A form post from a page cannot set that header.
+
+A change is recorded in the audit log with who made it, as the request says
+in `X-Llmgw-Actor` (letters, digits and `._-@`, at most 64; `unknown` when
+absent). `llmgw ctl` sends the name of whoever ran it; automation should send
+its own, `terraform` or `ci@deploy`, so `llmgw ctl audit` can tell them apart.
+
+A refusal is a 4xx or 5xx with `{"error": "…"}` saying why. 501 means this
+control plane lacks what the endpoint needs — a store, a mirror, guard
+policies — and says which.
+
+## Some calls
+
+```sh
+H=(-H "Authorization: Bearer $LLMGW_ADMIN_TOKEN" -H "Content-Type: application/json" -H "X-Llmgw-Actor: $USER")
+API=http://127.0.0.1:9090/api/v1
+
+# The fleet in one answer, and every model.
+curl -s "${H[@]}" $API/summary
+curl -s "${H[@]}" $API/models
+
+# Add a model, read back its definition with the defaults filled in, scale it.
+curl -s "${H[@]}" -X POST $API/models -d '{
+  "name": "qwen-small",
+  "source": "/srv/models/qwen2.5-1.5b-instruct-q4_k_m.gguf",
+  "profiles": [{"name": "cpu", "engine": "llamacpp", "min_memory_gb": 4, "cpu_cores": 4}],
+  "scaling": {"min": 1, "max": 2}
+}'
+curl -s "${H[@]}" $API/models/qwen-small
+curl -s "${H[@]}" -X POST $API/models/qwen-small/scale -d '{"min": 0, "max": 2, "idle_timeout": 1800000000000}'
+
+# A team's capacity quota.
+curl -s "${H[@]}" -X PUT $API/quotas -d '{"scope": "team:Acme/ml", "limit": {"gpus": 8}}'
+
+# Remove the model; a DELETE carries the content type too.
+curl -s "${H[@]}" -X DELETE $API/models/qwen-small
+```
+
+Durations in bodies are integer nanoseconds, as Go encodes them: half an hour
+is `1800000000000`.
+
+## The description
+
+The API is described in OpenAPI 3.1:
+
+- served by every control plane at `GET /api/v1/openapi.json` (with the
+  token, like the rest), as built into that binary, so it describes the
+  server you are talking to;
+- committed as [admin-api.openapi.json](admin-api.openapi.json) for reading
+  without a cluster.
+
+```sh
+curl -s "${H[@]}" $API/openapi.json > llmgw-admin.json
+```
+
+It lists every endpoint, its path and query parameters, and the schema of
+each request and answer, with the meaning of each field. Load it into any
+OpenAPI tool — Swagger UI, Redoc, an editor — or generate a client from it:
+
+```sh
+docker run --rm -v "$PWD:/w" openapitools/openapi-generator-cli generate \
+  -i /w/llmgw-admin.json -g python -o /w/llmgw-admin-client
+```
+
+### How it is kept true
+
+The document is generated, not written. `internal/control/adminapi/routes.go`
+holds a table of every endpoint: its method and path, a summary, its query
+parameters, and Go values of the types it reads and answers with. The
+generator in `internal/docgen/openapi` reads those types by reflection, the
+way `encoding/json` encodes them, and takes each field's description from its
+comment in the source.
+
+Two tests keep it from drifting. One registers the API on a recording mux and
+fails when an endpoint is served and not in the table, or in the table and not
+served. The other regenerates the document and fails when it differs from the
+committed one. After changing an endpoint or a type it carries:
+
+```sh
+go generate ./internal/docgen
+```
+
+## What it does not cover
+
+- **Organizations, teams, projects, people and API keys.** These live in the
+  store and are managed with `llmgw org`, `llmgw users` and `llmgw keys` on the
+  control plane, or in the web console's `/admin` pages on the client port
+  behind a session. The admin API reads the tree only where a quota or a
+  policy names a part of it.
+- **The client-facing API** (`/v1/chat/completions` and the rest), which is
+  OpenAI's and Anthropic's, on `listen`, with API keys.
+- **The rest of the admin listener**: `/metrics`, `/health`, the dashboard
+  pages and `/debug/pprof`, which are not under `/api`.

docs/clients.md

@@ -0,0 +1,557 @@
+# Using llmgw from code
+
+Written for a developer whose program talks to a model through llmgw. There
+is no llmgw SDK, and there will not be one: the gateway speaks OpenAI's API
+and Anthropic's Messages API, so the official SDKs for both work as they are.
+Only two things change — the base URL and the key. Everything llmgw adds on
+top is an HTTP header, which every one of those SDKs lets you set.
+
+The examples use `https://llm.example.com` for the gateway; use the address
+your operator gave you, or the one on the gateway's own front page. Every
+example reads the key from `LLMGW_API_KEY`. `<model-name>` is a model this
+gateway serves: `GET /v1/models` lists the ones your key may use, and sending
+the placeholder unchanged is answered with that list rather than with an
+error.
+
+## Getting a key
+
+Keys are made on the gateway's **Account** page after signing in, or issued
+by an operator. A key is shown once and never again — only its hash is kept —
+so put it in a password manager straight away. `GET /me` with the key says
+what it may do and what it has spent.
+
+## The base URL and the key
+
+| SDK | Base URL | Key |
+|---|---|---|
+| OpenAI (any language) | `https://llm.example.com/v1` | `Authorization: Bearer …`, as the SDK sends it |
+| Anthropic (any language) | `https://llm.example.com` — the SDK adds `/v1/messages` | `x-api-key: …`, as the SDK sends it |
+
+Both SDKs also read their usual environment variables, so a program that
+already uses them needs no change at all:
+
+```
+export OPENAI_BASE_URL=https://llm.example.com/v1
+export OPENAI_API_KEY=$LLMGW_API_KEY
+
+export ANTHROPIC_BASE_URL=https://llm.example.com
+export ANTHROPIC_API_KEY=$LLMGW_API_KEY
+```
+
+## A first request
+
+### curl
+
+```
+curl https://llm.example.com/v1/chat/completions \
+  -H "Authorization: Bearer $LLMGW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model": "<model-name>",
+       "messages": [{"role": "user", "content": "Say hello in Turkish."}]}'
+```
+
+### Python
+
+```
+pip install openai
+```
+
+```python
+import os
+from openai import OpenAI
+
+client = OpenAI(base_url="https://llm.example.com/v1",
+                api_key=os.environ["LLMGW_API_KEY"])
+
+reply = client.chat.completions.create(
+    model="<model-name>",
+    messages=[{"role": "user", "content": "Say hello in Turkish."}],
+)
+print(reply.choices[0].message.content)
+```
+
+### TypeScript
+
+```
+npm install openai
+```
+
+```typescript
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  baseURL: "https://llm.example.com/v1",
+  apiKey: process.env.LLMGW_API_KEY,
+});
+
+const reply = await client.chat.completions.create({
+  model: "<model-name>",
+  messages: [{ role: "user", content: "Say hello in Turkish." }],
+});
+console.log(reply.choices[0].message.content);
+```
+
+### Go
+
+```
+go get github.com/openai/openai-go/v3
+```
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+
+	"github.com/openai/openai-go/v3"
+	"github.com/openai/openai-go/v3/option"
+)
+
+func main() {
+	client := openai.NewClient(
+		option.WithBaseURL("https://llm.example.com/v1/"),
+		option.WithAPIKey(os.Getenv("LLMGW_API_KEY")),
+	)
+	reply, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
+		Model:    "<model-name>",
+		Messages: []openai.ChatCompletionMessageParamUnion{openai.UserMessage("Say hello in Turkish.")},
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Println(reply.Choices[0].Message.Content)
+}
+```
+
+The import path carries the SDK's major version; use the one your module
+already has.
+
+## Streaming
+
+Set `stream` and read the chunks. llmgw may send a last chunk that carries
+only the token counts and no choices, so check for a choice before reading
+one — the OpenAI API does the same when usage is asked for.
+
+```python
+stream = client.chat.completions.create(
+    model="<model-name>",
+    messages=[{"role": "user", "content": "Count to ten."}],
+    stream=True,
+)
+for chunk in stream:
+    if chunk.choices and chunk.choices[0].delta.content:
+        print(chunk.choices[0].delta.content, end="", flush=True)
+print()
+```
+
+```typescript
+const stream = await client.chat.completions.create({
+  model: "<model-name>",
+  messages: [{ role: "user", content: "Count to ten." }],
+  stream: true,
+});
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
+}
+```
+
+```go
+stream := client.Chat.Completions.NewStreaming(ctx, openai.ChatCompletionNewParams{
+	Model:    "<model-name>",
+	Messages: []openai.ChatCompletionMessageParamUnion{openai.UserMessage("Count to ten.")},
+})
+for stream.Next() {
+	chunk := stream.Current()
+	if len(chunk.Choices) > 0 {
+		fmt.Print(chunk.Choices[0].Delta.Content)
+	}
+}
+if err := stream.Err(); err != nil {
+	log.Fatal(err)
+}
+```
+
+With curl, add `"stream": true` to the body and `-N` so curl prints the
+events as they come.
+
+## Tools
+
+Function calling is OpenAI's: describe the tools, run the ones the model
+asks for, send the results back. Whether a model calls tools well is the
+model's business, not the gateway's; ask your operator which of the served
+models are set up for it.
+
+**Editors' agents need such a model.** Continue's Agent mode, Cline and
+Codex act only through tool calls: with a model whose calls come back as
+text — `<tool_call>{...}` or a JSON block in the answer, `tool_calls` empty —
+they chat but never read a file or run a command. Qwen2.5-Coder is one;
+Qwen3-Coder is not. The configuration the portal writes for Continue says
+`tool_use` only for a model whose catalog entry says tools, and gives
+Continue the model's context and longest answer, so it never sends a request
+the gateway refuses.
+
+```python
+import json
+
+tools = [{
+    "type": "function",
+    "function": {
+        "name": "get_weather",
+        "description": "The current weather in a city.",
+        "parameters": {
+            "type": "object",
+            "properties": {"city": {"type": "string"}},
+            "required": ["city"],
+        },
+    },
+}]
+
+messages = [{"role": "user", "content": "Is it raining in Ankara?"}]
+reply = client.chat.completions.create(model="<model-name>", messages=messages, tools=tools)
+msg = reply.choices[0].message
+
+if msg.tool_calls:
+    messages.append(msg)
+    for call in msg.tool_calls:
+        args = json.loads(call.function.arguments)
+        result = {"city": args["city"], "raining": False}  # your code here
+        messages.append({"role": "tool", "tool_call_id": call.id,
+                         "content": json.dumps(result)})
+    reply = client.chat.completions.create(model="<model-name>", messages=messages, tools=tools)
+
+print(reply.choices[0].message.content)
+```
+
+## Embeddings
+
+```python
+result = client.embeddings.create(
+    model="<embedding-model>",
+    input=["llmgw routes requests", "to GPUs it can reach"],
+)
+vectors = [d.embedding for d in result.data]
+```
+
+```typescript
+const result = await client.embeddings.create({
+  model: "<embedding-model>",
+  input: ["llmgw routes requests", "to GPUs it can reach"],
+});
+const vectors = result.data.map((d) => d.embedding);
+```
+
+An embedding model is a model of its own; a chat model does not answer
+`/v1/embeddings`.
+
+## The Responses API
+
+`/v1/responses` is served too, for clients that speak nothing else (Codex
+among them). llmgw translates it to chat completions, so it works with every
+model the gateway serves; what has no equivalent there — OpenAI's hosted
+tools, reasoning summaries — is ignored rather than refused.
+
+```python
+response = client.responses.create(
+    model="<model-name>",
+    instructions="Answer in one sentence.",
+    input="Why is the sky blue?",
+)
+print(response.output_text)
+```
+
+Streamed, the events are the Responses API's own:
+
+```python
+stream = client.responses.create(model="<model-name>", input="Count to ten.", stream=True)
+for event in stream:
+    if event.type == "response.output_text.delta":
+        print(event.delta, end="", flush=True)
+```
+
+## Batches
+
+For work that need not finish now: OpenAI's Files and Batch APIs. A batch runs
+at the lowest priority, so it uses what interactive traffic leaves free, and
+each line is counted against the key that submitted it.
+
+```python
+import json
+
+with open("requests.jsonl", "w") as f:
+    for i, text in enumerate(["first document", "second document"]):
+        f.write(json.dumps({
+            "custom_id": f"doc-{i}",
+            "method": "POST",
+            "url": "/v1/chat/completions",
+            "body": {"model": "<model-name>",
+                     "messages": [{"role": "user", "content": "Summarise: " + text}]},
+        }) + "\n")
+
+batch_file = client.files.create(file=open("requests.jsonl", "rb"), purpose="batch")
+batch = client.batches.create(
+    input_file_id=batch_file.id,
+    endpoint="/v1/chat/completions",
+    completion_window="24h",
+)
+
+# Later:
+batch = client.batches.retrieve(batch.id)
+if batch.status == "completed":
+    for line in client.files.content(batch.output_file_id).text.splitlines():
+        result = json.loads(line)
+        print(result["custom_id"], result["response"]["body"]["choices"][0]["message"]["content"])
+```
+
+## The Anthropic SDK
+
+`/v1/messages` is Anthropic's Messages API, translated to chat completions and
+back, streamed or not, with tools and images. It serves the gateway's own
+models — `model` is a model this gateway serves, not a Claude model.
+
+```
+pip install anthropic
+```
+
+```python
+import os
+import anthropic
+
+client = anthropic.Anthropic(base_url="https://llm.example.com",
+                             api_key=os.environ["LLMGW_API_KEY"])
+
+message = client.messages.create(
+    model="<model-name>",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Say hello in Turkish."}],
+)
+print(message.content[0].text)
+
+with client.messages.stream(
+    model="<model-name>",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Count to ten."}],
+) as stream:
+    for text in stream.text_stream:
+        print(text, end="", flush=True)
+```
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+
+const client = new Anthropic({
+  baseURL: "https://llm.example.com",
+  apiKey: process.env.LLMGW_API_KEY,
+});
+
+const message = await client.messages.create({
+  model: "<model-name>",
+  max_tokens: 1024,
+  messages: [{ role: "user", content: "Say hello in Turkish." }],
+});
+for (const block of message.content) {
+  if (block.type === "text") console.log(block.text);
+}
+```
+
+```go
+client := anthropic.NewClient(
+	option.WithBaseURL("https://llm.example.com/"),
+	option.WithAPIKey(os.Getenv("LLMGW_API_KEY")),
+)
+message, err := client.Messages.New(ctx, anthropic.MessageNewParams{
+	Model:     "<model-name>",
+	MaxTokens: 1024,
+	Messages: []anthropic.MessageParam{
+		anthropic.NewUserMessage(anthropic.NewTextBlock("Say hello in Turkish.")),
+	},
+})
+if err != nil {
+	log.Fatal(err)
+}
+for _, block := range message.Content {
+	if text, ok := block.AsAny().(anthropic.TextBlock); ok {
+		fmt.Println(text.Text)
+	}
+}
+```
+
+(`github.com/anthropics/anthropic-sdk-go` and its `option` package.)
+
+With curl:
+
+```
+curl https://llm.example.com/v1/messages \
+  -H "x-api-key: $LLMGW_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -H "Content-Type: application/json" \
+  -d '{"model": "<model-name>", "max_tokens": 1024,
+       "messages": [{"role": "user", "content": "Say hello in Turkish."}]}'
+```
+
+## What llmgw adds
+
+Each is a header, so a request stays exactly what the SDK would send anywhere
+else. Set one for every request on the client, or for one request:
+
+| | Every request | One request |
+|---|---|---|
+| Python (both SDKs) | `OpenAI(..., default_headers={...})` | `create(..., extra_headers={...})` |
+| TypeScript (both SDKs) | `new OpenAI({ ..., defaultHeaders: {...} })` | `create({...}, { headers: {...} })` |
+| Go (both SDKs) | `openai.NewClient(..., option.WithHeader(k, v))` | `New(ctx, params, option.WithHeader(k, v))` |
+| curl | | `-H "k: v"` |
+
+### Stored conversations: `x-llmgw-thread`
+
+Send the same thread id with each request and only the new turn; llmgw puts
+the stored conversation in front of it. The conversation continues on
+whichever model serves the next turn, even a different one. It must be
+turned on for your project by an operator (`llmgw keys threads`); a request
+that names a thread on a gateway that keeps none is refused rather than
+answered without its history.
+
+```python
+import uuid
+
+thread = str(uuid.uuid4())  # anyone in your project who knows it reads it
+for turn in ["My name is Deniz.", "What is my name?"]:
+    reply = client.chat.completions.create(
+        model="<model-name>",
+        messages=[{"role": "user", "content": turn}],
+        extra_headers={"x-llmgw-thread": thread},
+    )
+    print(reply.choices[0].message.content)
+```
+
+A thread belongs to the project, not to the key, so use an id nobody can
+guess: at most 128 letters, digits and `- _ . :`. When the conversation no
+longer fits the model, the oldest turns are left out and the reply carries
+`x-llmgw-thread-trimmed` with how many. `DELETE /v1/threads/{id}` forgets one:
+
+```
+curl -X DELETE https://llm.example.com/v1/threads/$THREAD \
+  -H "Authorization: Bearer $LLMGW_API_KEY"
+```
+
+### Sessions: `x-session-id`
+
+Requests with the same session id go to the same replica while it is
+healthy, so a conversation that resends its history finds it already in that
+replica's cache and answers sooner. Without the header, the body's `user`
+field is used. Nothing is stored; it is only a routing hint.
+
+```python
+client = OpenAI(base_url="https://llm.example.com/v1", api_key=os.environ["LLMGW_API_KEY"],
+                default_headers={"x-session-id": "chat-7f3a"})
+```
+
+### Tags and metadata
+
+Requests can be labelled so the usage they record can be told apart — by
+feature, by customer, by job. Send OpenAI's own `metadata`, string keys to
+string values, or the same as the `x-llmgw-tags` header for a client that
+cannot set `metadata`; the `user` field is recorded too. Which tags also
+become metric labels is the operator's choice (`router.tag_labels`).
+
+```python
+reply = client.chat.completions.create(
+    model="<model-name>",
+    messages=[{"role": "user", "content": "Classify this ticket."}],
+    metadata={"feature": "triage", "customer": "acme"},
+    user="user-1234",
+)
+```
+
+```
+curl https://llm.example.com/v1/chat/completions \
+  -H "Authorization: Bearer $LLMGW_API_KEY" \
+  -H "x-llmgw-tags: feature=triage,customer=acme" \
+  -H "Content-Type: application/json" \
+  -d '{"model": "<model-name>", "messages": [{"role": "user", "content": "Classify this ticket."}]}'
+```
+
+### Canaries: `x-llmgw-variant`
+
+While an operator tries a model's newer weights on a share of its traffic, a
+session stays on one side. `x-llmgw-variant: canary` sends a request to the
+canary deliberately — to try it before it is promoted, or to compare the two.
+
+```python
+reply = client.chat.completions.create(
+    model="<model-name>",
+    messages=[{"role": "user", "content": "hello"}],
+    extra_headers={"x-llmgw-variant": "canary"},
+)
+```
+
+### Memory notes: `/v1/memory`
+
+Notes an agent keeps for itself across conversations: a key, some text, and
+optional tags, private to your project and to the agent named in
+`x-llmgw-agent` (`default` when it is not sent). An operator turns them on for
+a project (`llmgw keys memory`). They are plain REST, so any HTTP client
+will do:
+
+```
+H="Authorization: Bearer $LLMGW_API_KEY"
+
+curl -X PUT https://llm.example.com/v1/memory/favourite-colour -H "$H" \
+  -H "x-llmgw-agent: helper" -H "Content-Type: application/json" \
+  -d '{"text": "The user likes dark green.", "tags": ["preference"]}'
+
+curl "https://llm.example.com/v1/memory?q=green" -H "$H" -H "x-llmgw-agent: helper"
+curl "https://llm.example.com/v1/memory?tag=preference" -H "$H" -H "x-llmgw-agent: helper"
+curl https://llm.example.com/v1/memory/favourite-colour -H "$H" -H "x-llmgw-agent: helper"
+curl -X DELETE https://llm.example.com/v1/memory/favourite-colour -H "$H" -H "x-llmgw-agent: helper"
+```
+
+A key is up to 200 bytes, a note up to 16 KiB, with at most 16 tags of
+lowercase letters, digits, `-` and `_`, and 1000 notes per agent.
+
+### MCP: `/mcp`
+
+The same notes as tools an agent can be given — `remember`, `recall` and
+`forget` — from an MCP server at `https://llm.example.com/mcp` (the HTTP
+transport, answered as plain JSON). Add it to your agent's MCP servers with
+the key as a bearer token and, if you want notes kept apart, `x-llmgw-agent`.
+llmgw does not put these tools into requests by itself: an agent that is not
+given the server never sees its notes.
+
+```
+curl https://llm.example.com/mcp \
+  -H "Authorization: Bearer $LLMGW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
+```
+
+### Headers llmgw sends back
+
+| Header | Says |
+|---|---|
+| `x-request-id` | The request's id in the gateway's logs and usage records — quote it when asking an operator about a request. |
+| `x-llmgw-served-model` | The model that answered, when it was not the one asked for: a spent budget can move a request to a cheaper model. |
+| `x-llmgw-queue-ms` | How long the request waited for room before it was sent. |
+| `x-llmgw-thread-trimmed` | How many stored turns were left out to fit the model. |
+
+## When something is refused
+
+Errors come back in the shape of the API that was called — OpenAI's
+`{"error": {"message": …, "type": …}}` or Anthropic's — so each SDK raises
+its usual exception with the gateway's message in it. The ones worth knowing:
+
+| Status | Usually means |
+|---|---|
+| 400 | Besides a malformed request: a prompt too long for the model, or a guardrail policy refused it (the code `content_policy_violation`). |
+| 401 | No key, a mistyped one, or one that was revoked or has expired. |
+| 403 | The key may not use that model. |
+| 429 | A rate limit or budget of the key, its project or its team was reached. `Retry-After` says when to try again, and is absent when waiting will not help — a spent monthly budget. |
+| 503 | No model of that name is served (the message lists the ones that are), the model is still loading, or every replica is busy and the request waited as long as it may. The SDKs retry by themselves; a name that is not served will not start to be. |
+
+## Priority
+
+With keys on, the key decides the request's priority band and routing
+profile, set by an operator; the `x-llmgw-band` and `x-llmgw-profile` headers
+are ignored, so a client cannot promote itself. On a gateway without keys
+they are read from the request.

docs/console.md

@@ -0,0 +1,330 @@
+# The console
+
+`sudo llmgw`, with nothing after it, on a machine llmgw runs on. On a machine
+with nothing installed it opens the setup screens; on a control plane, the
+console described here; on a node, the node's own console, which edits
+`agent.yaml`. Everything on these screens can also be done by command — each
+screen says which — so a script never needs them and a person never needs
+to remember the commands.
+
+The keyboard drives it; there is no mouse. **?** opens this page from
+anywhere, and the **Manual** entry holds every other page, as `llmgw docs`
+does without the console.
+
+## The layout
+
+A bar across the top names the machine. Down the left, the entries, in four
+groups: **Watch**, **People**, **Help**, **Settings** and **Do**. The panel on
+the right shows the entry chosen. The bottom line always says which keys do
+what at that moment, and a question or a result opens as a dialog over the
+panel.
+
+| Key | Does |
+|---|---|
+| ↑ ↓ | Choose an entry, or a row in the panel |
+| → or Enter | Go into the panel |
+| Enter on a row | What can be done to it: its details first, then the rest |
+| ← or Esc | Back out: from a page to its list, from the panel to the entries |
+| A | Add one, on a view that holds things: a quota, an account, a key |
+| PgUp PgDn | Scroll a long panel |
+| ? | This page |
+| Q | Leave; the cluster keeps running |
+| Ctrl-C | Leave at once |
+
+What is watched is read again every three seconds.
+
+## Forms and questions
+
+A change that needs values opens a form, filled in with what is set now. Tab
+or ↓ moves to the next field, ← → changes a choice, and Enter on **Apply**
+sends it; a form of one field is sent by Enter on it. A mistake the form can
+see — a maximum below the minimum, a word where a number goes — is said in the
+form and nothing is sent. One the control plane refuses comes back as a dialog
+with its reason, word for word.
+
+Anything that cannot be undone — removing, draining, deleting, revoking —
+asks first, and only **Y** goes ahead.
+
+Serving a model and moving one to new weights are jobs on the control plane:
+started from here, they run there in the background whatever this screen
+does, and the console is free at once. **Jobs** follows them. Upgrading the
+cluster, a backup and adding a node change this machine or another over ssh;
+those close the screen and run in the terminal, so their output is there to
+read, and Enter brings the console back.
+
+## Setting up
+
+On a machine with nothing installed, the control plane is set up from one
+form (`sudo llmgw server init`): the administrator's email, other names nodes
+reach the machine by, and ticks for PostgreSQL, the model mirror, this machine
+as a node, the starter model and the guardrails' judge. **Offline bundle**
+and **Its sha256** are for a site with no internet: the path of a bundle made
+by `llmgw bundle create`, and the sha256 it printed. Given, the bundle goes
+into the mirror, every file checked, and the cluster is set up to fetch
+nothing from outside (install.md, "Offline sites"). A bundle with no sha256,
+or with the mirror unticked, is said in the form and nothing starts.
+
+## Watch
+
+**Overview** is `llmgw ctl status`: nodes, GPUs by class, fabrics, replicas,
+models, the store's members, and anything parked, unplaced or idle.
+
+**Monitor** draws the cluster the way btop draws a machine: CPU, memory,
+GPU busy and GPU memory, requests and tokens a second, time to first token,
+requests in flight and queued, network and disk — Braille charts, filled
+and coloured green to red by height — over 5 minutes, an hour, a day or a
+week (**1**–**4**, or **R** for the next). Below them each node's CPU,
+memory and network now and as a sparkline, each card's busy, memory, heat
+and power, and each model's requests a second. The history comes from the
+Prometheus named by `monitoring.prometheus` in server.yaml; without one the
+charts draw what this console has seen since it opened, and say so. Network
+and disk come from each machine's node exporter, which `llmgw node add`
+installs. **N** sends a test notification to each webhook in server.yaml's
+`notify` section and says how each answered (`llmgw ctl notify test`). A node's and a model's own pages have their charts too, over the
+same range.
+
+**Nodes** lists every node with its state, where it is (its rack, or row,
+room or site, and PDUs), load, GPUs, replicas, disk and agent version. A node
+in a held rack reads *ready, held*. On a row:
+
+- **Details** — its address, location and any hold, system, load, engines and
+  GPUs, and any warning.
+- **Cordon** places nothing new on it; **Uncordon** undoes it.
+- **Location…** sets its site, room, row, rack and PDUs (the `llmgw.io/`
+  labels), which placement spreads replicas across.
+- **Hold rack …** places nothing new in the node's rack, and can drain it;
+  **Release …** on a node in a held domain undoes it. See
+  [facility-aware-placement.md](facility-aware-placement.md).
+- **Drain** moves its replicas off one at a time, each replacement up before
+  the original stops.
+- **vllm build / sglang build** (nodes with GPUs) — which build of the engine
+  the node installs: `auto` follows its hardware, `none` installs none.
+- **Upgrade its agent** to a release; its engines keep serving.
+- **Delete model files nothing uses** frees the node's disk.
+- **Remove from the cluster** — the control plane forgets it; the machine is
+  not touched.
+
+**GPUs** is every card: how busy, its memory, temperature, power, and the
+model holding it.
+
+**Models** lists the catalog: ready against wanted, status, class, profiles,
+and **UPDATE** when the registry has new weights for it. On a row:
+
+- **Details** — description, replicas, class, owner, profiles, source, where
+  its weights came from, what it reserves against what it uses, and its
+  replicas.
+- **Replicas (scale)** — the minimum kept running, the most it scales to,
+  and for a model loaded on demand how long it may sit unused. A maximum of
+  0 stops it.
+- **Class** — critical, standard or opportunistic: whose capacity gives way
+  when there is not enough for everyone.
+- **Owner** — the organization, team or project whose capacity quota it
+  counts against.
+- **Resources** — the memory and cores one replica reserves on its node.
+- **LoRA adapters** — `name=source[@scale]`, separated by commas.
+- **Restart its replicas**, one by one or in place.
+- **Update to …** — when the repository it came from has published different
+  weights for its files: they are fetched into the mirror beside the ones in
+  use, checked, swapped in, and the replicas replaced one at a time.
+  **Go back to …** returns to the weights the update replaced.
+  **Ask the registry for new weights now** checks without waiting for the
+  next scheduled look (`mirror.update_check`, six hours by default).
+- **Try the new weights as a canary…** — instead of swapping them in, runs
+  them beside the model as `MODEL-canary`, one replica, given the share of
+  its requests you choose. With a canary running the menu has **Canary's
+  share…**, **Promote the canary…** (the model moves to its weights, the
+  canary is removed) and **Take the canary out…**. A canary that errs or
+  answers more slowly than the model is taken out by itself. The MODEL
+  column shows `(10% to canary)` and `(canary of …)`.
+- **Ask it a quality suite…** — one of the suites the control plane has (in
+  `control.eval_dir`, or built in: `arithmetic`, `json-format`), asked
+  through the router; the dialog counts the answers as they come in, then
+  shows the score, each case and the model's last runs. Esc stops watching;
+  the run carries on and is kept. **Its quality runs** lists them, as
+  `llmgw ctl eval --history` does.
+- **Hold its updates to a quality suite…** — the suite and score its new
+  weights must reach before an update or a promotion moves it to them
+  (`llmgw ctl model gate`); **none** takes it away. With one set, **Update
+  to …** and **Promote the canary…** say so.
+- **Why is it placed where it is** — `llmgw ctl explain-placement`.
+- **Try again**, for a model parked after failing every start.
+- **Remove** — its replicas stop and it leaves the catalog. A model from
+  `server.yaml` is changed there instead; the console says so.
+
+**A** on Models adds one from a definition file on this machine: the YAML a
+model takes in `server.yaml`.
+
+**Replicas** lists every replica; on one, **Restart it**, replaced or in
+place.
+
+**Usage** is the last 24 hours by team, project or organization (→ changes
+which): requests, tokens, errors and spend.
+
+**Quotas** are capacity quotas: the GPUs, cores and memory each organization,
+team or project is guaranteed and may at most hold, and what it holds now.
+**A** adds one; on a row, change or remove it.
+
+**Mirror** is what the model mirror holds, one row for each version of each
+model — a file, or the set of files a model of several is: shards, a vision
+projector, a config and tokenizer — with how far its download has got and
+which models use it. **A** downloads a URL into it; **I** imports a model
+from an Ollama on this machine into a mirror directory on this machine — the
+mirror beside the control plane — and shows the model definition to add for
+it (a mirror elsewhere: `llmgw mirror import-ollama` there); on a row, its files with
+their checksums and where each was fetched from, the source a model
+definition names for it, or remove it — with a warning when a model still
+uses it.
+
+**Jobs** lists the models being served or updated since the control plane
+started: what each is doing now — the download's progress, a replica
+starting — and whether it ended done, failed, or waiting for room on busy
+cards. The entry shows how many are running. Enter on one shows its steps.
+`llmgw ctl jobs` is the same, and `llmgw ctl jobs ID` follows one.
+
+**Logs** shows a node's agent log, newest at the bottom, errors and warnings
+coloured.
+
+## People
+
+The accounts, keys and organizations live in the store; these views read it
+and change it with the same commands as `llmgw users`, `llmgw keys` and
+`llmgw org`, so their checks and messages are the ones shown.
+
+**Accounts** — who has signed up, their state, whether they see the cluster
+dashboard, and what they belong to. **A** creates an account, already
+approved. On a row: approve one waiting, suspend or reinstate, give or take
+the cluster dashboard, add to or take out of an organization, team or
+project, their limits, a new password (their sessions close), delete, and
+**Forget them…** for a request to be forgotten (`llmgw users forget`).
+
+**API keys** — every key, its project, owner, state and last use. **A**
+issues one; the key is shown once, in the result, and never again. On a row:
+its limits, **Rotate…** — a new key with the same project, owner and limits,
+the old one working on for the overlap you give (`llmgw keys rotate`) — or
+revoke it.
+
+**Accounts** rows also have **Staff role…**:
+- `viewer` looks at every page under /admin and changes nothing;
+- `operator` also runs the cluster from them (models through the mirror, a
+  node's engines);
+- `billing` sees usage and quotas;
+- `admin` may do anything.
+
+The STAFF column shows each person's role.
+
+On **Usage**, **E** exports usage as CSV to a file on the control plane:
+by hour, day or month and any of organization, team, project, user, key and
+model.
+
+**Audit** lists every change of the last week — through `ctl`, this console
+or the /admin pages, and people's own keys and passwords — with who made
+it, through what, and how it ended. Enter shows the fields it was given,
+with anything secret taken out. `llmgw ctl audit` is the same, with filters.
+
+**Organizations** — the tenancy tree: organizations, their teams, the teams'
+projects, with members, keys and limits. **A** adds an organization. On a
+row: add a team or project inside it, rename, move, limits for the level and
+for each of its members, its capacity quota, and for a project how long
+conversations and agent notes are kept, and whether its requests are
+(**Keep requests…**: for how long, and what share), and whether they stay in
+the cluster (**Requests stay in the cluster…**: never an outside provider),
+and whether the same request is answered again from memory (**Cache
+answers…**: for how long, and whether only reproducible answers or any). **Longest key lifetime…** caps how
+long a key made there may live, and is the expiry of one made without any
+(`llmgw keys ttl`; `auth.max_key_ttl` in server.yaml caps every key).
+**Remove** takes away only something empty.
+
+Limits are requests and tokens a minute, a budget per day or month, and the
+models allowed. Each level only narrows what is above it.
+
+**Guardrails…** on a row lists the guardrail policies server.yaml defines.
+Each policy is marked in one of three ways:
+
+- attached here (✓): Enter detaches it;
+- applying from above (·): from everywhere, or from the organization or
+  team named;
+- neither: Enter attaches it.
+
+The **GUARDRAILS** column names those attached to the row itself. Policies
+narrow like limits; see [guardrails.md](guardrails.md).
+
+## Help
+
+**Manual** lists every page there is: these, the installation and operation
+guides, the configuration reference, a page for every command, the README
+and the changes in each release. On a page:
+
+| Key | Does |
+|---|---|
+| ↑ ↓, PgUp PgDn, Space | Scroll |
+| g, G | The top, the end |
+| T | Contents: the page's headings, Enter goes to one |
+| / | Find; the lines holding it are marked |
+| n, N | The next match, the one before |
+| [ ] | The topic before, the one after |
+| ← | Back to the list |
+
+`llmgw docs` opens the same manual outside the console, on any machine,
+installed or not; `llmgw docs install` opens one page; piped, it prints the
+page's text.
+
+## Settings
+
+**server.yaml** (on a node, **agent.yaml**) is every key, as a tree of menus
+built from the configuration reference: the value set, or the one that
+applies when nothing is, its type, and what it is for. Enter changes a value
+or opens a block; on a list or map of blocks, Enter opens an entry and **D**
+removes one. **U** puts a key back to its default. **S** saves.
+
+On a control plane, the cluster's keys are read from and saved to the
+cluster's settings in the store — the same on every control plane, in force
+on all of them within seconds (`llmgw ctl config` does the same from a
+shell) — and this machine's own keys (listeners, certificates, the store's
+address) to its server.yaml, which the server notices and applies by itself.
+Either is checked before anything is kept, and the file's comments survive.
+On a node, agent.yaml is read when the agent starts, so the console offers
+to restart it.
+
+## Do
+
+- **Add a node** — installs llmgw on a machine over ssh, checks it, gives it a
+  certificate and starts its agent (`sudo llmgw node add`).
+- **Replicate the store** — moves the store onto two more machines under
+  Patroni (offered only while it is not replicated).
+- **Serve a model** — Hugging Face's models: trending, most downloaded,
+  most liked or newest (**S** changes which), or **/** to search. **F**
+  switches between GGUF files, which llama.cpp runs on the CPU or a GPU, and
+  original safetensors weights, which vLLM runs on GPUs. Enter on a
+  repository plans it against the cluster as it is, before anything is
+  fetched: the model's shape is read from one file's header, or its
+  config.json, and every file is listed with the best way it runs here — on
+  one card, on several of a node's cards, across several nodes' cards over a
+  fabric (original weights only), or on a CPU node — what each card or node
+  would hold, and whether that hardware is free now. The file that suits the
+  cluster best is first, marked ★; one that fits nowhere says so. Busy is not
+  unfit: which file is best follows the hardware the cluster has, not what it
+  is running, so a file for a card that is in use is still offered for it —
+  served, it waits for the card, or with a fallback runs elsewhere until then. Choosing a
+  file offers every way it fits, best first, and what to do when that one is
+  busy: the next best way, written as a lower-priority profile so placement
+  falls back to it, or wait. A vision model offers its projector too, fetched
+  beside it and loaded with it so the model reads images. What is chosen is
+  fetched into the mirror, checked, added to the catalog and started, and a
+  replica is asked to say hello (`llmgw ctl model serve`; the plan alone is
+  `llmgw ctl model plan`).
+  `mirror.registry` points it at another registry, for a site without the
+  internet.
+- **Upgrade the cluster** to a release: this machine, then every node in turn
+  (`sudo llmgw ctl upgrade`).
+- **Restart all replicas**, one at a time.
+- **Back up now** — the store and `/etc/llmgw` into one archive
+  (`sudo llmgw server backup`).
+- **Wipe this machine** — removes llmgw's services, configuration, state and
+  users from this machine, after listing them and asking for its name
+  (`sudo llmgw wipe`; on a node too).
+- **Leave**.
+
+## The node's console
+
+On a node, `sudo llmgw` opens `agent.yaml` in the same settings view, and the
+manual. The cluster is watched and changed from a control plane.

docs/data.md

@@ -16,20 +16,38 @@ who made a request, when, how many tokens, and what it cost.
 Two features change that, and both are off until somebody turns them on for a
 named project, and neither can be turned on without also saying for how long.
 
-Nothing on the serving path leaves the cluster.
+Nothing on the serving path leaves the cluster — **unless the catalog has a
+model served outside it** (`external:` in a model definition): a request for
+that model, or one that falls back to it, sends its prompt to that provider.
+A guardrail policy with `no_store` refuses both for the scopes it covers.
+
+**Guardrails** read every prompt and answer they are configured for, in the
+gateway's own memory, to judge them. What they record — in the usage row and
+the log — is the action, the policy, the category and how long it took: never
+the text, the value that matched, or the placeholder map of a redaction. See
+[guardrails.md](guardrails.md).
 
 ## What is stored, exactly
 
 **Usage records**, one per request: the key, the project, the model asked for,
 the model that answered, prompt and completion token counts, cost, HTTP status
 and latency. No message content. The row is in `internal/store/store.go` as
-`Usage` and there is no field for text in it.
+`Usage` and there is no field for text in it. What the client chose to say
+about the request is kept with it: OpenAI's `user` field and its `metadata`
+or `x-llmgw-tags` — short strings, set by the client, for attributing spend.
+A client that puts a person's name or address there puts it in the usage
+records; the field is the client's, and so is that choice. Tags are not sent
+on to the engine.
 
 **API keys**, as SHA-256 hashes. The key itself is shown once, at creation, and
 never stored — so a leaked database hands over no working credential, and
 neither llmgw nor an administrator can recover a key somebody lost. A prefix is
 kept so a key can be identified in a listing without revealing it.
 
+**The store's own secrets**, like the one engine keys are derived from, plain
+unless `secrets.master_key` seals them — with Vault's transit engine, so that
+neither the store nor its backups hold them.
+
 **People and tenancy**: accounts, the organisation/team/project tree, and the
 limits attached to it. Passwords are hashed.
 
@@ -37,10 +55,32 @@ limits attached to it. Passwords are hashed.
 
 **Conversations and agent notes** — only for a project that asked. See below.
 
+**Kept requests** — only for a project that asked (`llmgw keys requests`):
+what each request sent the model, after the guardrails' redaction and with
+any stored conversation in it, and the answer the client got, for the hours
+it said, all of them or a share. Never under a `no_store` policy.
+
+**Batch files** — when a client uses the Batch API: the file of requests it
+uploaded (prompts) and the files the batch wrote (answers), in the store,
+until deleted (`DELETE /v1/files/{id}`) or, for what a batch wrote, until
+`router.batch.retain_days` (30) pass. Only keys of the project that made
+them can read them, and a project under a `no_store` policy cannot make
+them.
+
+**Reused answers** — only for a project that asked (`llmgw keys cache`):
+each answer that may be reused, as the client got it, and a hash of the
+request it answers, in the gateway process's memory — never in the store,
+never on disk — for the project's TTL or until pushed out by newer ones
+(`router.cache.max_bytes`), and gone with a restart. Never under a `no_store`
+policy. Forgetting a person does not reach into it; the answers age out by
+the TTL. The store keeps only the setting, and a usage record's mark that it
+was answered from the cache.
+
 ## What is not stored
 
 Prompts. Completions. Anything the model was shown or produced, unless the
-project turned on conversations or notes.
+project turned on conversations, notes or kept requests, or sent a batch.
+(Reused answers are held in memory only, as above.)
 
 The chat page in llmgw's own web interface keeps the conversation in a
 JavaScript variable in the browser. Refresh it and the conversation is gone,
@@ -86,22 +126,62 @@ your own hardware, and the answer comes back. The router talks to engines, the
 engines talk to nothing, the agents talk to the control plane. All of it is
 inside the cluster.
 
-Two things can reach outside, both started by an operator rather than by a
-request:
+Around the serving path, a cluster set up the ordinary way does reach out.
+None of it carries a prompt, an answer, a key or a user — it is software and
+public model files coming in — but a review should know each one:
 
-**Fetching weights.** When a model's `source` is a URL, the agent downloads it.
-Point that at an internal mirror and nothing leaves at all — which is also the
+**Installing engines.** Each node's agent downloads the llama.cpp build for its
+hardware from GitHub, checked against the checksum GitHub publishes, and vLLM
+(SGLang when asked) from PyPI, with `uv` from GitHub. On every node, when it
+joins and when the engine version changes.
+
+**Releases.** `llmgw node add`, `llmgw ctl upgrade` and `llmgw upgrade` fetch
+llmgw's own release binaries from the project's release server, checked against
+its signed checksums.
+
+**Fetching weights.** When a model's `source` is a URL, the agent downloads it;
+the mirror fetches what it is asked to, from Hugging Face or another URL, and
+`server init` has it fetch the starter model and the guardrails' judge. Point
+sources at the mirror and the nodes fetch only from it — which is also the
 faster arrangement, because eight nodes pulling forty gigabytes from the
 internet is a day's work and from a local mirror it is minutes. A `source` that
 is a path on disk is never fetched.
 
-**`llmgw ctl plan`.** Reads a model's architecture from huggingface.co to work
-out whether it fits your hardware. An operator command run at planning time,
-not part of serving, and not run by anything automatically.
+**The registry.** With a mirror configured, the control plane asks Hugging Face
+every six hours whether the models served from it have newer files
+(`mirror.update_check`), and `/admin/mirror` searches it. `llmgw ctl plan`
+reads a model's architecture from huggingface.co to work out whether it fits
+your hardware.
 
-There is no telemetry, no licence check, and no call home. The binary is
-static, built with `CGO_ENABLED=0`, and runs in a network with no route to the
-internet as long as the weights are already on disk.
+There is no telemetry, no licence check, and no call home.
+
+### A cluster with no way out
+
+A site with no route to the internet installs from an **offline bundle**
+instead, and then nothing at all leaves the cluster (docs/install.md, "Offline
+sites"). The bundle is made on a machine that has internet — llmgw's release
+binaries with their signed checksums, the llama.cpp builds with the checksums
+GitHub publishes, the model files with the checksums Hugging Face publishes,
+each checked as it is downloaded — carried in, and imported into the mirror.
+With `offline.mirror` set in `server.yaml`, nodes install engines from the
+mirror and never from GitHub, releases come from the mirror, and the registry
+is not asked about newer weights.
+
+Verification is not weakened by any of this. A release is held to the project's
+signing key wherever it is fetched from. An engine file is held to the checksum
+recorded when the bundle was made, which the control plane keeps and hands each
+node over the agent's authenticated connection: the mirror serves plain HTTP,
+and nothing a node runs is taken on the mirror's word. The bundle itself is
+checked against the sha256 its maker printed, carried to the site apart from
+the bundle.
+
+What does not come in a bundle: vLLM and SGLang, which are Python environments
+from PyPI — an offline node serves with llama.cpp unless one is installed on it
+by hand — and the operating system's own packages (the OpenMP runtime the
+engine needs, PostgreSQL when chosen), which come from the machines' package
+sources: at an offline site, the distribution mirror it already has. Searching
+the registry from `/admin/mirror` and `llmgw ctl plan` need the internet and
+do not work offline; `mirror.registry` can point the first at an internal copy.
 
 ## What the software cannot do for you
 
@@ -131,3 +211,29 @@ touch, whatever the catalog says.
 | Scope is part of the lookup | `internal/store/threads.go`, `Thread` |
 | Deletion is a client endpoint | `internal/router/threads.go`, `handleDeleteThread` |
 | Weight fetching is the only serving-path egress | `internal/agent/weights/fetch.go` |
+
+## Forgetting a person
+
+`llmgw users forget <email> --yes` (or **Forget them…** in the console) is for
+a request to be forgotten:
+
+- their usage — every request record and every sum — is kept, so totals and
+  budgets stay true, but under a random pseudonym that links to nothing;
+- their kept requests (`keys requests`), personal files and batches, and
+  their own limits are deleted;
+- their email and id are taken out of the audit log, which keeps what was
+  done;
+- then the account goes, as `users delete` removes it: sessions ended, keys
+  revoked and left without an owner.
+
+Conversations and agent notes belong to projects, not to the people in them,
+and are not touched: a project forgets them by its retention, and a thread by
+`DELETE /v1/threads/{id}`. Backups taken before still hold everything until
+they age out; that is what their retention is for.
+
+## Keeping a project's requests in the cluster
+
+`llmgw keys residency --project <path> --in-cluster` refuses the project's
+keys any model served by an outside provider, and never uses one for them as
+a fallback or a canary: their prompts do not leave the machines the cluster
+runs on. `--anywhere` lifts it.

docs/development.md

@@ -1,8 +1,9 @@
-# Quickstart: one machine, one model, ten minutes
+# Development: llmgw from source on one machine
 
 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.**
+workstation, built from source, with no systemd and no `sudo` — for working on
+llmgw itself. **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.
@@ -26,7 +27,7 @@ make test
 ./bin/llmgw --version
 ```
 
-`make build` writes `./bin/llmgw`. Go 1.26 or later is the only requirement.
+`make build` writes `./bin/llmgw`. Go 1.26.6 or later is the only requirement (an older Go fetches it itself).
 
 ## 2. Check the path with a fake engine
 

docs/facility-aware-placement.md

@@ -0,0 +1,400 @@
+# Facility-aware placement: rack power, temperature and cooling
+
+**Status: steps 0, 1 and 2 are built, with the manual hold of step 4;
+temperature conditions (steps 3 and 4) and shedding (step 5) are not**,
+until the thermal data of a real site is at hand — without it thresholds would
+be designed against guesses. This is the design for step 5 of resource
+allocation, after reserved CPU cores and memory (1), capacity classes and
+preemption (2), tenant capacity quotas (3) and sizing by measured throughput
+(4). [What is built](#what-is-built) says what works today and where it
+departs from the design below; the rest of the document is the design.
+
+## What is built
+
+**Where a node is.** Five labels: `llmgw.io/site`, `room`, `row`, `rack` and
+`pdu` (a comma separated list, for a dual-fed rack). They come from the node's
+`agent.yaml` under `labels:`, or from the control plane:
+
+```
+llmgw ctl label gpu01 llmgw.io/rack=r12-07 llmgw.io/pdu=r12-07-a,r12-07-b
+llmgw ctl label gpu01 llmgw.io/rack-        # back to agent.yaml's value, if any
+```
+
+Labels set with `ctl label` are kept in the store, win over the agent's, and
+may be set before the node joins. A misspelt `llmgw.io/` key is refused. A
+domain is named `level:name` — `rack:r12-07`, `pdu:r12-07-a` — and names are
+taken as given, so two rooms that both have a rack `r1` must label them apart.
+A node without location labels is in no domain and places as it always did.
+
+**Spreading.** A model's next replica goes first to a node sharing no rack and
+no PDU with the nodes the model already runs on; nodes sharing fewer come
+before nodes sharing more. It is an ordering, never a filter: a rack holding
+the only free cards still takes the replica. It ranks above preferring a node
+that already holds the weights — a second replica one breaker away from the
+first is worth less than the copy saved — and above bin packing.
+
+**Keeping a replica together.** A profile's `keep_within: rack` (or `row`,
+`room`, `site`) keeps a multi-node replica's nodes in one such domain, inside
+the fabric or NVLink domain placement already requires; nodes without the
+label are passed over for it, with the reason.
+
+**Holds.** `llmgw ctl facility hold rack:r12-07 --reason "PDU swap"` places
+nothing new in the domain, as a cordon of each of its nodes would, including
+nodes labelled into it later. `--drain` also drains its nodes, one replica at
+a time with the replacement up first; `llmgw ctl facility release` undoes
+both. Holds are kept in the store across restarts (the drain itself is node
+state, which is not: after a restart the hold still keeps work out, and
+replicas not yet moved stay where they are). Any domain can be held: a PDU
+holds every rack on it.
+
+**Power budgets.** In `server.yaml`:
+
+```yaml
+facility:
+  margin: 0.1            # share of every cap kept free
+  gpu_watts: 700         # a card that reports no power limit
+  cpu_core_watts: 10     # a core reserved by a CPU replica (cpu_cores)
+  node_watts: 350        # each node's own draw beyond its cards
+  budgets:
+    - domain: rack:r12-07
+      cap_watts: 16000   # what one feed carries alone, derated
+      other_watts: 800   # switches, storage
+    - domain: pdu:r12-07-a
+      cap_watts: 7400
+```
+
+A replica's draw is the profile's `power_watts` (split over its nodes) when
+declared; otherwise each card at the power limit it reports through the agent's
+sensors (or `gpu_watts`), and each reserved core at `cpu_core_watts`. A
+domain's use is, node by node, `node_watts` plus the larger of what is placed
+there and what the node's sensors read in the last two minutes
+(`measured_fresh`), plus the domain's `other_watts`. A shard that would take
+any of its node's domains past `cap × (1 − margin)` is refused; a multi-node
+replica's shards are counted together, so two that each fit a rack alone do not
+both go into it. A draw nobody knows — no declared figure, no card limit, no
+`gpu_watts` — counts as nothing: missing data never blocks.
+
+**What people see.** `llmgw ctl explain-placement` names the domain: *rack
+r12-07 is held: PDU swap*, *rack r12-07: 14.2 kW of a 14.4 kW limit (16.0 kW
+cap less 10%) in use, the shard needs ~2.8 kW*. The rejections of a placed
+replica are kept too, so a replica in an unexpected rack says why. `llmgw ctl
+nodes` has a LOCATION column, shows *ready, held*, and filters with `--domain
+rack:r12-07`. `llmgw ctl facility` lists every domain with its nodes, use,
+limit, reserved and measured draw, and holds. The console's Nodes view has a
+WHERE column; a node's page shows its location and hold, and its menu sets
+the location (**Location…**) and holds or releases its rack. The admin API:
+`GET /api/v1/facility`, `POST /api/v1/facility/holds`, `DELETE
+/api/v1/facility/holds/{domain}`, `POST /api/v1/nodes/{id}/labels`.
+
+**Where it departs from the design below, and why.**
+
+- Domains come from labels alone; there is no facility file declaring them.
+  Budgets are in `server.yaml`, the one file the control plane already reads.
+  A DCIM export would generate that block.
+- Feeds are not modelled. The cap given is what one feed carries alone,
+  derated — the figure the design says matters — so the operator gives the
+  one number instead of llmgw deriving it from two.
+- The manual hold of step 4 is built now, without conditions: it needs no
+  sensor data and answers the commonest facility event, planned maintenance.
+  Its command is `ctl facility hold`, with a `--drain` the design did not have.
+- `keep_within` is new: the request that a multi-node replica stay in one rack
+  where the cabling requires it.
+- Spreading is an ordering of candidates, not the scoring of the design; power
+  headroom does not yet order racks ("level load across racks"), and
+  multi-node replicas are not spread across racks.
+- No `llmgw_domain_*` metrics or alerts yet; `ctl facility` and the API carry
+  the same figures.
+
+## Why
+
+In a large installation the scarce thing is often not a GPU but the room it
+sits in. Three failures are invisible to placement today:
+
+- **A rack goes over its power budget.** Every node in it reports healthy;
+  placement sees free cards and fills them; the breaker, or the facility's
+  power cap, decides the rest. A rack with A and B feeds is worse: it runs
+  fine until one feed fails and the other cannot carry the load.
+- **Hot hardware is slow hardware.** GPUs throttle long before they fail. A
+  replica placed in a rack whose inlet air is too warm serves fewer tokens per
+  second than its measured capacity says, and nothing connects the two.
+- **Correlated failure.** Two replicas of a model on two nodes in the same rack
+  or on the same PDU are one failure away from zero. Placement spreads replicas
+  across nodes, not across racks.
+
+The goal is for placement to treat facility limits the way it already treats
+memory and cores: reserve against a budget, refuse what does not fit, say why,
+and never let missing data stop the cluster.
+
+## What it builds on
+
+| Already in place | Used for |
+|---|---|
+| Node labels, reported by agents, matched by `node_selector` | Where a node is: its rack, row, PDU |
+| `inventory.Allocation` carries GPUs, memory and cores per shard | Adding watts, summed per rack and PDU |
+| Placement rejections (`explain-placement`, headroom's "why not") | Naming the rack that is full or hot |
+| Headroom: the scheduler dry-run on a copy of the inventory | Room that respects power budgets, for free |
+| Preemption with classes, minimums and a dry run (step 2) | Shedding load from a hot rack in the right order |
+| Measured throughput per profile (step 4) | Tokens per watt as a placement preference |
+| Node sensors, read by every agent (step 0, built) | Heat and power with no facility integration: see below |
+| `internal/promq`, a Prometheus client | Reading facility metrics that DCIM exporters publish |
+
+## Concepts
+
+**Location.** Each node has a place in a tree: site, room, row, rack. Power has
+its own tree beside it: a rack draws from one or more PDUs, and each PDU from a
+feed. Both are read from node labels with well-known keys:
+
+```yaml
+# agent.yaml
+labels:
+  llmgw.io/site: sto1
+  llmgw.io/room: hall-b
+  llmgw.io/row: "12"
+  llmgw.io/rack: r12-07
+  llmgw.io/pdu: r12-07-a,r12-07-b   # both feeds, for a dual-fed rack
+```
+
+A node without these labels is its own rack of one: placement behaves as it
+does today.
+
+**Domain.** A rack, a row, a PDU, a room: anything with a budget or a
+condition. Domains are declared in a facility file (below) or discovered from
+node labels; a label naming a domain the file does not declare creates it with
+no budget and no condition.
+
+**Budget.** A domain may have a power cap in watts. Placement reserves each
+replica's estimated draw against every domain its node belongs to and refuses a
+placement that would take any of them past its cap less a safety margin. For a
+dual-fed rack the cap that matters is what one feed can carry alone, since that
+is what the rack must survive.
+
+**Condition.** A domain has a thermal and cooling condition: `ok`, `warm`, `hot`
+or `unknown`, derived from readings against thresholds with hysteresis.
+Conditions change what placement prefers and allows; they are not amounts to
+fill.
+
+**Reading.** A measured value with a time: inlet temperature, power draw, a
+cooling unit's alarm state. Readings older than their staleness limit are
+treated as absent.
+
+## Estimating a replica's draw
+
+What placement reserves has to be known before the replica runs, so it is an
+estimate first and a measurement later:
+
+1. **Declared.** A profile may say `power_watts`. The operator's figure wins.
+2. **Derived.** Otherwise GPU profiles take each card's power limit from NVML
+   (the agent already reads the cards; the power limit is one more field) plus
+   a per-node share for CPU, memory and fans; CPU profiles take their reserved
+   cores times a per-core figure for the node's CPU model.
+3. **Measured.** Once replicas run, the agent reports their cards' actual draw
+   (NVML) and, where the BMC allows, the node's (Redfish or IPMI DCMI). A
+   domain's headroom is computed from the larger of what is reserved and what
+   is measured, so an estimate that was too low is corrected by the room it
+   stops offering, not by an outage.
+
+## Decisions
+
+### Power
+
+- **Hard limit.** A placement that would take any domain past `cap × (1 −
+  margin)` is rejected, with the domain and the figures: *rack r12-07: 14.2 of
+  16.0 kW reserved, replica needs ~2.8, margin 10%*.
+- **Feeds.** For a domain with two feeds the cap is the smaller feed's rating
+  times its derating (typically 80%), not the sum.
+- **Already over.** A domain found over its cap, because the estimate was low
+  or the cap was lowered, gets no new placements, and an alert. It is not
+  emptied automatically; shedding power is the facility's decision, and
+  stopping inference to do it is ours only if asked (see shedding below).
+
+### Temperature and cooling
+
+Thresholds are per domain with defaults, and each condition needs to hold for a
+while before it changes, in both directions, so a single reading neither
+starts nor ends anything:
+
+| Condition | Enters when | Placement |
+|---|---|---|
+| `ok` | below the warm threshold for 5 min | normal |
+| `warm` | inlet above the warm threshold for 2 min, GPU temperatures near throttling, or any GPU thermally throttled | allowed, scored down: other domains first |
+| `hot` | inlet above the hot threshold for 2 min, a cooling unit in alarm, or a sustained share of the domain's GPUs thermally throttled | no new placements, as a cordon would, but automatic and reversible |
+| `unknown` | no fresh reading | as `ok`, and reported as unknown |
+
+**Shedding** (optional, off by default): a domain `hot` for longer than its
+shed delay has load moved off it using step 2's machinery. The lowest class goes
+first, and replicas above their model's minimum go before any at it. A critical
+minimum is never touched, and moves are rate limited to one replica per domain
+per interval. The replica is placed elsewhere first where there is room, so
+shedding moves work rather than dropping it. GPU power capping (`nvidia-smi
+-pl`) is a gentler alternative worth measuring against shedding: less
+throughput, no restart.
+
+### Spreading
+
+Replicas of one model are spread across racks, and across PDUs, the way they
+are spread across nodes today. This is a preference, dropped when it is the only
+thing standing in the way, as node spreading already is.
+
+### Scoring
+
+Placement today filters, then takes the first candidate in a fixed order
+(fewest free GPUs for GPU profiles, fewest replicas for CPU ones, nodes holding
+the weights first). Facility signals are better as a score than as more
+filters. Candidates that pass the hard limits are ordered by:
+
+1. condition: `ok` before `warm`;
+2. power headroom left in the rack after this replica, more first, so load
+   levels across racks;
+3. the existing order.
+
+Once measurements include power, step 4's profile preference can use tokens per
+watt instead of tokens per GPU where both are known.
+
+## Where the data comes from
+
+A `FacilitySource` interface, implemented several ways, chosen in
+`server.yaml`:
+
+```go
+type FacilitySource interface {
+    // Domains is what the source knows: budgets, thresholds, members.
+    Domains(ctx) ([]Domain, error)
+    // Readings is the latest value of each signal, per domain.
+    Readings(ctx) ([]Reading, error)
+}
+```
+
+- **Static file.** Domains, caps and thresholds, written by hand or generated
+  from a DCIM export. Enough for power budgets with no live data at all.
+- **Prometheus.** DCIM, PDU (SNMP exporter) and BMC (Redfish exporter)
+  readings usually end up in Prometheus. The source runs configured instant
+  queries and maps their labels onto domains:
+
+  ```yaml
+  facility:
+    source: prometheus
+    prometheus: http://monitoring:9090
+    signals:
+      inlet_temp_c:
+        query: max by (rack) (dcim_rack_inlet_temperature_celsius)
+        domain_label: rack
+        stale_after: 2m
+      power_watts:
+        query: sum by (pdu) (pdu_outlet_power_watts)
+        domain_label: pdu
+      cooling_alarm:
+        query: max by (row) (crac_alarm)
+        domain_label: row
+  ```
+- **Agents (built, step 0).** What each node reads about itself, every ten
+  seconds at most, sent with its heartbeat:
+  - **GPUs, from nvidia-smi:** temperature, memory (HBM) temperature where the
+    driver reports it, power draw, the enforced power limit, and what is
+    holding the clocks down now — `sw_power_cap`, `hw_slowdown`, `sw_thermal`,
+    `hw_thermal`, `power_brake`.
+  - **CPUs, from hwmon** (what lm_sensors reads, without it installed): the
+    package temperature, or the hottest core; and the board's inlet or ambient
+    sensor where it has one (`SYSTIN`, `Inlet`, `Ambient`).
+  - **CPU power, from RAPL:** the packages' energy counters over time,
+    subdomains not counted twice, counter wrap handled.
+
+  A machine without a sensor reports nothing for it, never a zero; a VM has
+  none of them. Published as `llmgw_gpu_temperature_celsius`,
+  `llmgw_gpu_memory_temperature_celsius`, `llmgw_gpu_power_watts`,
+  `llmgw_gpu_power_limit_watts`, `llmgw_gpu_throttled{reason}`,
+  `llmgw_node_cpu_temperature_celsius`, `llmgw_node_cpu_power_watts` and
+  `llmgw_node_inlet_temperature_celsius`, and on each node's page.
+
+  What they can and cannot say:
+  - **Throttling is the strongest signal there is.** A temperature is a proxy;
+    a card holding its clocks down is the fact that invalidates its measured
+    capacity, and it needs no threshold to be chosen.
+  - **Measured power** is GPU draw plus CPU packages; memory, disks, fans and
+    power-supply losses are not in it, so a node's draw is that plus an
+    estimated remainder. A rack's is its llmgw nodes' plus a declared figure
+    for everything else in it: switches and storage report nothing here.
+  - **CPU and GPU temperatures follow the load, not the room.** A hot rack is
+    inferred from many nodes running hot at comparable load, or from
+    throttling, not from one node's CPU. Only a board inlet sensor reads the
+    air, and most boards have none.
+  - **No budget comes from a sensor.** A reading is a draw; the cap it is
+    measured against still comes from the facility.
+- **Simulated.** Readings from a script, for tests and for rehearsing a
+  thermal event on a cluster without facility data.
+
+## Safety
+
+- **Missing data never blocks.** A source that is down, a reading that is stale,
+  a node without location labels: placement behaves as it does today, and says
+  the data is missing (a metric, a line on the cluster page). Facility
+  awareness can make placement more careful, never impossible.
+- **Hysteresis and hold times** on every condition, so a noisy sensor does not
+  flap a rack between allowed and forbidden.
+- **Observe-only first.** A mode where every decision is computed, logged and
+  shown ("would have refused: rack r12-07 hot") but nothing is enforced, run
+  for long enough to trust the thresholds before turning enforcement on.
+- **Manual override.** `llmgw ctl facility hold RACK` and `release RACK`, for the
+  facility team to mark a domain unavailable, or to clear a condition they know
+  to be a sensor fault.
+- **Shedding is opt-in**, per domain or cluster-wide, and rate limited.
+
+## What people see
+
+- `explain-placement` and headroom name the domain: *rack r12-07 is hot (inlet
+  31°C for 6 min)*, *pdu r12-07-a: 7.1 of 7.4 kW*.
+- `llmgw ctl facility` lists domains with budget, reserved, measured and
+  condition. The cluster page gets a rack summary beside the nodes table.
+- Metrics: `llmgw_domain_power_budget_watts`, `_reserved_watts`,
+  `_measured_watts`, `llmgw_domain_condition{condition}`,
+  `llmgw_domain_reading_age_seconds`; alerts for a domain near its cap, a
+  domain hot, a domain over its cap, and facility data gone stale.
+
+## Rollout
+
+Each step ships on its own and is useful without the next:
+
+0. **Node sensors, observe-only (built).** GPU heat, power and throttling,
+   CPU heat and power, inlet air where the board has a sensor; published and
+   shown, no decision changed.
+1. **Location and spreading (built).** Well-known labels, domains from labels, replicas
+   spread across racks and PDUs, locations on the node views. No facility data
+   needed.
+2. **Power budgets from a static file (built, without headroom
+   scoring).** Caps and margins, estimated draw per
+   replica (declared or derived), hard limit in placement and headroom.
+3. **Readings, observe-only.** The Prometheus source beside the agents',
+   conditions with hysteresis (throttling first among them), measured power
+   folded into headroom; decisions shown, not enforced.
+4. **Thermal enforcement.** `warm` scored down, `hot` refused; the manual hold
+   and release are built.
+5. **Shedding and tokens per watt.** Opt-in shedding through step 2's
+   preemption; measured power in profile preference.
+
+## Testing
+
+- The simulated source drives unit tests of every condition transition, the
+  hysteresis, staleness, and the placement outcomes, with mutation checks as
+  for steps 1–4.
+- Property tests: whatever the readings, placement never exceeds a declared
+  cap with fresh data, and never refuses everything because data is missing.
+- On the PoC cluster, with no facility data: step 1 with labelled VMs, step 2
+  with a static file of made-up caps, steps 3–4 with the simulated source
+  replaying a thermal event.
+- Before enforcement anywhere real: a period in observe-only mode against the
+  site's actual data.
+
+## Open questions
+
+- **What the sites have.** Which DCIM, which PDUs, which BMCs, and whether any
+  of it already reaches a Prometheus. The source design assumes Prometheus is
+  the common ground; a site without it needs another source.
+- **Who owns the numbers.** Caps, deratings and thresholds belong to the
+  facility team. Whether they edit llmgw's file, or llmgw reads theirs.
+- **Phase balance.** Three-phase PDUs have per-phase limits; whether placement
+  should see phases or only the PDU total.
+- **Cooling granularity.** Cooling is often per row or per aisle, not per rack;
+  the domain tree allows either, but the defaults should match what sites
+  actually measure.
+- **Power capping instead of shedding.** Whether to lower GPU power limits in a
+  warm rack rather than move replicas, and how that interacts with measured
+  capacity from step 4, which would no longer hold at the lower limit.

docs/guardrails.md

@@ -0,0 +1,334 @@
+# Guardrails
+
+Written for the operator deciding what the gateway lets through: what a
+policy can check, what it can do, and how one is attached to a team.
+
+`llmgw server init` writes a `baseline` policy that applies to every
+request, with Qwen3Guard-Gen 0.6B as its judge on CPUs; see
+[install.md](install.md#2-the-control-plane) for what it checks. The
+policies are part of the cluster's settings, kept in the store: `llmgw ctl
+config edit` (or the console's Settings) changes them, and the change is in
+force on every control plane within seconds, without a restart. A cluster
+whose settings were brought in from a server.yaml without a `guard:` section
+gets the `baseline` policy, without a judge. With no policies, nothing is
+checked and nothing costs anything. With one, every request is judged once it is authorised and
+within its limits, with its stored conversation spliced in, and before it is
+sent to a model; and the answer is judged before the client sees it.
+
+## Turning them off and on
+
+```
+llmgw ctl guard off --note "why"   # no request is checked, whatever the policies say
+llmgw ctl guard on                 # every policy checks again, as it was
+```
+
+That is `guard.enabled` in the cluster's settings, in force on every control
+plane within seconds without a restart. The policies and where they are
+attached are kept. While off, `llmgw ctl status`, `llmgw ctl guard list` and
+the guardrails page say so. To stop one policy rather than all, give it
+`mode: off`, or `mode: shadow` to have it record what it would do.
+
+## A policy
+
+```yaml
+guard:
+  # Applied to every request.
+  default: [baseline]
+  policies:
+    baseline:
+      input:
+        pii: {secret: block, card: redact}
+        injection: flag
+      output:
+        pii: {secret: block}
+    finance:
+      mode: enforce          # enforce (default), shadow, off
+      fail: closed           # open (default) or closed, for checks that can fail
+      no_store: true         # no conversations, notes, prefix routing or external models
+      max_output_tokens: 2048
+      system_prompt: "You answer questions about Acme's products only."
+      drop_client_system: true
+      stream: sentence       # sentence (default) or buffer_all
+      require_capabilities: true   # no tools/images to models whose catalog entry lacks them
+      validate_structured: true    # answers must fit response_format's json_schema
+      input:
+        pii: {email: redact, phone: redact, iban: block, tckn: redact}
+        injection: block
+        max_chars: 40000
+        deny:
+          - {name: codename, regex: "(?i)project falcon", action: block}
+      output:
+        pii: {iban: redact, tckn: redact, secret: block}
+      tools:
+        allow: [search, fetch]
+        deny: [shell]
+        on_denied: strip     # strip (default) or block
+        max_calls_per_turn: 4
+        validate_arguments: true
+```
+
+**What is found.**
+
+- **Personal data:** email, phone, iban, card, tckn, ip. Each is checked
+  before it counts: IBANs by their mod-97 check, cards by Luhn and issuer
+  prefix, TCKNs by their two check digits, phone numbers only when written
+  to be dialled (`+90…`, `00…`, `0532…`).
+- **Secrets** (`secret`): OpenAI- and Anthropic-style keys, AWS access key
+  ids, GitHub, Slack and Google tokens, JWTs, PEM private keys and llmgw's
+  own keys.
+- **Prompt injection:** instructions to drop instructions (English and
+  Turkish), chat-template control tokens in user text, invisible Unicode,
+  long encoded blobs. These are found through disguises: fullwidth letters,
+  Cyrillic look-alikes, zero-width characters, and base64, hex and URL
+  encoding two levels deep.
+- **`deny` patterns:** matched against the text as written, and as a model
+  reads it once those disguises are removed.
+
+**What is done.**
+
+- **`flag`** lets the request through and records it.
+- **`redact`** rewrites the value as a placeholder (`[EMAIL_1]`; the same
+  value is the same placeholder throughout a request).
+- **`block`** stops it.
+
+**Shapes.**
+
+- `system_prompt` is put first.
+- `drop_client_system` removes the caller's own system and developer
+  messages.
+- `max_output_tokens` is set where a request asks for none, and lowers one
+  that asks for more.
+- A tool `deny`/`allow` list strips the tool from the request, or refuses
+  it.
+- In the answer, a call to a tool that is not allowed, more calls than
+  `max_calls_per_turn`, or arguments that do not fit the parameters the
+  request declared (`validate_arguments`) stop it.
+- `require_capabilities` refuses tools offered to a model whose catalog
+  entry does not say `capabilities.tools`, and images to one without
+  `capabilities.vision`. It is opt-in because an entry that says nothing is
+  read as "cannot".
+- `validate_structured` checks an answer against the `json_schema` the
+  request asked for in `response_format`. Buffered, or streamed with
+  `buffer_all`, an answer that does not fit is stopped; streamed a sentence
+  at a time it has gone out already, and is flagged.
+
+## A judge model
+
+Patterns find what has a shape. For what does not — violence, crime,
+sexual content, self-harm, jailbreaks, whatever a moderation model was
+trained on — a policy can have a **judge model on the cluster** read the
+text.
+
+The judge must be in the catalog under the name the policy gives, as a
+judge (`role: guard`), with a replica ready. When it is not, what the
+policy judges is refused with `guard_unavailable` (`fail: closed`) or served
+unjudged (`fail: open`), and `llmgw ctl status` and the console's Overview
+say which judge and why.
+
+### Which judge
+
+| judge | runs on | size | |
+|---|---|---|---|
+| `qwen3guard-0.6b` | CPUs | 0.8 GB | the default: about 2 s a check on two threads |
+| `qwen3guard-4b` | a GPU | 2.5 GB | for a cluster with a card to spare |
+| `qwen3guard-8b` | a GPU | 4.7 GB | |
+| `llama-guard-3-1b` | CPUs | 0.9 GB | the earlier default: refuses ordinary coding requests |
+| `llama-guard-3-8b` | a GPU | 4.6 GB | |
+
+Measured on the reference cluster, as the judge's probability of "unsafe"
+for ordinary coding requests against harmful ones, Llama Guard 3 1B could
+not tell them apart: "continue" 0.51, "continue the code above" 0.89, "how
+do I kill all child processes in bash" 0.92, against 0.97 to 1.00 for
+harmful requests, at any quantisation. Qwen3Guard-Gen 0.6B gave the
+ordinary ones 0.15 at the most and the harmful ones 1.00. Its verdicts are
+safe, unsafe and **controversial**; controversial counts as safe unless the
+policy says `controversial: unsafe`.
+
+A policy that names one of these is enough: the leader fetches its weights
+into the mirror and serves it as a judge, and serves it again if it is
+removed from the catalog. Another judge is served by hand with `--repo`.
+
+```
+llmgw ctl guard judge status              # each judge the policies ask, and what is wrong with it
+llmgw ctl guard judge enable              # Qwen3Guard-Gen 0.6B on CPUs, or the judge the policies ask that is missing
+llmgw ctl guard judge enable --gpu        # Qwen3Guard-Gen 4B on a GPU
+llmgw ctl guard judge use qwen3guard-4b qwen3guard-0.6b   # the order every policy asks them in
+llmgw ctl guard judge enable --replace    # when a model of that name is there, but not as a judge
+```
+
+or **Do → Serve the guardrails' judge** in the console.
+
+### A GPU and CPUs together
+
+`judge.models` is a list asked in turn: the first judge that answers gives
+the verdict. The next is asked when one has no replica serving, fails, or
+does not answer within `latency_budget`; a judge with no replica at all is
+passed over at once. A judge on a GPU first and one on CPUs after it is
+the GPU's speed while it has its card, and the CPUs' when it does not.
+
+```yaml
+judge:
+  models: [qwen3guard-4b, qwen3guard-0.6b]
+  input: block
+  output: block
+  latency_budget: 5s           # each judge's wait
+```
+
+A judge on a GPU is served as a `standard` model, on one card: it takes a
+card only from what may give one up, and waits while every card is busy,
+the judge on CPUs standing in. A judge on CPUs is `critical`, with two
+replicas, because every judged request waits on one. `llmgw ctl guard judge
+status` says, for each judge, which is asked when it gives no verdict.
+
+### When it refuses ordinary requests
+
+A refusal by a judge names the hazard it saw — the client is told `refused
+by the gateway's policy (judge: Violent)` — and the same is kept with the
+request: `llmgw ctl request <id>`, the server's log (`guard_rule`) and the
+guardrails page show it. To see what the judge says of any text, without
+anything being kept:
+
+```
+llmgw ctl guard judge ask 'How do I sort a list in Python?'
+# qwen3guard-0.6b: safe, 1900 ms
+# it answered: "Safety: Safe\nCategories: None"
+```
+
+A judge that says `unsafe` to ordinary text is usually Llama Guard 3 1B
+(`llmgw ctl guard judge use qwen3guard-0.6b`), the wrong weights (another
+repository's, without the judge's template: `judge enable --replace` serves
+the right ones), or a policy counting every category: give its judge
+`categories`. The baseline counts Violent, Non-violent Illegal Acts, Sexual
+Content or Sexual Acts, Suicide & Self-Harm and Jailbreak; PII is the
+patterns', and copyright, unethical acts and politically sensitive topics
+refuse too much ordinary work. While finding out, `judge.input: flag`
+records instead of refusing.
+
+A judge's file served from the mirror page — Llama Guard, Qwen3Guard,
+ShieldGemma — is served as a judge too, under the name the policies ask.
+By hand, the catalog entry is:
+
+```yaml
+# a catalog model (server.yaml models:, or ctl model add)
+- name: qwen3guard-0.6b
+  source: http://mirror:8081/qwen3guard-0.6b/…/Qwen3Guard-Gen-0.6B.Q8_0.gguf
+  role: guard
+  guard:
+    format: qwen3guard         # qwen3guard, llamaguard3, shieldgemma or json
+  scaling: {min: 2, max: 2}
+  profiles: [{name: cpu, engine: llamacpp}]
+
+# in a guard policy
+judge:
+  models: [qwen3guard-0.6b]    # or model: one judge
+  input: block                 # flag or block; empty does not ask about input
+  output: flag
+  categories: [Violent, Jailbreak]   # only these count; empty: any unsafe verdict
+  controversial: safe          # or unsafe
+  latency_budget: 250ms        # each judge's wait; after the last, fail: open serves (flagged), closed refuses
+```
+
+A model with `role: guard` is the guardrails' alone:
+
+- it is not in `/v1/models` or the chat page, and is refused (404) to
+  every key, as a name and as a fallback;
+- it must always run — on demand is refused. One on CPUs is `critical`
+  and should have two replicas on different nodes, because every judged
+  request waits on it.
+
+The gateway's calls to it go past admission, accounting and the guardrails
+themselves.
+
+- **Formats:**
+  - `qwen3guard` asks in Qwen3Guard's own words and reads "Safety: Safe |
+    Unsafe | Controversial" and its "Categories:".
+  - `llamaguard3` reads Meta's "safe" / "unsafe\nS1,S10"; give the catalog
+    entry `categories` to have S1 recorded as its name.
+  - `shieldgemma` asks Google's model whether the text breaks the listed
+    principles (`categories`, each a sentence) and reads Yes or No.
+  - `json` expects `{"safe": false, "categories": [...]}`.
+- **What is read:**
+  - **Input:** the request's last user turn, after the patterns.
+  - **Output:** the answer, together with that user turn. A streamed answer
+    is read every 600 characters and at the end, so text between two
+    readings has gone out already; `stream: buffer_all` holds it until it
+    is read.
+  - **A long text** is read by its start and its end (about 6000
+    characters), so a message with a file pasted into it fits the judge's
+    context rather than overflowing it and going unjudged.
+- **Cache:** the same text is not asked about twice within five minutes.
+
+## Where a policy applies
+
+`guard.default` applies everywhere. Others are attached to a part of the
+tenancy tree, and apply to everything below it:
+
+```
+llmgw ctl guard attach project:Acme/finance/payroll finance
+llmgw ctl guard attach key:key-7f3a baseline
+llmgw ctl guard list
+llmgw ctl guard detach project:Acme/finance/payroll finance
+```
+
+Policies narrow, as limits do. A policy attached lower can tighten what
+applies above it, never loosen it. Combined, they take:
+
+- the strictest mode and failure;
+- for each kind, the strictest action;
+- every deny pattern and denied tool;
+- only the tools every allow list allows;
+- the smallest limits;
+- `no_store` if any of them asks;
+- every pinned prompt, widest first.
+
+An attachment applies at once.
+
+## What a client sees
+
+**A refused request** is answered with 400:
+
+```json
+{"error": {"type": "invalid_request_error", "code": "content_policy_violation",
+           "message": "this request was refused by the gateway's policy (secret)"}}
+```
+
+It names the category, never the text, and costs nothing.
+
+**A stopped answer** ends with `finish_reason: "content_filter"`. A stream
+ends with that chunk and `[DONE]`, and the engine is cancelled. The
+Responses API reports it as `incomplete` with
+`incomplete_details.reason: "content_filter"`.
+
+**Headers:** `x-llmgw-guard` (`flagged`, `redacted`, `blocked`) and
+`x-llmgw-guard-policy` say what was done.
+
+**Streams.** A streamed answer is judged a sentence at a time. Text is held
+until a sentence, a line or 200 characters ends, released up to its last
+whitespace — so a value still arriving is never sent in two halves — and
+rewritten if needed. **What was released cannot be taken back**: a policy
+that must never let a word through uses `stream: buffer_all`, which holds
+the whole answer until it is judged.
+
+## Shadow mode
+
+`mode: shadow` judges and records — the usage row says `shadow-blocked`,
+`shadow-redacted` — and changes nothing. Run a new policy in shadow first,
+and read what it would have done before enforcing it.
+
+## What is recorded
+
+Each request's usage row has the action, policy, category and the time the
+checks took. The access log has the action, stage and policy. Neither has
+the text, a matched value, or the placeholder map: the map exists only in
+the gateway's memory while the request is served.
+
+## In the console
+
+`sudo llmgw` has a **Guardrails** view: each policy with its mode, what it
+does when it cannot judge, and what it checks; whether each judge model it
+leans on has replicas ready — a policy that fails closed refuses everything
+while its judge has none; where policies are attached, with A to attach one
+and Enter on a row to detach it; and what they did in the last day (W for an
+hour or a week), totals first and the newest requests after, each with the
+request id `llmgw ctl request` reads. The same is at `GET /api/v1/guard` and
+`GET /api/v1/guard/events?since=24h`, and on the portal's Guardrails page.

docs/kubernetes.md

@@ -0,0 +1,228 @@
+# llmgw and Kubernetes
+
+The control plane runs in Kubernetes, from the Helm chart in
+`deploy/helm/llmgw`. The GPU nodes do not: they stay ordinary machines,
+joined with `llmgw node add` as on any other cluster. This page says why,
+and how the two meet.
+
+## What goes where
+
+| Part | Where | Why |
+|---|---|---|
+| Control plane: the API on 8080, the agents' port 7443, the scheduler | A StatefulSet, from the chart | A Go binary with a store and three ports: what Kubernetes runs well |
+| Store | A file on a PersistentVolumeClaim (SQLite), or your PostgreSQL | Either, as on a host |
+| GPU and CPU nodes | Outside, as hosts | See below |
+| Model mirror | Outside, on a machine with a large disk | Every node pulls tens of gigabytes from it over plain HTTP; a pod with a volume that size is a host in all but name |
+
+### Why the nodes stay outside
+
+The agent on a node is not a service that happens to use a GPU. It installs
+the engines on the machine — the llama.cpp build for its driver, vLLM in a
+Python environment — checks them against their publisher's checksums and
+runs them; it chooses which GPUs each replica gets, by index and by NVLink
+topology; it starts engines as processes that outlive its own restarts, so a
+node upgrades while it serves; it writes the machine's firewall; and it
+replaces its own binary when the cluster upgrades. All of that is root on
+the host, which is exactly what a container is built to prevent.
+
+Run as a DaemonSet it would need to be privileged, with the host's network,
+process namespace and filesystem, and the NVIDIA device plugin would have to
+be kept off its GPUs — or the two would hand the same card to two owners.
+What is left is the host agent with a container's indirection around it, and
+none of the scheduling, isolation or restart guarantees that make a pod
+worth having. So the chart does not ship one, and this is the
+recommendation:
+
+- **Keep GPU machines out of Kubernetes**, and add them with `node add`.
+- **If they are already Kubernetes workers**, dedicate them: taint them so
+  no other pod lands there, keep the NVIDIA device plugin off them (most
+  installs select nodes by label — leave the label off), and run the llmgw
+  agent on the host, where `node add` puts it. llmgw then owns the GPUs, and
+  Kubernetes schedules nothing that would want them.
+
+## The image
+
+The project publishes binaries, not an image. Build one from the repository
+and push it where the cluster pulls from — at an offline site, the internal
+registry:
+
+```
+docker build -f deploy/container/Dockerfile --build-arg VERSION=v0.11.1 \
+  -t registry.internal/llmgw:v0.11.1 .
+docker push registry.internal/llmgw:v0.11.1
+```
+
+It is the static binary on a distroless base: no shell, running as user
+65532, with a read-only root filesystem in the pod.
+
+## The agent port's certificate
+
+Agents and the control plane authenticate each other with certificates from
+llmgw's own authority, and the TLS ends in the pod — so the authority's key
+stays outside the cluster, on the machine you will add nodes from, and the
+pod is given only its own certificate.
+
+Decide first the address agents will dial: the `-agents` Service is a
+LoadBalancer, so give it a fixed `agentService.loadBalancerIP` or a DNS name
+that points at it. That address has to be in the certificate:
+
+```
+llmgw ctl cert init-ca --dir ./pki
+llmgw ctl cert issue-server llmgw-ctl --host 10.0.0.200 --host llmgw-agents.example.com \
+  --dir ./pki --out ./pki
+kubectl -n llmgw create secret generic llmgw-agent-tls \
+  --from-file=ca.pem=pki/ca.pem \
+  --from-file=server.pem=pki/server.pem \
+  --from-file=server-key.pem=pki/server-key.pem
+```
+
+Keep `pki/ca-key.pem` as you would on a host: whoever holds it can make any
+node's identity.
+
+## Installing
+
+```yaml
+# values.yaml
+image:
+  repository: registry.internal/llmgw
+  tag: v0.11.1
+agentTLS:
+  existingSecret: llmgw-agent-tls
+agentService:
+  loadBalancerIP: 10.0.0.200
+ingress:
+  enabled: true
+  className: nginx
+  hosts: [{host: llm.example.com, paths: [{path: /, pathType: Prefix}]}]
+  tls: [{secretName: llm-example-com, hosts: [llm.example.com]}]
+config:
+  mirror:
+    api: http://models.internal:8082
+  # The address the router reaches nodes' engines from is a Kubernetes
+  # node's, once the pod's traffic leaves the cluster: the nodes' firewalls
+  # must let it in.
+  firewall_networks: ["10.0.1.0/24"]
+```
+
+```
+helm install llmgw deploy/helm/llmgw -n llmgw -f values.yaml
+```
+
+`config` is `server.yaml`: any key of [reference.md](reference.md), laid
+under what the chart sets itself — the listeners, where the certificates,
+the admin token and the store are mounted. A changed `config` restarts the
+pod.
+
+**The store.** By default SQLite, on a 10 GiB claim. For PostgreSQL, put its
+address in a Secret and point the chart at it:
+
+```
+kubectl -n llmgw create secret generic llmgw-store \
+  --from-literal=dsn='postgres://llmgw:…@pg.internal:5432/llmgw?sslmode=verify-full'
+```
+
+```yaml
+store:
+  type: postgres
+  postgres:
+    existingSecret: llmgw-store
+```
+
+**One control plane.** The chart runs one replica. Two against PostgreSQL
+would elect a leader and keep a standby, but a standby serves nothing and is
+never ready, so a StatefulSet rollout would wait on it for ever. Kubernetes
+replaces the one pod within seconds when it goes, and agents reconnect on
+their own; the replicas on the nodes keep serving meanwhile.
+
+**Probes.** Alive is `/health`. Ready is `/leader`, which on PostgreSQL waits
+for the lease of the pod it replaced to run out — not `/ready`, which waits
+for a model replica, and would keep a cluster with no node yet from ever
+accepting one.
+
+**Monitoring.** The metrics port, 9091, serves metrics and nothing else;
+`serviceMonitor.enabled: true` makes a ServiceMonitor for the Prometheus
+Operator, and `deploy/monitoring` holds the rules and dashboards.
+
+## Using it
+
+The admin API listens on the pod's loopback, as on a host — it can dump keys
+from the heap when profiling is on. Reach it through the pod:
+
+```
+kubectl -n llmgw exec -it statefulset/llmgw -- llmgw users create you@example.com --password '…'
+kubectl -n llmgw exec -it statefulset/llmgw -- llmgw users role you@example.com admin
+kubectl -n llmgw exec -it statefulset/llmgw -- llmgw ctl status
+```
+
+or from your machine, through a port-forward:
+
+```
+kubectl -n llmgw port-forward statefulset/llmgw 9090:9090 &
+export LLMGW_ADMIN_TOKEN=$(kubectl -n llmgw get secret llmgw-admin -o jsonpath='{.data.admin-token}' | base64 -d)
+llmgw ctl status
+```
+
+The token is made by the chart and kept across upgrades
+(`adminToken.existingSecret` brings your own).
+
+## Adding nodes
+
+From the machine holding `pki/`, with the port-forward above running and
+`LLMGW_ADMIN_TOKEN` set:
+
+```
+sudo -E llmgw node add ubuntu@gpu01 \
+  --server https://10.0.0.200:7443 --pki ./pki --admin 127.0.0.1:9090
+```
+
+`--server` is the address in the certificate. The node is installed, checked
+and started over ssh exactly as on any cluster ([node-onboarding.md](node-onboarding.md)),
+and dials the control plane in the pod. Its firewall comes from
+`firewall_networks` in the server configuration `node add` reads (`--config`,
+`/etc/llmgw/server.yaml` by default): copy the chart's out of the cluster
+first, or give `--no-firewall` and keep the engines' ports open to the
+Kubernetes nodes by hand.
+
+```
+kubectl -n llmgw get configmap llmgw -o jsonpath='{.data.server\.yaml}' > server.yaml
+sudo -E llmgw node add ubuntu@gpu01 --config ./server.yaml --server https://10.0.0.200:7443 \
+  --pki ./pki --admin 127.0.0.1:9090
+```
+
+## Offline
+
+An offline site ([install.md](install.md), "Offline sites") works the same
+way with the control plane in a pod. Import the bundle on the mirror's
+machine with `llmgw bundle import`, record its engines' checksums in a
+file, and give that file to the chart as a ConfigMap:
+
+```
+llmgw bundle trust llmgw-bundle.tar --sha256 3f2a… --file ./offline.sha256
+kubectl -n llmgw create configmap llmgw-offline --from-file=offline.sha256
+```
+
+```yaml
+offlineChecksums:
+  configMap: llmgw-offline
+config:
+  offline:
+    mirror: http://models.internal:8081
+```
+
+A later bundle: `bundle trust` into the same file, and replace the ConfigMap
+(`kubectl create configmap … --dry-run=client -o yaml | kubectl apply -f -`).
+The control plane reads the file again when it changes; there is no restart.
+
+## What has and has not been tried
+
+The chart is checked with `helm lint` and `helm template` for SQLite,
+PostgreSQL, an Ingress, a ServiceMonitor and an offline cluster, and refuses
+what would not work — no image, no certificate, a PostgreSQL store without
+its address, more than one replica. The image has been run the way the
+chart runs it — read-only root, user 65532, the same files mounted at the
+same paths, SQLite on a volume — and answered `/health`, `/leader` and
+`/metrics`, with `llmgw ctl` and `llmgw users` working through `exec`.
+
+It has **not** been installed on a Kubernetes cluster, and no node has yet
+joined a control plane running in one. Until it has, a control plane on a
+host is the well-trodden path.

docs/onboarding.md

@@ -65,6 +65,11 @@ model already in it:
   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.
+- **Claude Code** — not on the page yet; it speaks Anthropic's Messages API,
+  which the gateway translates at `/v1/messages`:
+  `ANTHROPIC_BASE_URL=https://<gateway> ANTHROPIC_AUTH_TOKEN=<key>
+  ANTHROPIC_MODEL=<model> ANTHROPIC_SMALL_FAST_MODEL=<model> claude`. It
+  needs a model that calls tools well.
 
 For Continue and Codex there is a one-line command,
 `curl -fsSL <gateway>/setup/<tool>?model=… | sh`. Its script is served without
@@ -191,7 +196,8 @@ 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.
+are. An administrator following `/org` lands on the same organization's panel
+on the people page instead, where all of that can be changed.
 
 `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;
@@ -259,7 +265,7 @@ 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 given in whole units, as the quotas page shows them, and what a unit
+Budgets are given in whole units, as the Limits tab 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
@@ -303,6 +309,28 @@ shown as text. Other schemes are never linked — configuration is not always
 written by whoever runs the gateway, and a `javascript:` href on a page served to
 every visitor is a short path to a stored XSS.
 
+## The docs portal
+
+The gateway also serves its manual at `/docs`: these pages, rendered, with
+[clients.md](clients.md) — how to use the gateway from the official OpenAI
+and Anthropic SDKs — first on its index. The landing page and the account
+page link to it, so a user's questions about streaming, tools or the Anthropic
+SDK have an answer that is not you.
+
+It is public, like the landing page. The client guide is for the person who
+has no account yet, and the operator documents describe llmgw in general —
+no address, model, node or key of this installation — which is what the
+project's repository publishes anyway. A site that would rather not say even
+that turns sign-in on:
+
+```yaml
+landing:
+  docs_sign_in: true
+```
+
+A visitor is then sent to sign in first. On a gateway with API keys and no
+accounts, the portal asks for a key instead, like the API.
+
 ## What the user sees
 
 They open the link, press the button, and get the key once. The page shows them
@@ -324,8 +352,15 @@ llmgw keys list --store … --project default
 minute. It is the column that tells you whether a key is still in use, which is
 what makes rotation safe:
 
-**To rotate**, issue the new key, let both work while the user switches, watch
-`LAST USED` on the old one stop moving, then revoke it.
+**To rotate**, `llmgw keys rotate <key-id> --overlap 48h` issues a new key with
+the same project, owner and limits and lets the old one work for the overlap,
+then stop. Watch `LAST USED` on the old one stop moving before it runs out.
+
+**To cap how long keys live**, `llmgw keys ttl project:Acme/ml/train 720h` (or
+`team:`, `org:`; `off` removes it), and `auth.max_key_ttl` in server.yaml for
+every key. A key is made within the shortest limit that applies, and one asked
+for without an expiry gets that limit. `keys list --all` shows each key's kind
+— service (a project's), member, personal — and when it expires.
 
 ```
 llmgw keys revoke --store … key-mpmip77twpt7qaxc
@@ -344,16 +379,38 @@ is what someone gets from a borrowed laptop, and the password is what they do no
 have — and it signs every other browser out, which is the point if they are
 changing it because something went wrong.
 
-There is no self-service reset, because this gateway sends no email and a reset
-link with nowhere to send it is not a reset. When someone loses theirs:
+Someone who has forgotten theirs follows **Forgotten your password?** on the
+sign-in page. With mail set up in the cluster's settings, a link to set a new one
+is mailed to their address — the page says the same whether or not the address
+has an account, so nobody can find out who does from it:
+
+```
+llmgw ctl config set mail '{smtp: smtp.example.com:587, from: llmgw@example.com,
+  username: llmgw, password_file: /etc/llmgw/secrets/smtp, base_url: https://llm.example.com}'
+```
+
+`base_url` is where the link points, and it is never taken from the request:
+otherwise a stranger could ask for someone's link from a page of their own. A
+link works once, for an hour, and a newer one replaces it.
+
+Without mail, the page says to ask an operator, who makes the link and hands it
+over however suits:
+
+```
+llmgw users reset-link ayse@example.com --store …    # --base-url without mail.base_url
+```
+
+Or sets a temporary password to give them, and has them change it from their
+profile:
 
 ```
 llmgw users reset-password usr-k4mq… --password "a temporary passphrase" --store …
 ```
 
-Tell them out of band and have them change it from their profile. Their sessions
-are closed — if they lost the password, the reason might be that someone else has
-it. Their API keys keep working; those are separate credentials.
+Either way their sessions are closed — if they lost the password, the reason
+might be that someone else has it. Their API keys keep working; those are
+separate credentials. People who sign in through single sign-on have no password
+here, and get no link.
 
 ## Trying a model in the browser
 
@@ -409,10 +466,19 @@ page exists.
 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.
+adds, renames, moves and removes organizations, teams and projects. A
+searchable list of every account is at the bottom. Choosing any organization,
+team, project or person opens a panel beside the tree with its limits, its
+capacity quota and its use over the last week, and its limits can be changed
+there.
+
+The same page has two more tabs, each at the address it had as a page of its
+own: **Limits** (`/admin/quotas`) is every limit in the tree at once — per
+branch, per member of any part of it, and per person — with the capacity quotas;
+**Usage** (`/admin/usage`) is the cluster's use over time by organization, team,
+project or person, and the GPU time each owner held. 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:
 
@@ -423,21 +489,26 @@ Three things are deliberately not there:
 | `llmgw keys create` | Issuing a credential on another person's behalf |
 
 Each of those turns a stolen admin cookie into more than it was, and each is
-rare enough that a shell is no hardship. Cordon, drain and everything else that
-touches the cluster are also CLI-only for the same reason: the dashboard shows
-the cluster, it does not steer it.
+rare enough that a shell is no hardship. Cordon and drain are CLI-only for the
+same reason; what the pages do change on the cluster — serving models through
+the mirror, a node's engines — needs the `operator` or `admin` staff role.
 
-Every administrative action is logged with who did it, including the ones that
-were refused.
+Every administrative change is recorded in the audit log — who, when, through
+what, the fields given with secrets taken out, and how it ended, refusals
+included: `llmgw ctl audit`, or **Audit** in the console.
 
 ## What this does not do
 
 - **No email.** No approval notice, no self-service password reset, no address
   verification. The loop is manual on purpose at this size; if it stops being
   the right size, that is the thing to automate.
-- **No SSO.** Accounts are local, with local passwords.
-- **No roles.** There is one flag, `is_admin`, and it grants looking at the
-  dashboard. Everything else an administrator does is the CLI, and having a
-  shell here is what makes someone one.
+- **Single sign-on is optional.** With `auth.oidc` people sign in through
+  your identity provider, and SCIM 2.0 (`auth.scim`) creates, updates and
+  suspends accounts from it; see [install.md](install.md#single-sign-on).
+  Without them accounts are local, with local passwords.
+- **Staff roles are coarse.** `viewer`, `operator`, `billing` and `admin`
+  (`llmgw users role`) decide what someone may see and do under /admin; an
+  organization's manager can view it but not change it. Every change is in
+  the audit log (`llmgw ctl audit`).
 - **Rate limits are per gateway instance.** With two instances each counts its own,
   so the effective limit doubles. v1 is single-instance by design.

docs/quick-install.md

@@ -8,10 +8,10 @@ explains every choice.
 
 | | |
 |---|---|
-| **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. |
+| **A control plane** | One machine, or three for high availability (the store replicated, either one able to take over). Linux, x86-64 or ARM64: Debian 12, Ubuntu 22.04+ or RHEL 10. No GPU needed; 2 GB RAM, 20 GB disk each — 8 GB RAM when it is also a node running the starter model and the two judges. |
+| **GPU nodes** (optional to start) | The same Linux, with the NVIDIA driver installed. vLLM needs driver 525 or newer and a Turing GPU or newer; a V100 gets an older vLLM. |
+| **root** | on the control plane. On the other two of a three-machine setup, `sudo` (its password is asked for if it needs one); on nodes, `sudo` without a password. |
+| **SSH** | from the control plane to the other machines. The setup screens take a key, the ssh agent or a password; `node add` uses ssh keys. A machine nothing may log into joins with a code instead (`llmgw join`). |
 | **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
@@ -35,26 +35,41 @@ install it.
 ## 2. Set up the control plane
 
 ```
-sudo llmgw server init
+sudo llmgw
 ```
 
-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`.
+With nothing installed, `llmgw` opens the setup screens. They ask whether
+this is **one machine or three** (high availability), and for three, the
+other two: address, user, and an ssh key, the ssh agent or a password. They
+check every machine before installing anything — system, disk, clock, ports,
+internet, whether the machines reach one another — show the plan, and
+install:
 
-- the service, its certificates and its configuration;
-- your administrator account. **The password is printed once. Copy it now.**
+- the service, its certificates and its configuration, and a firewall for
+  its internal ports;
+- with three machines, the store replicated across them (PostgreSQL under
+  Patroni);
+- your administrator account. **The password is shown 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.
+- this machine as a first node, and a small model (Qwen2.5 0.5B) on it;
+- guardrails on every request, with a judge model (Qwen3Guard-Gen 0.6B, two
+  replicas) on CPUs — a request it cannot check is refused, not let through — and API keys that expire within 90 days. What is hardened, and how
+  to loosen it: [install.md](install.md#2-the-control-plane).
+
+Run again later, `sudo llmgw` is the console: the cluster's state and
+everything you can do to it ([console.md](console.md)). Every step below is
+also there, under **Do**.
+
+**In a script**, the same for one machine:
+
+```
+sudo llmgw server init --admin you@example.com
+```
 
 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.
+`--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,
@@ -75,7 +90,7 @@ the account page.
 
 ## 3. Add the GPU nodes
 
-On the control plane:
+In the console, **Do → Add a node**. Or on the control plane:
 
 ```
 sudo llmgw node add ubuntu@10.0.0.21
@@ -197,6 +212,9 @@ through the proxy. There is an nginx configuration too:
 
 ## Next
 
-- [install.md](install.md): the same steps with every option explained.
+- [install.md](install.md): the same steps with every option explained, and
+  running the cluster after: monitoring, notifications, single sign-on,
+  backups, upgrades.
+- [console.md](console.md): everything the console does.
 - [fabrics.md](fabrics.md): InfiniBand and NVLink.
 - [onboarding.md](onboarding.md): accounts, projects, budgets and keys.

go.mod

@@ -1,13 +1,18 @@
 module gitea.mynodes.xyz/ilker/llmgw
 
-go 1.26.3
+go 1.26.6
 
 require (
 	connectrpc.com/connect v1.21.0
+	filippo.io/age v1.3.2
 	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/charmbracelet/x/ansi v0.11.6
+	github.com/coreos/go-oidc/v3 v3.21.0
+	github.com/go-jose/go-jose/v4 v4.1.4
+	github.com/go-zeromq/zmq4 v0.17.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
@@ -18,24 +23,29 @@ require (
 	github.com/prometheus/client_model v0.6.3
 	github.com/prometheus/common v0.71.0
 	github.com/spf13/cobra v1.10.2
+	github.com/vmihailenco/msgpack/v5 v5.4.1
 	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
+	go.yaml.in/yaml/v3 v3.0.5
 	golang.org/x/crypto v0.57.0
 	golang.org/x/net v0.59.0
+	golang.org/x/oauth2 v0.37.0
 	golang.org/x/sync v0.23.0
+	golang.org/x/text v0.42.0
 	google.golang.org/protobuf v1.36.12
 	modernc.org/sqlite v1.59.0
 )
 
 require (
+	filippo.io/edwards25519 v1.2.0 // indirect
+	filippo.io/hpke v0.4.0 // indirect
 	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
@@ -47,6 +57,7 @@ require (
 	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/go-zeromq/goczmq/v4 v4.2.2 // 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
@@ -54,6 +65,7 @@ require (
 	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/kylelemons/godebug v1.1.0 // 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
@@ -68,14 +80,13 @@ require (
 	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/vmihailenco/tagparser/v2 v2.0.0 // 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

go.sum

@@ -1,5 +1,13 @@
+c2sp.org/CCTV/age v0.0.0-20260829155415-4448f2097b2d h1:Blprhc2SbChNZtWcU+BLTM4YdoqYAS9V7cJgOwJKyAs=
+c2sp.org/CCTV/age v0.0.0-20260829155415-4448f2097b2d/go.mod h1:SrHC2C7r5GkDk8R+NFVzYy/sdj0Ypg9htaPXQq5Cqeo=
 connectrpc.com/connect v1.21.0 h1:LhqSJt7jHf5NJBo9Jq/t/9FjcYAideif0mg+qe2jCUs=
 connectrpc.com/connect v1.21.0/go.mod h1:A2ygJrukXwWy32vkCAAHNVguZrqZ+jeZ9rGRnGR4dN4=
+filippo.io/age v1.3.2 h1:r6RSZLFSMm6rzKepZ7ZAYkKCu14f3/Me8c7uKYh7C8c=
+filippo.io/age v1.3.2/go.mod h1:TH/Yr2sSRhCKbaH4XPxpUV0Us8Gv6txYUpiZQWz8Evk=
+filippo.io/edwards25519 v1.2.0 h1:crnVqOiS4jqYleHd9vaKZ+HKtHfllngJIiOpNpoJsjo=
+filippo.io/edwards25519 v1.2.0/go.mod h1:xzAOLCNug/yB62zG1bQ8uziwrIqIuxhctzJT18Q77mc=
+filippo.io/hpke v0.4.0 h1:p575VVQ6ted4pL+it6M00V/f2qTZITO0zgmdKCkd5+A=
+filippo.io/hpke v0.4.0/go.mod h1:EmAN849/P3qdeK+PCMkDpDm83vRHM5cDipBJ8xbQLVY=
 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=
@@ -28,6 +36,8 @@ github.com/clipperhouse/stringish v0.1.1 h1:+NSqMOr3GR6k1FdRhhnXrLfztGzuG+VuFDfa
 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/coreos/go-oidc/v3 v3.21.0 h1:wZo4Q9Pum8dYEj0eMUPrqR+kvuGkeUplbLpNCkBqoWM=
+github.com/coreos/go-oidc/v3 v3.21.0/go.mod h1:DYCf24+ncYi+XkIH97GY1+dqoRlbaSI26KVTCI9SrY4=
 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=
@@ -36,6 +46,8 @@ github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f h1:Y/CXytFA4m6
 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-jose/go-jose/v4 v4.1.4 h1:moDMcTHmvE6Groj34emNPLs/qtYXRVcd6S7NHbHz3kA=
+github.com/go-jose/go-jose/v4 v4.1.4/go.mod h1:x4oUasVrzR7071A4TnHLGSPpNOm2a21K9Kf04k1rs08=
 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=
@@ -43,6 +55,10 @@ 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/go-zeromq/goczmq/v4 v4.2.2 h1:HAJN+i+3NW55ijMJJhk7oWxHKXgAuSBkoFfvr8bYj4U=
+github.com/go-zeromq/goczmq/v4 v4.2.2/go.mod h1:Sm/lxrfxP/Oxqs0tnHD6WAhwkWrx+S+1MRrKzcxoaYE=
+github.com/go-zeromq/zmq4 v0.17.0 h1:r12/XdqPeRbuaF4C3QZJeWCt7a5vpJbslDH1rTXF+Kc=
+github.com/go-zeromq/zmq4 v0.17.0/go.mod h1:EQxjJD92qKnrsVMzAnx62giD6uJIPi1dMGZ781iCDtY=
 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=
@@ -124,6 +140,10 @@ 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/vmihailenco/msgpack/v5 v5.4.1 h1:cQriyiUvjTwOHg8QZaPihLWeRAAVoCpE00IUPn0Bjt8=
+github.com/vmihailenco/msgpack/v5 v5.4.1/go.mod h1:GaZTsDaehaPpQVyxrf5mtQlH+pc21PIudVV/E3rRQok=
+github.com/vmihailenco/tagparser/v2 v2.0.0 h1:y09buUbR+b5aycVFQs/g70pqKVZNBmxwAhO7/IwNM9g=
+github.com/vmihailenco/tagparser/v2 v2.0.0/go.mod h1:Wri+At7QHww0WTrCBeu4J6bNtoV6mEfg5OIWRZA9qds=
 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=
@@ -161,11 +181,15 @@ 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/oauth2 v0.37.0 h1:JUlcxA8oAtauLfiH8FX2/FkAWHAdi0QtGCGc+hofE98=
+golang.org/x/oauth2 v0.37.0/go.mod h1:IxwZNxUULJmpBFf9K/9NTMSIfZZuvuTy1gGxhigP/58=
 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/term v0.46.0 h1:3+OXuTbaKDgwk8jTi3aSLHRlmWqHEUDUtxnbFigO4YE=
+golang.org/x/term v0.46.0/go.mod h1:+K02xbkittuwc0Am4abfA3Fc+XRGXkvBXNO88NCXPoc=
 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=

internal/account/account_test.go

@@ -398,3 +398,90 @@ func TestGuessingTheCurrentPasswordIsBounded(t *testing.T) {
 		t.Errorf("guessing was unbounded: %v", err)
 	}
 }
+
+func TestSomebodyGuessingElsewhereCannotLockTheOwnerOut(t *testing.T) {
+	svc, st := newStoreAndUser(t)
+	ctx := context.Background()
+	must(t, st.ApproveUser(ctx, "usr-1", "proj", "ilker", time.Now()))
+	cfg := DefaultConfig()
+	cfg.MaxAttempts = 3
+	svc = New(st, cfg, slog.New(slog.DiscardHandler))
+
+	attacker, owner := WithClient(ctx, "203.0.113.9"), WithClient(ctx, "198.51.100.7")
+	for range 5 {
+		_, _, _ = svc.SignIn(attacker, "ayse@example.com", "nope")
+	}
+	if _, _, err := svc.SignIn(attacker, "ayse@example.com", "nope"); !errors.Is(err, ErrTooManyTries) {
+		t.Errorf("the guessing client was not held back: %v", err)
+	}
+	if _, _, err := svc.SignIn(owner, "ayse@example.com", goodPassword); err != nil {
+		t.Errorf("the owner, elsewhere, was locked out: %v", err)
+	}
+	// Spread over many clients, guessing is still bounded per address.
+	held := false
+	for i := range 40 {
+		c := WithClient(ctx, "192.0.2."+strings.Repeat("1", 1+i%3)+string(rune('0'+i%10)))
+		if _, _, err := svc.SignIn(c, "ayse@example.com", "nope"); errors.Is(err, ErrTooManyTries) {
+			held = true
+		}
+	}
+	if !held {
+		t.Error("guesses from many clients were not bounded")
+	}
+}
+
+func TestAHashThatCannotGetATurnSaysTheServerIsBusy(t *testing.T) {
+	was := argonWait
+	argonWait = 10 * time.Millisecond
+	t.Cleanup(func() { argonWait = was })
+	// Every turn taken.
+	n := cap(argonSlots)
+	for range n {
+		argonSlots <- struct{}{}
+	}
+	t.Cleanup(func() {
+		for range n {
+			<-argonSlots
+		}
+	})
+	if _, err := HashPassword(goodPassword); !errors.Is(err, ErrBusy) {
+		t.Errorf("a hash with no turn: %v", err)
+	}
+}
+
+func TestAForgottenPasswordIsResetOnceThroughALink(t *testing.T) {
+	svc, st := newService(t)
+	ctx := context.Background()
+	must(t, svc.SignUp(ctx, "ayse@example.com", "A", goodPassword))
+	u, _ := st.UserByEmail(ctx, "ayse@example.com")
+
+	// Waiting for approval: no link, said the same as for nobody.
+	if _, _, err := svc.RequestReset(ctx, st, "ayse@example.com"); !errors.Is(err, ErrNoReset) {
+		t.Fatalf("a pending account got a link: %v", err)
+	}
+	if _, _, err := svc.RequestReset(ctx, st, "nobody@example.com"); !errors.Is(err, ErrNoReset) {
+		t.Fatalf("an unknown address: %v", err)
+	}
+	must(t, st.ApproveUser(ctx, u.ID, "proj", "ilker", time.Now()))
+	session, _, err := svc.SignIn(ctx, "ayse@example.com", goodPassword)
+	must(t, err)
+
+	token, got, err := svc.RequestReset(ctx, st, "AYSE@example.com")
+	if err != nil || token == "" || got.ID != u.ID {
+		t.Fatalf("an active account: %q %+v %v", token, got, err)
+	}
+	if err := svc.ResetPassword(ctx, st, st, token, "short"); !errors.Is(err, ErrWeakPassword) {
+		t.Fatalf("a weak password: %v", err)
+	}
+	next := goodPassword + "-new"
+	must(t, svc.ResetPassword(ctx, st, st, token, next))
+	if _, _, err := svc.Resolve(ctx, session); err == nil {
+		t.Error("a session from before the reset still works")
+	}
+	if _, _, err := svc.SignIn(ctx, "ayse@example.com", next); err != nil {
+		t.Errorf("the new password does not sign in: %v", err)
+	}
+	if err := svc.ResetPassword(ctx, st, st, token, next+"2"); !errors.Is(err, ErrNoReset) {
+		t.Errorf("a link used twice: %v", err)
+	}
+}

internal/account/password.go

@@ -17,6 +17,7 @@ import (
 	"fmt"
 	"runtime"
 	"strings"
+	"time"
 
 	"golang.org/x/crypto/argon2"
 )
@@ -57,7 +58,10 @@ func HashPassword(password string) (string, error) {
 	if _, err := rand.Read(salt); err != nil {
 		return "", err
 	}
-	sum := idKey([]byte(password), salt, argonTime, argonMemory, argonThreads, argonKeyLen)
+	sum, err := idKey([]byte(password), salt, argonTime, argonMemory, argonThreads, argonKeyLen)
+	if err != nil {
+		return "", err
+	}
 
 	b64 := base64.RawStdEncoding.EncodeToString
 	return fmt.Sprintf("$argon2id$v=%d$m=%d,t=%d,p=%d$%s$%s",
@@ -94,7 +98,10 @@ func VerifyPassword(password, encoded string) (bool, error) {
 		return false, ErrBadHash
 	}
 
-	got := idKey([]byte(password), salt, time, memory, threads, uint32(len(want)))
+	got, err := idKey([]byte(password), salt, time, memory, threads, uint32(len(want)))
+	if err != nil {
+		return false, err
+	}
 	return subtle.ConstantTimeCompare(got, want) == 1, nil
 }
 
@@ -119,8 +126,19 @@ func init() {
 // 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{}{}
+// ErrBusy is a hash that waited its turn too long: the server is answering
+// more sign-ins than it can hash, and says so rather than hold the request.
+var ErrBusy = errors.New("too many sign-ins at once; try again in a moment")
+
+// argonWait bounds the wait for a turn; a variable so a test can shorten it.
+var argonWait = 10 * time.Second
+
+func idKey(password, salt []byte, t, memory uint32, threads uint8, keyLen uint32) ([]byte, error) {
+	select {
+	case argonSlots <- struct{}{}:
+	case <-time.After(argonWait):
+		return nil, ErrBusy
+	}
 	defer func() { <-argonSlots }()
-	return argon2.IDKey(password, salt, time, memory, threads, keyLen)
+	return argon2.IDKey(password, salt, t, memory, threads, keyLen), nil
 }

internal/account/service.go

@@ -138,7 +138,15 @@ func (s *Service) SignUp(ctx context.Context, email, name, password string) erro
 // the CSRF token that must accompany the forms in it.
 func (s *Service) SignIn(ctx context.Context, email, password string) (token, csrf string, err error) {
 	email = store.NormalizeEmail(email)
-	if !s.allowAttempt(email) {
+	// Counted per address and the client trying it, so somebody guessing
+	// from elsewhere cannot lock the owner out of their own account; and per
+	// address alone, more loosely, so guesses spread over many clients are
+	// still bounded.
+	byClient := email
+	if c := clientFrom(ctx); c != "" {
+		byClient = email + "|" + c
+	}
+	if !s.allowAttempt(byClient, s.cfg.MaxAttempts) || !s.allowAttempt("all|"+email, 10*s.cfg.MaxAttempts) {
 		return "", "", ErrTooManyTries
 	}
 
@@ -154,11 +162,15 @@ func (s *Service) SignIn(ctx context.Context, email, password string) (token, cs
 	}
 
 	ok, err := VerifyPassword(password, u.PasswordHash)
+	if errors.Is(err, ErrBusy) {
+		// Not an answer about the password: said as what it is.
+		return "", "", err
+	}
 	if err != nil || !ok {
 		return "", "", ErrBadCredentials
 	}
 	// The password was right, so this was not an attack.
-	s.clearAttempts(email)
+	s.clearAttempts(byClient)
 
 	// State is checked after the password, on purpose. Checking first would
 	// tell anyone who guesses an address whether it has a pending account.
@@ -224,7 +236,7 @@ func (s *Service) CheckCSRF(sess store.Session, submitted string) bool {
 // Per address rather than per IP: an attacker has many addresses to come from
 // and only one to guess against, and limiting by IP would lock out everyone
 // behind one office NAT the moment somebody fat-fingers their password.
-func (s *Service) allowAttempt(email string) bool {
+func (s *Service) allowAttempt(email string, limit int) bool {
 	now := s.now()
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -251,7 +263,20 @@ func (s *Service) allowAttempt(email string) bool {
 		return true
 	}
 	w.count++
-	return w.count <= s.cfg.MaxAttempts
+	return w.count <= limit
+}
+
+type clientKey struct{}
+
+// WithClient says which client a request comes from — its address — for the
+// sign-in throttle.
+func WithClient(ctx context.Context, client string) context.Context {
+	return context.WithValue(ctx, clientKey{}, client)
+}
+
+func clientFrom(ctx context.Context) string {
+	c, _ := ctx.Value(clientKey{}).(string)
+	return c
 }
 
 // maxTrackedAddresses bounds the throttle's memory. Unbounded, it grew by one
@@ -307,7 +332,7 @@ type PasswordChanger interface {
 func (s *Service) ChangePassword(ctx context.Context, pw PasswordChanger,
 	u store.User, current, next string,
 ) error {
-	if !s.allowAttempt("pw:" + u.ID) {
+	if !s.allowAttempt("pw:"+u.ID, s.cfg.MaxAttempts) {
 		return ErrTooManyTries
 	}
 	ok, err := VerifyPassword(current, u.PasswordHash)
@@ -348,3 +373,63 @@ func (s *Service) OpenSession(ctx context.Context, userID string) (token, csrf s
 	}
 	return token, csrf, nil
 }
+
+// ResetLinkTTL is how long a password reset link works.
+const ResetLinkTTL = time.Hour
+
+// ResetStore keeps password reset links.
+type ResetStore interface {
+	UserByEmail(ctx context.Context, email string) (store.User, error)
+	CreatePasswordReset(ctx context.Context, userID string, ttl time.Duration) (string, error)
+	PasswordResetUser(ctx context.Context, token string) (string, error)
+	UsePasswordReset(ctx context.Context, token string) (string, error)
+}
+
+// ErrNoReset is an address that gets no reset link: none has an account, the
+// account signs in through single sign-on, or it is not active. Never told to
+// whoever asked, who learns the same either way.
+var ErrNoReset = errors.New("no reset link for that address")
+
+// RequestReset mints a reset link token for the person an address belongs
+// to, when they sign in with a password and are active. A few a quarter of
+// an hour per address: each sends a mail.
+func (s *Service) RequestReset(ctx context.Context, rs ResetStore, email string) (string, store.User, error) {
+	email = store.NormalizeEmail(email)
+	if !validEmail(email) {
+		return "", store.User{}, ErrNoReset
+	}
+	if !s.allowAttempt("reset:"+email, 3) {
+		return "", store.User{}, ErrTooManyTries
+	}
+	u, err := rs.UserByEmail(ctx, email)
+	if err != nil || u.PasswordHash == "" || u.State != store.UserActive {
+		return "", store.User{}, ErrNoReset
+	}
+	token, err := rs.CreatePasswordReset(ctx, u.ID, ResetLinkTTL)
+	if err != nil {
+		return "", store.User{}, err
+	}
+	s.log.Info("a password reset link was made", "user", u.ID)
+	return token, u, nil
+}
+
+// ResetPassword sets a password from a reset link, which is spent, and signs
+// the person out everywhere: if they lost it, someone else may have it.
+func (s *Service) ResetPassword(ctx context.Context, rs ResetStore, pw PasswordChanger, token, next string) error {
+	hash, err := HashPassword(next)
+	if err != nil {
+		return err
+	}
+	userID, err := rs.UsePasswordReset(ctx, token)
+	if err != nil {
+		return ErrNoReset
+	}
+	if err := pw.SetPassword(ctx, userID, hash); err != nil {
+		return err
+	}
+	if err := pw.DeleteUserSessions(ctx, userID); err != nil {
+		return err
+	}
+	s.log.Info("a password was set from a reset link", "user", userID)
+	return nil
+}

internal/account/throttle_bound_test.go

@@ -12,22 +12,22 @@ func TestSprayingAddressesCannotGrowTheThrottleOrEscapeIt(t *testing.T) {
 
 	// The target is being guessed at.
 	for i := 0; i < s.cfg.MaxAttempts; i++ {
-		s.allowAttempt("victim@example.com")
+		s.allowAttempt("victim@example.com", s.cfg.MaxAttempts)
 	}
 	// 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))
+		s.allowAttempt(fmt.Sprintf("x%d@example.com", i), s.cfg.MaxAttempts)
 	}
 	if n := len(s.attempts); n > maxTrackedAddresses {
 		t.Errorf("the table grew to %d", n)
 	}
-	if s.allowAttempt("victim@example.com") {
+	if s.allowAttempt("victim@example.com", s.cfg.MaxAttempts) {
 		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") {
+	if !s.allowAttempt("new@example.com", s.cfg.MaxAttempts) {
 		t.Error("a new address was refused after the flood expired")
 	}
 }

internal/accounting/accounting.go

@@ -6,9 +6,11 @@ import (
 	"fmt"
 	"log/slog"
 	"strings"
+	"sync/atomic"
 	"time"
 
 	"gitea.mynodes.xyz/ilker/llmgw/internal/auth"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/notify"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
 )
 
@@ -45,8 +47,13 @@ type Accountant struct {
 	tokens   *Limiter
 	recorder *Recorder
 	log      *slog.Logger
+	// notify is told when a budget runs out; nil tells no one.
+	notify atomic.Pointer[notify.Notifier]
 }
 
+// SetNotifier gives the accountant somewhere to say a budget is spent.
+func (a *Accountant) SetNotifier(n *notify.Notifier) { a.notify.Store(n) }
+
 // New builds an accountant.
 func New(pricing *Pricing, recorder *Recorder, log *slog.Logger) *Accountant {
 	if log == nil {
@@ -182,6 +189,10 @@ func (a *Accountant) Check(p auth.Principal, model string, estimatedTokens int64
 	if !price.Zero() {
 		for _, l := range chain {
 			if l.Budget != nil && a.budgets.Exhausted(l.Counter, l.Period, *l.Budget) {
+				a.notify.Load().Notify(notify.BudgetSpent, l.Counter,
+					fmt.Sprintf("the %s budget of %s is spent: requests to priced models are refused until it renews",
+						or(string(l.Period), "total"), l.Counter),
+					map[string]any{"counter": l.Counter, "period": string(l.Period), "budget": *l.Budget})
 				return res, &LimitError{Err: ErrBudgetSpent}
 			}
 		}
@@ -306,7 +317,13 @@ func (a *Accountant) Record(res Reservation, u store.Usage) {
 		a.tokens.Charge(c, actual-res.EstimatedTokens)
 	}
 
-	u.CostMicros = res.Price.Cost(u.PromptTokens, u.CompletionTokens)
+	// Priced by the model that answered: a fallback served by another model
+	// costs what that one costs, not what the one asked for would have.
+	price := res.Price
+	if u.ServedModel != "" && u.ServedModel != u.Model && a.pricing != nil {
+		price = a.pricing.For(u.ServedModel)
+	}
+	u.CostMicros = price.Cost(u.PromptTokens, u.CompletionTokens)
 	for _, b := range res.Budgets {
 		a.budgets.Add(b.Counter, b.Period, u.CostMicros)
 	}
@@ -316,6 +333,17 @@ func (a *Accountant) Record(res Reservation, u store.Usage) {
 	}
 }
 
+// RecordRefused queues the row of a request a limit refused: nothing is
+// charged — it used nothing — but it is counted, so a team running into its
+// limits shows as one rather than as a team that went quiet.
+func (a *Accountant) RecordRefused(u store.Usage) {
+	if u.KeyID == "" || a.recorder == nil {
+		return
+	}
+	u.PromptTokens, u.CompletionTokens, u.CostMicros = 0, 0, 0
+	a.recorder.Record(u)
+}
+
 // Status returns what a key has used, for headers and `ctl`.
 func (a *Accountant) Status(p auth.Principal) (spent int64, rpm, tpm float64) {
 	if p.KeyID == "" {

internal/accounting/accounting_test.go

@@ -5,11 +5,14 @@ import (
 	"errors"
 	"log/slog"
 	"path/filepath"
+	"strings"
 	"sync"
 	"testing"
 	"time"
 
 	"gitea.mynodes.xyz/ilker/llmgw/internal/auth"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/notify"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/notify/notifytest"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
 )
 
@@ -658,3 +661,46 @@ func TestHeadroomIsTheTightestLimitAfterThisRequest(t *testing.T) {
 		t.Errorf("a key with no limits advertised some: %+v", none)
 	}
 }
+
+func TestAFallbackIsChargedWhatTheModelThatAnsweredCosts(t *testing.T) {
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	p := inTree("fb-k", teamBudget("fb", 1_000_000))
+	res, err := a.Check(p, "paid", 400)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// Asked for "paid", answered by "free": nothing is owed.
+	a.Record(res, store.Usage{KeyID: "fb-k", Model: "paid", ServedModel: "free", PromptTokens: 200, CompletionTokens: 200})
+	if spent, _, _ := a.Status(p); spent != 0 {
+		t.Errorf("charged %d for a request the free model answered", spent)
+	}
+	res, _ = a.Check(p, "paid", 400)
+	a.Record(res, store.Usage{KeyID: "fb-k", Model: "paid", ServedModel: "paid", PromptTokens: 200, CompletionTokens: 200})
+	if spent, _, _ := a.Status(p); spent == 0 {
+		t.Error("the paid model answering cost nothing")
+	}
+}
+
+func TestASpentBudgetTellsSomeoneOnce(t *testing.T) {
+	a := New(pricing(t), nil, slog.New(slog.DiscardHandler))
+	n, sent := notifytest.Catch(t)
+	a.SetNotifier(n)
+	p := principal("k1", func(e *store.Effective) {
+		e.Budget = i64p(100)
+		e.BudgetPeriod = store.PeriodMonth
+	})
+	res, err := a.Check(p, "paid", 10)
+	if err != nil {
+		t.Fatal(err)
+	}
+	a.Record(res, store.Usage{KeyID: "k1", PromptTokens: 1000})
+	for range 3 {
+		if _, err := a.Check(p, "paid", 10); !errors.Is(err, ErrBudgetSpent) {
+			t.Fatalf("not refused: %v", err)
+		}
+	}
+	got := sent()
+	if len(got) != 1 || got[0].Kind != notify.BudgetSpent || !strings.Contains(got[0].Message, "month") {
+		t.Fatalf("sent %+v, want one budget_spent", got)
+	}
+}

internal/agent/agent.go

@@ -14,13 +14,18 @@ import (
 	"math/rand/v2"
 	"net"
 	"net/http"
+	"net/netip"
 	"os"
 	"path/filepath"
 	"runtime"
 	"slices"
+	"strconv"
 	"sync"
+	"sync/atomic"
 	"time"
 
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/trace"
 	"golang.org/x/net/http2"
 
 	llmgwv1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1"
@@ -31,16 +36,22 @@ 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/firewall"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/kvevents"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/obs"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/tlsconf"
 )
 
 // Agent runs on a GPU node.
 type Agent struct {
-	cfg  Config
-	log  *slog.Logger
-	sup  *supervisor.Supervisor
-	reg  *engines.Registry
-	http connectHTTPClient
+	cfg Config
+	// answered says the current session heard from its control plane, which
+	// starts the reconnect backoff again when it ends.
+	answered atomic.Bool
+	log      *slog.Logger
+	sup      *supervisor.Supervisor
+	reg      *engines.Registry
+	http     connectHTTPClient
 
 	// engineOnce probes the configured engines once before registering.
 	//
@@ -73,8 +84,15 @@ type Agent struct {
 	lastEngineProbe time.Time
 	probingEngines  bool
 
-	mu  sync.Mutex
-	inv discovery.Inventory
+	mu sync.Mutex
+	// serverList is every control plane to dial: the configured ones, and
+	// any the leader has named since. Read through servers().
+	serverList []string
+	// fwMu keeps one firewall change at a time; fwRunner runs its scripts
+	// (nil: this machine's shell).
+	fwMu     sync.Mutex
+	fwRunner firewall.Runner
+	inv      discovery.Inventory
 	// shardReplica remembers which replica a shard belongs to, so a status
 	// report can name both. The control plane keys on the replica.
 	shardReplica map[string]string
@@ -101,12 +119,23 @@ type Agent struct {
 	smsErr map[string]string
 	// load measures the machine between heartbeats.
 	load *discovery.LoadSampler
+	// sensors reads heat and power: CPU and board from hwmon and RAPL, GPUs
+	// from nvidia-smi.
+	sensors *discovery.SensorSampler
+	// wear reads what wears a GPU out: remapped rows, PCIe retries, XIDs.
+	wear *discovery.HealthSampler
 
 	// 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
 	// — eight shards starting together produce one download — and all eight
 	// are waiting, so all eight should say so.
 	fetchWatchers map[string][]func(weights.Progress)
+
+	// kv mirrors the KV caches of the engines that publish events, for the
+	// router's precise index; kvSubs are their listeners by shard, guarded
+	// by mu.
+	kv     *kvevents.Mirror
+	kvSubs map[string]*kvevents.Subscriber
 }
 
 // connectHTTPClient is the HTTP client connect uses; an interface so tests can
@@ -146,6 +175,11 @@ func New(cfg Config, httpClient connectHTTPClient, log *slog.Logger) (*Agent, er
 		logRing:      ring,
 		provKick:     make(chan struct{}, 1),
 		load:         discovery.NewLoadSampler(),
+		sensors:      discovery.NewSensorSampler(),
+		wear:         discovery.NewHealthSampler(),
+		serverList:   loadControlPlanes(cfg.Servers, cfg.TLS.Enabled()),
+		kv:           kvevents.NewMirror(),
+		kvSubs:       map[string]*kvevents.Subscriber{},
 	}
 	a.prov = &provision.Installer{Root: cfg.EnginesDir, Log: log, OnStatus: a.provisionStatus}
 	return a, nil
@@ -178,7 +212,9 @@ func (a *Agent) Run(ctx context.Context) error {
 	attempt := 0
 	next := 0
 	for ctx.Err() == nil {
-		server := a.cfg.Servers[next%len(a.cfg.Servers)]
+		// Read each time round: the leader may have named another since.
+		servers := a.servers()
+		server := servers[next%len(servers)]
 		err := a.session(ctx, server)
 		if ctx.Err() != nil {
 			break
@@ -188,17 +224,25 @@ func (a *Agent) Run(ctx context.Context) error {
 		// never answers — from here they are the same thing, and trying
 		// somewhere else is the answer to all three.
 		next++
+		// A session that was answered was a connection that worked, however
+		// it ended: the backoff starts again rather than carrying on from
+		// the last outage. Without this every failover the agent lived
+		// through made the next one slower — the third waited half a minute
+		// on a control plane that had been ready for twenty seconds.
+		if a.answered.Swap(false) {
+			attempt = 0
+		}
 		attempt++
 		delay := a.reconnectDelay(attempt)
 		// No wait when there is somewhere else to try: the delay exists to
 		// stop hammering one control plane, and the next address has not been
 		// hammered. With a single address this is the old behaviour exactly.
-		if len(a.cfg.Servers) > 1 && next%len(a.cfg.Servers) != 0 {
+		if len(servers) > 1 && next%len(servers) != 0 {
 			delay = 0
 		}
 		a.log.Warn("disconnected from the control plane, retrying",
 			"err", err, "server", server,
-			"next", a.cfg.Servers[next%len(a.cfg.Servers)],
+			"next", servers[next%len(servers)],
 			"in", delay.Round(time.Millisecond), "attempt", attempt)
 
 		select {
@@ -262,6 +306,12 @@ func (a *Agent) recoverOrphans() {
 			a.mu.Lock()
 			a.shardReplica[o.ShardID] = o.ReplicaID
 			a.mu.Unlock()
+			// The engine is still publishing to the port the last agent
+			// listened on; listen there again.
+			if o.Spec.KVEventsPort > 0 {
+				spec := o.Spec
+				a.listenKV(&spec, o.Spec.KVEventsPort)
+			}
 			a.log.Info("adopted a running engine",
 				"shard", o.ShardID, "replica", o.ReplicaID, "pid", o.PID)
 			go a.settleAdopted(sh, o)
@@ -297,7 +347,7 @@ func (a *Agent) settleAdopted(sh *supervisor.Shard, o supervisor.Orphan) {
 	// The same two paths a freshly started shard takes: a rank that serves HTTP
 	// is health-checked, a worker is judged by staying alive.
 	if eng.ServesHTTP(o.Spec) {
-		base := fmt.Sprintf("http://127.0.0.1:%d", o.Spec.HTTPPort)
+		base := a.engineBase(o.Spec)
 		err = a.sup.WaitReady(ctx, sh, base, o.Spec.Profile.ServedModelName, a.cfg.AdoptReadyTimeout)
 	} else {
 		err = a.sup.WaitAlive(ctx, sh)
@@ -310,6 +360,23 @@ func (a *Agent) settleAdopted(sh *supervisor.Shard, o supervisor.Orphan) {
 			"shard", o.ShardID, "replica", o.ReplicaID, "err", err)
 		return
 	}
+	// An engine started by an agent older than the GPU check may be one
+	// serving a GPU placement on the CPU. Stopped, so its replacement starts
+	// through the check and fails there in words, if the build still sees
+	// no GPU — rather than going on unnoticed after the upgrade that could
+	// have caught it.
+	if err := a.onItsGPUs(ctx, eng, o.Spec, sh.Status().PID); err != nil {
+		a.log.Error("stopping an adopted engine that computes on the CPU though placed on GPUs",
+			"shard", o.ShardID, "replica", o.ReplicaID, "err", err)
+		_ = a.sup.Stop(ctx, o.ShardID)
+		return
+	}
+	// What it computes on, for one started before the agent kept that.
+	if a.sup.ComputeOf(o.ShardID) == nil {
+		if c, ok := a.gpuCompute(ctx, o.Spec.GPUIndices, sh.Status().PID); ok {
+			a.sup.SetCompute(o.ShardID, c)
+		}
+	}
 	a.log.Info("adopted engine is serving",
 		"shard", o.ShardID, "replica", o.ReplicaID)
 }
@@ -350,6 +417,17 @@ func (a *Agent) weights() *weights.Fetcher {
 }
 
 // runningShards describes what this agent is supervising, for registration.
+// unready are the shards a registration reported as not yet ready.
+func unready(running []*llmgwv1.RunningShard) map[string]bool {
+	out := map[string]bool{}
+	for _, r := range running {
+		if r.GetState() != agentsvc.StateToWire(supervisor.Ready) {
+			out[r.GetShardId()] = true
+		}
+	}
+	return out
+}
+
 func (a *Agent) runningShards() []*llmgwv1.RunningShard {
 	var out []*llmgwv1.RunningShard
 	for _, st := range a.sup.Statuses() {
@@ -375,6 +453,7 @@ func (a *Agent) runningShards() []*llmgwv1.RunningShard {
 			Pool:       spec.Pool,
 			Fabric:     spec.Fabric,
 			ProfileFp:  spec.ProfileFP,
+			Compute:    computeToWire(a.sup.ComputeOf(st.ID)),
 			LeaderAddr: a.cfg.MgmtAddr,
 			LeaderPort: int32(spec.LeaderPort),
 		})
@@ -393,6 +472,17 @@ func int32Slice(v []int) []int32 {
 	return out
 }
 
+func int32Ints(v []int32) []int {
+	out := make([]int, len(v))
+	for i, x := range v {
+		out[i] = int(x)
+	}
+	return out
+}
+
+// tracerName names the spans the agent opens.
+const tracerName = "gitea.mynodes.xyz/ilker/llmgw/internal/agent"
+
 // scan refreshes the node's hardware inventory.
 func (a *Agent) scan(ctx context.Context) error {
 	// Carried from the agent's own configuration rather than duplicated into
@@ -446,7 +536,7 @@ 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.InstallableEngines = slices.DeleteFunc(provision.Installable(), a.disabled)
 	reg.Features = []string{FeatureFabricTest}
 	reg.RunningShards = a.runningShards()
 	a.mu.Lock()
@@ -492,6 +582,9 @@ func (a *Agent) session(ctx context.Context, server string) error {
 		a.sendLoop(ctx, stream, out)
 	}()
 	defer wg.Wait()
+	go a.watchExits(ctx, out, unready(reg.RunningShards))
+	go a.forwardKV(ctx, out)
+	go a.reportCompute(ctx, out)
 
 	for {
 		msg, err := stream.Receive()
@@ -511,6 +604,7 @@ func (a *Agent) session(ctx context.Context, server string) error {
 			// why it is not registering is one an operator cannot fix.
 			return err
 		}
+		a.answered.Store(true)
 		a.handle(ctx, msg, out)
 	}
 }
@@ -573,8 +667,24 @@ func (a *Agent) heartbeat() *llmgwv1.AgentMessage {
 	}
 	a.mu.Unlock()
 
-	for _, g := range inv.GPUs {
-		hb.GpuMemoryUsedMb = append(hb.GpuMemoryUsedMb, int32(g.MemoryUsedMB))
+	// Measured now, not carried from registration: a card is shared with
+	// whatever else runs on the machine, and that comes and goes while the
+	// agent runs. The registration figure stays only for a node where
+	// nvidia-smi cannot be asked.
+	if len(inv.GPUs) > 0 {
+		var shards []int
+		for _, st := range a.sup.Statuses() {
+			if st.PID > 0 {
+				shards = append(shards, st.PID)
+			}
+		}
+		hb.GpuForeignMemoryMb, hb.GpuMemoryUsedMb = a.foreignGPUMemory(context.Background(), shards)
+	}
+	if len(hb.GpuMemoryUsedMb) != len(inv.GPUs) {
+		hb.GpuForeignMemoryMb, hb.GpuMemoryUsedMb = nil, nil
+		for _, g := range inv.GPUs {
+			hb.GpuMemoryUsedMb = append(hb.GpuMemoryUsedMb, int32(g.MemoryUsedMB))
+		}
 	}
 
 	// Rescanned here rather than reused from registration. Disk is not a fact
@@ -638,6 +748,39 @@ func (a *Agent) sampleLoad() *llmgwv1.NodeLoad {
 			ShardId: sh.ID, CpuCores: sh.CPUCores, MemoryRssBytes: sh.RSSBytes,
 		})
 	}
+	if a.sensors != nil {
+		se := a.sensors.Sample(context.Background())
+		out.CpuTempC, out.CpuPowerW, out.InletTempC = se.CPUTempC, se.CPUPowerW, se.InletTempC
+		var wear map[int]discovery.GPUWear
+		if a.wear != nil && len(se.GPUs) > 0 {
+			wear = map[int]discovery.GPUWear{}
+			for _, w := range a.wear.Sample(context.Background()) {
+				wear[w.Index] = w
+			}
+		}
+		for _, g := range se.GPUs {
+			gs := &llmgwv1.GPUSensor{
+				Index: int32(g.Index), TempC: g.TempC, MemoryTempC: g.MemoryTempC,
+				PowerW: g.PowerW, PowerLimitW: g.PowerLimitW, Throttle: g.Throttle,
+				UtilizationPercent: g.UtilPercent, MemoryUtilizationPercent: g.MemUtilPercent,
+				MemoryUsedMb: g.MemoryUsedMB, MemoryTotalMb: g.MemoryTotalMB,
+				SmClockMhz: g.SMClockMHz, EccUncorrected: g.ECCUncorrected,
+			}
+			if w, ok := wear[g.Index]; ok {
+				gs.HasWear = true
+				gs.PcieReplays, gs.RetiredPagesSbe, gs.RetiredPagesDbe, gs.RetirementPending =
+					w.PCIeReplays, w.RetiredSBE, w.RetiredDBE, w.RetirePending
+				gs.RemappedRowsCorrectable, gs.RemappedRowsUncorrectable, gs.RemapPending, gs.RemapFailure =
+					w.RemappedCorrectable, w.RemappedUncorrectable, w.RemapPending, w.RemapFailure
+				gs.NvlinkCrcErrors, gs.NvlinkReplayErrors, gs.NvlinkRecoveryErrors = w.NVLinkCRC, w.NVLinkReplay, w.NVLinkRecovery
+				gs.XidErrors, gs.LastXid, gs.LastXidText = w.XIDs, int32(w.LastXID), w.LastXIDText
+				if !w.LastXIDAt.IsZero() {
+					gs.LastXidUnix = w.LastXIDAt.Unix()
+				}
+			}
+			out.Gpus = append(out.Gpus, gs)
+		}
+	}
 	return out
 }
 
@@ -710,21 +853,41 @@ func (a *Agent) removeWeights(paths []string) {
 }
 
 func (a *Agent) handle(ctx context.Context, msg *llmgwv1.ControlMessage, out chan<- *llmgwv1.AgentMessage) {
+	// The control plane's span that sent this, when it is tracing: what is
+	// done here for a start or a stop goes into the same trace.
+	tctx := obs.Extract(ctx, msg.GetTrace())
 	switch m := msg.Msg.(type) {
 	case *llmgwv1.ControlMessage_Start:
-		go a.startShard(ctx, m.Start, out)
+		go a.startShard(tctx, m.Start, out)
 	case *llmgwv1.ControlMessage_Stop:
-		go a.stopShard(ctx, m.Stop.GetShardId(), out)
+		go a.stopShard(tctx, m.Stop.GetShardId(), out)
 	case *llmgwv1.ControlMessage_Drain:
-		if err := a.sup.Drain(m.Drain.GetShardId()); err != nil {
+		_, span := obs.Tracer(tracerName).Start(tctx, "drain shard",
+			trace.WithSpanKind(trace.SpanKindConsumer),
+			trace.WithAttributes(attribute.String("llmgw.shard", m.Drain.GetShardId())))
+		err := a.sup.Drain(m.Drain.GetShardId())
+		if err != nil {
 			a.log.Warn("draining failed", "shard", m.Drain.GetShardId(), "err", err)
 		}
+		obs.End(span, err)
 	case *llmgwv1.ControlMessage_RemoveWeights:
 		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_ControlPlanes:
+		a.setControlPlanes(m.ControlPlanes)
+	case *llmgwv1.ControlMessage_Firewall:
+		go a.applyFirewall(m.Firewall)
+	case *llmgwv1.ControlMessage_RestartAgent:
+		go func() {
+			a.log.Info("restarting, as the control plane asks; the engines keep serving",
+				"reason", m.RestartAgent.GetReason())
+			// A moment for the log line to leave before the process does.
+			time.Sleep(300 * time.Millisecond)
+			exitForUpgrade()
+		}()
 	case *llmgwv1.ControlMessage_Logs:
 		reply := a.logsReply(m.Logs)
 		// Off the receive loop: a full send queue must not stop commands being
@@ -810,9 +973,64 @@ func (a *Agent) watchFetch(source string, fn func(weights.Progress)) (stop func(
 	}
 }
 
+// bindAddr is where engines listen: the management address the control
+// plane reaches them on, not every address the node has — a public one
+// included. Empty, on every address, when that is a name rather than an
+// address this machine holds.
+func (a *Agent) bindAddr() string {
+	ip, err := netip.ParseAddr(a.cfg.MgmtAddr)
+	if err != nil || ip.IsUnspecified() || !localAddr(ip) {
+		return ""
+	}
+	return ip.String()
+}
+
+// engineBase is where the agent asks an engine whether it is ready: where it
+// listens, loopback when that is every address.
+func (a *Agent) engineBase(s engines.ShardSpec) string {
+	host := s.BindAddr
+	if host == "" {
+		host = "127.0.0.1"
+	}
+	return "http://" + net.JoinHostPort(host, strconv.Itoa(s.HTTPPort))
+}
+
+// localAddr reports whether an address is one of this machine's.
+func localAddr(ip netip.Addr) bool {
+	addrs, err := net.InterfaceAddrs()
+	if err != nil {
+		return false
+	}
+	for _, a := range addrs {
+		if p, err := netip.ParsePrefix(a.String()); err == nil && p.Addr().Unmap() == ip.Unmap() {
+			return true
+		}
+	}
+	return false
+}
+
 func (a *Agent) startShard(ctx context.Context, m *llmgwv1.StartShard, out chan<- *llmgwv1.AgentMessage) {
 	shardID, replicaID := m.GetShardId(), m.GetReplicaId()
 
+	// This node's whole part of the start, from the command arriving to the
+	// engine answering, beneath the control plane's span that sent it. The
+	// steps — weights, launch, readiness — are its children.
+	ctx, span := obs.Tracer(tracerName).Start(ctx, "start shard",
+		trace.WithSpanKind(trace.SpanKindConsumer),
+		trace.WithAttributes(
+			attribute.String("llmgw.node", a.cfg.NodeID),
+			attribute.String("llmgw.replica", replicaID),
+			attribute.String("llmgw.shard", shardID),
+			attribute.Int("llmgw.rank", int(m.GetRank())),
+			attribute.String("llmgw.model", m.GetProfile().GetServedModelName()),
+			attribute.String("llmgw.profile", m.GetProfile().GetName()),
+			attribute.String("llmgw.engine", m.GetProfile().GetEngine()),
+			attribute.String("llmgw.gpu_class", m.GetProfile().GetGpuClass()),
+			attribute.IntSlice("llmgw.gpus", int32Ints(m.GetGpuIndices())),
+		))
+	var failed error
+	defer func() { obs.End(span, failed) }()
+
 	a.mu.Lock()
 	a.shardReplica[shardID] = replicaID
 	a.mu.Unlock()
@@ -825,6 +1043,9 @@ func (a *Agent) startShard(ctx context.Context, m *llmgwv1.StartShard, out chan<
 		}
 	}
 	report := func(st supervisor.State, errMsg string, tail []string) {
+		if st == supervisor.Failed {
+			failed = errors.New(errMsg)
+		}
 		send(&llmgwv1.ShardStatus{
 			State: agentsvc.StateToWire(st), Error: errMsg, LastOutput: tail,
 		})
@@ -832,6 +1053,7 @@ func (a *Agent) startShard(ctx context.Context, m *llmgwv1.StartShard, out chan<
 
 	spec, timeout := agentsvc.ShardSpecFromStart(m)
 	a.localizeSpec(&spec)
+	spec.BindAddr = a.bindAddr()
 
 	eng, err := a.reg.Get(spec.Profile.Engine)
 	if err != nil {
@@ -845,6 +1067,12 @@ func (a *Agent) startShard(ctx context.Context, m *llmgwv1.StartShard, out chan<
 
 	// Validate before launching. An engine that refuses a profile does so after
 	// minutes of loading; catching it here costs nothing.
+	// Checked again here, whatever sent the profile: this is the process
+	// about to run as root.
+	if err := engines.UnsafeArgs(spec.Profile.Engine, spec.Profile.Args); err != nil {
+		report(supervisor.Failed, err.Error(), nil)
+		return
+	}
 	if err := eng.Validate(spec.Profile, gpuInfo(inv, spec.GPUIndices)); err != nil {
 		report(supervisor.Failed, err.Error(), nil)
 		return
@@ -877,9 +1105,31 @@ func (a *Agent) startShard(ctx context.Context, m *llmgwv1.StartShard, out chan<
 		stop()
 		spec.Profile.ModelPath = path
 	}
+	// Adapters are fetched like the model, and before the engine starts: it
+	// loads them at start, and one missing is a replica that answers for the
+	// base model under the adapter's name.
+	for i, ad := range spec.Profile.Adapters {
+		path, err := a.weights().Ensure(ctx, ad.Path)
+		if err != nil {
+			report(supervisor.Failed, fmt.Sprintf("adapter %s: %v", ad.Name, err), nil)
+			return
+		}
+		spec.Profile.Adapters[i].Path = path
+	}
+	// Adapters that load on demand are loaded by the router, by a path that
+	// has to mean the same file on every node: a link of the adapter's name
+	// in the directory engines run in.
+	if spec.Profile.RuntimeLoRA() {
+		if err := engines.LinkRuntimeAdapters(a.sup.EngineDir(), spec.Profile.Adapters); err != nil {
+			report(supervisor.Failed, err.Error(), nil)
+			return
+		}
+	}
 
+	a.listenKV(&spec, 0)
 	cmds, err := eng.Commands(spec)
 	if err != nil {
+		a.stopKV(shardID, replicaID)
 		report(supervisor.Failed, err.Error(), nil)
 		return
 	}
@@ -892,6 +1142,7 @@ func (a *Agent) startShard(ctx context.Context, m *llmgwv1.StartShard, out chan<
 			report(sh.Status().State, "", nil)
 			return
 		}
+		a.stopKV(shardID, replicaID)
 		report(supervisor.Failed, err.Error(), sh.Logs(10))
 		return
 	}
@@ -901,46 +1152,117 @@ func (a *Agent) startShard(ctx context.Context, m *llmgwv1.StartShard, out chan<
 	// staying alive, and the replica's real readiness is the leader answering,
 	// which only happens once every worker has joined (plan §11, phase 4).
 	if eng.ServesHTTP(spec) {
-		base := fmt.Sprintf("http://127.0.0.1:%d", spec.HTTPPort)
+		base := a.engineBase(spec)
 		err = a.sup.WaitReady(ctx, sh, base, spec.Profile.ServedModelName, timeout)
 	} else {
 		err = a.sup.WaitAlive(ctx, sh)
 	}
+	// Where it put the model, by its own account: said with the readiness,
+	// and a GPU placement it computes on the CPU refused even where
+	// nvidia-smi cannot be asked.
+	compute, said, cerr := engineCompute(eng, spec.GPUIndices, sh.Logs(512))
+	if err == nil && cerr != nil {
+		err = cerr
+		_ = a.sup.Stop(ctx, shardID)
+	}
+	if err == nil {
+		err = a.onItsGPUs(ctx, eng, spec, sh.Status().PID)
+		if err != nil {
+			// Serving, but not where it was placed: stopped, so the GPU it
+			// holds in the inventory is not taken by a CPU process.
+			_ = a.sup.Stop(ctx, shardID)
+		}
+	}
 	if err != nil {
 		report(supervisor.Failed, err.Error(), sh.Logs(20))
 		return
 	}
-	report(supervisor.Ready, "", nil)
-
-	// Watch for the engine dying later. Nothing else would notice: the router
-	// would simply see failing requests.
-	go a.watch(ctx, sh, replicaID, shardID, out)
+	// The engine's own account when it gave one, with its layers; else what
+	// nvidia-smi sees the shard holding.
+	if !said {
+		compute, said = a.gpuCompute(ctx, spec.GPUIndices, sh.Status().PID)
+	}
+	if said {
+		// Kept with the shard, so an agent restarted, or a control plane
+		// taking over, still learns it.
+		a.sup.SetCompute(shardID, compute)
+		send(&llmgwv1.ShardStatus{State: agentsvc.StateToWire(supervisor.Ready), Compute: computeToWire(&compute)})
+	} else {
+		report(supervisor.Ready, "", nil)
+	}
+	// Its dying later is reported by the session's watchExits.
 }
 
-// watch reports a shard that exits after it was ready.
-func (a *Agent) watch(ctx context.Context, sh *supervisor.Shard, replicaID, shardID string, out chan<- *llmgwv1.AgentMessage) {
+// watchExits reports, for as long as this session lasts, every shard that
+// was ready and has failed: the ones this agent started, and the ones it
+// adopted from the agent before it.
+//
+// Per session rather than per shard. A watcher tied to the stream a shard
+// was started on stopped with that stream, so after a reconnect nothing
+// reported the engine dying; and an adopted engine had no watcher at all —
+// on node06 one was killed and its replica stayed "ready" for the control
+// plane, routed to and failing, indefinitely.
+//
+// It also reports the shards the registration said were not ready yet once
+// they are. An adopted engine is health-checked after the agent registers,
+// and a shard started on the stream before is reported on that stream; so
+// when the registration came first nothing ever told the control plane, and
+// the replica stayed "starting" while it served — on node05, after a
+// control plane restart, the only replica of a model.
+func (a *Agent) watchExits(ctx context.Context, out chan<- *llmgwv1.AgentMessage, pending map[string]bool) {
 	t := time.NewTicker(time.Second)
 	defer t.Stop()
-
+	ready := map[string]bool{}
 	for {
+		for _, st := range a.sup.Statuses() {
+			switch st.State {
+			case supervisor.Ready:
+				ready[st.ID] = true
+				if !pending[st.ID] {
+					continue
+				}
+				delete(pending, st.ID)
+				sh, err := a.sup.Get(st.ID)
+				if err != nil {
+					continue
+				}
+				msg := &llmgwv1.AgentMessage{Msg: &llmgwv1.AgentMessage_Shard{Shard: &llmgwv1.ShardStatus{
+					NodeId: a.cfg.NodeID, ReplicaId: sh.Spec.ReplicaID, ShardId: st.ID,
+					State:   agentsvc.StateToWire(st.State),
+					Compute: computeToWire(a.sup.ComputeOf(st.ID)),
+				}}}
+				select {
+				case out <- msg:
+				case <-ctx.Done():
+					return
+				}
+			case supervisor.Failed:
+				if !ready[st.ID] {
+					continue // never ready here: its start reported it
+				}
+				delete(ready, st.ID)
+				sh, err := a.sup.Get(st.ID)
+				if err != nil {
+					continue
+				}
+				msg := &llmgwv1.AgentMessage{Msg: &llmgwv1.AgentMessage_Shard{Shard: &llmgwv1.ShardStatus{
+					NodeId: a.cfg.NodeID, ReplicaId: sh.Spec.ReplicaID, ShardId: st.ID,
+					State: agentsvc.StateToWire(st.State), Error: st.Err,
+					ExitCode: int32(st.ExitCode), LastOutput: sh.Logs(20),
+				}}}
+				select {
+				case out <- msg:
+				case <-ctx.Done():
+					return
+				}
+			default:
+				delete(ready, st.ID)
+			}
+		}
 		select {
 		case <-ctx.Done():
 			return
 		case <-t.C:
-			st := sh.Status()
-			if !st.State.Terminal() {
-				continue
-			}
-			msg := &llmgwv1.AgentMessage{Msg: &llmgwv1.AgentMessage_Shard{Shard: &llmgwv1.ShardStatus{
-				NodeId: a.cfg.NodeID, ReplicaId: replicaID, ShardId: shardID,
-				State: agentsvc.StateToWire(st.State), Error: st.Err,
-				ExitCode: int32(st.ExitCode), LastOutput: sh.Logs(20),
-			}}}
-			select {
-			case out <- msg:
-			case <-ctx.Done():
-			}
-			return
 		}
 	}
 }
@@ -951,9 +1273,19 @@ func (a *Agent) stopShard(ctx context.Context, shardID string, out chan<- *llmgw
 	delete(a.shardReplica, shardID)
 	a.mu.Unlock()
 
-	if err := a.sup.Stop(ctx, shardID); err != nil {
+	ctx, span := obs.Tracer(tracerName).Start(ctx, "stop shard",
+		trace.WithSpanKind(trace.SpanKindConsumer),
+		trace.WithAttributes(
+			attribute.String("llmgw.node", a.cfg.NodeID),
+			attribute.String("llmgw.replica", replicaID),
+			attribute.String("llmgw.shard", shardID),
+		))
+	err := a.sup.Stop(ctx, shardID)
+	if err != nil {
 		a.log.Warn("stopping a shard failed", "shard", shardID, "err", err)
 	}
+	a.stopKV(shardID, replicaID)
+	obs.End(span, err)
 	a.sup.Remove(shardID)
 
 	msg := &llmgwv1.AgentMessage{Msg: &llmgwv1.AgentMessage_Shard{Shard: &llmgwv1.ShardStatus{
@@ -998,7 +1330,9 @@ func Client(cfg tlsconf.Config, timeout time.Duration) (*http.Client, error) {
 	if !cfg.Enabled() {
 		return &http.Client{
 			Transport: &http2.Transport{
-				AllowHTTP: true,
+				AllowHTTP:       true,
+				ReadIdleTimeout: streamIdle,
+				PingTimeout:     streamPing,
 				DialTLSContext: func(ctx context.Context, network, addr string, _ *tls.Config) (net.Conn, error) {
 					return (&net.Dialer{Timeout: timeout}).DialContext(ctx, network, addr)
 				},
@@ -1013,25 +1347,49 @@ func Client(cfg tlsconf.Config, timeout time.Duration) (*http.Client, error) {
 	if err != nil {
 		return nil, err
 	}
-	return &http.Client{Transport: &http2.Transport{TLSClientConfig: tc}}, nil
+	return &http.Client{Transport: &http2.Transport{
+		TLSClientConfig: tc,
+		ReadIdleTimeout: streamIdle,
+		PingTimeout:     streamPing,
+		// Bounded, as the plaintext branch's is: dialling a control plane
+		// whose machine is off waits out the kernel's connect retries,
+		// about two minutes, before the next address is tried.
+		DialTLSContext: func(ctx context.Context, network, addr string, c *tls.Config) (net.Conn, error) {
+			d := tls.Dialer{NetDialer: &net.Dialer{Timeout: timeout}, Config: c}
+			return d.DialContext(ctx, network, addr)
+		},
+	}}, nil
 }
 
+// A stream to a control plane whose machine stopped dead — powered off, cut
+// off — is never closed: nothing sends the FIN, and the agent's heartbeats sit
+// in the socket's buffer until the kernel gives up retransmitting, fifteen
+// minutes later. Found by switching off a leader: the standby took over in 14
+// seconds and the node stayed with the dead one. An HTTP/2 ping after ten
+// quiet seconds, given five to answer, finds it in a quarter of a minute.
+const (
+	streamIdle = 10 * time.Second
+	streamPing = 5 * time.Second
+)
+
 // localizeSpec fills in what only this node knows.
 //
 // 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.
+// network is on ens3 rather than eth0 would have NCCL bind nothing. On RoCE,
+// which GID entry routes is a property of these adapters. And a MIG instance
+// is opened by its UUID, which only this node knows.
 func (a *Agent) localizeSpec(spec *engines.ShardSpec) {
 	if a.cfg.MgmtInterface != "" {
 		spec.MgmtInterface = a.cfg.MgmtInterface
 	}
+	a.mu.Lock()
+	hcas, gpus := a.inv.HCAs, a.inv.GPUs
+	a.mu.Unlock()
+	spec.GPUUUIDs = migUUIDs(gpus, spec.GPUIndices)
 	if len(spec.HCAs) == 0 {
 		return
 	}
-	a.mu.Lock()
-	hcas := a.inv.HCAs
-	a.mu.Unlock()
 	want := map[string]bool{}
 	for _, h := range spec.HCAs {
 		want[h] = true
@@ -1050,6 +1408,27 @@ func (a *Agent) localizeSpec(spec *engines.ShardSpec) {
 	}
 }
 
+// migUUIDs names a shard's devices by UUID when one of them is a MIG
+// instance, and is nil otherwise: whole cards keep being given by index, as
+// they always were. A device this node does not have is left to fail where
+// it always has, in the engine, rather than guessed at here.
+func migUUIDs(gpus []discovery.GPU, indices []int) []string {
+	var out []string
+	mig := false
+	for _, i := range indices {
+		k := slices.IndexFunc(gpus, func(g discovery.GPU) bool { return g.Index == i })
+		if k < 0 || gpus[k].UUID == "" {
+			return nil
+		}
+		mig = mig || gpus[k].IsMIG()
+		out = append(out, gpus[k].UUID)
+	}
+	if !mig {
+		return nil
+	}
+	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) {
@@ -1066,3 +1445,42 @@ func ResolveManagement(c Config) (addr, iface string) {
 	}
 	return addr, iface
 }
+
+// reportCompute tells the control plane, once a session, what each running
+// shard computes on as soon as that is known: an adopted engine's is found
+// after registration, which carried what was known then.
+func (a *Agent) reportCompute(ctx context.Context, out chan<- *llmgwv1.AgentMessage) {
+	sent := map[string]bool{}
+	t := time.NewTicker(5 * time.Second)
+	defer t.Stop()
+	for range 60 {
+		for _, st := range a.sup.Statuses() {
+			if st.State.Terminal() || sent[st.ID] {
+				continue
+			}
+			c := a.sup.ComputeOf(st.ID)
+			if c == nil {
+				continue
+			}
+			sh, err := a.sup.Get(st.ID)
+			if err != nil {
+				continue
+			}
+			// No state: a report of compute alone, not a transition.
+			msg := &llmgwv1.AgentMessage{Msg: &llmgwv1.AgentMessage_Shard{Shard: &llmgwv1.ShardStatus{
+				NodeId: a.cfg.NodeID, ReplicaId: sh.Spec.ReplicaID, ShardId: st.ID, Compute: computeToWire(c),
+			}}}
+			select {
+			case out <- msg:
+				sent[st.ID] = true
+			case <-ctx.Done():
+				return
+			}
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+		}
+	}
+}

internal/agent/agent_test.go

@@ -37,11 +37,12 @@ import (
 type statusRecorder struct {
 	ch chan status
 
-	mu      sync.Mutex
-	calls   []adoptCall
-	adopted []reconciler.AdoptedShard
-	unclaim []string // shard ids to report back as unclaimed
-	fetches []fetchReport
+	mu       sync.Mutex
+	calls    []adoptCall
+	adopted  []reconciler.AdoptedShard
+	unclaim  []string // shard ids to report back as unclaimed
+	fetches  []fetchReport
+	computes []reconciler.Compute
 }
 
 type status struct {
@@ -61,6 +62,12 @@ func (r *statusRecorder) OnShardStatus(replicaID, shardID string, st supervisor.
 
 // fetches records download progress, so a test can assert that a fetch is
 // visible from the control plane rather than only in the node's log.
+func (r *statusRecorder) OnShardCompute(replicaID, shardID string, c reconciler.Compute) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.computes = append(r.computes, c)
+}
+
 func (r *statusRecorder) OnFetchProgress(replicaID, shardID, source string, done, total int64) {
 	r.mu.Lock()
 	defer r.mu.Unlock()

internal/agent/bindaddr_test.go

@@ -0,0 +1,30 @@
+package agent
+
+import (
+	"testing"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/engines"
+)
+
+func TestEnginesListenOnTheManagementAddressWhenItIsThisMachines(t *testing.T) {
+	cases := map[string]string{
+		"127.0.0.1":   "127.0.0.1", // one of this machine's
+		"203.0.113.9": "",          // not: every address rather than none
+		"gpu07.lan":   "",          // a name
+		"0.0.0.0":     "",
+		"":            "",
+	}
+	for mgmt, want := range cases {
+		a := &Agent{cfg: Config{MgmtAddr: mgmt}}
+		if got := a.bindAddr(); got != want {
+			t.Errorf("management address %q: listens on %q, expected %q", mgmt, got, want)
+		}
+	}
+	a := &Agent{}
+	if got := a.engineBase(engines.ShardSpec{HTTPPort: 8000}); got != "http://127.0.0.1:8000" {
+		t.Errorf("on every address, asked at %s", got)
+	}
+	if got := a.engineBase(engines.ShardSpec{HTTPPort: 8000, BindAddr: "10.0.0.147"}); got != "http://10.0.0.147:8000" {
+		t.Errorf("on one address, asked at %s", got)
+	}
+}

internal/agent/config.go

@@ -14,6 +14,7 @@ import (
 	"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/obs"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/tlsconf"
 )
 
@@ -94,6 +95,13 @@ type Config struct {
 	Engines   engines.Config    `koanf:"engines"`
 	Superv    supervisor.Config `koanf:"supervisor"`
 
+	// Tracing sends this node's part of each replica start — the weights
+	// fetched, the engine launched, the wait for it to answer — to an
+	// OpenTelemetry collector, inside the control plane's trace of that
+	// start. Give it the collector server.yaml's tracing names. Off unless
+	// an endpoint is set here or in OTEL_EXPORTER_OTLP_ENDPOINT.
+	Tracing obs.Tracing `koanf:"tracing"`
+
 	Version string
 }
 

internal/agent/controlplanes.go

@@ -0,0 +1,77 @@
+package agent
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"slices"
+
+	llmgwv1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1"
+)
+
+// controlPlanesFile keeps the control planes the leader last named, beside
+// the agent's configuration rather than in it: the configuration is the
+// operator's, and a list rewritten in it would be a file nobody wrote.
+var controlPlanesFile = "/var/lib/llmgw-agent/control-planes.json"
+
+// servers is every address to dial, in the order to try them: the
+// configuration's, then any the leader named that it lacks.
+func (a *Agent) servers() []string {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	if len(a.serverList) == 0 {
+		return a.cfg.Servers
+	}
+	return a.serverList
+}
+
+// mergeServers puts the leader's list after the configured one, without
+// repeats, and says whether that changed anything.
+func mergeServers(configured, told []string, secure bool) []string {
+	out := slices.Clone(configured)
+	for _, s := range told {
+		fixed, err := normalizeOne(s, secure)
+		if err != nil {
+			continue
+		}
+		if !slices.Contains(out, fixed) {
+			out = append(out, fixed)
+		}
+	}
+	return out
+}
+
+// setControlPlanes takes the leader's list: used from the next reconnect,
+// and kept for the next start.
+func (a *Agent) setControlPlanes(m *llmgwv1.ControlPlanes) {
+	told := m.GetServers()
+	merged := mergeServers(a.cfg.Servers, told, a.cfg.TLS.Enabled())
+	a.mu.Lock()
+	changed := !slices.Equal(merged, a.serverList)
+	a.serverList = merged
+	a.mu.Unlock()
+	if !changed {
+		return
+	}
+	a.log.Info("the control planes to dial", "servers", merged)
+	b, _ := json.Marshal(told)
+	if err := os.MkdirAll(filepath.Dir(controlPlanesFile), 0o755); err == nil {
+		tmp := controlPlanesFile + ".new"
+		if err := os.WriteFile(tmp, b, 0o644); err == nil {
+			_ = os.Rename(tmp, controlPlanesFile)
+		}
+	}
+}
+
+// loadControlPlanes is the list kept from the last time the leader named it.
+func loadControlPlanes(configured []string, secure bool) []string {
+	b, err := os.ReadFile(controlPlanesFile)
+	if err != nil {
+		return configured
+	}
+	var told []string
+	if json.Unmarshal(b, &told) != nil {
+		return configured
+	}
+	return mergeServers(configured, told, secure)
+}

internal/agent/controlplanes_test.go

@@ -0,0 +1,41 @@
+package agent
+
+import (
+	"log/slog"
+	"path/filepath"
+	"slices"
+	"testing"
+
+	llmgwv1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/tlsconf"
+)
+
+func TestAControlPlaneTheLeaderNamesIsDialledAndRemembered(t *testing.T) {
+	old := controlPlanesFile
+	controlPlanesFile = filepath.Join(t.TempDir(), "control-planes.json")
+	t.Cleanup(func() { controlPlanesFile = old })
+
+	configured := []string{"https://10.0.0.140:7443"}
+	// TLS on, as every onboarded node has it: an agent without it refuses
+	// https:// addresses, and the leader's are https://.
+	a := &Agent{cfg: Config{Servers: configured, TLS: tlsconf.Config{CA: "/etc/llmgw/ca.pem"}}, log: slog.New(slog.DiscardHandler)}
+	if got := a.servers(); !slices.Equal(got, configured) {
+		t.Fatalf("before anything is named: %v", got)
+	}
+	// The configured one stays first; the new one is added after it, once.
+	a.setControlPlanes(&llmgwv1.ControlPlanes{Servers: []string{"https://10.0.0.140:7443", "https://10.0.0.150:7443"}})
+	want := []string{"https://10.0.0.140:7443", "https://10.0.0.150:7443"}
+	if got := a.servers(); !slices.Equal(got, want) {
+		t.Errorf("after the leader named two: %v", got)
+	}
+	// And after a restart, before the leader says anything.
+	if got := loadControlPlanes(configured, true); !slices.Equal(got, want) {
+		t.Errorf("after a restart: %v", got)
+	}
+	// A list that drops the configured one does not drop it: the
+	// configuration is the operator's.
+	a.setControlPlanes(&llmgwv1.ControlPlanes{Servers: []string{"https://10.0.0.150:7443"}})
+	if got := a.servers(); got[0] != "https://10.0.0.140:7443" {
+		t.Errorf("the configured server was dropped: %v", got)
+	}
+}

internal/agent/disabled_test.go

@@ -0,0 +1,32 @@
+package agent
+
+import (
+	"testing"
+
+	llmgwv1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/engines"
+)
+
+func TestAnEngineDisabledOnTheNodeIsNeitherInstalledNorAdvertised(t *testing.T) {
+	a := &Agent{}
+	a.cfg.Engines.Disabled = []string{"vllm"}
+	a.setProvision(&llmgwv1.Provision{Engines: []*llmgwv1.EngineWant{
+		{Engine: "llamacpp", Version: "b1"}, {Engine: "vllm", Version: "0.30.0"},
+	}})
+	if len(a.provWants) != 1 || a.provWants[0].Engine != "llamacpp" {
+		t.Errorf("wants %+v: vLLM is disabled here and must not be installed", a.provWants)
+	}
+	a.configuredVers = map[string]string{"vllm": "0.25.0"}
+	a.installedVers = map[string]string{"llamacpp": "b1"}
+	if got := a.engineReportLocked(); got["vllm"] != "" || got["llamacpp"] != "b1" {
+		t.Errorf("advertised %v: a disabled engine found on disk is still not offered", got)
+	}
+}
+
+func TestAnEngineNamedByHandIsNotInstalledOverIt(t *testing.T) {
+	a := &Agent{reg: engines.NewRegistry(engines.Config{LlamaCpp: engines.LlamaCppConfig{Bin: "/opt/own/llama-server"}})}
+	a.setProvision(&llmgwv1.Provision{Engines: []*llmgwv1.EngineWant{{Engine: "llamacpp", Version: "b1"}}})
+	if len(a.provWants) != 0 {
+		t.Errorf("wants %+v: an installed build would be used over the operator's own", a.provWants)
+	}
+}

internal/agent/discovery/gpu.go

@@ -47,6 +47,11 @@ type GPU struct {
 	Fabric *GPUFabric `json:"fabric,omitempty"`
 	// Health carries anything that should keep the GPU out of placement.
 	Health GPUHealth `json:"health"`
+	// MIG is set when this is a MIG instance rather than a whole card: its
+	// Index is then MIGIndex's, its UUID the instance's (MIG-…), and its
+	// memory the instance's share. Utilisation stays unreported, because no
+	// driver measures it per instance.
+	MIG *MIGDevice `json:"mig,omitempty"`
 }
 
 // GPUHealth records conditions that make a GPU unsafe to schedule onto.
@@ -94,8 +99,30 @@ func (g GPU) Class() string {
 	}
 
 	// Round to the nearest GiB: vendors report 81559 MiB for an "80GB" card.
-	gb := int(math.Round(float64(g.MemoryTotalMB) / 1024))
-	return fmt.Sprintf("%s-%dg", model, gb)
+	// A MIG instance is named from its card's memory and then its profile,
+	// so two instances are one class only when both the card and the slice
+	// are the same.
+	mem := g.MemoryTotalMB
+	if g.MIG != nil {
+		mem = g.MIG.ParentMemoryTotalMB
+	}
+	gb := int(math.Round(float64(mem) / 1024))
+	class := fmt.Sprintf("%s-%dg", model, gb)
+	if g.MIG != nil {
+		return migClass(class, g.MIG.Profile)
+	}
+	return class
+}
+
+// normalizeBusID makes bus ids comparable: NVML reports them uppercase from one
+// call and lowercase from another, and sometimes with a shortened domain.
+func normalizeBusID(s string) string {
+	s = strings.ToLower(strings.TrimSpace(s))
+	// "0000:1b:00.0" and "00000000:1B:00.0" are the same device.
+	if i := strings.Index(s, ":"); i > 0 {
+		s = strings.TrimLeft(s[:i], "0") + s[i:]
+	}
+	return strings.TrimPrefix(s, ":")
 }
 
 // MarshalJSON adds the derived class, so a consumer of the JSON does not have

internal/agent/discovery/gpu_nvml.go

@@ -14,7 +14,6 @@ package discovery
 import (
 	"context"
 	"fmt"
-	"strings"
 
 	"github.com/NVIDIA/go-nvml/pkg/nvml"
 )
@@ -83,11 +82,18 @@ func DiscoverGPUsNVML(_ context.Context) ([]GPU, error) {
 		}
 
 		assessHealth(&g)
-		gpus = append(gpus, g)
+		// A card in MIG mode is its instances, not itself: CUDA will not
+		// open the whole card while MIG is on.
+		devs, _ := migFromNVML(g, nvmlCard{dev})
+		gpus = append(gpus, devs...)
 	}
 
-	// A second pass, because a link's remote end may be a GPU enumerated later.
+	// A second pass, because a link's remote end may be a GPU enumerated
+	// later. MIG instances have no NVLink of their own to use.
 	for i := range gpus {
+		if gpus[i].IsMIG() {
+			continue
+		}
 		dev, ret := nvml.DeviceGetHandleByIndex(gpus[i].Index)
 		if ret != nvml.SUCCESS {
 			continue
@@ -136,13 +142,73 @@ func busIDString(b []int8) string {
 	return string(buf)
 }
 
-// normalizeBusID makes bus ids comparable: NVML reports them uppercase from one
-// call and lowercase from another, and sometimes with a shortened domain.
-func normalizeBusID(s string) string {
-	s = strings.ToLower(strings.TrimSpace(s))
-	// "0000:1b:00.0" and "00000000:1B:00.0" are the same device.
-	if i := strings.Index(s, ":"); i > 0 {
-		s = strings.TrimLeft(s[:i], "0") + s[i:]
+// nvmlCard adapts an NVML device to what MIG discovery reads of it.
+type nvmlCard struct{ dev nvml.Device }
+
+func (c nvmlCard) MIGMode() (current, pending, ok bool) {
+	cur, pend, ret := c.dev.GetMigMode()
+	if ret != nvml.SUCCESS {
+		// NOT_SUPPORTED on a card without MIG, which is most of them.
+		return false, false, false
 	}
-	return strings.TrimPrefix(s, ":")
+	return cur == nvml.DEVICE_MIG_ENABLE, pend == nvml.DEVICE_MIG_ENABLE, true
+}
+
+func (c nvmlCard) MaxMIGDevices() int {
+	n, ret := c.dev.GetMaxMigDeviceCount()
+	if ret != nvml.SUCCESS {
+		return 0
+	}
+	return n
+}
+
+func (c nvmlCard) MIGDevice(i int) (nvmlMIGInstance, bool) {
+	h, ret := c.dev.GetMigDeviceHandleByIndex(i)
+	if ret != nvml.SUCCESS {
+		// NOT_FOUND for an index with no instance: the count is the most a
+		// card can hold, not how many it has.
+		return nil, false
+	}
+	return nvmlMIG{h}, true
+}
+
+// nvmlMIG adapts a MIG device handle.
+type nvmlMIG struct{ dev nvml.Device }
+
+func (m nvmlMIG) UUID() string {
+	u, _ := m.dev.GetUUID()
+	return u
+}
+
+func (m nvmlMIG) Name() string {
+	n, _ := m.dev.GetName()
+	return n
+}
+
+func (m nvmlMIG) Memory() (totalMB, usedMB int, ok bool) {
+	mem, ret := m.dev.GetMemoryInfo()
+	if ret != nvml.SUCCESS {
+		return 0, 0, false
+	}
+	return int(mem.Total / (1 << 20)), int(mem.Used / (1 << 20)), true
+}
+
+func (m nvmlMIG) Instances() (gpuInstance, computeInstance int) {
+	gi, ret := m.dev.GetGpuInstanceId()
+	if ret != nvml.SUCCESS {
+		gi = -1
+	}
+	ci, ret := m.dev.GetComputeInstanceId()
+	if ret != nvml.SUCCESS {
+		ci = -1
+	}
+	return gi, ci
+}
+
+func (m nvmlMIG) Attributes() (slices, memoryMB int, ok bool) {
+	a, ret := m.dev.GetAttributes()
+	if ret != nvml.SUCCESS {
+		return 0, 0, false
+	}
+	return int(a.GpuInstanceSliceCount), int(a.MemorySizeMB), true
 }

internal/agent/discovery/gpu_smi.go

@@ -60,7 +60,33 @@ func DiscoverGPUsSMI(ctx context.Context, binary string) ([]GPU, error) {
 	if err != nil {
 		return nil, fmt.Errorf("running %s: %w", binary, err)
 	}
-	return parseSMI(string(out))
+	cards, err := parseSMI(string(out))
+	if err != nil || len(cards) == 0 {
+		return cards, err
+	}
+	// The query lists whole cards, MIG mode or not. A card in MIG mode is
+	// replaced by its instances, which only -L names and only the full
+	// report sizes; asked only when some card could be in MIG mode, since
+	// the report is the slowest thing nvidia-smi does.
+	if !anyMIGCapable(cards) {
+		return cards, nil
+	}
+	listed, report := readMIG(ctx, binary)
+	return expandMIG(cards, listed, report), nil
+}
+
+// anyMIGCapable reports whether any card could be in MIG mode: MIG began
+// with compute capability 8.0 (the A100). The consumer cards of the same
+// generations have none, but telling them apart by name is guesswork, and
+// asking one costs only two more nvidia-smi runs at registration.
+func anyMIGCapable(cards []GPU) bool {
+	for _, c := range cards {
+		major, _, _ := strings.Cut(c.ComputeCapability, ".")
+		if n, err := strconv.Atoi(major); err == nil && n >= 8 {
+			return true
+		}
+	}
+	return false
 }
 
 func parseSMI(out string) ([]GPU, error) {
@@ -106,9 +132,27 @@ func parseSMI(out string) ([]GPU, error) {
 	return gpus, nil
 }
 
-// residentMemoryToleranceMB is how much allocated memory is written off as
+// ForeignMemoryToleranceMB is how much allocated memory is written off as
 // driver overhead rather than a foreign process.
-const residentMemoryToleranceMB = 512
+const ForeignMemoryToleranceMB = 512
+
+// foreignMemorySuffix ends the problem a card with another tenant on it is
+// kept out of placement for. One phrase, so that the control plane can find
+// it again and drop it when the tenant leaves.
+const foreignMemorySuffix = " MiB already allocated by another process"
+
+// ForeignMemoryProblem is the problem for mb of memory held by something
+// that is not one of this agent's engines, or "" when that is too little to
+// count.
+func ForeignMemoryProblem(mb int) string {
+	if mb <= ForeignMemoryToleranceMB {
+		return ""
+	}
+	return fmt.Sprintf("%d%s", mb, foreignMemorySuffix)
+}
+
+// IsForeignMemoryProblem reports whether a problem is ForeignMemoryProblem's.
+func IsForeignMemoryProblem(p string) bool { return strings.HasSuffix(p, foreignMemorySuffix) }
 
 // assessHealth flags conditions that should keep a GPU out of placement.
 func assessHealth(g *GPU) {
@@ -119,8 +163,12 @@ func assessHealth(g *GPU) {
 	// Memory already in use means something else is on the card. Starting an
 	// engine there would either fail to allocate or quietly evict the other
 	// process's throughput.
-	if g.MemoryUsedMB > residentMemoryToleranceMB {
-		g.Health.Problems = append(g.Health.Problems,
-			fmt.Sprintf("%d MiB already allocated by another process", g.MemoryUsedMB))
+	//
+	// Only a first reading: this runs before the agent knows which processes
+	// are its own, so an engine still running from before a restart reads as
+	// foreign here. Every heartbeat measures it again, without the agent's
+	// own engines, and the control plane replaces this with that.
+	if p := ForeignMemoryProblem(g.MemoryUsedMB); p != "" {
+		g.Health.Problems = append(g.Health.Problems, p)
 	}
 }

internal/agent/discovery/gpuhealth.go

@@ -0,0 +1,280 @@
+package discovery
+
+import (
+	"context"
+	"encoding/xml"
+	"os/exec"
+	"regexp"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// GPUWear is what wears a card out or takes it down, beyond temperature:
+// read every minute, from nvidia-smi and the kernel's log. The early signs of
+// a card failing are here — a growing count of rows its memory had to remap,
+// PCIe link retries, XID errors — long before a replica on it fails.
+//
+// A count of -1 is not reported: a card without row remapping (before
+// Ampere) has no such count, which is not the same as none.
+type GPUWear struct {
+	Index int
+	// PCIeReplays are link-level retries on the card's PCIe link: a few are
+	// noise, a count that keeps climbing is a riser, slot or cable.
+	PCIeReplays int64
+	// RetiredSBE and RetiredDBE are memory pages retired for single and
+	// double bit errors (cards before Ampere); RetirePending is a page
+	// waiting for a reset to be retired.
+	RetiredSBE, RetiredDBE int64
+	RetirePending          bool
+	// RemappedCorrectable and RemappedUncorrectable are memory rows remapped
+	// (Ampere and later). RemapPending waits for a reset; RemapFailure is a
+	// card out of spare rows — it needs replacing.
+	RemappedCorrectable, RemappedUncorrectable int64
+	RemapPending, RemapFailure                 bool
+	// NVLink errors summed over the card's links, by kind.
+	NVLinkCRC, NVLinkReplay, NVLinkRecovery int64
+	// XIDs are the driver's error events for this card since the agent
+	// started, and the last of them.
+	XIDs        int64
+	LastXID     int
+	LastXIDText string
+	LastXIDAt   time.Time
+}
+
+// healthEvery is how often health is read: it changes over hours, and the
+// kernel log and nvidia-smi's full report are the heavier reads.
+const healthEvery = time.Minute
+
+// HealthSampler reads GPUWear, keeping the XID counts between reads.
+type HealthSampler struct {
+	run func(ctx context.Context, name string, args ...string) ([]byte, error)
+	now func() time.Time
+
+	mu      sync.Mutex
+	at      time.Time
+	last    []GPUWear
+	since   time.Time
+	xids    map[int]*GPUWear
+	started bool
+}
+
+// NewHealthSampler reads the machine's own nvidia-smi and kernel log.
+func NewHealthSampler() *HealthSampler {
+	return &HealthSampler{now: time.Now, xids: map[int]*GPUWear{},
+		run: func(ctx context.Context, name string, args ...string) ([]byte, error) {
+			return exec.CommandContext(ctx, name, args...).Output() //nolint:gosec // fixed tools
+		}}
+}
+
+// Sample is the cards' health, read again once healthEvery has passed. Nil
+// on a machine without nvidia-smi.
+func (h *HealthSampler) Sample(ctx context.Context) []GPUWear {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	now := h.now()
+	if !h.at.IsZero() && now.Sub(h.at) < healthEvery {
+		return h.last
+	}
+	h.at = now
+	ctx, cancel := context.WithTimeout(ctx, 15*time.Second)
+	defer cancel()
+	report, err := h.run(ctx, "nvidia-smi", "-q", "-x")
+	if err != nil {
+		h.last = nil
+		return nil
+	}
+	cards, bus := parseHealthReport(report)
+	if out, err := h.run(ctx, "nvidia-smi", "nvlink", "-e"); err == nil {
+		for i, e := range parseNVLinkErrors(string(out)) {
+			if i < len(cards) {
+				cards[i].NVLinkCRC, cards[i].NVLinkReplay, cards[i].NVLinkRecovery = e[0], e[1], e[2]
+			}
+		}
+	}
+	h.readXIDs(ctx, now, bus)
+	for i := range cards {
+		if x := h.xids[i]; x != nil {
+			cards[i].XIDs, cards[i].LastXID, cards[i].LastXIDText, cards[i].LastXIDAt = x.XIDs, x.LastXID, x.LastXIDText, x.LastXIDAt
+		}
+	}
+	h.last = cards
+	return cards
+}
+
+// readXIDs adds the XID events logged since the last read. The first read
+// starts from now: what happened before the agent started was before, and
+// counting the whole log would raise every alert on every restart.
+func (h *HealthSampler) readXIDs(ctx context.Context, now time.Time, bus map[string]int) {
+	if !h.started {
+		h.started, h.since = true, now
+		return
+	}
+	since := h.since
+	h.since = now
+	out, err := h.run(ctx, "journalctl", "-k", "--no-pager", "-o", "short-unix",
+		"--since", "@"+strconv.FormatInt(since.Unix(), 10), "-g", "NVRM: Xid")
+	if err != nil {
+		// No journal, or nothing matched (journalctl exits 1 for that).
+		return
+	}
+	for _, e := range parseXIDs(string(out)) {
+		i, ok := bus[e.bus]
+		if !ok {
+			continue
+		}
+		x := h.xids[i]
+		if x == nil {
+			x = &GPUWear{Index: i}
+			h.xids[i] = x
+		}
+		x.XIDs++
+		x.LastXID, x.LastXIDText = e.code, e.text
+		x.LastXIDAt = now
+		if e.at > 0 {
+			x.LastXIDAt = time.Unix(int64(e.at), 0)
+		}
+	}
+}
+
+// healthLog is the part of nvidia-smi's XML report health is read from.
+type healthLog struct {
+	GPUs []struct {
+		ID  string `xml:"id,attr"`
+		PCI struct {
+			Replay string `xml:"replay_counter"`
+		} `xml:"pci"`
+		Retired struct {
+			SBE     string `xml:"multiple_single_bit_retirement>retired_count"`
+			DBE     string `xml:"double_bit_retirement>retired_count"`
+			Pending string `xml:"pending_retirement"`
+			// Older drivers name it pending_blacklist.
+			Blacklist string `xml:"pending_blacklist"`
+		} `xml:"retired_pages"`
+		Remapped struct {
+			Corr    string `xml:"remapped_row_corr"`
+			Unc     string `xml:"remapped_row_unc"`
+			Pending string `xml:"remapped_row_pending"`
+			Failure string `xml:"remapped_row_failure"`
+		} `xml:"remapped_rows"`
+	} `xml:"gpu"`
+}
+
+// parseHealthReport reads each card's health, in index order, and maps each
+// card's PCI bus ("3b:00", as the kernel names it) to its index.
+func parseHealthReport(report []byte) ([]GPUWear, map[string]int) {
+	var log healthLog
+	if err := xml.Unmarshal(report, &log); err != nil {
+		return nil, nil
+	}
+	bus := map[string]int{}
+	out := make([]GPUWear, 0, len(log.GPUs))
+	for i, g := range log.GPUs {
+		bus[busOf(g.ID)] = i
+		out = append(out, GPUWear{
+			Index:                 i,
+			PCIeReplays:           count(g.PCI.Replay),
+			RetiredSBE:            count(g.Retired.SBE),
+			RetiredDBE:            count(g.Retired.DBE),
+			RetirePending:         yes(g.Retired.Pending) || yes(g.Retired.Blacklist),
+			RemappedCorrectable:   count(g.Remapped.Corr),
+			RemappedUncorrectable: count(g.Remapped.Unc),
+			RemapPending:          yes(g.Remapped.Pending),
+			RemapFailure:          yes(g.Remapped.Failure),
+		})
+	}
+	return out, bus
+}
+
+// busOf is a PCI address as the kernel's XID lines carry it: nvidia-smi
+// says "00000000:3B:00.0", the kernel "0000:3b:00".
+func busOf(id string) string {
+	id = strings.ToLower(strings.TrimSpace(id))
+	if i := strings.LastIndex(id, "."); i >= 0 {
+		id = id[:i]
+	}
+	parts := strings.Split(id, ":")
+	if len(parts) >= 2 {
+		return parts[len(parts)-2] + ":" + parts[len(parts)-1]
+	}
+	return id
+}
+
+func count(s string) int64 {
+	n, err := strconv.ParseInt(strings.TrimSpace(s), 10, 64)
+	if err != nil {
+		return -1
+	}
+	return n
+}
+
+func yes(s string) bool { return strings.EqualFold(strings.TrimSpace(s), "yes") }
+
+// nvlinkError matches a line of `nvidia-smi nvlink -e`, whose wording varies
+// by driver: "Link 0: Replay Errors: 0", "Link 0: CRC Errors: 0",
+// "Link 3: Data CRC Errors: 2".
+var (
+	nvlinkGPU   = regexp.MustCompile(`^GPU (\d+):`)
+	nvlinkError = regexp.MustCompile(`Link \d+:\s*(.*?)\s*Errors?\s*:\s*(\d+)`)
+)
+
+// parseNVLinkErrors sums each card's link errors by kind: CRC, replay,
+// recovery.
+func parseNVLinkErrors(out string) map[int][3]int64 {
+	res := map[int][3]int64{}
+	gpu := -1
+	for _, line := range strings.Split(out, "\n") {
+		if m := nvlinkGPU.FindStringSubmatch(strings.TrimSpace(line)); m != nil {
+			gpu, _ = strconv.Atoi(m[1])
+			continue
+		}
+		m := nvlinkError.FindStringSubmatch(line)
+		if m == nil || gpu < 0 {
+			continue
+		}
+		n, _ := strconv.ParseInt(m[2], 10, 64)
+		e := res[gpu]
+		kind := strings.ToLower(m[1])
+		switch {
+		case strings.Contains(kind, "crc"):
+			e[0] += n
+		case strings.Contains(kind, "replay"):
+			e[1] += n
+		case strings.Contains(kind, "recovery"):
+			e[2] += n
+		}
+		res[gpu] = e
+	}
+	return res
+}
+
+type xidEvent struct {
+	bus  string
+	code int
+	text string
+	at   float64
+}
+
+// xidLine matches the driver's report of an XID:
+// "NVRM: Xid (PCI:0000:3b:00): 79, pid=..., GPU has fallen off the bus."
+var xidLine = regexp.MustCompile(`NVRM: Xid \(PCI:([0-9a-fA-F:.]+)\): (\d+),\s*(.*)$`)
+
+// parseXIDs reads journalctl's short-unix lines: a timestamp, then the
+// message.
+func parseXIDs(out string) []xidEvent {
+	var evs []xidEvent
+	for _, line := range strings.Split(out, "\n") {
+		m := xidLine.FindStringSubmatch(line)
+		if m == nil {
+			continue
+		}
+		code, _ := strconv.Atoi(m[2])
+		e := xidEvent{bus: busOf(m[1]), code: code, text: strings.TrimSpace(m[3])}
+		if f := strings.Fields(line); len(f) > 0 {
+			e.at, _ = strconv.ParseFloat(f[0], 64)
+		}
+		evs = append(evs, e)
+	}
+	return evs
+}

internal/agent/discovery/gpuhealth_test.go

@@ -0,0 +1,101 @@
+package discovery
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+)
+
+const healthXML = `<?xml version="1.0" ?>
+<nvidia_smi_log>
+  <gpu id="00000000:3B:00.0">
+    <pci><replay_counter>0</replay_counter></pci>
+    <retired_pages>
+      <multiple_single_bit_retirement><retired_count>N/A</retired_count></multiple_single_bit_retirement>
+      <double_bit_retirement><retired_count>N/A</retired_count></double_bit_retirement>
+      <pending_retirement>N/A</pending_retirement>
+    </retired_pages>
+    <remapped_rows>
+      <remapped_row_corr>2</remapped_row_corr>
+      <remapped_row_unc>1</remapped_row_unc>
+      <remapped_row_pending>Yes</remapped_row_pending>
+      <remapped_row_failure>No</remapped_row_failure>
+    </remapped_rows>
+  </gpu>
+  <gpu id="00000000:5E:00.0">
+    <pci><replay_counter>4021</replay_counter></pci>
+    <retired_pages>
+      <multiple_single_bit_retirement><retired_count>3</retired_count></multiple_single_bit_retirement>
+      <double_bit_retirement><retired_count>1</retired_count></double_bit_retirement>
+      <pending_blacklist>Yes</pending_blacklist>
+    </retired_pages>
+    <remapped_rows>N/A</remapped_rows>
+  </gpu>
+</nvidia_smi_log>`
+
+const nvlinkOut = `GPU 0: NVIDIA H100 80GB HBM3 (UUID: GPU-aaa)
+	 Link 0: Replay Errors: 1
+	 Link 0: Recovery Errors: 0
+	 Link 0: CRC Errors: 5
+	 Link 1: Data CRC Errors: 2
+GPU 1: NVIDIA H100 80GB HBM3 (UUID: GPU-bbb)
+	 Link 0: Replay Errors: 0
+`
+
+func TestAGPUsWearAndFailuresAreReadAndCountedFromWhenTheAgentStarted(t *testing.T) {
+	now := time.Unix(1_800_000_000, 0)
+	journal := ""
+	h := &HealthSampler{now: func() time.Time { return now }, xids: map[int]*GPUWear{},
+		run: func(_ context.Context, name string, args ...string) ([]byte, error) {
+			switch {
+			case name == "nvidia-smi" && args[0] == "-q":
+				return []byte(healthXML), nil
+			case name == "nvidia-smi" && args[0] == "nvlink":
+				return []byte(nvlinkOut), nil
+			case name == "journalctl":
+				if journal == "" {
+					return nil, errors.New("exit status 1")
+				}
+				return []byte(journal), nil
+			}
+			return nil, errors.New("unexpected " + name)
+		}}
+	got := h.Sample(t.Context())
+	if len(got) != 2 {
+		t.Fatalf("%+v", got)
+	}
+	a, b := got[0], got[1]
+	if a.RemappedCorrectable != 2 || a.RemappedUncorrectable != 1 || !a.RemapPending || a.RemapFailure ||
+		a.RetiredSBE != -1 || a.PCIeReplays != 0 || a.NVLinkCRC != 7 || a.NVLinkReplay != 1 {
+		t.Errorf("card 0 %+v", a)
+	}
+	if b.PCIeReplays != 4021 || b.RetiredSBE != 3 || b.RetiredDBE != 1 || !b.RetirePending || b.RemappedCorrectable != -1 {
+		t.Errorf("card 1 %+v", b)
+	}
+
+	// An XID on card 1, logged after the agent started; read on the next
+	// sample a minute on.
+	journal = "1800000030.123456 gpu07 kernel: NVRM: Xid (PCI:0000:5e:00): 79, pid=1234, name=llama-server, GPU has fallen off the bus.\n"
+	now = now.Add(61 * time.Second)
+	got = h.Sample(t.Context())
+	if got[1].XIDs != 1 || got[1].LastXID != 79 || !strings.Contains(got[1].LastXIDText, "fallen off the bus") ||
+		got[1].LastXIDAt.Unix() != 1_800_000_030 || got[0].XIDs != 0 {
+		t.Errorf("after an XID: %+v / %+v", got[0], got[1])
+	}
+	// Within the minute, the last reading.
+	journal = ""
+	now = now.Add(10 * time.Second)
+	if again := h.Sample(t.Context()); again[1].XIDs != 1 {
+		t.Errorf("%+v", again[1])
+	}
+}
+
+func TestBusIDsAreReadAsTheKernelWritesThem(t *testing.T) {
+	for in, want := range map[string]string{"00000000:3B:00.0": "3b:00", "0000:3b:00": "3b:00", "0000:5e:00.0": "5e:00"} {
+		if got := busOf(in); got != want {
+			t.Errorf("%s: %s, want %s", in, got, want)
+		}
+	}
+}

internal/agent/discovery/gpuprocs.go

@@ -0,0 +1,142 @@
+package discovery
+
+import (
+	"context"
+	"encoding/xml"
+	"fmt"
+	"os/exec"
+	"slices"
+	"strconv"
+	"strings"
+)
+
+// GPUProcesses reports which processes hold memory on each GPU, by the GPU's
+// nvidia-smi index: what a process actually computes on, as opposed to what it
+// was told to use. A llama.cpp started with --n-gpu-layers on a GPU whose
+// backend did not load runs on the CPU without a word, and this is where that
+// shows — the process is on no GPU's list.
+//
+// From the full query rather than --query-compute-apps, which lists compute
+// processes only: llama.cpp's Vulkan build is listed as a graphics one, and
+// would have read as not on its GPU at all.
+//
+// A node with no nvidia-smi returns nil and no error, as discovery does.
+func GPUProcesses(ctx context.Context, binary string) (map[int][]int, error) {
+	if binary == "" {
+		if _, err := exec.LookPath("nvidia-smi"); err != nil {
+			return nil, nil
+		}
+		binary = "nvidia-smi"
+	}
+	out, err := exec.CommandContext(ctx, binary, "-q", "-x").Output()
+	if err != nil {
+		return nil, fmt.Errorf("running %s: %w", binary, err)
+	}
+	return parseGPUProcesses(out)
+}
+
+// GPUMemory is one device's memory as nvidia-smi reports it at a moment: what
+// is allocated on it, and which processes hold how much of that.
+//
+// A device is what discovery reports: a whole card, or each MIG instance of a
+// card in MIG mode, in the same order, so the readings line up with the
+// inventory one for one.
+type GPUMemory struct {
+	// Index is the device's number as placement knows it: the card's
+	// nvidia-smi index, or MIGIndex's for an instance.
+	Index  int
+	UsedMB int
+	Procs  []GPUProcess
+}
+
+// GPUProcess is one process holding memory on a card.
+type GPUProcess struct {
+	PID    int
+	UsedMB int
+}
+
+// GPUMemoryByProcess reports each GPU's memory, by index, with the processes
+// holding it — from the same report as GPUProcesses, so the two never
+// disagree about who is on a card.
+//
+// A node with no nvidia-smi returns nil and no error, as discovery does.
+func GPUMemoryByProcess(ctx context.Context, binary string) ([]GPUMemory, error) {
+	if binary == "" {
+		if _, err := exec.LookPath("nvidia-smi"); err != nil {
+			return nil, nil
+		}
+		binary = "nvidia-smi"
+	}
+	out, err := exec.CommandContext(ctx, binary, "-q", "-x").Output()
+	if err != nil {
+		return nil, fmt.Errorf("running %s: %w", binary, err)
+	}
+	return parseGPUMemory(out)
+}
+
+// parseGPUProcesses reads the report, by device as placement numbers them:
+// nvidia-smi's index for a whole card, MIGIndex's for a MIG instance.
+func parseGPUProcesses(report []byte) (map[int][]int, error) {
+	mem, err := parseGPUMemory(report)
+	if err != nil {
+		return nil, err
+	}
+	out := map[int][]int{}
+	for _, g := range mem {
+		for _, p := range g.Procs {
+			out[g.Index] = append(out[g.Index], p.PID)
+		}
+	}
+	return out, nil
+}
+
+// parseGPUMemory reads the report into each device's memory and its holders.
+//
+// Cards are listed in index order, which is nvidia-smi's own numbering. A
+// card in MIG mode is read as its instances, each with its own memory and
+// the processes nvidia-smi attributes to its GPU and compute instance: a
+// process on one instance is not on its neighbours, and the card's total
+// would have charged every instance with all of them.
+func parseGPUMemory(report []byte) ([]GPUMemory, error) {
+	var log migLog
+	if err := xml.Unmarshal(report, &log); err != nil {
+		return nil, fmt.Errorf("reading nvidia-smi's report: %w", err)
+	}
+	out := make([]GPUMemory, 0, len(log.GPUs))
+	for i, g := range log.GPUs {
+		procs := func(gi, ci int) []GPUProcess {
+			var ps []GPUProcess
+			for _, p := range g.Processes {
+				pid, err := strconv.Atoi(strings.TrimSpace(p.PID))
+				if err != nil {
+					continue
+				}
+				if gi >= 0 && (atoiOr(p.GPUInstance, -1) != gi || atoiOr(p.ComputeInstance, -1) != ci) {
+					continue
+				}
+				ps = append(ps, GPUProcess{PID: pid, UsedMB: mib(p.UsedMB)})
+			}
+			return ps
+		}
+		if !enabled(g.Current) || len(g.Devices) == 0 {
+			out = append(out, GPUMemory{Index: i, UsedMB: mib(g.Used), Procs: procs(-1, -1)})
+			continue
+		}
+		devs := slices.Clone(g.Devices)
+		slices.SortFunc(devs, func(a, b migLogDevice) int { return atoiOr(a.Index, -1) - atoiOr(b.Index, -1) })
+		for _, d := range devs {
+			out = append(out, GPUMemory{
+				Index:  MIGIndex(i, atoiOr(d.Index, 0)),
+				UsedMB: mib(d.Used),
+				Procs:  procs(atoiOr(d.GPUInstance, -1), atoiOr(d.ComputeInstance, -1)),
+			})
+		}
+	}
+	return out, nil
+}
+
+// mib reads "4932 MiB"; anything else, "N/A" included, is zero.
+func mib(s string) int {
+	n, _ := strconv.Atoi(strings.TrimSpace(strings.TrimSuffix(strings.TrimSpace(s), "MiB")))
+	return n
+}

internal/agent/discovery/gpuprocs_test.go

@@ -0,0 +1,78 @@
+package discovery
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestGPUProcessesOfEveryKindAreListedByIndex(t *testing.T) {
+	report := `<?xml version="1.0" ?>
+<nvidia_smi_log>
+  <driver_version>580.65.06</driver_version>
+  <gpu id="00000000:17:00.0"><product_name>Tesla V100-SXM2-32GB</product_name>
+    <processes></processes>
+  </gpu>
+  <gpu id="00000000:65:00.0"><product_name>Tesla V100-SXM2-32GB</product_name>
+    <processes>
+      <process_info><pid>4100</pid><type>C</type><process_name>llama-server</process_name></process_info>
+      <process_info><pid>4300</pid><type>G</type><process_name>llama-server</process_name></process_info>
+    </processes>
+  </gpu>
+  <gpu id="00000000:B3:00.0"><processes>
+      <process_info><pid>4200</pid><type>C+G</type></process_info>
+  </processes></gpu>
+</nvidia_smi_log>`
+	got, err := parseGPUProcesses([]byte(report))
+	if err != nil {
+		t.Fatal(err)
+	}
+	// A Vulkan engine is a graphics process ("G") and is on its GPU all the
+	// same; a compute-only query would have missed it.
+	want := map[int][]int{1: {4100, 4300}, 2: {4200}}
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("got %v, want %v", got, want)
+	}
+	if _, err := parseGPUProcesses([]byte("not xml")); err == nil {
+		t.Error("a report that does not parse was read as no processes")
+	}
+}
+
+func TestGPUMemoryIsReadPerProcess(t *testing.T) {
+	report := `<?xml version="1.0" ?>
+<nvidia_smi_log>
+  <gpu id="00000000:01:00.0"><product_name>Quadro RTX 6000</product_name>
+    <fb_memory_usage><total>24576 MiB</total><used>14514 MiB</used><free>10062 MiB</free></fb_memory_usage>
+    <processes>
+      <process_info><pid>71315</pid><type>C</type><used_memory>4932 MiB</used_memory></process_info>
+      <process_info><pid>4100</pid><type>C</type><used_memory>9500 MiB</used_memory></process_info>
+    </processes>
+  </gpu>
+  <gpu id="00000000:02:00.0">
+    <fb_memory_usage><used>N/A</used></fb_memory_usage>
+    <processes></processes>
+  </gpu>
+</nvidia_smi_log>`
+	got, err := parseGPUMemory([]byte(report))
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []GPUMemory{
+		{Index: 0, UsedMB: 14514, Procs: []GPUProcess{{PID: 71315, UsedMB: 4932}, {PID: 4100, UsedMB: 9500}}},
+		{Index: 1},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("got %+v, want %+v", got, want)
+	}
+}
+
+func TestForeignMemoryBelowTheToleranceIsNoProblem(t *testing.T) {
+	// A CUDA context that has let go of its model still holds a few hundred
+	// MiB: ComfyUI after /free held 324.
+	if p := ForeignMemoryProblem(330); p != "" {
+		t.Errorf("330 MiB is a problem: %q", p)
+	}
+	p := ForeignMemoryProblem(5014)
+	if !IsForeignMemoryProblem(p) || IsForeignMemoryProblem("2 uncorrected ECC errors") {
+		t.Errorf("%q is not recognised as the foreign memory problem, or ECC is", p)
+	}
+}

internal/agent/discovery/mig.go

@@ -0,0 +1,560 @@
+package discovery
+
+// MIG — Multi-Instance GPU — carves one A100, H100 or later card into up to
+// seven instances, each with its own memory, its own share of the
+// multiprocessors and its own UUID. To CUDA an instance is a device of its
+// own, and to placement it is one too: a card in MIG mode is reported as its
+// instances instead of as the whole card, each a GPU of a class named from
+// the card's and the instance's profile ("a100-80g-mig-3g.40gb").
+//
+// llmgw does not create instances. Which split a card gets is an operator's
+// decision, made with nvidia-smi mig; discovery reads what is there.
+//
+// Two facts about MIG shape everything below. A process is given one MIG
+// device: CUDA enumerates a single instance however many are made visible.
+// And instances have no NVLink or peer-to-peer access between them. A replica
+// on MIG therefore runs on exactly one instance, never a tensor-parallel group
+// of them, and the catalog refuses a profile that asks for more.
+
+import (
+	"context"
+	"encoding/xml"
+	"fmt"
+	"math"
+	"os/exec"
+	"regexp"
+	"slices"
+	"strconv"
+	"strings"
+)
+
+// MIGDevice is what a MIG instance carries beyond any GPU's fields: which
+// card it is carved from, and how.
+type MIGDevice struct {
+	// ParentIndex is the card's nvidia-smi index, which is what its sensors,
+	// topology and wear are reported by.
+	ParentIndex int    `json:"parent_index"`
+	ParentUUID  string `json:"parent_uuid,omitempty"`
+	// ParentMemoryTotalMB is the whole card's memory: the class is named from
+	// the card, so an instance of an 80 GB card is not mistaken for one of a
+	// 40 GB card that happens to have the same profile name.
+	ParentMemoryTotalMB int `json:"parent_memory_total_mb"`
+	// Device is the instance's number on its card, as nvidia-smi -L lists it.
+	Device int `json:"device"`
+	// Profile is NVIDIA's name for the slice, like "3g.40gb": three of the
+	// card's seven compute slices and forty gigabytes of its memory.
+	Profile string `json:"profile"`
+	// GPUInstance and ComputeInstance are the instance's ids in nvidia-smi
+	// mig -lgi and -lci, which is how nvidia-smi attributes processes to it.
+	GPUInstance     int `json:"gpu_instance"`
+	ComputeInstance int `json:"compute_instance"`
+}
+
+// migIndexBase starts the numbers MIG instances are given.
+//
+// Placement, the agent protocol and every running shard name a node's devices
+// by an integer, which for a whole card is its nvidia-smi index. An instance
+// has none of its own, so it is given 1000 + 100 × card + device: card 0's
+// instance 2 is 1002, card 3's instance 0 is 1300. Readable, stable while the
+// instances are, and never one a whole card could have.
+const migIndexBase = 1000
+
+// MIGIndex is the device number placement knows a MIG instance by.
+func MIGIndex(card, device int) int { return migIndexBase + 100*card + device }
+
+// IsMIGIndex reports whether a device number names a MIG instance.
+func IsMIGIndex(i int) bool { return i >= migIndexBase }
+
+// DeviceLabel is how a device number is shown to people: "3" for a whole
+// card, "0/mig2" for card 0's MIG instance 2.
+func DeviceLabel(i int) string {
+	if !IsMIGIndex(i) {
+		return strconv.Itoa(i)
+	}
+	i -= migIndexBase
+	return fmt.Sprintf("%d/mig%d", i/100, i%100)
+}
+
+// DeviceLabels is DeviceLabel for each of a list.
+func DeviceLabels(is []int) []string {
+	out := make([]string, len(is))
+	for k, i := range is {
+		out[k] = DeviceLabel(i)
+	}
+	return out
+}
+
+// IsMIG reports whether this GPU is a MIG instance rather than a whole card.
+func (g GPU) IsMIG() bool { return g.MIG != nil }
+
+// CardIndex is the nvidia-smi index of the physical card this GPU is on: its
+// own index for a whole card, its parent's for a MIG instance.
+func (g GPU) CardIndex() int {
+	if g.MIG != nil {
+		return g.MIG.ParentIndex
+	}
+	return g.Index
+}
+
+// migClassMarker joins a card's class to an instance's profile in a MIG
+// class: "a100-80g" + "-mig-" + "3g.40gb".
+const migClassMarker = "-mig-"
+
+// IsMIGClass reports whether a GPU class names MIG instances.
+func IsMIGClass(class string) bool { return strings.Contains(class, migClassMarker) }
+
+// migProfileClean keeps a profile name to what a class may hold: "1g.10gb+me"
+// becomes "1g.10gb-me".
+var migProfileClean = regexp.MustCompile(`[^a-z0-9.]+`)
+
+// migClass is the class of a MIG instance: the card's class and the profile.
+func migClass(parentClass, profile string) string {
+	p := migProfileClean.ReplaceAllString(strings.ToLower(strings.TrimSpace(profile)), "-")
+	return parentClass + migClassMarker + strings.Trim(p, "-")
+}
+
+// MIGProfileMemoryGB reads the memory out of a MIG class or profile:
+// 40 from "a100-80g-mig-3g.40gb" or "3g.40gb". Zero when there is none.
+func MIGProfileMemoryGB(s string) int {
+	if i := strings.LastIndex(s, migClassMarker); i >= 0 {
+		s = s[i+len(migClassMarker):]
+	}
+	m := migProfileMemory.FindStringSubmatch(strings.ToLower(s))
+	if m == nil {
+		return 0
+	}
+	gb, _ := strconv.Atoi(m[1])
+	return gb
+}
+
+var migProfileMemory = regexp.MustCompile(`^\d+g\.(\d+)gb`)
+
+// --- nvidia-smi -L ---
+
+// listedMIG is one MIG instance as nvidia-smi -L lists it.
+type listedMIG struct {
+	Device  int
+	Profile string
+	UUID    string
+}
+
+var (
+	// "GPU 0: NVIDIA A100-SXM4-80GB (UUID: GPU-5d5ba0d6-...)"
+	smiListGPU = regexp.MustCompile(`^GPU (\d+):`)
+	// "  MIG 3g.40gb     Device  0: (UUID: MIG-c6d4f1ef-...)". Drivers before
+	// R470 name the instance MIG-GPU-<card uuid>/<gi>/<ci>, which CUDA of that
+	// era takes in the same place, so the UUID is read as whatever it is.
+	smiListMIG = regexp.MustCompile(`^\s+MIG\s+(\S+)\s+Device\s+(\d+):\s*\(UUID:\s*([^)\s]+)\)`)
+)
+
+// parseSMIList reads nvidia-smi -L into each card's MIG instances, by the
+// card's index, in device order. A card with none is absent.
+func parseSMIList(out string) map[int][]listedMIG {
+	res := map[int][]listedMIG{}
+	card := -1
+	for _, line := range strings.Split(out, "\n") {
+		if m := smiListGPU.FindStringSubmatch(line); m != nil {
+			card, _ = strconv.Atoi(m[1])
+			continue
+		}
+		m := smiListMIG.FindStringSubmatch(line)
+		if m == nil || card < 0 {
+			continue
+		}
+		dev, _ := strconv.Atoi(m[2])
+		res[card] = append(res[card], listedMIG{Device: dev, Profile: m[1], UUID: m[3]})
+	}
+	for c := range res {
+		slices.SortFunc(res[c], func(a, b listedMIG) int { return a.Device - b.Device })
+	}
+	return res
+}
+
+// --- nvidia-smi -q -x ---
+
+// migLog is the part of nvidia-smi's XML report MIG is read from: each card's
+// mode, and each instance's ids and memory.
+type migLog struct {
+	GPUs []migLogGPU `xml:"gpu"`
+}
+
+type migLogGPU struct {
+	ID      string         `xml:"id,attr"`
+	Current string         `xml:"mig_mode>current_mig"`
+	Pending string         `xml:"mig_mode>pending_mig"`
+	Devices []migLogDevice `xml:"mig_devices>mig_device"`
+	// Processes carry the GPU and compute instance they run in on a card
+	// in MIG mode, and "N/A" for both otherwise.
+	Processes []struct {
+		GPUInstance     string `xml:"gpu_instance_id"`
+		ComputeInstance string `xml:"compute_instance_id"`
+		PID             string `xml:"pid"`
+		UsedMB          string `xml:"used_memory"`
+	} `xml:"processes>process_info"`
+	Used string `xml:"fb_memory_usage>used"`
+}
+
+type migLogDevice struct {
+	Index           string `xml:"index"`
+	GPUInstance     string `xml:"gpu_instance_id"`
+	ComputeInstance string `xml:"compute_instance_id"`
+	Total           string `xml:"fb_memory_usage>total"`
+	Used            string `xml:"fb_memory_usage>used"`
+}
+
+// migState is one card's MIG mode and instances from the report.
+type migState struct {
+	BusID          string
+	Enabled        bool
+	PendingEnabled bool
+	Devices        []migReported
+}
+
+// migReported is one instance as the report describes it.
+type migReported struct {
+	Device, GPUInstance, ComputeInstance int
+	TotalMB, UsedMB                      int
+}
+
+// enabled reads nvidia-smi's mode words: "Enabled", "Disabled", "N/A".
+func enabled(s string) bool { return strings.EqualFold(strings.TrimSpace(s), "Enabled") }
+
+func atoiOr(s string, def int) int {
+	n, err := strconv.Atoi(strings.TrimSpace(s))
+	if err != nil {
+		return def
+	}
+	return n
+}
+
+// parseMIGReport reads each card's MIG state from the XML report, in the
+// report's order, which is nvidia-smi's index order.
+func parseMIGReport(report []byte) ([]migState, error) {
+	var log migLog
+	if err := xml.Unmarshal(report, &log); err != nil {
+		return nil, fmt.Errorf("reading nvidia-smi's report: %w", err)
+	}
+	out := make([]migState, len(log.GPUs))
+	for i, g := range log.GPUs {
+		out[i] = migState{BusID: g.ID, Enabled: enabled(g.Current), PendingEnabled: enabled(g.Pending)}
+		for _, d := range g.Devices {
+			out[i].Devices = append(out[i].Devices, migReported{
+				Device: atoiOr(d.Index, -1), GPUInstance: atoiOr(d.GPUInstance, -1),
+				ComputeInstance: atoiOr(d.ComputeInstance, -1),
+				TotalMB:         mib(d.Total), UsedMB: mib(d.Used),
+			})
+		}
+		slices.SortFunc(out[i].Devices, func(a, b migReported) int { return a.Device - b.Device })
+	}
+	return out, nil
+}
+
+// --- putting it together ---
+
+// migProblemNoInstances keeps a card in MIG mode with nothing carved from it
+// out of placement: CUDA cannot use the whole card while MIG is on, and
+// there is no instance to use instead.
+const migProblemNoInstances = "MIG is enabled with no instances created: nothing can run on it " +
+	"until instances are created (nvidia-smi mig -cgi … -C) or MIG is turned off"
+
+// migProblemUnnamed is a card whose instances exist but could not be named:
+// an engine is given an instance by its UUID, and without one it cannot be.
+const migProblemUnnamed = "MIG is enabled and has instances, but nvidia-smi -L did not name them, " +
+	"so none can be given to an engine"
+
+// expandMIG replaces each card in MIG mode with its instances.
+//
+// listed is nvidia-smi -L's instances by card, which names them; report is
+// the XML report's state per card, which gives their memory and ids. Either
+// may be missing: -L alone still says which instances exist, and the report
+// alone still says a card is in MIG mode, so a card it says has instances
+// that -L did not name is kept as the whole card with the reason, rather
+// than placed as a card CUDA will not open.
+func expandMIG(cards []GPU, listed map[int][]listedMIG, report []migState) []GPU {
+	if len(listed) == 0 && !slices.ContainsFunc(report, func(s migState) bool { return s.Enabled }) {
+		return cards
+	}
+	byBus := map[string]migState{}
+	for _, s := range report {
+		byBus[normalizeBusID(s.BusID)] = s
+	}
+	out := make([]GPU, 0, len(cards))
+	for pos, c := range cards {
+		st, ok := byBus[normalizeBusID(c.PCIBusID)]
+		if !ok && pos < len(report) {
+			st = report[pos]
+		}
+		devs := listed[c.Index]
+		if !st.Enabled && len(devs) == 0 {
+			out = append(out, c)
+			continue
+		}
+		if len(devs) == 0 {
+			p := migProblemNoInstances
+			if len(st.Devices) > 0 {
+				p = migProblemUnnamed
+			}
+			c.Health.Problems = append(c.Health.Problems, p)
+			out = append(out, c)
+			continue
+		}
+		for _, d := range devs {
+			var rep migReported
+			found := false
+			for _, r := range st.Devices {
+				if r.Device == d.Device {
+					rep, found = r, true
+				}
+			}
+			mig := migInstance(c, d.Device, d.Profile, d.UUID)
+			if found {
+				mig.MIG.GPUInstance, mig.MIG.ComputeInstance = rep.GPUInstance, rep.ComputeInstance
+				mig.MemoryTotalMB, mig.MemoryUsedMB = rep.TotalMB, rep.UsedMB
+			}
+			if mig.MemoryTotalMB == 0 {
+				// The profile says it to the gigabyte, which is close enough
+				// to place by when the report could not be read.
+				mig.MemoryTotalMB = MIGProfileMemoryGB(d.Profile) * 1024
+			}
+			assessHealth(&mig)
+			out = append(out, mig)
+		}
+	}
+	return out
+}
+
+// migInstance builds a MIG instance of card: everything about the card that
+// is shared — driver, compute capability, NUMA node, bus, temperature and
+// ECC errors — and nothing that is not. Not NVLink, which an instance cannot
+// use; not utilisation, which no driver reports per instance; and not the
+// card's memory or problems, which the instance's own replace.
+func migInstance(card GPU, device int, profile, uuid string) GPU {
+	g := GPU{
+		Index: MIGIndex(card.Index, device), UUID: uuid,
+		Name:              strings.TrimSpace(card.Name + " MIG " + profile),
+		ComputeCapability: card.ComputeCapability, NUMANode: card.NUMANode,
+		PCIBusID: card.PCIBusID, DriverVersion: card.DriverVersion, CUDAVersion: card.CUDAVersion,
+		NICPaths: card.NICPaths, Fabric: card.Fabric,
+		Health: GPUHealth{ECCErrors: card.Health.ECCErrors, TemperatureC: card.Health.TemperatureC},
+		MIG: &MIGDevice{
+			ParentIndex: card.Index, ParentUUID: card.UUID, ParentMemoryTotalMB: card.MemoryTotalMB,
+			Device: device, Profile: profile, GPUInstance: -1, ComputeInstance: -1,
+		},
+	}
+	return g
+}
+
+// readMIG asks nvidia-smi for what expandMIG needs. A failure of either
+// command leaves its half empty, which expandMIG is written to take.
+func readMIG(ctx context.Context, binary string) (map[int][]listedMIG, []migState) {
+	var listed map[int][]listedMIG
+	if out, err := exec.CommandContext(ctx, binary, "-L").Output(); err == nil {
+		listed = parseSMIList(string(out))
+	}
+	var report []migState
+	if out, err := exec.CommandContext(ctx, binary, "-q", "-x").Output(); err == nil {
+		report, _ = parseMIGReport(out)
+	}
+	return listed, report
+}
+
+// --- NVML ---
+
+// nvmlMIGCard is the part of an NVML device MIG discovery reads, behind an
+// interface so the logic is tested without a driver: gpu_nvml.go adapts
+// nvml.Device to it.
+type nvmlMIGCard interface {
+	// MIGMode is nvmlDeviceGetMigMode; ok is false on a card without MIG.
+	MIGMode() (current, pending, ok bool)
+	// MaxMIGDevices is nvmlDeviceGetMaxMigDeviceCount.
+	MaxMIGDevices() int
+	// MIGDevice is nvmlDeviceGetMigDeviceHandleByIndex; ok is false for an
+	// index with no instance behind it, which is how NVML says so.
+	MIGDevice(i int) (nvmlMIGInstance, bool)
+}
+
+// nvmlMIGInstance is one MIG device handle.
+type nvmlMIGInstance interface {
+	UUID() string
+	// Name is "NVIDIA A100-SXM4-80GB MIG 3g.40gb" on the drivers that name
+	// MIG devices, which is where the profile is read from.
+	Name() string
+	Memory() (totalMB, usedMB int, ok bool)
+	Instances() (gpuInstance, computeInstance int)
+	// Slices and MemoryMB are the instance's attributes, which name the
+	// profile on a driver whose device name does not.
+	Attributes() (slices, memoryMB int, ok bool)
+}
+
+var nvmlMIGName = regexp.MustCompile(`MIG\s+(\S+)\s*$`)
+
+// migFromNVML is what one card is to placement under NVML: its instances if
+// it is in MIG mode, itself if it is not. isMIG says which.
+func migFromNVML(card GPU, dev nvmlMIGCard) (out []GPU, isMIG bool) {
+	current, _, ok := dev.MIGMode()
+	if !ok || !current {
+		return []GPU{card}, false
+	}
+	n := dev.MaxMIGDevices()
+	for i := range n {
+		h, ok := dev.MIGDevice(i)
+		if !ok {
+			continue
+		}
+		profile := ""
+		if m := nvmlMIGName.FindStringSubmatch(h.Name()); m != nil {
+			profile = m[1]
+		} else if n, mem, ok := h.Attributes(); ok {
+			// The convention NVIDIA's names follow: compute slices, then the
+			// memory in whole gigabytes.
+			profile = fmt.Sprintf("%dg.%dgb", n, int(math.Round(float64(mem)/1024)))
+		}
+		g := migInstance(card, i, profile, h.UUID())
+		g.MIG.GPUInstance, g.MIG.ComputeInstance = h.Instances()
+		if total, used, ok := h.Memory(); ok {
+			g.MemoryTotalMB, g.MemoryUsedMB = total, used
+		} else {
+			g.MemoryTotalMB = MIGProfileMemoryGB(profile) * 1024
+		}
+		assessHealth(&g)
+		out = append(out, g)
+	}
+	if len(out) == 0 {
+		card.Health.Problems = append(card.Health.Problems, migProblemNoInstances)
+		return []GPU{card}, true
+	}
+	return out, true
+}
+
+// --- what the doctor reports ---
+
+// MIGCard is one card's MIG state, as `llmgw doctor` reports it.
+type MIGCard struct {
+	Index int    `json:"index"`
+	Name  string `json:"name,omitempty"`
+	// Enabled is the mode in force; PendingEnabled the mode after the next
+	// reset of the card, which differs from it until the card is reset.
+	Enabled        bool `json:"enabled"`
+	PendingEnabled bool `json:"pending_enabled"`
+	// Instances are the MIG devices an engine can be given, as nvidia-smi -L
+	// lists them.
+	Instances []MIGListed `json:"instances,omitempty"`
+	// GPUInstances and ComputeInstances are nvidia-smi mig -lgi and -lci: a
+	// GPU instance with no compute instance in it is not a device yet.
+	GPUInstances     []MIGInstance `json:"gpu_instances,omitempty"`
+	ComputeInstances []MIGInstance `json:"compute_instances,omitempty"`
+}
+
+// MIGListed is one instance an engine can be given.
+type MIGListed struct {
+	Device  int    `json:"device"`
+	Profile string `json:"profile"`
+	UUID    string `json:"uuid"`
+}
+
+// MIGInstance is one row of nvidia-smi mig -lgi or -lci.
+type MIGInstance struct {
+	GPU     int    `json:"gpu"`
+	Profile string `json:"profile"`
+	// ProfileID is NVIDIA's number for the profile.
+	ProfileID int `json:"profile_id"`
+	// GPUInstance is the GPU instance's id; ComputeInstance the compute
+	// instance's within it, -1 in a -lgi row.
+	GPUInstance     int    `json:"gpu_instance"`
+	ComputeInstance int    `json:"compute_instance"`
+	Placement       string `json:"placement,omitempty"`
+}
+
+var (
+	// -lgi: "|   0  MIG 3g.40gb          9        2          4:4     |"
+	migLGIRow = regexp.MustCompile(`^\|\s*(\d+)\s+MIG\s+(\S+)\s+(\d+)\s+(\d+)\s+(\d+:\d+)\s*\|`)
+	// -lci: "|   0      1       MIG 3g.40gb          2         0          0:3     |"
+	migLCIRow = regexp.MustCompile(`^\|\s*(\d+)\s+(\d+)\s+MIG\s+(\S+)\s+(\d+)\s+(\d+)\s+(\d+:\d+)\s*\|`)
+)
+
+// ParseMIGInstances reads nvidia-smi mig -lgi or -lci, whichever it is
+// given: the two tables differ by the GPU instance column -lci adds. "No GPU
+// instances found" and the like are no rows, not an error.
+func ParseMIGInstances(out string) []MIGInstance {
+	var res []MIGInstance
+	for _, line := range strings.Split(out, "\n") {
+		line = strings.TrimSpace(line)
+		if m := migLCIRow.FindStringSubmatch(line); m != nil {
+			res = append(res, MIGInstance{
+				GPU: atoiOr(m[1], -1), GPUInstance: atoiOr(m[2], -1), Profile: m[3],
+				ProfileID: atoiOr(m[4], -1), ComputeInstance: atoiOr(m[5], -1), Placement: m[6],
+			})
+			continue
+		}
+		if m := migLGIRow.FindStringSubmatch(line); m != nil {
+			res = append(res, MIGInstance{
+				GPU: atoiOr(m[1], -1), Profile: m[2], ProfileID: atoiOr(m[3], -1),
+				GPUInstance: atoiOr(m[4], -1), ComputeInstance: -1, Placement: m[5],
+			})
+		}
+	}
+	return res
+}
+
+// DiscoverMIG reads every card's MIG state for the doctor: the mode from the
+// XML report, the devices from -L, the instances from nvidia-smi mig. Only
+// cards that support MIG are listed, and an error is returned only when the
+// report itself cannot be read.
+func DiscoverMIG(ctx context.Context, binary string) ([]MIGCard, error) {
+	out, err := exec.CommandContext(ctx, binary, "-q", "-x").Output()
+	if err != nil {
+		return nil, fmt.Errorf("running %s -q -x: %w", binary, err)
+	}
+	var list, lgi, lci string
+	if b, err := exec.CommandContext(ctx, binary, "-L").Output(); err == nil {
+		list = string(b)
+	}
+	// nvidia-smi mig exits non-zero when there is nothing to list, with the
+	// table or the reason on its output either way.
+	b, _ := exec.CommandContext(ctx, binary, "mig", "-lgi").CombinedOutput()
+	lgi = string(b)
+	b, _ = exec.CommandContext(ctx, binary, "mig", "-lci").CombinedOutput()
+	lci = string(b)
+	return buildMIGCards(out, list, lgi, lci)
+}
+
+// buildMIGCards is DiscoverMIG from the commands' output.
+func buildMIGCards(report []byte, list, lgi, lci string) ([]MIGCard, error) {
+	var log struct {
+		GPUs []struct {
+			Name    string `xml:"product_name"`
+			Current string `xml:"mig_mode>current_mig"`
+			Pending string `xml:"mig_mode>pending_mig"`
+		} `xml:"gpu"`
+	}
+	if err := xml.Unmarshal(report, &log); err != nil {
+		return nil, fmt.Errorf("reading nvidia-smi's report: %w", err)
+	}
+	listed := parseSMIList(list)
+	gis, cis := ParseMIGInstances(lgi), ParseMIGInstances(lci)
+	var out []MIGCard
+	for i, g := range log.GPUs {
+		cur, pend := strings.TrimSpace(g.Current), strings.TrimSpace(g.Pending)
+		// A card without MIG says N/A, or nothing on a driver that predates
+		// it; neither is worth a line.
+		if !enabled(cur) && !enabled(pend) && !strings.EqualFold(cur, "Disabled") {
+			continue
+		}
+		c := MIGCard{Index: i, Name: strings.TrimSpace(g.Name), Enabled: enabled(cur), PendingEnabled: enabled(pend)}
+		for _, l := range listed[i] {
+			c.Instances = append(c.Instances, MIGListed(l))
+		}
+		for _, gi := range gis {
+			if gi.GPU == i && gi.ComputeInstance < 0 {
+				c.GPUInstances = append(c.GPUInstances, gi)
+			}
+		}
+		for _, ci := range cis {
+			if ci.GPU == i && ci.ComputeInstance >= 0 {
+				c.ComputeInstances = append(c.ComputeInstances, ci)
+			}
+		}
+		out = append(out, c)
+	}
+	return out, nil
+}

internal/agent/discovery/mig_test.go

@@ -0,0 +1,418 @@
+package discovery
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"reflect"
+	"slices"
+	"strings"
+	"testing"
+)
+
+// Two A100 80GB cards: card 0 in MIG mode, cut into two 3g.40gb instances,
+// card 1 whole. What nvidia-smi prints for that machine, by command. None of
+// it is from real MIG hardware, which this was written without; the shapes
+// follow NVIDIA's documentation and the output of drivers R470 to R550.
+const (
+	migQuery = `0, GPU-5d5ba0d6-d33d-2b2c-524d-9e3d8d2b8a77, NVIDIA A100-SXM4-80GB, 81920, 0, 8.0, 00000000:07:00.0, 550.54.15, 31, 0, [N/A]
+1, GPU-1f2e3d4c-5b6a-7980-a1b2-c3d4e5f60718, NVIDIA A100-SXM4-80GB, 81920, 0, 8.0, 00000000:0F:00.0, 550.54.15, 33, 0, 0
+`
+	migList = `GPU 0: NVIDIA A100-SXM4-80GB (UUID: GPU-5d5ba0d6-d33d-2b2c-524d-9e3d8d2b8a77)
+  MIG 3g.40gb     Device  0: (UUID: MIG-c6d4f1ef-42e4-5de3-91c7-45d71c87eb3f)
+  MIG 3g.40gb     Device  1: (UUID: MIG-0f7c3a2e-9d1b-5a8e-b3c4-1e2f3a4b5c6d)
+GPU 1: NVIDIA A100-SXM4-80GB (UUID: GPU-1f2e3d4c-5b6a-7980-a1b2-c3d4e5f60718)
+`
+	migReport = `<?xml version="1.0" ?>
+<nvidia_smi_log>
+  <driver_version>550.54.15</driver_version>
+  <gpu id="00000000:07:00.0">
+    <product_name>NVIDIA A100-SXM4-80GB</product_name>
+    <mig_mode><current_mig>Enabled</current_mig><pending_mig>Enabled</pending_mig></mig_mode>
+    <mig_devices>
+      <mig_device>
+        <index>1</index>
+        <gpu_instance_id>1</gpu_instance_id>
+        <compute_instance_id>0</compute_instance_id>
+        <device_attributes><shared><multiprocessor_count>42</multiprocessor_count></shared></device_attributes>
+        <fb_memory_usage><total>40192 MiB</total><reserved>0 MiB</reserved><used>21000 MiB</used><free>19192 MiB</free></fb_memory_usage>
+      </mig_device>
+      <mig_device>
+        <index>0</index>
+        <gpu_instance_id>2</gpu_instance_id>
+        <compute_instance_id>0</compute_instance_id>
+        <fb_memory_usage><total>40192 MiB</total><reserved>0 MiB</reserved><used>37 MiB</used><free>40155 MiB</free></fb_memory_usage>
+      </mig_device>
+    </mig_devices>
+    <fb_memory_usage><total>81920 MiB</total><used>21037 MiB</used></fb_memory_usage>
+    <processes>
+      <process_info>
+        <gpu_instance_id>1</gpu_instance_id>
+        <compute_instance_id>0</compute_instance_id>
+        <pid>4100</pid><type>C</type><process_name>vllm</process_name>
+        <used_memory>20900 MiB</used_memory>
+      </process_info>
+    </processes>
+  </gpu>
+  <gpu id="00000000:0F:00.0">
+    <product_name>NVIDIA A100-SXM4-80GB</product_name>
+    <mig_mode><current_mig>Disabled</current_mig><pending_mig>Disabled</pending_mig></mig_mode>
+    <mig_devices>None</mig_devices>
+    <fb_memory_usage><total>81920 MiB</total><used>300 MiB</used></fb_memory_usage>
+    <processes>
+      <process_info>
+        <gpu_instance_id>N/A</gpu_instance_id>
+        <compute_instance_id>N/A</compute_instance_id>
+        <pid>5200</pid><type>C</type><used_memory>250 MiB</used_memory>
+      </process_info>
+    </processes>
+  </gpu>
+</nvidia_smi_log>`
+	migLGI = `+-------------------------------------------------------+
+| GPU instances:                                        |
+| GPU   Name             Profile  Instance   Placement  |
+|                          ID       ID       Start:Size |
+|=======================================================|
+|   0  MIG 3g.40gb          9        1          4:4     |
++-------------------------------------------------------+
+|   0  MIG 3g.40gb          9        2          0:4     |
++-------------------------------------------------------+
+`
+	migLCI = `+--------------------------------------------------------------------+
+| Compute instances:                                                 |
+| GPU     GPU       Name             Profile   Instance   Placement  |
+|       Instance                       ID        ID       Start:Size |
+|         ID                                                         |
+|====================================================================|
+|   0      1       MIG 3g.40gb          2         0          0:3     |
++--------------------------------------------------------------------+
+|   0      2       MIG 3g.40gb          2         0          0:3     |
++--------------------------------------------------------------------+
+`
+)
+
+func migMachine(t *testing.T) []GPU {
+	t.Helper()
+	cards, err := parseSMI(migQuery)
+	if err != nil {
+		t.Fatal(err)
+	}
+	report, err := parseMIGReport([]byte(migReport))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return expandMIG(cards, parseSMIList(migList), report)
+}
+
+func TestACardInMIGModeIsReportedAsItsInstancesInsteadOfItself(t *testing.T) {
+	gpus := migMachine(t)
+	var got []string
+	for _, g := range gpus {
+		got = append(got, DeviceLabel(g.Index)+" "+g.Class())
+	}
+	want := []string{"0/mig0 a100-80g-mig-3g.40gb", "0/mig1 a100-80g-mig-3g.40gb", "1 a100-80g"}
+	if !slices.Equal(got, want) {
+		t.Fatalf("devices = %q, want %q", got, want)
+	}
+
+	mig := gpus[1]
+	if mig.Index != 1001 || mig.UUID != "MIG-0f7c3a2e-9d1b-5a8e-b3c4-1e2f3a4b5c6d" {
+		t.Errorf("instance 1 is %d %s; an engine is given it by that UUID", mig.Index, mig.UUID)
+	}
+	if mig.MemoryTotalMB != 40192 || mig.MemoryUsedMB != 21000 {
+		t.Errorf("instance 1 memory %d/%d, want its own 21000/40192 rather than the card's",
+			mig.MemoryUsedMB, mig.MemoryTotalMB)
+	}
+	if m := mig.MIG; m == nil || m.ParentIndex != 0 || m.Device != 1 || m.Profile != "3g.40gb" ||
+		m.GPUInstance != 1 || m.ComputeInstance != 0 || m.ParentUUID != "GPU-5d5ba0d6-d33d-2b2c-524d-9e3d8d2b8a77" {
+		t.Errorf("instance 1's parentage: %+v", mig.MIG)
+	}
+	if mig.ComputeCapability != "8.0" || mig.DriverVersion != "550.54.15" || mig.Health.TemperatureC != 31 {
+		t.Errorf("what the card and its instances share was not carried: %+v", mig)
+	}
+	// Twenty gigabytes in use on an instance is a foreign tenant there, and
+	// only there: instance 0 next to it is free.
+	if mig.Health.OK() || !gpus[0].Health.OK() {
+		t.Errorf("foreign memory judged per instance: 0 %v, 1 %v", gpus[0].Health.Problems, mig.Health.Problems)
+	}
+	// No driver reports utilisation per instance, and none is made up.
+	if mig.UtilizationPercent != 0 {
+		t.Errorf("an instance reported utilisation %d", mig.UtilizationPercent)
+	}
+	if gpus[2].IsMIG() || gpus[2].Index != 1 || gpus[2].CardIndex() != 1 || gpus[0].CardIndex() != 0 {
+		t.Errorf("the whole card beside it changed: %+v", gpus[2])
+	}
+}
+
+func TestAMIGInstanceSurvivesTheTripToTheControlPlaneWithItsClass(t *testing.T) {
+	g := migMachine(t)[0]
+	b, err := json.Marshal(g)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(b), `"class":"a100-80g-mig-3g.40gb"`) {
+		t.Errorf("the JSON carries no class for the instance: %s", b)
+	}
+	var back GPU
+	if err := json.Unmarshal(b, &back); err != nil {
+		t.Fatal(err)
+	}
+	if back.Class() != g.Class() || !reflect.DeepEqual(back.MIG, g.MIG) {
+		t.Errorf("came back as %s %+v", back.Class(), back.MIG)
+	}
+}
+
+func TestMIGClassesAreNamedFromTheCardAndTheProfile(t *testing.T) {
+	for _, c := range []struct {
+		name    string
+		cardMB  int
+		profile string
+		want    string
+	}{
+		{"NVIDIA A100-SXM4-80GB MIG 3g.40gb", 81920, "3g.40gb", "a100-80g-mig-3g.40gb"},
+		// The same profile name on a 40 GB card is another class: its
+		// instance is the same size, but the card is not, and neither is
+		// the set of profiles that card can be cut to.
+		{"NVIDIA A100-SXM4-40GB MIG 3g.20gb", 40960, "3g.20gb", "a100-40g-mig-3g.20gb"},
+		{"NVIDIA H100 80GB HBM3 MIG 1g.10gb+me", 81559, "1g.10gb+me", "h100-80g-mig-1g.10gb-me"},
+		{"NVIDIA H100 80GB HBM3 MIG 7g.80gb", 81559, "7g.80gb", "h100-80g-mig-7g.80gb"},
+	} {
+		g := GPU{Name: c.name, MemoryTotalMB: 10000, MIG: &MIGDevice{ParentMemoryTotalMB: c.cardMB, Profile: c.profile}}
+		if got := g.Class(); got != c.want {
+			t.Errorf("%s -> %s, want %s", c.name, got, c.want)
+		}
+		if !IsMIGClass(g.Class()) {
+			t.Errorf("%s is not recognised as a MIG class", g.Class())
+		}
+	}
+	if IsMIGClass("a100-80g") || IsMIGClass("6000-24g") {
+		t.Error("a whole card's class was taken for a MIG one")
+	}
+	if MIGProfileMemoryGB("a100-80g-mig-3g.40gb") != 40 || MIGProfileMemoryGB("1g.10gb+me") != 10 || MIGProfileMemoryGB("a100-80g") != 0 {
+		t.Error("the instance's memory is misread from its profile")
+	}
+}
+
+func TestDeviceNumbersAreShownAsCardAndInstance(t *testing.T) {
+	for i, want := range map[int]string{0: "0", 7: "7", MIGIndex(0, 2): "0/mig2", MIGIndex(3, 0): "3/mig0", 1302: "3/mig2"} {
+		if got := DeviceLabel(i); got != want {
+			t.Errorf("DeviceLabel(%d) = %s, want %s", i, got, want)
+		}
+	}
+	if IsMIGIndex(15) || !IsMIGIndex(MIGIndex(0, 0)) {
+		t.Error("whole cards and instances are told apart wrongly")
+	}
+}
+
+func TestACardInMIGModeWithNoInstancesIsKeptOutOfPlacement(t *testing.T) {
+	cards, _ := parseSMI(migQuery)
+	report, _ := parseMIGReport([]byte(strings.Replace(migReport,
+		migReport[strings.Index(migReport, "<mig_devices>"):strings.Index(migReport, "</mig_devices>")+len("</mig_devices>")],
+		"<mig_devices>None</mig_devices>", 1)))
+	gpus := expandMIG(cards, parseSMIList("GPU 0: NVIDIA A100-SXM4-80GB (UUID: GPU-x)\nGPU 1: NVIDIA A100-SXM4-80GB (UUID: GPU-y)\n"), report)
+	if len(gpus) != 2 || gpus[0].IsMIG() {
+		t.Fatalf("got %+v", gpus)
+	}
+	// CUDA will not open the whole card while MIG is on, and there is no
+	// instance to open instead: placing anything here fails at start.
+	if gpus[0].Health.OK() || !strings.Contains(gpus[0].Health.Problems[0], "no instances") {
+		t.Errorf("card 0's problems: %v", gpus[0].Health.Problems)
+	}
+	if !gpus[1].Health.OK() {
+		t.Errorf("card 1, not in MIG mode, was flagged: %v", gpus[1].Health.Problems)
+	}
+
+	// Instances the report sees but -L could not name cannot be given to an
+	// engine either; the card says why.
+	report, _ = parseMIGReport([]byte(migReport))
+	gpus = expandMIG(cards, nil, report)
+	if len(gpus) != 2 || gpus[0].Health.OK() || !strings.Contains(gpus[0].Health.Problems[0], "did not name") {
+		t.Errorf("with -L failing: %+v", gpus)
+	}
+}
+
+func TestInstancesAreFoundFromTheListAloneWhenTheReportCannotBeRead(t *testing.T) {
+	cards, _ := parseSMI(migQuery)
+	gpus := expandMIG(cards, parseSMIList(migList), nil)
+	if len(gpus) != 3 || !gpus[0].IsMIG() || gpus[0].MemoryTotalMB != 40*1024 {
+		t.Errorf("without the report: %+v", gpus)
+	}
+}
+
+func TestAnOlderDriversInstanceUUIDIsTakenAsItIs(t *testing.T) {
+	// R450 and R460 name an instance by its card and ids, and CUDA of that
+	// era takes exactly that in CUDA_VISIBLE_DEVICES.
+	l := parseSMIList("GPU 0: A100-SXM4-40GB (UUID: GPU-5d5ba0d6-d33d-2b2c-524d-9e3d8d2b8a77)\n" +
+		"  MIG 1g.5gb Device 0: (UUID: MIG-GPU-5d5ba0d6-d33d-2b2c-524d-9e3d8d2b8a77/7/0)\n")
+	if len(l[0]) != 1 || l[0][0].UUID != "MIG-GPU-5d5ba0d6-d33d-2b2c-524d-9e3d8d2b8a77/7/0" || l[0][0].Profile != "1g.5gb" {
+		t.Errorf("parsed %+v", l)
+	}
+}
+
+func TestProcessesOnAMIGCardAreChargedToTheirOwnInstance(t *testing.T) {
+	mem, err := parseGPUMemory([]byte(migReport))
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []GPUMemory{
+		{Index: 1000, UsedMB: 37},
+		{Index: 1001, UsedMB: 21000, Procs: []GPUProcess{{PID: 4100, UsedMB: 20900}}},
+		{Index: 1, UsedMB: 300, Procs: []GPUProcess{{PID: 5200, UsedMB: 250}}},
+	}
+	if !reflect.DeepEqual(mem, want) {
+		t.Errorf("got %+v\nwant %+v", mem, want)
+	}
+	// In the order discovery reports the devices, so a heartbeat's readings
+	// line up with the inventory one for one.
+	gpus := migMachine(t)
+	for i := range gpus {
+		if mem[i].Index != gpus[i].Index {
+			t.Errorf("reading %d is for device %d, inventory has %d", i, mem[i].Index, gpus[i].Index)
+		}
+	}
+	procs, _ := parseGPUProcesses([]byte(migReport))
+	if !reflect.DeepEqual(procs, map[int][]int{1001: {4100}, 1: {5200}}) {
+		t.Errorf("processes by device: %v", procs)
+	}
+}
+
+func TestAMIGInstanceTakesItsCardsPlaceInTheTopologyButNoNVLink(t *testing.T) {
+	gpus := migMachine(t)
+	topo := Topology{
+		NVLink:  map[int]map[int]int{0: {1: 12}, 1: {0: 12}},
+		NUMA:    map[int]int{0: 0, 1: 1},
+		NICPath: map[int]map[string]string{0: {"mlx5_0": "PIX"}},
+	}
+	topo.Apply(gpus)
+	if len(gpus[0].NVLinkPeers) != 0 || len(gpus[1].NVLinkPeers) != 0 {
+		t.Errorf("MIG instances were given NVLink peers: %v %v", gpus[0].NVLinkPeers, gpus[1].NVLinkPeers)
+	}
+	if gpus[1].NUMANode != 0 || gpus[1].NICPaths["mlx5_0"] != "PIX" {
+		t.Errorf("instance 1 did not take its card's NUMA node and adapters: %+v", gpus[1])
+	}
+	if gpus[2].NUMANode != 1 || !slices.Equal(gpus[2].NVLinkPeers, []int{0}) {
+		t.Errorf("the whole card's topology: %+v", gpus[2])
+	}
+}
+
+func TestMIGInstancesAreDiscoveredThroughNvidiaSMI(t *testing.T) {
+	// The real code path against a stub binary that answers each command as
+	// the machine above would.
+	dir := t.TempDir()
+	stub := filepath.Join(dir, "nvidia-smi")
+	script := "#!/bin/sh\ncase \"$1\" in\n" +
+		"-L) cat <<'EOF'\n" + migList + "EOF\n;;\n" +
+		"-q) cat <<'EOF'\n" + migReport + "\nEOF\n;;\n" +
+		"*) cat <<'EOF'\n" + migQuery + "EOF\n;;\nesac\n"
+	if err := os.WriteFile(stub, []byte(script), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	gpus, err := DiscoverGPUsSMI(t.Context(), stub)
+	if err != nil {
+		t.Fatal(err)
+	}
+	inv := Inventory{GPUs: gpus}
+	if !slices.Equal(inv.Classes(), []string{"a100-80g", "a100-80g-mig-3g.40gb"}) || len(gpus) != 3 {
+		t.Errorf("classes %v from %d devices", inv.Classes(), len(gpus))
+	}
+}
+
+// fakeMIGCard is NVML's view of one card, as nvmlDeviceGetMigMode,
+// nvmlDeviceGetMaxMigDeviceCount and nvmlDeviceGetMigDeviceHandleByIndex
+// would give it.
+type fakeMIGCard struct {
+	mode, pending, supported bool
+	max                      int
+	devs                     map[int]fakeMIGInstance
+}
+
+func (c fakeMIGCard) MIGMode() (bool, bool, bool) { return c.mode, c.pending, c.supported }
+func (c fakeMIGCard) MaxMIGDevices() int          { return c.max }
+func (c fakeMIGCard) MIGDevice(i int) (nvmlMIGInstance, bool) {
+	d, ok := c.devs[i]
+	return d, ok
+}
+
+type fakeMIGInstance struct {
+	uuid, name      string
+	total, used     int
+	gi, ci          int
+	slices, attrMem int
+}
+
+func (m fakeMIGInstance) UUID() string { return m.uuid }
+func (m fakeMIGInstance) Name() string { return m.name }
+func (m fakeMIGInstance) Memory() (int, int, bool) {
+	return m.total, m.used, m.total > 0
+}
+func (m fakeMIGInstance) Instances() (int, int) { return m.gi, m.ci }
+func (m fakeMIGInstance) Attributes() (int, int, bool) {
+	return m.slices, m.attrMem, m.slices > 0
+}
+
+func TestNVMLReportsACardInMIGModeAsItsInstances(t *testing.T) {
+	card := GPU{Index: 2, UUID: "GPU-card", Name: "NVIDIA H100 80GB HBM3", MemoryTotalMB: 81559,
+		ComputeCapability: "9.0", NUMANode: 1, Health: GPUHealth{TemperatureC: 40}}
+	// Seven slots, three filled, one of them on a driver that does not put
+	// the profile in the device's name.
+	dev := fakeMIGCard{mode: true, pending: true, supported: true, max: 7, devs: map[int]fakeMIGInstance{
+		0: {uuid: "MIG-aaa", name: "NVIDIA H100 80GB HBM3 MIG 3g.40gb", total: 40448, used: 10, gi: 2, ci: 0},
+		1: {uuid: "MIG-bbb", name: "NVIDIA H100 80GB HBM3 MIG 3g.40gb", total: 40448, used: 10, gi: 1, ci: 0},
+		4: {uuid: "MIG-ccc", name: "NVIDIA H100 80GB HBM3", total: 9984, gi: 9, ci: 0, slices: 1, attrMem: 9984},
+	}}
+	gpus, isMIG := migFromNVML(card, dev)
+	if !isMIG || len(gpus) != 3 {
+		t.Fatalf("got %d devices, MIG %v", len(gpus), isMIG)
+	}
+	var classes []string
+	for _, g := range gpus {
+		classes = append(classes, DeviceLabel(g.Index)+" "+g.UUID+" "+g.Class())
+	}
+	want := []string{"2/mig0 MIG-aaa h100-80g-mig-3g.40gb", "2/mig1 MIG-bbb h100-80g-mig-3g.40gb",
+		"2/mig4 MIG-ccc h100-80g-mig-1g.10gb"}
+	if !slices.Equal(classes, want) {
+		t.Errorf("devices %q, want %q", classes, want)
+	}
+	if g := gpus[1]; g.MemoryTotalMB != 40448 || g.MIG.GPUInstance != 1 || g.NUMANode != 1 ||
+		g.Health.TemperatureC != 40 || len(g.NVLinkPeers) != 0 {
+		t.Errorf("instance 1: %+v", g)
+	}
+
+	// MIG on and nothing carved: the card, kept out of placement.
+	gpus, isMIG = migFromNVML(card, fakeMIGCard{mode: true, supported: true, max: 7})
+	if !isMIG || len(gpus) != 1 || gpus[0].IsMIG() || gpus[0].Health.OK() {
+		t.Errorf("an empty MIG card: %+v", gpus)
+	}
+	// MIG off, or a card without it: the card, as it always was.
+	for _, d := range []fakeMIGCard{{supported: true, max: 7}, {}} {
+		gpus, isMIG = migFromNVML(card, d)
+		if isMIG || len(gpus) != 1 || !reflect.DeepEqual(gpus[0], card) {
+			t.Errorf("a card not in MIG mode came back as %+v", gpus)
+		}
+	}
+}
+
+func TestMIGInstanceTablesAreRead(t *testing.T) {
+	gis := ParseMIGInstances(migLGI)
+	if len(gis) != 2 || gis[0] != (MIGInstance{GPU: 0, Profile: "3g.40gb", ProfileID: 9, GPUInstance: 1,
+		ComputeInstance: -1, Placement: "4:4"}) {
+		t.Errorf("-lgi: %+v", gis)
+	}
+	cis := ParseMIGInstances(migLCI)
+	if len(cis) != 2 || cis[1] != (MIGInstance{GPU: 0, GPUInstance: 2, Profile: "3g.40gb", ProfileID: 2,
+		ComputeInstance: 0, Placement: "0:3"}) {
+		t.Errorf("-lci: %+v", cis)
+	}
+	if got := ParseMIGInstances("No GPU instances found: Not Found\n"); len(got) != 0 {
+		t.Errorf("nothing to list read as %+v", got)
+	}
+
+	cards, err := buildMIGCards([]byte(migReport), migList, migLGI, migLCI)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(cards) != 2 || !cards[0].Enabled || len(cards[0].Instances) != 2 || len(cards[0].GPUInstances) != 2 ||
+		len(cards[0].ComputeInstances) != 2 || cards[1].Enabled {
+		t.Errorf("cards: %+v", cards)
+	}
+}

internal/agent/discovery/sensors.go

@@ -0,0 +1,287 @@
+package discovery
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// Sensors is what a node's own hardware says about heat and power: the CPUs,
+// the board where it has an inlet sensor, and each GPU. A zero is not
+// measured, never a reading of zero — a VM has none of these, and must not
+// look like a machine running at 0 °C on no power.
+type Sensors struct {
+	// CPUTempC is the hottest CPU sensor: the package, or the hottest core
+	// where no package reading exists.
+	CPUTempC float64
+	// CPUPowerW is the CPU packages' draw, from RAPL: the change in their
+	// energy counters over the time between two samples.
+	CPUPowerW float64
+	// InletTempC is the air coming in, where the board has a sensor it calls
+	// that. Most do not, and a CPU's temperature is not a substitute: it
+	// follows the load, not the room.
+	InletTempC float64
+	GPUs       []GPUSensor
+}
+
+// GPUSensor is one card's heat, power and whether it is slowing itself down.
+type GPUSensor struct {
+	Index       int
+	TempC       float64
+	MemoryTempC float64
+	PowerW      float64
+	PowerLimitW float64
+	// Throttle names what is holding the card's clocks down now:
+	// sw_power_cap, hw_slowdown, sw_thermal, hw_thermal, power_brake. Empty
+	// is running free. Idle and application clock settings are left out;
+	// they are not the card being held back.
+	Throttle []string
+	// How busy it is, read with the rest every sample. Discovery reads the
+	// same once, at start, which made a busy card look as idle as it was
+	// when the agent came up. -1 is not reported by the driver; zero
+	// MemoryTotalMB is a sample without these at all.
+	UtilPercent, MemUtilPercent float64
+	MemoryUsedMB, MemoryTotalMB float64
+	SMClockMHz                  float64
+	ECCUncorrected              float64
+}
+
+// sensorEvery bounds how often nvidia-smi is run. Heartbeats come more often
+// than temperatures change, and each run costs a few hundred milliseconds.
+const sensorEvery = 10 * time.Second
+
+// SensorSampler reads Sensors. The first sample has no CPU power, which needs
+// two readings of the energy counters.
+type SensorSampler struct {
+	sys string // /sys, or a test's copy of it
+	smi func(ctx context.Context, fields string) ([]byte, error)
+	now func() time.Time
+
+	mu         sync.Mutex
+	last       Sensors
+	lastAt     time.Time
+	prevEnergy map[string]uint64
+	prevAt     time.Time
+}
+
+// NewSensorSampler reads this machine.
+func NewSensorSampler() *SensorSampler {
+	return &SensorSampler{sys: "/sys", smi: runSMI, now: time.Now}
+}
+
+func runSMI(ctx context.Context, fields string) ([]byte, error) {
+	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	//nolint:gosec // fixed binary, fields from this file
+	return exec.CommandContext(ctx, "nvidia-smi", "--query-gpu="+fields,
+		"--format=csv,noheader,nounits").Output()
+}
+
+// Sample reads the sensors, or returns the last reading when that is recent.
+func (s *SensorSampler) Sample(ctx context.Context) Sensors {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	now := s.now()
+	if !s.lastAt.IsZero() && now.Sub(s.lastAt) < sensorEvery {
+		return s.last
+	}
+	out := Sensors{}
+	out.CPUTempC, out.InletTempC = s.hwmon()
+	out.CPUPowerW = s.rapl(now)
+	out.GPUs = s.gpus(ctx)
+	s.last, s.lastAt = out, now
+	return out
+}
+
+// hwmon reads the hottest CPU sensor and an inlet sensor, from every hwmon
+// device the kernel exposes — what lm_sensors reads, without it installed.
+func (s *SensorSampler) hwmon() (cpu, inlet float64) {
+	devs, _ := filepath.Glob(filepath.Join(s.sys, "class/hwmon/hwmon*"))
+	var pkg, core float64
+	for _, d := range devs {
+		name := readTrim(filepath.Join(d, "name"))
+		inputs, _ := filepath.Glob(filepath.Join(d, "temp*_input"))
+		for _, in := range inputs {
+			milli, err := strconv.ParseFloat(readTrim(in), 64)
+			if err != nil || milli <= 0 {
+				continue
+			}
+			c := milli / 1000
+			label := strings.ToLower(readTrim(strings.TrimSuffix(in, "_input") + "_label"))
+			switch {
+			case isCPUSensor(name) && (strings.HasPrefix(label, "package") || label == "tctl" || label == "tdie"):
+				pkg = max(pkg, c)
+			case isCPUSensor(name):
+				core = max(core, c)
+			case label == "cpu":
+				// A board's own reading of the CPU, as Dell's SMM gives.
+				core = max(core, c)
+			case strings.Contains(label, "inlet") || strings.Contains(label, "ambient") ||
+				strings.Contains(label, "intake") || label == "systin":
+				inlet = max(inlet, c)
+			}
+		}
+	}
+	if pkg > 0 {
+		return pkg, inlet
+	}
+	return core, inlet
+}
+
+func isCPUSensor(name string) bool {
+	switch name {
+	case "coretemp", "k10temp", "zenpower", "cpu_thermal":
+		return true
+	}
+	return false
+}
+
+// rapl is the CPU packages' power from their energy counters. Package
+// domains only: the dram and core subdomains are parts of a package, and
+// adding them would count the same energy twice.
+func (s *SensorSampler) rapl(now time.Time) float64 {
+	doms, _ := filepath.Glob(filepath.Join(s.sys, "class/powercap/intel-rapl:*"))
+	energy := map[string]uint64{}
+	wrap := map[string]uint64{}
+	for _, d := range doms {
+		if strings.Count(filepath.Base(d), ":") != 1 {
+			continue // intel-rapl:0:0 is a subdomain of intel-rapl:0
+		}
+		e, err := strconv.ParseUint(readTrim(filepath.Join(d, "energy_uj")), 10, 64)
+		if err != nil {
+			continue // unreadable without root on newer kernels
+		}
+		energy[d] = e
+		wrap[d], _ = strconv.ParseUint(readTrim(filepath.Join(d, "max_energy_range_uj")), 10, 64)
+	}
+	prev, prevAt := s.prevEnergy, s.prevAt
+	s.prevEnergy, s.prevAt = energy, now
+	dt := now.Sub(prevAt).Seconds()
+	if prev == nil || dt <= 0 || len(energy) == 0 {
+		return 0
+	}
+	var joules float64
+	for d, e := range energy {
+		p, ok := prev[d]
+		if !ok {
+			return 0 // a domain appeared: no fair difference this time
+		}
+		if e < p { // the counter wrapped
+			e += wrap[d]
+		}
+		joules += float64(e-p) / 1e6
+	}
+	return joules / dt
+}
+
+// The throttle reasons nvidia-smi reports, as bits. Only those that mean the
+// card is being held back are named.
+var throttleBits = []struct {
+	bit  uint64
+	name string
+}{
+	{0x4, "sw_power_cap"},
+	{0x8, "hw_slowdown"},
+	{0x20, "sw_thermal"},
+	{0x40, "hw_thermal"},
+	{0x80, "power_brake"},
+}
+
+// gpus asks nvidia-smi for each card's heat and power. The memory temperature
+// is not known to every driver, and a field nvidia-smi does not know fails the
+// whole query, so it is asked for first and dropped on failure.
+// gpuFields are what each sample asks nvidia-smi for, in order. The busy
+// figures follow the throttle reasons; the memory temperature is last, being
+// the one field a driver may reject outright.
+const (
+	gpuBase  = "index,temperature.gpu,power.draw,enforced.power.limit,clocks_throttle_reasons.active"
+	gpuBusy  = ",utilization.gpu,utilization.memory,memory.used,memory.total,clocks.sm,ecc.errors.uncorrected.volatile.total"
+	gpuHBMTC = ",temperature.memory"
+)
+
+func (s *SensorSampler) gpus(ctx context.Context) []GPUSensor {
+	// Most fields first, fewer on a driver that refuses one: a query naming
+	// a field the driver does not know fails as a whole.
+	var out []byte
+	var busy bool
+	for _, q := range []struct {
+		fields string
+		busy   bool
+	}{{gpuBase + gpuBusy + gpuHBMTC, true}, {gpuBase + gpuBusy, true}, {gpuBase + gpuHBMTC, false}, {gpuBase, false}} {
+		var err error
+		if out, err = s.smi(ctx, q.fields); err == nil {
+			busy = q.busy
+			break
+		}
+		out = nil
+	}
+	if out == nil {
+		return nil
+	}
+	var gs []GPUSensor
+	for _, line := range strings.Split(strings.TrimSpace(string(out)), "\n") {
+		f := strings.Split(line, ",")
+		if len(f) < 5 {
+			continue
+		}
+		for i := range f {
+			f[i] = strings.TrimSpace(f[i])
+		}
+		idx, err := strconv.Atoi(f[0])
+		if err != nil {
+			continue
+		}
+		g := GPUSensor{Index: idx, TempC: num(f[1]), PowerW: num(f[2]), PowerLimitW: num(f[3])}
+		if bits, err := strconv.ParseUint(strings.TrimPrefix(f[4], "0x"), 16, 64); err == nil {
+			for _, b := range throttleBits {
+				if bits&b.bit != 0 {
+					g.Throttle = append(g.Throttle, b.name)
+				}
+			}
+		}
+		rest := f[5:]
+		if busy && len(rest) >= 6 {
+			g.UtilPercent, g.MemUtilPercent = numOrUnknown(rest[0]), numOrUnknown(rest[1])
+			g.MemoryUsedMB, g.MemoryTotalMB = num(rest[2]), num(rest[3])
+			g.SMClockMHz, g.ECCUncorrected = num(rest[4]), numOrUnknown(rest[5])
+			rest = rest[6:]
+		}
+		if len(rest) > 0 {
+			g.MemoryTempC = num(rest[0])
+		}
+		gs = append(gs, g)
+	}
+	return gs
+}
+
+// numOrUnknown is a figure, or -1 where nvidia-smi says it has none: a card
+// without ECC has no error count, which is not the same as none.
+func numOrUnknown(s string) float64 {
+	v, err := strconv.ParseFloat(s, 64)
+	if err != nil || v < 0 {
+		return -1
+	}
+	return v
+}
+
+// num reads a figure nvidia-smi may give as "[N/A]" or "N/A".
+func num(s string) float64 {
+	v, err := strconv.ParseFloat(s, 64)
+	if err != nil || v < 0 {
+		return 0
+	}
+	return v
+}
+
+func readTrim(path string) string {
+	b, err := os.ReadFile(path) //nolint:gosec // sysfs
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(b))
+}

internal/agent/discovery/sensors_test.go

@@ -0,0 +1,210 @@
+package discovery
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func put(t *testing.T, root, rel, body string) {
+	t.Helper()
+	p := filepath.Join(root, rel)
+	if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(p, []byte(body+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// dellHost is the layout of the Proxmox host these tests were written
+// against: Dell's SMM with a CPU and SODIMM sensors, coretemp with a package
+// and cores, and RAPL with a package and its dram subdomain.
+func dellHost(t *testing.T) string {
+	root := t.TempDir()
+	put(t, root, "class/hwmon/hwmon0/name", "dell_smm")
+	put(t, root, "class/hwmon/hwmon0/temp1_input", "55000")
+	put(t, root, "class/hwmon/hwmon0/temp1_label", "CPU")
+	put(t, root, "class/hwmon/hwmon0/temp2_input", "47000")
+	put(t, root, "class/hwmon/hwmon0/temp2_label", "SODIMM")
+	put(t, root, "class/hwmon/hwmon1/name", "coretemp")
+	put(t, root, "class/hwmon/hwmon1/temp1_input", "58000")
+	put(t, root, "class/hwmon/hwmon1/temp1_label", "Package id 0")
+	put(t, root, "class/hwmon/hwmon1/temp10_input", "61000")
+	put(t, root, "class/hwmon/hwmon1/temp10_label", "Core 8")
+	put(t, root, "class/powercap/intel-rapl:0/energy_uj", "1000000000")
+	put(t, root, "class/powercap/intel-rapl:0/max_energy_range_uj", "262143328850")
+	put(t, root, "class/powercap/intel-rapl:0:0/energy_uj", "5000000")
+	return root
+}
+
+func sampler(sys string, smi func(context.Context, string) ([]byte, error), clock *time.Time) *SensorSampler {
+	return &SensorSampler{sys: sys, smi: smi, now: func() time.Time { return *clock }}
+}
+
+func noSMI(context.Context, string) ([]byte, error) { return nil, errors.New("not found") }
+
+func TestAHostsCPUHeatAndPowerAreReadAsLmSensorsWould(t *testing.T) {
+	root := dellHost(t)
+	now := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
+	s := sampler(root, noSMI, &now)
+
+	first := s.Sample(t.Context())
+	// The package reading, not the hotter core: the package is what the
+	// chip itself reports as its temperature.
+	if first.CPUTempC != 58 {
+		t.Errorf("CPU %.1f °C, expected the package's 58", first.CPUTempC)
+	}
+	if first.CPUPowerW != 0 {
+		t.Error("power from one reading of a counter is invented")
+	}
+	if first.InletTempC != 0 || first.GPUs != nil {
+		t.Errorf("sensors this host does not have were reported: %+v", first)
+	}
+
+	// 10 s later the package has used 650 J, and its dram subdomain some of
+	// that — counted once.
+	put(t, root, "class/powercap/intel-rapl:0/energy_uj", "1650000000")
+	put(t, root, "class/powercap/intel-rapl:0:0/energy_uj", "99000000")
+	now = now.Add(10 * time.Second)
+	if got := s.Sample(t.Context()).CPUPowerW; got < 64.9 || got > 65.1 {
+		t.Errorf("CPU power %.2f W, expected 65", got)
+	}
+}
+
+func TestACounterThatWrapsIsNotANegativeDraw(t *testing.T) {
+	root := dellHost(t)
+	now := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
+	put(t, root, "class/powercap/intel-rapl:0/energy_uj", "262143000000")
+	s := sampler(root, noSMI, &now)
+	s.Sample(t.Context())
+	// 328,850 µJ to the wrap, then 499,671,150 past it: 500 J in 10 s.
+	put(t, root, "class/powercap/intel-rapl:0/energy_uj", "499671150")
+	now = now.Add(10 * time.Second)
+	if got := s.Sample(t.Context()).CPUPowerW; got < 49.9 || got > 50.1 {
+		t.Errorf("across a wrap: %.2f W, expected 50", got)
+	}
+}
+
+func TestAVMHasNoSensorsAndSaysNothing(t *testing.T) {
+	root := t.TempDir()
+	put(t, root, "class/thermal/cooling_device0/type", "Processor")
+	now := time.Now()
+	got := sampler(root, noSMI, &now).Sample(t.Context())
+	if got.CPUTempC != 0 || got.CPUPowerW != 0 || got.InletTempC != 0 || got.GPUs != nil {
+		t.Errorf("a machine with no sensors reported %+v", got)
+	}
+}
+
+func TestABoardsInletSensorIsTheRoomNotTheCPU(t *testing.T) {
+	root := t.TempDir()
+	put(t, root, "class/hwmon/hwmon2/name", "nct6798")
+	put(t, root, "class/hwmon/hwmon2/temp1_input", "24500")
+	put(t, root, "class/hwmon/hwmon2/temp1_label", "SYSTIN")
+	put(t, root, "class/hwmon/hwmon3/name", "k10temp")
+	put(t, root, "class/hwmon/hwmon3/temp1_input", "71250")
+	put(t, root, "class/hwmon/hwmon3/temp1_label", "Tctl")
+	now := time.Now()
+	got := sampler(root, noSMI, &now).Sample(t.Context())
+	if got.InletTempC != 24.5 || got.CPUTempC != 71.25 {
+		t.Errorf("inlet %.2f, CPU %.2f", got.InletTempC, got.CPUTempC)
+	}
+}
+
+func TestEachGPUSaysHowHotHowHungryAndWhatHoldsItBack(t *testing.T) {
+	var asked []string
+	smi := func(_ context.Context, fields string) ([]byte, error) {
+		asked = append(asked, fields)
+		return []byte(
+			"0, 71, 612.45, 700.00, 0x0000000000000000, 84\n" +
+				"1, 88, 698.10, 700.00, 0x0000000000000024, 95\n" + // sw_power_cap + sw_thermal
+				"2, 45, [N/A], 700.00, 0x0000000000000001, [N/A]\n"), nil // idle only
+	}
+	now := time.Now()
+	ss := sampler(t.TempDir(), smi, &now)
+	got := ss.Sample(t.Context())
+	if len(got.GPUs) != 3 {
+		t.Fatalf("%+v", got.GPUs)
+	}
+	g0, g1, g2 := got.GPUs[0], got.GPUs[1], got.GPUs[2]
+	if g0.TempC != 71 || g0.PowerW != 612.45 || g0.PowerLimitW != 700 || g0.MemoryTempC != 84 || g0.Throttle != nil {
+		t.Errorf("card 0 %+v", g0)
+	}
+	if strings.Join(g1.Throttle, ",") != "sw_power_cap,sw_thermal" {
+		t.Errorf("card 1 throttled by %v", g1.Throttle)
+	}
+	if g2.PowerW != 0 || g2.MemoryTempC != 0 || g2.Throttle != nil {
+		t.Errorf("card 2: N/A is not a reading, and idle is not being held back: %+v", g2)
+	}
+	// Within ten seconds the last reading is reused rather than running
+	// nvidia-smi on every heartbeat; after, it is asked again.
+	now = now.Add(5 * time.Second)
+	ss.Sample(t.Context())
+	if len(asked) != 1 {
+		t.Errorf("nvidia-smi was asked %d times within ten seconds", len(asked))
+	}
+	now = now.Add(6 * time.Second)
+	ss.Sample(t.Context())
+	if len(asked) != 2 {
+		t.Errorf("nvidia-smi was asked %d times after eleven seconds, expected 2", len(asked))
+	}
+}
+
+func TestADriverThatDoesNotKnowMemoryTemperatureStillReportsTheRest(t *testing.T) {
+	smi := func(_ context.Context, fields string) ([]byte, error) {
+		if strings.Contains(fields, "temperature.memory") {
+			return nil, errors.New(`Field "temperature.memory" is not a valid field to query.`)
+		}
+		return []byte("0, 66, 250.0, 300.0, 0x0000000000000040\n"), nil
+	}
+	now := time.Now()
+	got := sampler(t.TempDir(), smi, &now).Sample(t.Context())
+	if len(got.GPUs) != 1 || got.GPUs[0].TempC != 66 || strings.Join(got.GPUs[0].Throttle, ",") != "hw_thermal" {
+		t.Errorf("%+v", got.GPUs)
+	}
+}
+
+func TestEachSampleSaysHowBusyEachGPUIs(t *testing.T) {
+	// What the card is doing now, every sample: discovery read it once, at
+	// start, and a card busy since looked as idle as it was then.
+	smi := func(_ context.Context, fields string) ([]byte, error) {
+		if !strings.Contains(fields, "utilization.gpu") {
+			return nil, errors.New("asked without how busy the cards are")
+		}
+		return []byte(
+			"0, 71, 612.45, 700.00, 0x0000000000000000, 97, 64, 71234, 81559, 1980, 0, 84\n" +
+				"1, 30, 70.10, 700.00, 0x0000000000000001, 0, 0, 512, 81559, 345, [N/A], [N/A]\n"), nil
+	}
+	now := time.Now()
+	got := sampler(t.TempDir(), smi, &now).Sample(t.Context()).GPUs
+	if len(got) != 2 {
+		t.Fatalf("%+v", got)
+	}
+	g0, g1 := got[0], got[1]
+	if g0.UtilPercent != 97 || g0.MemUtilPercent != 64 || g0.MemoryUsedMB != 71234 || g0.MemoryTotalMB != 81559 ||
+		g0.SMClockMHz != 1980 || g0.ECCUncorrected != 0 || g0.MemoryTempC != 84 {
+		t.Errorf("card 0 %+v", g0)
+	}
+	// Idle is zero; a count the card does not keep is unknown, not zero.
+	if g1.UtilPercent != 0 || g1.ECCUncorrected != -1 || g1.MemoryTempC != 0 {
+		t.Errorf("card 1 %+v", g1)
+	}
+}
+
+func TestADriverThatDoesNotKnowTheBusyFieldsStillReportsHeatAndPower(t *testing.T) {
+	smi := func(_ context.Context, fields string) ([]byte, error) {
+		if strings.Contains(fields, "utilization.gpu") {
+			return nil, errors.New(`Field "ecc.errors.uncorrected.volatile.total" is not a valid field to query.`)
+		}
+		return []byte("0, 66, 250.0, 300.0, 0x0000000000000000, 70\n"), nil
+	}
+	now := time.Now()
+	got := sampler(t.TempDir(), smi, &now).Sample(t.Context()).GPUs
+	if len(got) != 1 || got[0].TempC != 66 || got[0].MemoryTempC != 70 || got[0].MemoryTotalMB != 0 {
+		t.Errorf("%+v", got)
+	}
+}

internal/agent/discovery/topo.go

@@ -166,19 +166,25 @@ func splitTabs(l string) []string {
 
 // 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.
+//
+// The matrix is of whole cards. A MIG instance takes its card's NUMA node and
+// adapters, and none of its NVLink: instances cannot reach each other or any
+// other card over it, and peers listed for one would draw a tensor-parallel
+// group onto it.
 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] {
+		card := g.CardIndex()
+		if len(g.NVLinkPeers) == 0 && !g.IsMIG() {
+			for peer := range t.NVLink[card] {
 				g.NVLinkPeers = append(g.NVLinkPeers, peer)
 			}
 			sort.Ints(g.NVLinkPeers)
 		}
-		if n, ok := t.NUMA[g.Index]; ok {
+		if n, ok := t.NUMA[card]; ok {
 			g.NUMANode = n
 		}
-		if paths := t.NICPath[g.Index]; len(paths) > 0 {
+		if paths := t.NICPath[card]; len(paths) > 0 {
 			g.NICPaths = paths
 		}
 	}

internal/agent/engines/compute.go

@@ -0,0 +1,79 @@
+package engines
+
+import (
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+// Compute is where an engine runs its model, as it said while loading it.
+type Compute struct {
+	// Backend is CUDA, Vulkan, Metal, ROCm or CPU.
+	Backend string
+	// Devices are those it named: "CUDA0: Quadro RTX 6000 (7.5)".
+	Devices []string
+	// Offloaded of Total layers went to the devices; 0 and 0 when it did
+	// not say.
+	Offloaded, Total int
+	// NoGPU is the engine saying it found no device it could use.
+	NoGPU bool
+}
+
+var (
+	offloadedRE = regexp.MustCompile(`offloaded (\d+)/(\d+) layers to GPU`)
+	usingRE     = regexp.MustCompile(`using device ([A-Za-z]+\d+) \(([^)]*)\)`)
+	ccRE        = regexp.MustCompile(`Device (\d+): ([^,]+), compute capability ([0-9.]+)`)
+	noDevicesRE = regexp.MustCompile(`found 0 (CUDA|Vulkan|ROCm) devices|no usable GPU found`)
+)
+
+// ReadLlamaCompute reads llama.cpp's start-up output for where it put the
+// model, reporting false when the output says nothing of it.
+func ReadLlamaCompute(lines []string) (Compute, bool) {
+	var c Compute
+	known := false
+	cc := map[string]string{} // device index → compute capability
+	for _, l := range lines {
+		if m := ccRE.FindStringSubmatch(l); m != nil {
+			cc[m[1]] = m[3]
+		}
+	}
+	seen := map[string]bool{}
+	for _, l := range lines {
+		if m := offloadedRE.FindStringSubmatch(l); m != nil {
+			c.Offloaded, _ = strconv.Atoi(m[1])
+			c.Total, _ = strconv.Atoi(m[2])
+			known = true
+		}
+		if m := usingRE.FindStringSubmatch(l); m != nil && !seen[m[1]] {
+			seen[m[1]] = true
+			d := m[1] + ": " + strings.TrimSpace(m[2])
+			idx := strings.TrimLeft(m[1], "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz")
+			if v, ok := cc[idx]; ok && strings.HasPrefix(m[1], "CUDA") {
+				d += " (" + v + ")"
+			}
+			c.Devices = append(c.Devices, d)
+			if c.Backend == "" {
+				c.Backend = strings.TrimRight(m[1], "0123456789")
+			}
+			known = true
+		}
+		if noDevicesRE.MatchString(l) {
+			c.NoGPU, known = true, true
+		}
+	}
+	switch {
+	case c.OnTheCPU():
+		c.Backend = "CPU"
+	case c.Backend == "" && c.Offloaded > 0:
+		c.Backend = "GPU"
+	case c.Backend == "":
+		c.Backend = "CPU"
+	}
+	return c, known
+}
+
+// OnTheCPU is whether a model the engine was given GPUs for is computed on
+// the CPU, by its own account: no device found, or no layer offloaded.
+func (c Compute) OnTheCPU() bool {
+	return c.NoGPU || (c.Total > 0 && c.Offloaded == 0)
+}

internal/agent/engines/compute_test.go

@@ -0,0 +1,32 @@
+package engines
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestLlamaCppSaysWhereItPutTheModel(t *testing.T) {
+	gpu := strings.Split(`ggml_cuda_init: found 1 CUDA devices:
+  Device 0: Quadro RTX 6000, compute capability 7.5, VMM: yes
+load_backend: loaded CUDA backend from /opt/llmgw/engines/llamacpp/b10991/libggml-cuda.so
+llama_model_load_from_file_impl: using device CUDA0 (Quadro RTX 6000) - 23800 MiB free
+load_tensors: offloading 48 repeating layers to GPU
+load_tensors: offloaded 49/49 layers to GPU`, "\n")
+	c, ok := ReadLlamaCompute(gpu)
+	if !ok || c.Backend != "CUDA" || c.Offloaded != 49 || c.Total != 49 || c.OnTheCPU() ||
+		len(c.Devices) != 1 || c.Devices[0] != "CUDA0: Quadro RTX 6000 (7.5)" {
+		t.Errorf("on the GPU: %+v %v", c, ok)
+	}
+
+	cpu := strings.Split(`warning: no usable GPU found, --gpu-layers option will be ignored
+warning: one possible reason is that llama.cpp was compiled without GPU support
+load_tensors: offloaded 0/49 layers to GPU`, "\n")
+	c, ok = ReadLlamaCompute(cpu)
+	if !ok || c.Backend != "CPU" || !c.OnTheCPU() {
+		t.Errorf("fell back to the CPU: %+v %v", c, ok)
+	}
+
+	if _, ok := ReadLlamaCompute([]string{"main: server is listening on http://127.0.0.1:20001"}); ok {
+		t.Error("output that says nothing was read as saying something")
+	}
+}

internal/agent/engines/engine.go

@@ -9,6 +9,7 @@
 package engines
 
 import (
+	"context"
 	"fmt"
 	"os"
 	"slices"
@@ -40,6 +41,12 @@ type Profile struct {
 	ModelPath string
 	// ServedModelName is the name clients use, which need not match the path.
 	ServedModelName string
+	// Adapters are LoRA adapters to load beside the model, in order: an
+	// adapter's index is the id requests apply it by.
+	Adapters []Adapter
+	// KVEvents has the engine publish its KV cache events to the agent,
+	// for the router's precise index. vLLM only.
+	KVEvents bool `json:"kv_events,omitempty"`
 }
 
 // ShardSpec is one shard of one replica on this node.
@@ -58,6 +65,12 @@ type ShardSpec struct {
 
 	// GPUIndices are the local GPUs this shard uses.
 	GPUIndices []int
+	// GPUUUIDs name the same devices by UUID, in the same order, and are set
+	// by the agent only when one of them is a MIG instance. An instance has
+	// no index CUDA knows: CUDA_VISIBLE_DEVICES=MIG-<uuid> is the only way to
+	// give a process one, and the indices placement uses for it (1000 and
+	// up) mean nothing to CUDA.
+	GPUUUIDs []string `json:"gpu_uuids,omitempty"`
 	// HCAs are the adapters of the chosen fabric, and only that fabric. A shard
 	// must never be given HCAs from two fabrics.
 	HCAs []string
@@ -69,13 +82,22 @@ type ShardSpec struct {
 
 	HTTPPort int
 	Profile  Profile
+	// BindAddr is the address the engine listens on: the node's management
+	// address, which is what the router reaches it on, set by the agent.
+	// Empty listens on every address.
+	BindAddr string `json:"bind_addr,omitempty"`
 
 	// 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
+	// the node's management address; without a key anybody who can reach it
 	// 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"`
+	// KVEventsPort is the loopback port the agent receives this shard's KV
+	// cache events on, chosen by the agent; zero when it publishes none.
+	// Kept with the spec so an agent that restarts listens where the engine
+	// it adopts is still sending.
+	KVEventsPort int `json:"kv_events_port,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.
@@ -92,6 +114,18 @@ type ShardSpec struct {
 	// lets the control plane tell, after its own restart, whether a shard that
 	// is still running matches the profile the catalog holds now.
 	ProfileFP string
+
+	// Compute is where the engine said it put the model as it became ready,
+	// kept with the shard's state so an agent restarted later still knows.
+	Compute *Compute `json:",omitempty"`
+}
+
+// Host is where the engine listens.
+func (s ShardSpec) Host() string {
+	if s.BindAddr == "" {
+		return "0.0.0.0"
+	}
+	return s.BindAddr
 }
 
 // Leader reports whether this shard serves HTTP for the replica.
@@ -143,6 +177,22 @@ type Engine interface {
 	MetricsPath() string
 }
 
+// CPUFallback is an engine that can come up on the CPU when it was placed on
+// GPUs, and keep serving there without an error. The agent checks such a shard
+// is on its GPUs before calling it ready.
+type CPUFallback interface {
+	FallsBackToCPU() bool
+	// Devices lists the GPUs the engine's build can see, for saying why.
+	Devices(ctx context.Context) ([]string, error)
+}
+
+// HelpCommand is an engine whose program is not asked for its help by
+// running the command's path with --help, because the path is an interpreter
+// starting it through a launcher.
+type HelpCommand interface {
+	HelpCommand(c Command) (path string, args []string)
+}
+
 // GPUInfo is the subset of GPU facts validation needs.
 type GPUInfo struct {
 	Index             int
@@ -162,6 +212,7 @@ func NewRegistry(cfg Config) *Registry {
 	r.Add(&VLLM{cfg: cfg.VLLM})
 	r.Add(&SGLang{cfg: cfg.SGLang})
 	r.Add(&LlamaCpp{cfg: cfg.LlamaCpp})
+	r.Add(&TRTLLM{cfg: cfg.TRTLLM})
 	r.Add(&Sim{cfg: cfg.Sim})
 	return r
 }
@@ -200,10 +251,17 @@ func (r *Registry) Names() []string {
 
 // Config configures the engine adapters.
 type Config struct {
+	// Disabled are engines this node never installs or advertises, whatever
+	// the control plane asks: vLLM on a node of cards no build of it runs on,
+	// that is meant for llama.cpp alone.
+	Disabled []string       `koanf:"disabled"`
 	VLLM     VLLMConfig     `koanf:"vllm"`
 	SGLang   SGLangConfig   `koanf:"sglang"`
 	LlamaCpp LlamaCppConfig `koanf:"llamacpp"`
-	Sim      SimConfig      `koanf:"sim"`
+	// TRTLLM is TensorRT-LLM, which the agent does not install: a node
+	// offers it only when its interpreter is named here.
+	TRTLLM TRTLLMConfig `koanf:"trtllm"`
+	Sim    SimConfig    `koanf:"sim"`
 }
 
 // --- shared helpers ---
@@ -228,7 +286,12 @@ func NCCLEnv(s ShardSpec) map[string]string { return baseEnv(s) }
 //     one instead of timing out.
 func baseEnv(s ShardSpec) map[string]string {
 	env := map[string]string{
-		"CUDA_VISIBLE_DEVICES": joinInts(s.GPUIndices),
+		"CUDA_VISIBLE_DEVICES": visibleDevices(s),
+		// The indices above are nvidia-smi's, which counts by PCI bus. CUDA
+		// counts fastest first unless told otherwise, and on a node with two
+		// kinds of GPU the shard would get a different card than placement
+		// gave it — one another shard may hold.
+		"CUDA_DEVICE_ORDER": "PCI_BUS_ID",
 	}
 
 	if len(s.HCAs) > 0 {
@@ -295,6 +358,21 @@ func materializeEnv(generated map[string]string) []string {
 	return out
 }
 
+// visibleDevices is CUDA_VISIBLE_DEVICES for a shard: the indices placement
+// gave it, or their UUIDs when the agent named them, which it does for a MIG
+// instance.
+func visibleDevices(s ShardSpec) string {
+	if len(s.GPUUUIDs) > 0 {
+		return strings.Join(s.GPUUUIDs, ",")
+	}
+	return joinInts(s.GPUIndices)
+}
+
+// OnMIG reports whether the shard was given a MIG instance.
+func (s ShardSpec) OnMIG() bool {
+	return slices.ContainsFunc(s.GPUUUIDs, func(u string) bool { return strings.HasPrefix(u, "MIG-") })
+}
+
 func joinInts(v []int) string {
 	parts := make([]string, len(v))
 	for i, n := range v {
@@ -373,3 +451,10 @@ func quantizationOf(args []string) string {
 	}
 	return ""
 }
+
+// Adapter is a LoRA adapter an engine loads beside its model. Path is a
+// source until the agent has fetched it, a local file after.
+type Adapter struct {
+	Name string `json:"name"`
+	Path string `json:"path"`
+}

internal/agent/engines/engines_test.go

@@ -323,8 +323,8 @@ func TestSGLangMultiNodeArgs(t *testing.T) {
 	if cmd.Path != "/opt/sglang/bin/python" {
 		t.Errorf("Path=%q", cmd.Path)
 	}
-	if cmd.Args[0] != "-m" || cmd.Args[1] != "sglang.launch_server" {
-		t.Errorf("not launched as a module: %v", cmd.Args[:2])
+	if cmd.Args[0] != "-c" || !strings.Contains(cmd.Args[1], `run_module("sglang.launch_server"`) {
+		t.Errorf("not launched as the module: %v", cmd.Args[:2])
 	}
 	if argValue(cmd.Args, "--nnodes") != "2" || argValue(cmd.Args, "--node-rank") != "1" {
 		t.Errorf("multi-node flags wrong: %v", cmd.Args)
@@ -334,6 +334,58 @@ func TestSGLangMultiNodeArgs(t *testing.T) {
 	}
 }
 
+func TestSGLangsKeyIsNotOnItsCommandLine(t *testing.T) {
+	s := singleNodeSpec()
+	s.APIKey = "k1"
+	cmd := buildOne(t, &SGLang{}, s)
+	if slices.Contains(cmd.Args, "k1") || slices.Contains(cmd.Args, "--api-key") {
+		t.Errorf("the key is in the arguments: %v", cmd.Args)
+	}
+	if !slices.Contains(cmd.Env, sglangKeyEnv+"=k1") {
+		t.Errorf("the key is not in the environment")
+	}
+	// A worker serves no HTTP, and is not given it.
+	w := multiNodeSpec(1)
+	w.APIKey = "k1"
+	if cmd := buildOne(t, &SGLang{}, w); slices.Contains(cmd.Env, sglangKeyEnv+"=k1") {
+		t.Error("a worker was given the key")
+	}
+}
+
+func TestEnginesListenOnTheAddressTheyAreGiven(t *testing.T) {
+	s := singleNodeSpec()
+	for _, e := range []Engine{&VLLM{}, &SGLang{}} {
+		s.BindAddr = ""
+		if got := argValue(buildOne(t, e, s).Args, "--host"); got != "0.0.0.0" {
+			t.Errorf("%s: without an address listens on %q", e.Name(), got)
+		}
+		s.BindAddr = "10.0.0.147"
+		if got := argValue(buildOne(t, e, s).Args, "--host"); got != "10.0.0.147" {
+			t.Errorf("%s: listens on %q, expected the management address", e.Name(), got)
+		}
+	}
+}
+
+func TestSGLangIsStartedServingItsMetrics(t *testing.T) {
+	// Without --enable-metrics SGLang has no /metrics, and every scrape of
+	// the replica fails as though it were unreachable.
+	if cmd := buildOne(t, &SGLang{}, singleNodeSpec()); !slices.Contains(cmd.Args, "--enable-metrics") {
+		t.Errorf("not started with its metrics: %v", cmd.Args)
+	}
+}
+
+func TestSGLangIsAskedForItsHelpThroughItsModule(t *testing.T) {
+	g := &SGLang{cfg: SGLangConfig{Python: "/opt/sglang/bin/python"}}
+	g.UseInstalled("/opt/llmgw/engines/sglang/0.5.21-cu13/bin/python")
+	path, args := g.HelpCommand(Command{})
+	if path != "/opt/llmgw/engines/sglang/0.5.21-cu13/bin/python" {
+		t.Errorf("asked %s, not the interpreter it was installed into", path)
+	}
+	if !slices.Equal(args, []string{"-m", "sglang.launch_server", "--help"}) {
+		t.Errorf("asked %v", args)
+	}
+}
+
 func TestSGLangSingleNodeOmitsMultiNodeFlags(t *testing.T) {
 	cmd := buildOne(t, &SGLang{}, singleNodeSpec())
 	for _, flag := range []string{"--nnodes", "--node-rank", "--dist-init-addr"} {
@@ -425,14 +477,14 @@ func TestValidateRequiresModelPath(t *testing.T) {
 
 func TestRegistry(t *testing.T) {
 	r := NewRegistry(Config{})
-	if got := r.Names(); !slices.Equal(got, []string{"llamacpp", "sglang", "sim", "vllm"}) {
+	if got := r.Names(); !slices.Equal(got, []string{"llamacpp", "sglang", "sim", "trtllm", "vllm"}) {
 		t.Errorf("registry contents: %v", got)
 	}
 	if _, err := r.Get("vllm"); err != nil {
 		t.Errorf("vllm missing: %v", err)
 	}
 	err := func() error { _, err := r.Get("nope"); return err }()
-	if err == nil || !strings.Contains(err.Error(), "llamacpp, sglang, sim, vllm") {
+	if err == nil || !strings.Contains(err.Error(), "llamacpp, sglang, sim, trtllm, vllm") {
 		t.Errorf("an unknown engine should list what is available: %v", err)
 	}
 }

internal/agent/engines/kvevents_test.go

@@ -0,0 +1,47 @@
+package engines
+
+import (
+	"slices"
+	"strings"
+	"testing"
+)
+
+func TestAVLLMShardWithKVEventsPublishesToTheAgentOnLoopback(t *testing.T) {
+	s := singleNodeSpec()
+	s.Profile.KVEvents = true
+	s.KVEventsPort = 5999
+	s.Profile.Args = []string{"--max-model-len", "8192"}
+	cmd := buildOne(t, &VLLM{}, s)
+
+	i := slices.Index(cmd.Args, "--kv-events-config")
+	if i < 0 || !strings.Contains(cmd.Args[i+1], `"endpoint":"tcp://127.0.0.1:5999"`) {
+		t.Fatalf("args %v should name the agent's loopback port", cmd.Args)
+	}
+	if j := slices.Index(cmd.Args, "--prefix-caching-hash-algo"); j < 0 || cmd.Args[j+1] != "sha256_cbor" {
+		t.Fatalf("args %v should pin the hashing the router computes", cmd.Args)
+	}
+	if slices.Index(cmd.Args, "--max-model-len") < i {
+		t.Fatal("profile arguments come last, so an operator can still override")
+	}
+	if !slices.Contains(cmd.Env, "PYTHONHASHSEED=1729") {
+		t.Fatalf("env %v should fix the hash seed", cmd.Env)
+	}
+}
+
+func TestNoKVEventsWithoutAPortOrOffTheLeader(t *testing.T) {
+	s := singleNodeSpec()
+	s.Profile.KVEvents = true // but the agent could not listen
+	if cmd := buildOne(t, &VLLM{}, s); slices.Contains(cmd.Args, "--kv-events-config") {
+		t.Fatal("an engine told to publish where nobody listens only fills a queue")
+	}
+	w := multiNodeSpec(1)
+	w.Profile.KVEvents, w.KVEventsPort = true, 5999
+	if cmd := buildEngine(t, &VLLM{}, w); slices.Contains(cmd.Args, "--kv-events-config") {
+		t.Fatal("a headless worker has no scheduler to publish from")
+	}
+	off := singleNodeSpec()
+	off.KVEventsPort = 5999
+	if cmd := buildOne(t, &VLLM{}, off); slices.Contains(cmd.Args, "--kv-events-config") {
+		t.Fatal("kv_events is opt-in")
+	}
+}

internal/agent/engines/llamacpp.go

@@ -1,8 +1,10 @@
 package engines
 
 import (
+	"context"
 	"fmt"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"runtime"
 	"sort"
@@ -65,25 +67,25 @@ func (*LlamaCpp) ServesHTTP(ShardSpec) bool { return true }
 
 // Validate checks the profile against the GPUs it would run on.
 //
-// The two refusals here are about not pretending: llama.cpp has no equivalent
-// of a tensor-parallel group spanning machines, and its multi-GPU support is a
-// different mechanism (--split-mode, --tensor-split) that this adapter does not
-// drive. Accepting either would produce a replica that starts and then serves
-// from one machine while the catalog believes it has several.
+// llama.cpp spreads a model over a node's GPUs by layer (--split-mode layer),
+// so gpus_per_node is how many it gets. It has no tensor parallelism and no
+// group spanning machines, and accepting tp or nodes would produce a replica
+// that serves from fewer cards, or one machine, while the catalog believes
+// otherwise.
 func (*LlamaCpp) Validate(p Profile, gpus []GPUInfo) error {
-	if err := validateCommon(p, gpus); err != nil {
-		return err
-	}
 	if p.Nodes > 1 {
 		return fmt.Errorf("profile %q: llamacpp does not span nodes; use vllm or sglang for a %d-node replica",
 			p.Name, p.Nodes)
 	}
-	if p.TP > 1 {
-		return fmt.Errorf("profile %q: llamacpp does not do tensor parallelism; "+
-			"it splits a model across local GPUs with --tensor-split, which this adapter does not drive",
-			p.Name)
+	if p.TP > 1 || p.PP > 1 {
+		return fmt.Errorf("profile %q: llamacpp splits a model across a node's GPUs by layer, not by tp or pp; "+
+			"write gpus_per_node: %d instead", p.Name, max(p.TP, 1)*max(p.PP, 1))
 	}
-	return nil
+	// The common checks count a replica's GPUs as tp; for llama.cpp the
+	// count is gpus_per_node.
+	q := p
+	q.TP = max(p.GPUsPerNode, 1)
+	return validateCommon(q, gpus)
 }
 
 // Commands returns the processes for one shard, which is always one process.
@@ -91,13 +93,13 @@ func (l *LlamaCpp) Commands(s ShardSpec) ([]Command, error) {
 	bin := l.bin()
 	p := s.Profile
 
-	model, err := ggufIn(p.ModelPath)
+	model, projector, err := ggufIn(p.ModelPath)
 	if err != nil {
 		return nil, err
 	}
 	args := []string{
 		"--model", model,
-		"--host", "0.0.0.0",
+		"--host", s.Host(),
 		"--port", strconv.Itoa(s.HTTPPort),
 		// Without this there is no /metrics, and an endpoint the router cannot
 		// measure is one it has to route to blind.
@@ -118,6 +120,11 @@ func (l *LlamaCpp) Commands(s ShardSpec) ([]Command, error) {
 	if p.ServedModelName != "" {
 		args = append(args, "--alias", p.ServedModelName)
 	}
+	// A vision model's projector, fetched beside it: what turns an image in
+	// a request into something the language model reads.
+	if projector != "" && !hasFlag(p.Args, "--mmproj", "-mm") {
+		args = append(args, "--mmproj", projector)
+	}
 	if !hasFlag(p.Args, "--parallel", "-np") {
 		n := l.cfg.Parallel
 		if n <= 0 {
@@ -132,6 +139,13 @@ 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")
 	}
+	// Several GPUs: the layers spread across all of them, which is the only
+	// split llama.cpp does without a matched interconnect. In proportion to
+	// each card's free memory, which for the whole cards placement gives is
+	// an even split.
+	if len(s.GPUIndices) > 1 && !hasFlag(p.Args, "--split-mode", "-sm") {
+		args = append(args, "--split-mode", "layer")
+	}
 	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.
@@ -144,12 +158,33 @@ func (l *LlamaCpp) Commands(s ShardSpec) ([]Command, error) {
 		}
 		args = append(args, "--threads", strconv.Itoa(n))
 	}
+	// Loaded at start, applied per request: a request that names an adapter
+	// carries "lora": [{"id": i, "scale": s}], and one that names none is the
+	// base model. Each is loaded at scale zero, not with --lora and
+	// --lora-init-without-apply: that leaves an adapter's scale at 1, and
+	// llama-server applies it at that scale to every request with no "lora"
+	// of its own — every request for the model itself.
+	for _, a := range p.Adapters {
+		args = append(args, "--lora-scaled", a.Path+":0")
+	}
 	args = append(args, p.Args...)
 
 	env := baseEnv(s)
 	if s.APIKey != "" {
 		env["LLAMA_API_KEY"] = s.APIKey
 	}
+	// The Vulkan build — what a GPU older than the CUDA builds gets — does
+	// not read CUDA_VISIBLE_DEVICES; this is its own. Vulkan numbers devices
+	// as the driver lists them, which on NVIDIA follows the same bus order
+	// as nvidia-smi; were it not to, the shard would not hold memory on its
+	// own GPUs, and starting it checks exactly that.
+	//
+	// Not on a MIG instance, which Vulkan does not see at all: only CUDA
+	// opens one, by the UUID CUDA_VISIBLE_DEVICES carries, and an index here
+	// would name some other card.
+	if len(s.GPUIndices) > 0 && !s.OnMIG() {
+		env["GGML_VK_VISIBLE_DEVICES"] = joinInts(s.GPUIndices)
+	}
 	return []Command{{
 		Name: "llama-server", Path: bin, Args: args, Env: materializeEnv(env),
 	}}, nil
@@ -177,30 +212,46 @@ func hasFlag(args []string, names ...string) bool {
 //
 // A path that is already a file is returned untouched, which is every
 // single-file model and every hand-staged one.
-func ggufIn(path string) (string, error) {
+//
+// A vision projector in the directory — an mmproj file — is not the model:
+// it is returned second, to be loaded beside it.
+func ggufIn(path string) (model, projector string, err error) {
 	st, err := os.Stat(path)
 	if err != nil || !st.IsDir() {
 		// Not a directory, or not there at all — the second is the engine's to
 		// report, with the message it would have given anyway.
-		return path, nil //nolint:nilerr // a missing path is the engine's error to give
+		return path, "", nil //nolint:nilerr // a missing path is the engine's error to give
 	}
 	entries, err := os.ReadDir(path)
 	if err != nil {
-		return "", err
+		return "", "", err
 	}
-	var names []string
+	var names, projectors []string
 	for _, e := range entries {
-		if !e.IsDir() && strings.HasSuffix(strings.ToLower(e.Name()), ".gguf") {
+		lower := strings.ToLower(e.Name())
+		if e.IsDir() || !strings.HasSuffix(lower, ".gguf") {
+			continue
+		}
+		if strings.Contains(lower, "mmproj") {
+			projectors = append(projectors, e.Name())
+		} else {
 			names = append(names, e.Name())
 		}
 	}
 	if len(names) == 0 {
-		return "", fmt.Errorf("%s holds no .gguf file", path)
+		if len(projectors) > 0 {
+			return "", "", fmt.Errorf("%s holds a vision projector and no model", path)
+		}
+		return "", "", fmt.Errorf("%s holds no .gguf file", path)
 	}
 	// Sorted, so a split model's first part comes first: the parts are named
 	// "-00001-of-00004" and lexical order is shard order.
 	sort.Strings(names)
-	return filepath.Join(path, names[0]), nil
+	if len(projectors) > 0 {
+		sort.Strings(projectors)
+		projector = filepath.Join(path, projectors[0])
+	}
+	return filepath.Join(path, names[0]), projector, nil
 }
 
 // UseInstalled points the engine at a build the agent installed and checked.
@@ -225,3 +276,41 @@ func (l *LlamaCpp) bin() string {
 	}
 	return "llama-server"
 }
+
+// Binary is the llama-server this engine runs.
+func (l *LlamaCpp) Binary() string { return l.bin() }
+
+// FallsBackToCPU says that llama.cpp keeps running when its GPU backend does
+// not load: --n-gpu-layers asks for layers on a GPU it then has none of, and
+// the server comes up and answers on the CPU, at a tenth of the speed, with no
+// error anywhere. Its readiness on a GPU placement needs checking separately.
+func (*LlamaCpp) FallsBackToCPU() bool { return true }
+
+// Devices lists the GPUs this build can compute on, as llama-server's
+// --list-devices names them ("CUDA0: NVIDIA L4 (22994 MiB, 22713 MiB free)").
+// Empty, on a machine with GPUs, is a build whose GPU backend did not load:
+// the CPU build, or a CUDA build missing a library its backend links.
+func (l *LlamaCpp) Devices(ctx context.Context) ([]string, error) {
+	out, err := exec.CommandContext(ctx, l.bin(), "--list-devices").CombinedOutput() //nolint:gosec // the engine's own binary
+	if err != nil {
+		return nil, fmt.Errorf("%s --list-devices: %v: %s", l.bin(), err, strings.TrimSpace(string(out)))
+	}
+	return parseDevices(string(out)), nil
+}
+
+// parseDevices reads --list-devices: the lines after "Available devices:",
+// which says "(none)" when there are none. Log lines before it are skipped.
+func parseDevices(out string) []string {
+	var devs []string
+	listing := false
+	for _, line := range strings.Split(out, "\n") {
+		line = strings.TrimSpace(line)
+		switch {
+		case strings.HasPrefix(line, "Available devices"):
+			listing = true
+		case listing && line != "" && line != "(none)":
+			devs = append(devs, line)
+		}
+	}
+	return devs
+}

internal/agent/engines/llamacpp_test.go

@@ -204,7 +204,7 @@ func TestASetDirectoryResolvesToItsFirstPart(t *testing.T) {
 		}
 	}
 
-	got, err := ggufIn(dir)
+	got, _, err := ggufIn(dir)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -221,7 +221,7 @@ func TestAPlainFilePathIsUntouched(t *testing.T) {
 	if err := os.WriteFile(p, []byte("x"), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	if got, _ := ggufIn(p); got != p {
+	if got, _, _ := ggufIn(p); got != p {
 		t.Errorf("expected the path unchanged, got %s", got)
 	}
 }
@@ -231,7 +231,7 @@ func TestADirectoryWithNoWeightsSaysSo(t *testing.T) {
 	if err := os.WriteFile(filepath.Join(dir, "config.json"), []byte("{}"), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	if _, err := ggufIn(dir); err == nil {
+	if _, _, err := ggufIn(dir); err == nil {
 		t.Error("a directory with no .gguf in it is not a model llama.cpp can load")
 	}
 }
@@ -240,7 +240,7 @@ func TestAMissingPathIsLeftToTheEngine(t *testing.T) {
 	// The engine's own "no such file" names the path and the flag it came
 	// from, which is more use than anything this could say.
 	p := "/nonexistent/model.gguf"
-	got, err := ggufIn(p)
+	got, _, err := ggufIn(p)
 	if err != nil || got != p {
 		t.Errorf("expected it passed through, got %q %v", got, err)
 	}
@@ -306,3 +306,83 @@ func TestTheCoresPlacementReservedAreTheThreads(t *testing.T) {
 		t.Errorf("--threads %q; what placement reserved should win over the node's setting", v)
 	}
 }
+
+func TestAdaptersAreLoadedAtStartAndAppliedToNoneByDefault(t *testing.T) {
+	s := llamaSpec(nil)
+	s.Profile.Adapters = []Adapter{{Name: "sql", Path: "/w/sql.gguf"}, {Name: "docs", Path: "/w/docs.gguf"}}
+	cmds, err := (&LlamaCpp{}).Commands(s)
+	if err != nil {
+		t.Fatal(err)
+	}
+	args := strings.Join(cmds[0].Args, " ")
+	if !strings.Contains(args, "--lora-scaled /w/sql.gguf:0 --lora-scaled /w/docs.gguf:0") {
+		t.Errorf("args %s: both adapters, in order, loaded at scale zero", args)
+	}
+	plain, _ := (&LlamaCpp{}).Commands(llamaSpec(nil))
+	if strings.Contains(strings.Join(plain[0].Args, " "), "--lora") {
+		t.Error("a model with no adapters was given lora flags")
+	}
+}
+
+func TestDevicesAreReadFromListDevices(t *testing.T) {
+	cuda := "ggml_cuda_init: found 2 CUDA devices:\nAvailable devices:\n  CUDA0: NVIDIA L4 (22994 MiB, 22713 MiB free)\n  CUDA1: NVIDIA L4 (22994 MiB, 22713 MiB free)\n"
+	if got := parseDevices(cuda); len(got) != 2 || !strings.HasPrefix(got[0], "CUDA0: NVIDIA L4") {
+		t.Errorf("CUDA build: %q", got)
+	}
+	// A CUDA build whose backend did not load says what the CPU build says.
+	if got := parseDevices("Available devices:\n  (none)\n"); len(got) != 0 {
+		t.Errorf("no devices: %q", got)
+	}
+}
+
+func TestLlamaCppSpreadsAReplicaOverItsNodesGPUsByLayer(t *testing.T) {
+	four := Profile{Name: "t4x4", Engine: "llamacpp", GPUClass: "t4", TP: 1, GPUsPerNode: 4, ModelPath: "/m"}
+	if err := (&LlamaCpp{}).Validate(four, h100(4)); err != nil {
+		t.Fatalf("four GPUs on a four-GPU node: %v", err)
+	}
+	if err := (&LlamaCpp{}).Validate(four, h100(2)); err == nil {
+		t.Error("four GPUs were accepted on a node with two")
+	}
+
+	s := llamaSpec([]int{0, 1, 2, 3})
+	s.Profile.GPUsPerNode = 4
+	cmds, err := (&LlamaCpp{}).Commands(s)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if v, _ := flagValue(cmds[0].Args, "--split-mode"); v != "layer" {
+		t.Errorf("--split-mode %q over four GPUs", v)
+	}
+	if !slices.Contains(cmds[0].Env, "CUDA_VISIBLE_DEVICES=0,1,2,3") {
+		t.Errorf("env %v: the replica must see all four of its GPUs", cmds[0].Env)
+	}
+	one, _ := (&LlamaCpp{}).Commands(llamaSpec([]int{2}))
+	if hasFlag(one[0].Args, "--split-mode") {
+		t.Error("a one-GPU replica was given a split mode")
+	}
+}
+
+func TestAVisionProjectorIsLoadedBesideTheModelNotAsIt(t *testing.T) {
+	dir := t.TempDir()
+	// "mmproj" sorts before the model's name; it must still not be taken for it.
+	for _, n := range []string{"gemma-3-4b-it-Q4_K_M.gguf", "mmproj-gemma-3-4b-it-f16.gguf"} {
+		if err := os.WriteFile(filepath.Join(dir, n), []byte("x"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	cmds, err := (&LlamaCpp{}).Commands(ShardSpec{HTTPPort: 8080, Profile: Profile{ModelPath: dir}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	args := strings.Join(cmds[0].Args, " ")
+	if !strings.Contains(args, "--model "+filepath.Join(dir, "gemma-3-4b-it-Q4_K_M.gguf")) ||
+		!strings.Contains(args, "--mmproj "+filepath.Join(dir, "mmproj-gemma-3-4b-it-f16.gguf")) {
+		t.Errorf("%s", args)
+	}
+	// One the profile names itself is left as it is.
+	cmds, _ = (&LlamaCpp{}).Commands(ShardSpec{HTTPPort: 8080, Profile: Profile{ModelPath: dir,
+		Args: []string{"--mmproj", "/elsewhere.gguf"}}})
+	if strings.Count(strings.Join(cmds[0].Args, " "), "--mmproj") != 1 {
+		t.Errorf("two projectors: %v", cmds[0].Args)
+	}
+}

internal/agent/engines/lora.go

@@ -0,0 +1,136 @@
+package engines
+
+import (
+	"fmt"
+	"maps"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+)
+
+// RuntimeLoRAEnv is the variable that lets vLLM load and unload adapters
+// while it runs, through POST /v1/load_lora_adapter and
+// /v1/unload_lora_adapter. Without it those routes do not exist.
+//
+// It doubles as the mark that a profile's adapters load on demand: the
+// catalog sets it for a model with max_loaded_adapters and refuses it set by
+// hand anywhere else, so it cannot disagree with what the router does.
+const RuntimeLoRAEnv = "VLLM_ALLOW_RUNTIME_LORA_UPDATING"
+
+// RuntimeLoRADir is where an agent links each adapter it fetched for a
+// replica whose adapters load on demand, under the adapter's name, relative
+// to the directory engines run in.
+//
+// Relative on purpose. The router asks the engine to load an adapter by a
+// path, and does not know where any node keeps its cache — each node may
+// keep it somewhere else, and a replica spanning nodes reads the adapter on
+// every one of them. vLLM resolves a relative path that exists against its
+// working directory, which on every node is the one the agent starts
+// engines in, and the agent links the adapter there before the engine
+// starts. So one path, the same everywhere, names the right file on each.
+const RuntimeLoRADir = "llmgw-lora"
+
+// WithRuntimeLoRA has a vLLM profile with adapters start holding none of
+// them, ready to load up to limit at a time on demand: the engine is allowed
+// runtime loading, and --max-loras — how many adapters one batch may mix —
+// is the cap, unless the operator's arguments already say. Anything else is
+// returned as it is.
+func (p Profile) WithRuntimeLoRA(limit int) Profile {
+	if limit <= 0 || p.Engine != "vllm" || len(p.Adapters) == 0 {
+		return p
+	}
+	env := maps.Clone(p.Env)
+	if env == nil {
+		env = map[string]string{}
+	}
+	env[RuntimeLoRAEnv] = "True"
+	p.Env = env
+	if !hasFlag(p.Args, "--max-loras") {
+		p.Args = append([]string{"--max-loras", strconv.Itoa(limit)}, p.Args...)
+	}
+	return p
+}
+
+// RuntimeLoRA reports whether a profile's adapters load on demand rather
+// than at start.
+func (p Profile) RuntimeLoRA() bool {
+	v, ok := p.Env[RuntimeLoRAEnv]
+	return ok && v != "" && v != "0" && !strings.EqualFold(v, "false")
+}
+
+// RuntimeLoRAPath is the lora_path the router gives vLLM to load an adapter
+// from: the link the agent made, or, for a Hugging Face repository id, the
+// id, which vLLM downloads itself and the agent leaves alone.
+func RuntimeLoRAPath(name, source string) string {
+	if IsHubID(source) {
+		return source
+	}
+	return RuntimeLoRADir + "/" + name
+}
+
+// IsHubID reports whether a source is a bare Hugging Face repository id
+// ("org/repo") rather than a URL or a path: what the agent passes to an
+// engine untouched.
+func IsHubID(source string) bool {
+	switch {
+	case source == "",
+		strings.HasPrefix(source, "/"), strings.HasPrefix(source, "./"), strings.HasPrefix(source, "../"),
+		strings.HasPrefix(source, "~"),
+		strings.HasPrefix(source, "http://"), strings.HasPrefix(source, "https://"),
+		strings.HasPrefix(source, "hf:"):
+		return false
+	}
+	return true
+}
+
+// LinkRuntimeAdapters makes RuntimeLoRADir under dir hold a link to each
+// fetched adapter, named as the adapter is. A link already there is
+// replaced, so a replica started after an adapter's source changed loads
+// the new one. Adapters still named by a repository id have nothing local
+// to link.
+func LinkRuntimeAdapters(dir string, ads []Adapter) error {
+	if len(ads) == 0 {
+		return nil
+	}
+	root := filepath.Join(dir, RuntimeLoRADir)
+	if err := os.MkdirAll(root, 0o755); err != nil {
+		return fmt.Errorf("making the adapters' directory: %w", err)
+	}
+	for _, a := range ads {
+		if IsHubID(a.Path) {
+			continue
+		}
+		if a.Name == "" || strings.ContainsAny(a.Name, `/\`) || a.Name == "." || a.Name == ".." {
+			return fmt.Errorf("adapter %q: not a name a file can have", a.Name)
+		}
+		target, err := filepath.Abs(a.Path)
+		if err != nil {
+			return fmt.Errorf("adapter %s: %w", a.Name, err)
+		}
+		link := filepath.Join(root, a.Name)
+		// Made beside the old one and renamed over it, so an engine loading
+		// the adapter at this moment sees one or the other and never neither.
+		tmp := link + ".new"
+		_ = os.Remove(tmp)
+		if err := os.Symlink(target, tmp); err != nil {
+			return fmt.Errorf("adapter %s: %w", a.Name, err)
+		}
+		if err := os.Rename(tmp, link); err != nil {
+			_ = os.Remove(tmp)
+			return fmt.Errorf("adapter %s: %w", a.Name, err)
+		}
+	}
+	return nil
+}
+
+// loraModules is vLLM's --lora-modules for adapters loaded at start: one
+// flag followed by every name=path, since vLLM keeps only the last of a
+// repeated flag.
+func loraModules(ads []Adapter) []string {
+	out := []string{"--lora-modules"}
+	for _, a := range ads {
+		out = append(out, a.Name+"="+a.Path)
+	}
+	return out
+}

internal/agent/engines/lora_test.go

@@ -0,0 +1,129 @@
+package engines
+
+import (
+	"os"
+	"path/filepath"
+	"slices"
+	"testing"
+)
+
+func adapterSpec() ShardSpec {
+	s := singleNodeSpec()
+	s.Profile.Engine = "vllm"
+	s.Profile.Adapters = []Adapter{
+		{Name: "sql", Path: "/cache/ab-sql"},
+		{Name: "docs", Path: "/cache/cd-docs"},
+	}
+	return s
+}
+
+func TestVLLMLoadsEveryAdapterAtStartUnderOneFlag(t *testing.T) {
+	cmd := buildOne(t, &VLLM{}, adapterSpec())
+	if !slices.Contains(cmd.Args, "--enable-lora") {
+		t.Errorf("LoRA not enabled: %v", cmd.Args)
+	}
+	// vLLM keeps only the last of a repeated --lora-modules, so both
+	// adapters must follow one flag.
+	i := slices.Index(cmd.Args, "--lora-modules")
+	if i < 0 || !slices.Equal(cmd.Args[i+1:i+3], []string{"sql=/cache/ab-sql", "docs=/cache/cd-docs"}) {
+		t.Errorf("adapters not registered at start: %v", cmd.Args)
+	}
+	if n := countFlag(cmd.Args, "--lora-modules"); n != 1 {
+		t.Errorf("--lora-modules given %d times", n)
+	}
+	if _, set := envMap(cmd.Env)[RuntimeLoRAEnv]; set {
+		t.Error("runtime loading was allowed for adapters loaded at start")
+	}
+}
+
+func TestVLLMWithAdaptersOnDemandStartsHoldingNone(t *testing.T) {
+	s := adapterSpec()
+	s.Profile = s.Profile.WithRuntimeLoRA(3)
+	cmd := buildOne(t, &VLLM{}, s)
+	if slices.Contains(cmd.Args, "--lora-modules") {
+		t.Errorf("adapters registered at start: %v", cmd.Args)
+	}
+	if !slices.Contains(cmd.Args, "--enable-lora") || argValue(cmd.Args, "--max-loras") != "3" {
+		t.Errorf("want LoRA enabled with the cap as --max-loras: %v", cmd.Args)
+	}
+	if envMap(cmd.Env)[RuntimeLoRAEnv] != "True" {
+		t.Errorf("the load and unload routes were not turned on: %v", cmd.Env)
+	}
+}
+
+func TestTheOperatorsMaxLorasWinsOverTheCap(t *testing.T) {
+	p := adapterSpec().Profile
+	p.Args = []string{"--max-loras", "8"}
+	got := p.WithRuntimeLoRA(3)
+	if argValue(got.Args, "--max-loras") != "8" || countFlag(got.Args, "--max-loras") != 1 {
+		t.Errorf("args %v", got.Args)
+	}
+	if p.Env != nil {
+		t.Error("the profile's own env map was written to")
+	}
+}
+
+func TestRuntimeLoRALeavesOtherProfilesAlone(t *testing.T) {
+	llama := adapterSpec().Profile
+	llama.Engine = "llamacpp"
+	none := adapterSpec().Profile
+	none.Adapters = nil
+	for _, p := range []Profile{llama, none} {
+		if got := p.WithRuntimeLoRA(2); got.RuntimeLoRA() || len(got.Args) != 0 {
+			t.Errorf("%s with %d adapters: %+v", p.Engine, len(p.Adapters), got)
+		}
+	}
+}
+
+func TestTheRouterLoadsAnAdapterByItsLinkOrItsRepository(t *testing.T) {
+	for source, want := range map[string]string{
+		"http://mirror:8081/sql-lora/v1/":    "llmgw-lora/sql",
+		"/srv/adapters/sql":                  "llmgw-lora/sql",
+		"hf:org/repo/adapter.gguf":           "llmgw-lora/sql",
+		"someone/sql-lora":                   "someone/sql-lora",
+		"https://huggingface.co/someone/sql": "llmgw-lora/sql",
+	} {
+		if got := RuntimeLoRAPath("sql", source); got != want {
+			t.Errorf("%s: %s, want %s", source, got, want)
+		}
+	}
+}
+
+func TestAdaptersAreLinkedUnderTheirNamesAndRelinkedWhenTheyChange(t *testing.T) {
+	dir := t.TempDir()
+	old := filepath.Join(dir, "old-sql")
+	cur := filepath.Join(dir, "new-sql")
+	for _, d := range []string{old, cur} {
+		if err := os.Mkdir(d, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	ads := []Adapter{{Name: "sql", Path: old}, {Name: "hub", Path: "someone/hub-lora"}}
+	if err := LinkRuntimeAdapters(dir, ads); err != nil {
+		t.Fatal(err)
+	}
+	ads[0].Path = cur
+	if err := LinkRuntimeAdapters(dir, ads); err != nil {
+		t.Fatal(err)
+	}
+	got, err := os.Readlink(filepath.Join(dir, RuntimeLoRADir, "sql"))
+	if err != nil || got != cur {
+		t.Errorf("link to %q (%v), want %q", got, err, cur)
+	}
+	if _, err := os.Lstat(filepath.Join(dir, RuntimeLoRADir, "hub")); !os.IsNotExist(err) {
+		t.Errorf("a repository id was linked: %v", err)
+	}
+	if err := LinkRuntimeAdapters(dir, []Adapter{{Name: "../escape", Path: cur}}); err == nil {
+		t.Error("an adapter named like a path was linked")
+	}
+}
+
+func countFlag(args []string, flag string) int {
+	n := 0
+	for _, a := range args {
+		if a == flag {
+			n++
+		}
+	}
+	return n
+}

internal/agent/engines/mig_test.go

@@ -0,0 +1,49 @@
+package engines
+
+import "testing"
+
+const migUUID = "MIG-c6d4f1ef-42e4-5de3-91c7-45d71c87eb3f"
+
+func TestAShardOnAMIGInstanceIsGivenItByUUID(t *testing.T) {
+	// Placement numbers card 0's instance 1 as 1001, which CUDA has never
+	// heard of: CUDA_VISIBLE_DEVICES=1001 is no device at all, and =1 would
+	// be the wrong card.
+	s := singleNodeSpec()
+	s.GPUIndices, s.GPUUUIDs = []int{1001}, []string{migUUID}
+	s.Profile.TP = 1
+
+	env := envMap(buildOne(t, &VLLM{}, s).Env)
+	if env["CUDA_VISIBLE_DEVICES"] != migUUID {
+		t.Errorf("vLLM: CUDA_VISIBLE_DEVICES=%q, want the instance's UUID", env["CUDA_VISIBLE_DEVICES"])
+	}
+
+	l := llamaSpec([]int{1001})
+	l.GPUUUIDs = s.GPUUUIDs
+	cmds, err := (&LlamaCpp{}).Commands(l)
+	if err != nil {
+		t.Fatal(err)
+	}
+	env = envMap(cmds[0].Env)
+	if env["CUDA_VISIBLE_DEVICES"] != migUUID {
+		t.Errorf("llama.cpp: CUDA_VISIBLE_DEVICES=%q, want the instance's UUID", env["CUDA_VISIBLE_DEVICES"])
+	}
+	// Vulkan does not see MIG instances, and an index for it would name
+	// some other card.
+	if v, set := env["GGML_VK_VISIBLE_DEVICES"]; set {
+		t.Errorf("GGML_VK_VISIBLE_DEVICES=%q on a MIG instance", v)
+	}
+	if v, _ := flagValue(cmds[0].Args, "--n-gpu-layers"); v != "999" {
+		t.Errorf("the model was not offloaded to the instance: --n-gpu-layers %q", v)
+	}
+}
+
+func TestAShardOnWholeCardsIsStillGivenThemByIndex(t *testing.T) {
+	env := envMap(buildOne(t, &VLLM{}, singleNodeSpec()).Env)
+	if env["CUDA_VISIBLE_DEVICES"] != "0,1,2,3" {
+		t.Errorf("CUDA_VISIBLE_DEVICES=%q", env["CUDA_VISIBLE_DEVICES"])
+	}
+	cmds, _ := (&LlamaCpp{}).Commands(llamaSpec([]int{2}))
+	if env := envMap(cmds[0].Env); env["GGML_VK_VISIBLE_DEVICES"] != "2" {
+		t.Errorf("GGML_VK_VISIBLE_DEVICES=%q", env["GGML_VK_VISIBLE_DEVICES"])
+	}
+}

internal/agent/engines/sglang.go

@@ -40,7 +40,15 @@ func (*SGLang) Name() string { return "sglang" }
 // HealthPath is SGLang's readiness endpoint.
 func (*SGLang) HealthPath() string { return "/health" }
 
-// MetricsPath is SGLang's Prometheus endpoint.
+// HelpCommand is how to ask SGLang for its help: through its module, in the
+// environment it was installed into, since the command itself is llmgw's
+// launcher and the interpreter's own --help describes Python.
+func (g *SGLang) HelpCommand(Command) (string, []string) {
+	return g.python(), []string{"-m", "sglang.launch_server", "--help"}
+}
+
+// MetricsPath is SGLang's Prometheus endpoint, served only with
+// --enable-metrics.
 func (*SGLang) MetricsPath() string { return "/metrics" }
 
 // Validate checks the profile against the GPUs it would run on.
@@ -79,11 +87,17 @@ func (g *SGLang) serverCommand(s ShardSpec) (Command, error) {
 	python := g.python()
 	p := s.Profile
 
-	args := []string{"-m", "sglang.launch_server",
+	args := []string{"-c", sglangLauncher,
 		"--model-path", p.ModelPath,
-		"--host", "0.0.0.0",
+		"--host", s.Host(),
 		"--port", strconv.Itoa(s.HTTPPort),
-		"--tp", strconv.Itoa(p.TP),
+		// The flag's whole name: SGLang's documentation writes --tp, which
+		// argparse accepts only as an abbreviation of --tp-size and only
+		// while no other flag begins with it.
+		"--tp-size", strconv.Itoa(p.TP),
+		// Without it SGLang serves no /metrics at all, and the router has
+		// nothing to schedule this replica by.
+		"--enable-metrics",
 	}
 	if p.ServedModelName != "" {
 		args = append(args, "--served-model-name", p.ServedModelName)
@@ -96,11 +110,23 @@ 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.
+	env := baseEnv(s)
 	if s.APIKey != "" && s.Leader() {
-		args = append(args, "--api-key", s.APIKey)
+		env[sglangKeyEnv] = s.APIKey
 	}
-
-	return Command{Name: "sglang", Path: python, Args: args, Env: materializeEnv(baseEnv(s))}, nil
+	return Command{Name: "sglang", Path: python, Args: args, Env: materializeEnv(env)}, nil
 }
+
+// SGLang reads its key only from the command line, where every user on the
+// node can read it in the process list. So the key goes in the environment,
+// which only the engine's own user and root can read, and this launcher —
+// sglang.launch_server under another name — adds it to the arguments inside
+// the process: sys.argv is Python's copy, not what /proc shows.
+const (
+	sglangKeyEnv   = "LLMGW_ENGINE_KEY"
+	sglangLauncher = `import os, runpy, sys
+key = os.environ.pop("` + sglangKeyEnv + `", "")
+sys.argv = ["sglang.launch_server"] + sys.argv[1:] + (["--api-key", key] if key else [])
+runpy.run_module("sglang.launch_server", run_name="__main__", alter_sys=True)
+`
+)

internal/agent/engines/sim.go

@@ -2,6 +2,7 @@ package engines
 
 import (
 	"fmt"
+	"net"
 	"os"
 	"strconv"
 )
@@ -63,7 +64,7 @@ func (s *Sim) Commands(spec ShardSpec) ([]Command, error) {
 	p := spec.Profile
 
 	args := []string{"sim-engine",
-		"--listen", "0.0.0.0:" + strconv.Itoa(spec.HTTPPort),
+		"--listen", net.JoinHostPort(spec.Host(), strconv.Itoa(spec.HTTPPort)),
 		"--model", p.ServedModelName,
 	}
 	if spec.NNodes > 1 {

internal/agent/engines/trtllm.go

@@ -0,0 +1,218 @@
+package engines
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+)
+
+// TRTLLMConfig locates a TensorRT-LLM the operator installed.
+//
+// llmgw does not install TensorRT-LLM. It is a pip package pinned to one
+// CUDA, one PyTorch and an MPI the machine must provide, and NVIDIA's own
+// advice is its container; an installer that guessed at all of that would
+// fail on most machines it met, a long way into a large download. So it is
+// brought by the operator — a virtual environment, or NVIDIA's container —
+// and named here.
+type TRTLLMConfig struct {
+	// Python is the interpreter of the environment TensorRT-LLM is installed
+	// in: <venv>/bin/python for a virtual environment, python3 in NVIDIA's
+	// container. Naming it is what makes this node offer the engine; empty
+	// offers nothing.
+	//
+	// The interpreter rather than trtllm-serve, because llmgw starts the
+	// server through a few lines of its own that make it demand the
+	// gateway's key, which trtllm-serve has no option for.
+	Python string `koanf:"python"`
+}
+
+// TRTLLM builds TensorRT-LLM launch commands: its OpenAI-compatible server,
+// trtllm-serve, on one node.
+//
+// Written against TensorRT-LLM's documented command line and server, and not
+// yet run on hardware by anyone working on llmgw: no datacenter GPU was at
+// hand. `llmgw ctl engine-check trtllm` asks an installed one whether it
+// takes the flags built here.
+type TRTLLM struct{ cfg TRTLLMConfig }
+
+// Name identifies the engine in the catalog.
+func (*TRTLLM) Name() string { return "trtllm" }
+
+// HealthPath is trtllm-serve's liveness endpoint: 200 once the executor is
+// up, 503 while it is not. The supervisor's /v1/models step is what says the
+// model is being served.
+func (*TRTLLM) HealthPath() string { return "/health" }
+
+// MetricsPath is trtllm-serve's Prometheus endpoint. Its /metrics is a
+// different thing — a JSON list of iteration statistics, drained by each
+// read — and a scrape there would both fail to parse and steal the numbers
+// from anyone else reading them.
+func (*TRTLLM) MetricsPath() string { return "/prometheus/metrics" }
+
+// ServesHTTP reports whether this rank answers the API; a TensorRT-LLM
+// replica is one node, and so one rank.
+func (*TRTLLM) ServesHTTP(s ShardSpec) bool { return s.Leader() }
+
+// Validate checks the profile against the GPUs it would run on.
+//
+// One node: trtllm-serve spans machines only when started under MPI or
+// Slurm from one of them (trtllm-llmapi-launch), and the agents each start
+// their own node's part, which is not that. Ampere or newer: the oldest
+// generation current TensorRT-LLM builds kernels for.
+func (*TRTLLM) Validate(p Profile, gpus []GPUInfo) error {
+	if p.Nodes > 1 {
+		return fmt.Errorf("profile %q: trtllm runs a replica on one node; "+
+			"use vllm or sglang for a %d-node replica", p.Name, p.Nodes)
+	}
+	if err := validateCommon(p, gpus); err != nil {
+		return err
+	}
+	return requireComputeCapability(p, gpus, 8.0, "TensorRT-LLM")
+}
+
+// Commands returns the processes for one shard, which is one process. Tensor
+// and pipeline parallel ranks on the node are trtllm-serve's own MPI workers,
+// started by it.
+func (t *TRTLLM) Commands(s ShardSpec) ([]Command, error) {
+	if s.NNodes > 1 {
+		return nil, fmt.Errorf("trtllm: a replica spanning %d nodes is not something llmgw starts; "+
+			"TensorRT-LLM runs one node per replica here", s.NNodes)
+	}
+	p := s.Profile
+	args := []string{"-c", trtllmLauncher,
+		// The subcommand by name: trtllm-serve takes a bare model as "serve",
+		// but saying it costs nothing and does not depend on that default.
+		"serve", p.ModelPath,
+		"--host", s.Host(),
+		"--port", strconv.Itoa(s.HTTPPort),
+		"--tp_size", strconv.Itoa(p.TP),
+	}
+	if p.PP > 1 {
+		args = append(args, "--pp_size", strconv.Itoa(p.PP))
+	}
+	if p.ServedModelName != "" {
+		// Without it the model is named after its directory, and the agent's
+		// readiness check, which looks for this name in /v1/models, never
+		// finds it.
+		args = append(args, "--served_model_name", p.ServedModelName)
+	}
+	// What makes the queue and the cache measurable: the options file the
+	// launcher writes turns on the Prometheus endpoint and the iteration
+	// statistics its gauges are set from. A placeholder here, so the flag is
+	// one engine-check sees and checks; the launcher replaces it.
+	args = append(args, "--extra_llm_api_options", trtllmOptionsPlaceholder)
+	args = append(args, p.Args...)
+
+	env := baseEnv(s)
+	if s.APIKey != "" {
+		env[trtllmKeyEnv] = s.APIKey
+	}
+	// TensorRT-LLM reports usage to NVIDIA unless told not to. A gateway on
+	// somebody's own network does not phone home on their behalf, and a
+	// model's profile cannot make it: these are set after the profile's env.
+	env["TRTLLM_NO_USAGE_STATS"] = "1"
+	env["DO_NOT_TRACK"] = "1"
+	return []Command{{Name: "trtllm-serve", Path: t.python(), Args: args, Env: materializeEnv(env)}}, nil
+}
+
+// python is the interpreter to start trtllm-serve with.
+func (t *TRTLLM) python() string {
+	if t.cfg.Python != "" {
+		return t.cfg.Python
+	}
+	return "python3"
+}
+
+// Configured reports whether the configuration names TensorRT-LLM's
+// interpreter, which is the only way a node offers it.
+func (t *TRTLLM) Configured() bool { return t.cfg.Python != "" }
+
+// Probe reports the installed TensorRT-LLM's version.
+//
+// From the package's metadata rather than by importing it: the import loads
+// CUDA, MPI and PyTorch and takes longer than a probe may, while what
+// placement needs is whether the package is there. Whether it runs is
+// engine-check's question, and the replica's.
+func (t *TRTLLM) Probe(ctx context.Context) (string, error) {
+	return versionOfModule(ctx, t.python(), "-c",
+		"import importlib.metadata as m, importlib.util as u, sys\n"+
+			"if u.find_spec('tensorrt_llm') is None: sys.exit(1)\n"+
+			"sys.stdout.write(m.version('tensorrt_llm'))")
+}
+
+// HelpCommand is how to ask trtllm-serve for its help: through its module,
+// since the command itself is llmgw's launcher.
+func (t *TRTLLM) HelpCommand(Command) (string, []string) {
+	return t.python(), []string{"-m", "tensorrt_llm.commands.serve", "serve", "--help"}
+}
+
+const (
+	trtllmKeyEnv             = "LLMGW_ENGINE_KEY"
+	trtllmOptionsPlaceholder = "@llmgw-options"
+)
+
+// trtllmLauncher starts trtllm-serve inside the process, after two things
+// trtllm-serve has no flag for.
+//
+// The key. trtllm-serve checks none, and an engine listens on the node's
+// management address, where without one anybody who can reach the port talks
+// to the model past the gateway's authentication, quotas and accounting. So
+// every FastAPI application the process makes — trtllm-serve's server is one
+// — is given a middleware demanding it, before trtllm-serve imports anything.
+// /health is left open: it says only up or down, and a supervisor of
+// TensorRT-LLM's own may ask it without a key. The key comes in the
+// environment and is taken out of it, so the MPI workers and anything else
+// started from here never hold it.
+//
+// The options. The Prometheus endpoint exists only with return_perf_metrics,
+// and its queue gauges move only with enable_iter_perf_stats; both are
+// settings of TensorRT-LLM's options file, not flags. The file is written to
+// an unnamed temporary file and passed by descriptor: nothing is left on disk
+// however the server ends.
+//
+// trtllm-serve can start further HTTP front ends as copies of its own command
+// line (--num_serve_frontends); those would not run this, so the flag is
+// refused in a profile, and a copy started anyway would be given a program
+// path that cannot exist — /dev/null is no directory — and fail rather than
+// serve without the key. Click names itself by the path's last element, so
+// trtllm-serve's messages still say trtllm-serve.
+const trtllmLauncher = `import hmac, os, sys, tempfile
+key = os.environ.pop("` + trtllmKeyEnv + `", "")
+if key:
+    import fastapi
+    want = ("Bearer " + key).encode()
+    denied = b'{"error":{"message":"a valid API key is required","type":"invalid_request_error","code":"invalid_api_key"}}'
+    class RequireKey:
+        def __init__(self, app):
+            self.app = app
+        async def __call__(self, scope, receive, send):
+            if scope["type"] in ("http", "websocket") and scope.get("path") != "/health":
+                got = b""
+                for name, value in scope.get("headers") or ():
+                    if name == b"authorization":
+                        got = value
+                if not hmac.compare_digest(got, want):
+                    if scope["type"] == "websocket":
+                        await send({"type": "websocket.close", "code": 1008})
+                        return
+                    await send({"type": "http.response.start", "status": 401,
+                                "headers": [(b"content-type", b"application/json")]})
+                    await send({"type": "http.response.body", "body": denied})
+                    return
+            await self.app(scope, receive, send)
+    plain_init = fastapi.FastAPI.__init__
+    def init_with_key(self, *a, **kw):
+        plain_init(self, *a, **kw)
+        self.add_middleware(RequireKey)
+    fastapi.FastAPI.__init__ = init_with_key
+args = sys.argv[1:]
+if "` + trtllmOptionsPlaceholder + `" in args:
+    options = tempfile.TemporaryFile()
+    options.write(b"return_perf_metrics: true\nenable_iter_perf_stats: true\n")
+    options.flush()
+    options.seek(0)
+    args[args.index("` + trtllmOptionsPlaceholder + `")] = "/dev/fd/%d" % options.fileno()
+sys.argv = ["/dev/null/trtllm-serve"] + args
+from tensorrt_llm.commands.serve import main
+main()
+`

internal/agent/engines/trtllm_test.go

@@ -0,0 +1,316 @@
+package engines
+
+import (
+	"encoding/json"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"slices"
+	"strings"
+	"testing"
+)
+
+func trtllmSpec() ShardSpec {
+	s := singleNodeSpec()
+	s.Profile.Engine = "trtllm"
+	s.Profile.ServedModelName = "llama-3.1-70b"
+	return s
+}
+
+func TestTRTLLMRunsTrtllmServeWithTheFlagsItDocuments(t *testing.T) {
+	s := trtllmSpec()
+	s.BindAddr = "10.0.0.147"
+	s.Profile.Args = []string{"--max_batch_size", "64"}
+	cmd := buildOne(t, &TRTLLM{cfg: TRTLLMConfig{Python: "/opt/trtllm/bin/python"}}, s)
+
+	if cmd.Path != "/opt/trtllm/bin/python" {
+		t.Errorf("Path=%q, expected the configured interpreter", cmd.Path)
+	}
+	if cmd.Args[0] != "-c" || !strings.Contains(cmd.Args[1], "from tensorrt_llm.commands.serve import main") {
+		t.Fatalf("not started through the launcher: %v", cmd.Args[:2])
+	}
+	rest := cmd.Args[2:]
+	if rest[0] != "serve" || rest[1] != "/models/llama" {
+		t.Errorf("expected serve and the model first, got %v", rest[:2])
+	}
+	for flag, want := range map[string]string{
+		"--host": "10.0.0.147", "--port": "20000", "--tp_size": "4",
+		"--served_model_name":     "llama-3.1-70b",
+		"--extra_llm_api_options": trtllmOptionsPlaceholder,
+	} {
+		if got := argValue(rest, flag); got != want {
+			t.Errorf("%s=%q, want %q (args %v)", flag, got, want, rest)
+		}
+	}
+	// One pipeline stage is the default, and saying so would only be one
+	// more flag for a version to rename.
+	if slices.Contains(rest, "--pp_size") {
+		t.Errorf("--pp_size given for a single stage: %v", rest)
+	}
+	// The profile's own, last, so a tuning flag is the operator's to set.
+	if got := rest[len(rest)-2:]; !slices.Equal(got, []string{"--max_batch_size", "64"}) {
+		t.Errorf("profile args are not last: %v", rest)
+	}
+
+	s.Profile.TP, s.Profile.PP = 2, 2
+	if got := argValue(buildOne(t, &TRTLLM{}, s).Args, "--pp_size"); got != "2" {
+		t.Errorf("--pp_size=%q for two stages", got)
+	}
+	if got := buildOne(t, &TRTLLM{}, s).Path; got != "python3" {
+		t.Errorf("unconfigured, the interpreter is %q", got)
+	}
+}
+
+func TestTRTLLMsKeyIsNotOnItsCommandLine(t *testing.T) {
+	s := trtllmSpec()
+	s.APIKey = "k1"
+	cmd := buildOne(t, &TRTLLM{}, s)
+	for _, a := range cmd.Args {
+		if strings.Contains(a, "k1") && a != cmd.Args[1] {
+			t.Errorf("the key is in the arguments: %v", cmd.Args)
+		}
+	}
+	if envMap(cmd.Env)[trtllmKeyEnv] != "k1" {
+		t.Error("the key is not in the environment")
+	}
+}
+
+func TestTRTLLMDoesNotReportUsageToNVIDIA(t *testing.T) {
+	s := trtllmSpec()
+	s.Profile.Env = map[string]string{"TRTLLM_NO_USAGE_STATS": "0", "TRTLLM_ENABLE_PDL": "1"}
+	env := envMap(buildOne(t, &TRTLLM{}, s).Env)
+	if env["TRTLLM_NO_USAGE_STATS"] != "1" || env["DO_NOT_TRACK"] != "1" {
+		t.Errorf("usage reporting is not off: %q %q", env["TRTLLM_NO_USAGE_STATS"], env["DO_NOT_TRACK"])
+	}
+	// Tuning still reaches it.
+	if env["TRTLLM_ENABLE_PDL"] != "1" {
+		t.Error("a profile's TensorRT-LLM tuning was dropped")
+	}
+}
+
+func TestTRTLLMIsReadFromItsPrometheusEndpoint(t *testing.T) {
+	// /metrics on trtllm-serve is JSON, and each read drains what it returns.
+	if got := (&TRTLLM{}).MetricsPath(); got != "/prometheus/metrics" {
+		t.Errorf("MetricsPath=%q", got)
+	}
+	if !(&TRTLLM{}).ServesHTTP(trtllmSpec()) {
+		t.Error("the one rank of a replica serves its API")
+	}
+}
+
+func TestTRTLLMRunsAReplicaOnOneNode(t *testing.T) {
+	p := trtllmSpec().Profile
+	p.Nodes, p.GPUsPerNode, p.TP = 2, 4, 8
+	err := (&TRTLLM{}).Validate(p, nil)
+	if err == nil || !strings.Contains(err.Error(), "one node") {
+		t.Errorf("a two-node profile was accepted: %v", err)
+	}
+	s := multiNodeSpec(0)
+	s.Profile.Engine = "trtllm"
+	if _, err := (&TRTLLM{}).Commands(s); err == nil {
+		t.Error("a command was built for a shard of a two-node replica")
+	}
+}
+
+func TestTRTLLMNeedsAmpereOrNewer(t *testing.T) {
+	p := trtllmSpec().Profile
+	p.TP = 2
+	v100 := []GPUInfo{{Index: 0, Name: "Tesla V100", ComputeCapability: "7.0"}, {Index: 1, Name: "Tesla V100", ComputeCapability: "7.0"}}
+	if err := (&TRTLLM{}).Validate(p, v100); err == nil {
+		t.Error("a V100 was accepted")
+	}
+	h100 := []GPUInfo{{Index: 0, Name: "H100", ComputeCapability: "9.0"}, {Index: 1, Name: "H100", ComputeCapability: "9.0"}}
+	if err := (&TRTLLM{}).Validate(p, h100); err != nil {
+		t.Errorf("two H100s were refused: %v", err)
+	}
+}
+
+func TestTRTLLMProfilesMayNotOpenWhatTheAgentCloses(t *testing.T) {
+	for _, args := range [][]string{
+		{"--trust_remote_code"},
+		{"--num_serve_frontends", "4"},
+		{"--grpc"},
+		{"--config", "/etc/shadow"},
+		{"--extra_llm_api_options=/tmp/x.yaml"},
+		{"--served_model_name", "other"},
+		{"--middleware", "evil.mw"},
+		{"--tp_size", "8"},
+	} {
+		if err := UnsafeArgs("trtllm", args); err == nil {
+			t.Errorf("%v was allowed", args)
+		}
+	}
+	if err := UnsafeArgs("trtllm", []string{"--max_batch_size", "64", "--set", "kv_cache_config.enable_block_reuse=false",
+		"--free_gpu_memory_fraction", "0.85"}); err != nil {
+		t.Errorf("tuning was refused: %v", err)
+	}
+}
+
+func TestTRTLLMIsOfferedOnlyWhenItsPackageIsThere(t *testing.T) {
+	there := script(t, "python3", `echo "1.3.0rc29"`)
+	r := NewRegistry(Config{})
+	r.engines = map[string]Engine{"trtllm": &TRTLLM{cfg: TRTLLMConfig{Python: there}}}
+	if got := r.ProbeConfigured(t.Context()); got["trtllm"] != "1.3.0rc29" {
+		t.Errorf("expected the version, got %v", got)
+	}
+
+	// An interpreter without the package, which every machine has.
+	absent := script(t, "python3", "exit 1")
+	r.engines = map[string]Engine{"trtllm": &TRTLLM{cfg: TRTLLMConfig{Python: absent}}}
+	if got := r.ProbeConfigured(t.Context()); len(got) != 0 {
+		t.Errorf("reported without its package: %v", got)
+	}
+
+	// Not named, not offered: python3 on PATH is nobody's TensorRT-LLM.
+	r.engines = map[string]Engine{"trtllm": &TRTLLM{}}
+	if got := r.ProbeConfigured(t.Context()); len(got) != 0 {
+		t.Errorf("offered without being configured: %v", got)
+	}
+}
+
+// fakeTRTLLM is a Python path holding stand-ins for fastapi and
+// tensorrt_llm: enough of each for the launcher to do what it does in front
+// of the real server, and for the stand-in server to report what it saw.
+func fakeTRTLLM(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	files := map[string]string{
+		"fastapi/__init__.py": `
+class FastAPI:
+    def __init__(self, *a, **kw):
+        self.user_middleware = []
+    def add_middleware(self, cls, **kw):
+        self.user_middleware.append(cls)
+`,
+		"tensorrt_llm/__init__.py":          "",
+		"tensorrt_llm/commands/__init__.py": "",
+		"tensorrt_llm/commands/serve.py": `
+import asyncio, json, os, sys
+import fastapi
+
+def main():
+    args = sys.argv[1:]
+    with open(args[args.index("--extra_llm_api_options") + 1]) as f:
+        options = f.read()
+    app = fastapi.FastAPI()
+
+    async def server(scope, receive, send):
+        await send({"type": "http.response.start", "status": 200, "headers": []})
+        await send({"type": "http.response.body", "body": b"ok"})
+
+    handler = server
+    for mw in reversed(app.user_middleware):
+        handler = mw(handler)
+
+    async def ask(path, auth=None):
+        headers = [(b"authorization", auth.encode())] if auth else []
+        sent = []
+        async def send(msg):
+            sent.append(msg)
+        async def receive():
+            return {"type": "http.request"}
+        await handler({"type": "http", "path": path, "headers": headers}, receive, send)
+        return sent[0]["status"]
+
+    async def run():
+        return {
+            "health": await ask("/health"),
+            "anonymous": await ask("/v1/chat/completions"),
+            "wrong": await ask("/v1/models", "Bearer nope"),
+            "keyed": await ask("/prometheus/metrics", "Bearer k1"),
+        }
+
+    out = asyncio.run(run())
+    out.update(options=options, argv0=sys.argv[0], args=args,
+               key_left=os.environ.get("LLMGW_ENGINE_KEY"))
+    print(json.dumps(out))
+`,
+	}
+	for name, body := range files {
+		p := filepath.Join(dir, name)
+		if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(p, []byte(body), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return dir
+}
+
+type launched struct {
+	Health, Anonymous, Wrong, Keyed int
+	Options, Argv0                  string
+	Args                            []string
+	KeyLeft                         *string `json:"key_left"`
+}
+
+func launch(t *testing.T, s ShardSpec) launched {
+	t.Helper()
+	python, err := exec.LookPath("python3")
+	if err != nil {
+		t.Skip("no python3 here to run the launcher with")
+	}
+	cmd := buildOne(t, &TRTLLM{cfg: TRTLLMConfig{Python: python}}, s)
+	c := exec.Command(cmd.Path, cmd.Args...) //nolint:gosec // the command under test
+	c.Env = append(cmd.Env, "PYTHONPATH="+fakeTRTLLM(t))
+	out, err := c.Output()
+	if err != nil {
+		var stderr string
+		if ee, ok := err.(*exec.ExitError); ok {
+			stderr = string(ee.Stderr)
+		}
+		t.Fatalf("the launcher failed: %v\n%s", err, stderr)
+	}
+	var got launched
+	if err := json.Unmarshal(out, &got); err != nil {
+		t.Fatalf("%v: %s", err, out)
+	}
+	return got
+}
+
+func TestTheTRTLLMLauncherDemandsTheKey(t *testing.T) {
+	s := trtllmSpec()
+	s.APIKey = "k1"
+	got := launch(t, s)
+
+	if got.Anonymous != 401 || got.Wrong != 401 {
+		t.Errorf("served without the key: anonymous %d, wrong key %d", got.Anonymous, got.Wrong)
+	}
+	if got.Keyed != 200 {
+		t.Errorf("refused the key: %d", got.Keyed)
+	}
+	// Up or down is all /health says, and it is asked without one.
+	if got.Health != 200 {
+		t.Errorf("/health answered %d", got.Health)
+	}
+	// Taken out of the environment, so nothing the server starts holds it.
+	if got.KeyLeft != nil {
+		t.Errorf("the key was left in the environment: %q", *got.KeyLeft)
+	}
+	// A copy of this command line, as trtllm-serve's extra front ends are,
+	// names no program that exists and so cannot serve without the key.
+	if _, err := os.Stat(got.Argv0); err == nil || filepath.Base(got.Argv0) != "trtllm-serve" {
+		t.Errorf("argv[0] is %q", got.Argv0)
+	}
+}
+
+func TestTheTRTLLMLauncherTurnsOnTheMetricsTheRouterReads(t *testing.T) {
+	got := launch(t, trtllmSpec())
+	for _, want := range []string{"return_perf_metrics: true", "enable_iter_perf_stats: true"} {
+		if !strings.Contains(got.Options, want) {
+			t.Errorf("the options file lacks %q: %q", want, got.Options)
+		}
+	}
+	path := argValue(got.Args, "--extra_llm_api_options")
+	if !strings.HasPrefix(path, "/dev/fd/") {
+		t.Errorf("the options were not passed by descriptor: %q", path)
+	}
+	if slices.Contains(got.Args, trtllmOptionsPlaceholder) {
+		t.Error("the placeholder reached trtllm-serve")
+	}
+	// Without a key there is nothing to demand.
+	if got.Anonymous != 200 {
+		t.Errorf("with no key set, a request was refused: %d", got.Anonymous)
+	}
+}

internal/agent/engines/unsafeenv.go

@@ -1,30 +1,174 @@
 package engines
 
-import "strings"
+import (
+	"fmt"
+	"strings"
+)
+
+// A model profile's env and args are the operator's escape hatch for tuning
+// an engine, and they reach a process the agent starts as root on every node
+// the model is placed on. Some of what an engine accepts is not tuning but a
+// way to run other code, or to read or write files, in that process: a
+// loader preload, an NCCL network plugin, a CUDA injection library, vLLM's
+// --trust-remote-code, llama.cpp's --log-file pointed at /etc/cron.d. Taken
+// from a model definition, which the admin API or a config file supplies,
+// they would turn "add a model" into "run this as root on every node".
+//
+// So env is an allowlist — the families of variables engines are tuned with
+// — less any whose name says it names a path, a plugin or a library, and args
+// are checked against what each engine takes that reads, writes or loads.
+// Both are refused where a model is defined and again where an engine starts.
+
+// envFamilies are the prefixes of variables engines are tuned with.
+var envFamilies = []string{
+	"CUDA_", "NCCL_", "NVIDIA_", "NVTE_", "GLOO_", "UCX_", "TORCH_", "PYTORCH_",
+	"VLLM_", "SGLANG_", "GGML_", "LLAMA_", "OMP_", "MKL_", "OPENBLAS_", "KMP_",
+	"HF_", "TRANSFORMERS_", "TOKENIZERS_", "TRITON_", "FLASHINFER_",
+	"TRTLLM_", "TLLM_",
+}
+
+// envExact are single variables that are tuning too.
+var envExact = map[string]bool{
+	"PYTHONUNBUFFERED": true, "PYTHONHASHSEED": true, "TZ": true,
+}
+
+// envNever are names in an allowed family that load code or move where the
+// engine reads and writes.
+var envNever = []string{
+	"PLUGIN", "INJECTION", "PRELOAD", "LIBRARY", "_LIB",
+	"_PATH", "_DIR", "_HOME", "_FILE", "_ROOT", "_CACHE", "_CONFIG",
+	"_ADDRESS", "_ENDPOINT", "_TOKEN", "_URL",
+}
 
 // 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"
+	k := strings.ToUpper(strings.TrimSpace(key))
+	if k == "" {
+		return true, "it has no name"
+	}
+	allowed := envExact[k]
+	for _, f := range envFamilies {
+		if strings.HasPrefix(k, f) {
+			allowed = true
+			break
+		}
+	}
+	if !allowed {
+		return true, "only the variables engines are tuned with are allowed (" +
+			strings.Join(envFamilies, "*, ") + "*)"
+	}
+	for _, n := range envNever {
+		if strings.Contains(k, n) && !envExact[k] {
+			return true, "it names a path, a plugin, a library or an address, which is a way to make the engine " +
+				"read, write or load something other than its model"
+		}
+	}
+	// llama.cpp reads every flag from LLAMA_ARG_<FLAG> too.
+	if rest, ok := strings.CutPrefix(k, "LLAMA_ARG_"); ok {
+		flag := "--" + strings.ToLower(strings.ReplaceAll(rest, "_", "-"))
+		if why := unsafeFlag("llamacpp", flag, ""); why != "" {
+			return true, "it is " + flag + ", which " + why
+		}
 	}
 	return false, ""
 }
+
+// flagsNever are flags no profile may give, by engine; "" is every engine.
+// Each reads or writes files the agent did not choose, loads code, or moves
+// what the agent itself sets: where the engine listens and the key it
+// demands.
+var flagsNever = map[string]map[string]string{
+	"": {
+		"--host": "is set by the agent", "--port": "is set by the agent",
+		"--api-key": "is set by the agent", "--api-key-file": "is set by the agent",
+		"--model": "is the model's source, set by the agent", "-m": "is the model's source, set by the agent",
+		"--ssl-keyfile": "reads a file", "--ssl-certfile": "reads a file",
+		"--ssl-key-file": "reads a file", "--ssl-cert-file": "reads a file",
+		"--trust-remote-code": "runs Python the model repository ships",
+	},
+	"llamacpp": {
+		"--log-file": "writes a file", "--slot-save-path": "writes files",
+		"--path": "serves a directory's files over HTTP", "--rpc": "sends the model's work to other machines",
+		"--chat-template-file": "reads a file", "--system-prompt-file": "reads a file",
+		"--grammar-file": "reads a file", "--json-schema-file": "reads a file",
+		"--lora":           "loads a file; adapters are set in the model's adapters",
+		"--lora-scaled":    "loads a file; adapters are set in the model's adapters",
+		"--control-vector": "loads a file", "--control-vector-scaled": "loads a file",
+		"--mmproj":    "loads a file; the projector is fetched with the model",
+		"--model-url": "downloads a model", "-mu": "downloads a model",
+		"--hf-repo": "downloads a model", "-hf": "downloads a model", "--hf-file": "downloads a model",
+		"--hf-token": "is a credential", "--alias": "is set by the agent",
+		"--model-draft": "loads a file", "-md": "loads a file",
+		"--prompt-cache": "writes a file", "--logdir": "writes files",
+	},
+	"vllm": {
+		"--download-dir": "writes files", "--tokenizer": "reads another repository or path",
+		"--chat-template": "reads a file", "--allowed-local-media-path": "serves local files to requests",
+		"--lora-modules":       "loads files; adapters are set in the model's adapters",
+		"--tool-parser-plugin": "runs a Python file", "--middleware": "imports Python",
+		"--worker-extension-cls": "imports Python", "--worker-cls": "imports Python",
+		"--load-format":          "changes how weights are loaded, some ways running code",
+		"--otlp-traces-endpoint": "sends request traces elsewhere",
+		"--served-model-name":    "is set by the agent",
+		"--enable-log-requests":  "logs prompts",
+	},
+	"sglang": {
+		"--tokenizer-path": "reads another repository or path", "--chat-template": "reads a file",
+		"--file-storage-path": "writes files", "--log-requests": "logs prompts",
+		"--model-path": "is the model's source, set by the agent", "--served-model-name": "is set by the agent",
+		"--lora-paths": "loads files", "--download-dir": "writes files",
+	},
+	// trtllm-serve spells its flags with underscores, so the shared list's
+	// hyphenated names do not reach them.
+	"trtllm": {
+		"--trust_remote_code":     "runs Python the model repository ships",
+		"--served_model_name":     "is set by the agent",
+		"--config":                "reads a file; the agent writes the options file itself",
+		"--extra_llm_api_options": "reads a file; the agent writes the options file itself",
+		"--tokenizer":             "reads another repository or path",
+		"--custom_tokenizer":      "imports Python", "--post_processor_hook": "imports Python",
+		"--custom_module_dirs": "imports Python", "--middleware": "imports Python",
+		"--chat_template":               "reads a file",
+		"--metadata_server_config_file": "reads a file",
+		"--visual_gen_args":             "reads a file",
+		"--report_addr":                 "writes a file",
+		"--otlp_traces_endpoint":        "sends request traces elsewhere",
+		"--disagg_cluster_uri":          "joins the server to another cluster",
+		"--server_role":                 "makes the server part of another cluster",
+		"--allow_request_chat_template": "lets a request supply the chat template",
+		"--grpc":                        "serves without the key the agent sets",
+		"--num_serve_frontends":         "starts front ends that do not demand the key the agent sets",
+		"--telemetry":                   "sends usage to NVIDIA",
+		"--tensor_parallel_size":        "is set by the agent from tp",
+		"--tp_size":                     "is set by the agent from tp",
+		"--pipeline_parallel_size":      "is set by the agent from pp",
+		"--pp_size":                     "is set by the agent from pp",
+	},
+}
+
+// unsafeFlag is why an engine may not be given a flag, or "".
+func unsafeFlag(engine, flag, _ string) string {
+	name, _, _ := strings.Cut(flag, "=")
+	for _, set := range []string{"", engine} {
+		if why, ok := flagsNever[set][name]; ok && why != "" {
+			return why
+		}
+	}
+	return ""
+}
+
+// UnsafeArgs refuses the first of a profile's arguments an engine may not be
+// given, saying why.
+func UnsafeArgs(engine string, args []string) error {
+	for _, a := range args {
+		if !strings.HasPrefix(a, "-") {
+			continue // a value
+		}
+		if why := unsafeFlag(engine, a, ""); why != "" {
+			name, _, _ := strings.Cut(a, "=")
+			return fmt.Errorf("argument %s is not allowed: it %s", name, why)
+		}
+	}
+	return nil
+}

internal/agent/engines/unsafeenv_test.go

@@ -0,0 +1,64 @@
+package engines
+
+import "testing"
+
+func TestTuningVariablesAreAllowedAndWaysToRunCodeAreNot(t *testing.T) {
+	for _, k := range []string{
+		"CUDA_VISIBLE_DEVICES", "CUDA_MODULE_LOADING", "NCCL_IB_HCA", "NCCL_DEBUG", "NCCL_NET",
+		"VLLM_ATTENTION_BACKEND", "PYTORCH_CUDA_ALLOC_CONF", "OMP_NUM_THREADS", "HF_HUB_OFFLINE",
+		"GGML_VK_VISIBLE_DEVICES", "TOKENIZERS_PARALLELISM", "PYTHONUNBUFFERED", "LLAMA_ARG_CTX_SIZE",
+	} {
+		if bad, why := UnsafeEnv(k); bad {
+			t.Errorf("%s refused: %s", k, why)
+		}
+	}
+	for _, k := range []string{
+		"LD_PRELOAD", "PATH", "PYTHONPATH", "PYTHONSTARTUP", "BASH_ENV",
+		// What the denylist missed: each loads a library or moves where the
+		// engine reads and writes.
+		"NCCL_NET_PLUGIN", "NCCL_TUNER_PLUGIN", "NCCL_PROFILER_PLUGIN", "CUDA_INJECTION64_PATH",
+		"NVTX_INJECTION64_PATH", "TRITON_CACHE_DIR", "HF_HOME", "HF_TOKEN", "NCCL_DEBUG_FILE",
+		"VLLM_PLUGINS", "UCX_MODULE_DIR", "TORCH_EXTENSIONS_DIR",
+		// llama.cpp's flags as variables.
+		"LLAMA_ARG_LOG_FILE", "LLAMA_ARG_HOST", "LLAMA_ARG_SLOT_SAVE_PATH",
+		// Anything outside the families.
+		"SOMETHING_ELSE", "",
+	} {
+		if bad, _ := UnsafeEnv(k); !bad {
+			t.Errorf("%s allowed", k)
+		}
+	}
+}
+
+func TestArgumentsThatReadWriteOrLoadAreRefused(t *testing.T) {
+	ok := map[string][]string{
+		"llamacpp": {"--ctx-size", "16384", "--embedding", "--parallel", "4", "--jinja", "--n-gpu-layers=999"},
+		"vllm":     {"--max-model-len", "8192", "--gpu-memory-utilization", "0.9", "--enable-auto-tool-choice"},
+		"sglang":   {"--mem-fraction-static", "0.8", "--tool-call-parser", "qwen25"},
+	}
+	for eng, args := range ok {
+		if err := UnsafeArgs(eng, args); err != nil {
+			t.Errorf("%s %v: %v", eng, args, err)
+		}
+	}
+	for _, c := range []struct {
+		eng  string
+		args []string
+	}{
+		{"vllm", []string{"--trust-remote-code"}},
+		{"sglang", []string{"--trust-remote-code"}},
+		{"vllm", []string{"--tool-parser-plugin", "/tmp/x.py"}},
+		{"vllm", []string{"--middleware=evil.mod"}},
+		{"vllm", []string{"--allowed-local-media-path", "/"}},
+		{"llamacpp", []string{"--log-file", "/etc/cron.d/x"}},
+		{"llamacpp", []string{"--slot-save-path=/root"}},
+		{"llamacpp", []string{"--path", "/"}},
+		{"llamacpp", []string{"--system-prompt-file", "/etc/shadow"}},
+		{"llamacpp", []string{"--host", "0.0.0.0"}},
+		{"vllm", []string{"--api-key", "x"}},
+	} {
+		if err := UnsafeArgs(c.eng, c.args); err == nil {
+			t.Errorf("%s %v allowed", c.eng, c.args)
+		}
+	}
+}

internal/agent/engines/vllm.go

@@ -2,8 +2,11 @@ package engines
 
 import (
 	"fmt"
+	"maps"
 	"strconv"
 	"sync/atomic"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/kvevents"
 )
 
 // VLLMConfig locates the vLLM installation and picks how it is launched.
@@ -106,7 +109,7 @@ func (v *VLLM) serverCommand(s ShardSpec) (Command, error) {
 	p := s.Profile
 
 	args := []string{"serve", p.ModelPath,
-		"--host", "0.0.0.0",
+		"--host", s.Host(),
 		"--port", strconv.Itoa(s.HTTPPort),
 		"--tensor-parallel-size", strconv.Itoa(p.TP),
 	}
@@ -147,6 +150,28 @@ func (v *VLLM) serverCommand(s ShardSpec) (Command, error) {
 		}
 	}
 
+	// Adapters loaded at start are registered under their names, and a
+	// request names one as its model. Adapters loaded on demand start
+	// unregistered: the router loads each when a request first wants it
+	// here, by the link the agent made (RuntimeLoRADir). --max-loras is
+	// vLLM's default of one at start — raise it in the profile's arguments
+	// to mix more adapters in a batch — and the cap on demand, which
+	// WithRuntimeLoRA put in the arguments.
+	if len(p.Adapters) > 0 {
+		args = append(args, "--enable-lora")
+		if !p.RuntimeLoRA() {
+			args = append(args, loraModules(p.Adapters)...)
+		}
+	}
+
+	// The KV cache events, for the router's precise index: published to the
+	// agent on loopback, hashed the way the router hashes. Only the leader
+	// has a scheduler to publish from.
+	if p.KVEvents && s.KVEventsPort > 0 && s.Leader() {
+		args = append(args, kvevents.VLLMArgs(fmt.Sprintf("tcp://127.0.0.1:%d", s.KVEventsPort))...)
+		maps.Copy(env, kvevents.VLLMEnv())
+	}
+
 	// Profile arguments last, so an operator can override anything above.
 	args = append(args, p.Args...)
 

internal/agent/failover_test.go

@@ -6,6 +6,7 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"strings"
+	"sync/atomic"
 	"testing"
 	"time"
 
@@ -105,3 +106,49 @@ func TestALeaderStillAcceptsWithNoLeadershipConfigured(t *testing.T) {
 	}
 	t.Fatal("a service with no leadership configured refused an agent")
 }
+
+// flipping is a leader that can stop leading partway through a test.
+type flipping struct{ leading atomic.Bool }
+
+func (f *flipping) IsLeader() bool { return f.leading.Load() }
+
+func TestAnAgentLeavesAControlPlaneThatStopsLeading(t *testing.T) {
+	// Leadership lost while the process lives on: the store was slow and the
+	// lease lapsed, or another control plane took it. Agents that stayed on
+	// the old leader would leave the new one with no nodes, so the old one
+	// has to let them go rather than wait for them to leave.
+	was := &flipping{}
+	was.leading.Store(true)
+	wasInv, wasAddr := startPlain(t, was)
+	nowInv, nowAddr := startPlain(t, standby(false))
+
+	ag := runAgent(t, Config{
+		NodeID: "n1", MgmtAddr: "127.0.0.1",
+		Servers: []string{wasAddr, nowAddr},
+	})
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+	go ag.Run(ctx)
+
+	waitFor(t, 5*time.Second, "the agent never reached the first leader", func() bool {
+		_, ok := wasInv.Get("n1")
+		return ok
+	})
+	was.leading.Store(false)
+	waitFor(t, 8*time.Second, "the agent stayed on a control plane that stopped leading", func() bool {
+		_, ok := nowInv.Get("n1")
+		return ok
+	})
+}
+
+func waitFor(t *testing.T, d time.Duration, msg string, ok func() bool) {
+	t.Helper()
+	deadline := time.Now().Add(d)
+	for time.Now().Before(deadline) {
+		if ok() {
+			return
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+	t.Fatal(msg)
+}

internal/agent/firewall.go

@@ -0,0 +1,89 @@
+package agent
+
+import (
+	"context"
+	"net"
+	"net/netip"
+	"net/url"
+	"strings"
+	"time"
+
+	llmgwv1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/firewall"
+)
+
+// applyFirewall keeps llmgw's firewall on this node as the cluster's
+// settings say: the engines' ports and the node exporter's for the networks
+// the node reaches its control planes on, and those named, or no table at
+// all. Off the receive loop, one at a time.
+func (a *Agent) applyFirewall(m *llmgwv1.Firewall) {
+	a.fwMu.Lock()
+	defer a.fwMu.Unlock()
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+	r := a.fwRunner
+	if r == nil {
+		r = firewall.Local{}
+	}
+	if !m.GetEnabled() {
+		had, err := firewall.Disable(ctx, r)
+		switch {
+		case err != nil:
+			a.log.Warn("could not take llmgw's firewall off this node", "err", err)
+		case had:
+			a.log.Info("llmgw's firewall is off on this node, as the cluster's settings say")
+		}
+		return
+	}
+	a.mu.Lock()
+	servers := append([]string(nil), a.serverList...)
+	a.mu.Unlock()
+	nets, err := firewall.Networks(ctx, r, controlPlaneIPs(ctx, servers))
+	if err != nil {
+		a.log.Warn("could not tell which networks reach the control planes; the firewall is left as it is", "err", err)
+		return
+	}
+	for _, n := range m.GetNetworks() {
+		if p, err := netip.ParsePrefix(n); err == nil {
+			nets = append(nets, p)
+		} else if ad, err := netip.ParseAddr(n); err == nil {
+			nets = append(nets, netip.PrefixFrom(ad, ad.BitLen()))
+		}
+	}
+	from, to := int(m.GetEnginePortsFrom()), int(m.GetEnginePortsTo())
+	ports := []firewall.Port{firewall.NodeExporter}
+	if from > 0 && to >= from {
+		ports = append(ports, firewall.Engines(from, to))
+	}
+	changed, err := firewall.Install(ctx, r, firewall.Spec{Ports: ports, Allow: nets})
+	switch {
+	case err != nil:
+		a.log.Warn("could not put llmgw's firewall on this node", "err", err)
+	case changed:
+		a.log.Info("llmgw's firewall is on this node", "networks", len(nets))
+	}
+}
+
+// controlPlaneIPs are the addresses of the control planes an agent dials.
+func controlPlaneIPs(ctx context.Context, servers []string) []string {
+	var out []string
+	for _, s := range servers {
+		host := s
+		if u, err := url.Parse(s); err == nil && u.Host != "" {
+			host = u.Hostname()
+		}
+		host = strings.Trim(host, "[]")
+		if a, err := netip.ParseAddr(host); err == nil {
+			out = append(out, a.String())
+			continue
+		}
+		ips, err := net.DefaultResolver.LookupNetIP(ctx, "ip", host)
+		if err != nil {
+			continue
+		}
+		for _, ip := range ips {
+			out = append(out, ip.Unmap().String())
+		}
+	}
+	return out
+}

internal/agent/firewall_test.go

@@ -0,0 +1,57 @@
+package agent
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"strings"
+	"testing"
+
+	llmgwv1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1"
+)
+
+// fakeShell answers the firewall package's scripts and records what was
+// installed or removed.
+type fakeShell struct {
+	present   bool
+	installed string
+	deleted   bool
+}
+
+func (f *fakeShell) Run(_ context.Context, script string, stdin []byte) ([]byte, error) {
+	switch {
+	case strings.HasPrefix(script, "ip -o route get 10.0.0.140"):
+		return []byte("10.0.0.140 dev eth0 src 10.0.0.141 uid 0\n2: eth0    inet 10.0.0.141/24 brd 10.0.0.255 scope global eth0\n"), nil
+	case strings.HasPrefix(script, "sudo -n /usr/sbin/nft list table"):
+		if f.present {
+			return nil, nil
+		}
+		return nil, errors.New("no table")
+	case strings.Contains(script, "nft delete table") && !strings.Contains(script, "cat > "):
+		f.deleted, f.present = true, false
+		return nil, nil
+	case strings.HasPrefix(script, "sudo cat "):
+		return nil, nil
+	default:
+		f.installed, f.present = string(stdin), true
+		return []byte("changed\n"), nil
+	}
+}
+
+func TestANodeKeepsOrDropsItsFirewallAsTheClusterSays(t *testing.T) {
+	sh := &fakeShell{}
+	a := &Agent{log: slog.New(slog.DiscardHandler), fwRunner: sh, serverList: []string{"https://10.0.0.140:7443"}}
+
+	a.applyFirewall(&llmgwv1.Firewall{Enabled: true, Networks: []string{"192.168.5.0/24", "10.9.9.9"},
+		EnginePortsFrom: 20000, EnginePortsTo: 20999})
+	for _, want := range []string{"10.0.0.0/24", "192.168.5.0/24", "10.9.9.9/32", "20000-20999", "9100"} {
+		if !strings.Contains(sh.installed, want) {
+			t.Errorf("the rules lack %s:\n%s", want, sh.installed)
+		}
+	}
+
+	a.applyFirewall(&llmgwv1.Firewall{Enabled: false})
+	if !sh.deleted {
+		t.Error("turned off, the table stayed")
+	}
+}

internal/agent/gpucheck.go

@@ -0,0 +1,224 @@
+package agent
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"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/agent/engines"
+)
+
+// gpuProcesses and processGroup are variables so tests can stand in for
+// nvidia-smi and /proc.
+var (
+	gpuProcesses = discovery.GPUProcesses
+	gpuMemory    = discovery.GPUMemoryByProcess
+	processGroup = pgidOf
+	// gpuCheckWait is how long a shard has, once it answers, to show up on
+	// its GPUs: the weights are on them by then, but nvidia-smi can lag.
+	gpuCheckWait = 15 * time.Second
+)
+
+// onItsGPUs checks that a shard placed on GPUs computes on them.
+//
+// For an engine that falls back to the CPU when its GPU backend does not load,
+// "it answers" is not "it is ready": llama.cpp built for CUDA but missing
+// cuBLAS comes up on the CPU, answers at a tenth of the speed, and the GPU it
+// was given sits idle and reserved. What it computes on is what nvidia-smi
+// lists it on, so a shard none of whose processes hold memory on one of its
+// GPUs is refused, with what the engine itself can see.
+func (a *Agent) onItsGPUs(ctx context.Context, eng engines.Engine, spec engines.ShardSpec, pid int) error {
+	fb, ok := eng.(engines.CPUFallback)
+	if !ok || !fb.FallsBackToCPU() || len(spec.GPUIndices) == 0 || pid <= 0 {
+		return nil
+	}
+	group := processGroup(pid)
+	deadline := time.Now().Add(gpuCheckWait)
+	var missing []int
+	for {
+		procs, err := gpuProcesses(ctx, a.cfg.Discovery.NvidiaSMI)
+		if err != nil || procs == nil {
+			// No nvidia-smi to ask is no evidence either way, and a node that
+			// was given GPUs has one; say so and let the shard serve.
+			a.log.Warn("could not check that a GPU shard runs on its GPUs", "shard", spec.ShardID, "err", err)
+			return nil
+		}
+		missing = missing[:0]
+		for _, i := range spec.GPUIndices {
+			if !holds(procs[i], pid, group) {
+				missing = append(missing, i)
+			}
+		}
+		if len(missing) == 0 {
+			return nil
+		}
+		if time.Now().After(deadline) {
+			break
+		}
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-time.After(time.Second):
+		}
+	}
+	seen := "it lists no GPU at all"
+	if devs, err := fb.Devices(ctx); err != nil {
+		seen = "listing its devices failed: " + err.Error()
+	} else if len(devs) > 0 {
+		seen = "it lists " + strings.Join(devs, "; ")
+	}
+	return fmt.Errorf("placed on GPU %s but computing on the CPU: the engine holds no memory there. "+
+		"Its GPU backend did not load (%s). Check the build with `ldd` on its libggml-cuda.so, "+
+		"or run `llmgw doctor` on this node", joinIndices(missing), seen)
+}
+
+// foreignGPUMemory is what each GPU holds for anything other than this
+// agent's shards, by index, and each GPU's memory in use. Nil when nvidia-smi
+// cannot be asked, which is no reading rather than an empty card.
+//
+// Everything allocated less what the shards' processes hold, rather than the
+// sum of the other processes: a process in another container's PID namespace
+// holds memory nvidia-smi lists under no PID this node can see, and it is
+// still not memory placement can hand out.
+func (a *Agent) foreignGPUMemory(ctx context.Context, shards []int) (foreign, used []int32) {
+	mem, err := gpuMemory(ctx, a.cfg.Discovery.NvidiaSMI)
+	if err != nil || mem == nil {
+		return nil, nil
+	}
+	groups := make([]int, len(shards))
+	for i, pid := range shards {
+		groups[i] = processGroup(pid)
+	}
+	ours := func(p int) bool {
+		for i, pid := range shards {
+			if holds([]int{p}, pid, groups[i]) {
+				return true
+			}
+		}
+		return false
+	}
+	for _, g := range mem {
+		f := g.UsedMB
+		for _, p := range g.Procs {
+			if ours(p.PID) {
+				f -= p.UsedMB
+			}
+		}
+		foreign = append(foreign, int32(max(f, 0)))
+		used = append(used, int32(g.UsedMB))
+	}
+	return foreign, used
+}
+
+// holds reports whether any of pids is the shard's process or in its group:
+// an engine that computes in a child process is still the shard.
+func holds(pids []int, pid, group int) bool {
+	for _, p := range pids {
+		if p == pid || (group > 0 && processGroup(p) == group) {
+			return true
+		}
+	}
+	return false
+}
+
+// pgidOf reads a process's group from /proc; zero when it cannot.
+func pgidOf(pid int) int {
+	b, err := os.ReadFile("/proc/" + strconv.Itoa(pid) + "/stat")
+	if err != nil {
+		return 0
+	}
+	// The command name, in parentheses, may hold spaces; the fields after its
+	// closing parenthesis are state, ppid, pgrp.
+	s := string(b)
+	i := strings.LastIndexByte(s, ')')
+	if i < 0 {
+		return 0
+	}
+	f := strings.Fields(s[i+1:])
+	if len(f) < 3 {
+		return 0
+	}
+	n, _ := strconv.Atoi(f[2])
+	return n
+}
+
+func joinIndices(is []int) string {
+	s := make([]string, len(is))
+	for k, i := range is {
+		s[k] = strconv.Itoa(i)
+	}
+	return strings.Join(s, ", ")
+}
+
+// engineCompute is where an engine said it put its model, from its output
+// so far — llama.cpp's, which says — and false for one that said nothing. A
+// shard given GPUs that its engine says it computes on the CPU is an error,
+// found this way even where nvidia-smi cannot be asked.
+func engineCompute(eng engines.Engine, gpus []int, lines []string) (engines.Compute, bool, error) {
+	if _, ok := eng.(engines.CPUFallback); !ok {
+		return engines.Compute{}, false, nil
+	}
+	read, ok := engines.ReadLlamaCompute(lines)
+	if !ok {
+		return engines.Compute{}, false, nil
+	}
+	if len(gpus) > 0 && read.OnTheCPU() {
+		why := "its GPU backend saw no device it could use"
+		if read.Total > 0 && !read.NoGPU {
+			why = fmt.Sprintf("it offloaded %d of %d layers", read.Offloaded, read.Total)
+		}
+		return read, true, fmt.Errorf("placed on GPU %v but computing on the CPU: %s, by llama.cpp's own account "+
+			"(llmgw ctl engine-check on this node says why)", gpus, why)
+	}
+	return read, true, nil
+}
+
+// computeToWire is a compute as it travels to the control plane.
+func computeToWire(c *engines.Compute) *llmgwv1.Compute {
+	if c == nil {
+		return nil
+	}
+	return &llmgwv1.Compute{Backend: c.Backend, Devices: c.Devices,
+		LayersOffloaded: int32(c.Offloaded), LayersTotal: int32(c.Total)} //nolint:gosec // layer counts
+}
+
+// gpuCompute is where a shard computes as nvidia-smi sees it: the CPU for a
+// shard given no GPU, else the GPUs whose memory its processes hold, and how
+// much. False when nvidia-smi cannot be asked. Engine-agnostic, and needing
+// no log line: llama.cpp says where its layers went only at -lv 4.
+func (a *Agent) gpuCompute(ctx context.Context, gpus []int, pid int) (engines.Compute, bool) {
+	if len(gpus) == 0 {
+		return engines.Compute{Backend: "CPU"}, true
+	}
+	mem, err := gpuMemory(ctx, a.cfg.Discovery.NvidiaSMI)
+	if err != nil || mem == nil || pid <= 0 {
+		return engines.Compute{}, false
+	}
+	group := processGroup(pid)
+	c := engines.Compute{Backend: "CUDA"}
+	for _, g := range mem {
+		if !slices.Contains(gpus, g.Index) {
+			continue
+		}
+		used := 0
+		for _, p := range g.Procs {
+			if holds([]int{p.PID}, pid, group) {
+				used += p.UsedMB
+			}
+		}
+		if used > 0 {
+			c.Devices = append(c.Devices, fmt.Sprintf("GPU %d: %.1f GB", g.Index, float64(used)/1024))
+		}
+	}
+	if len(c.Devices) == 0 {
+		// Placed on GPUs and holding none of their memory.
+		c.Backend = "CPU"
+	}
+	return c, true
+}

internal/agent/gpucheck_test.go

@@ -0,0 +1,176 @@
+package agent
+
+import (
+	"context"
+	"log/slog"
+	"slices"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/discovery"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/engines"
+)
+
+// fallbackEngine is an engine that comes up on the CPU when its GPU backend
+// does not load, and lists the devices it can see.
+type fallbackEngine struct {
+	engines.Engine
+	devices []string
+}
+
+func (fallbackEngine) FallsBackToCPU() bool { return true }
+func (f fallbackEngine) Devices(context.Context) ([]string, error) {
+	return f.devices, nil
+}
+
+func TestAGPUShardComputingOnTheCPUIsNotReady(t *testing.T) {
+	procs := map[int][]int{}
+	oldProcs, oldGroup, oldWait := gpuProcesses, processGroup, gpuCheckWait
+	gpuProcesses = func(context.Context, string) (map[int][]int, error) { return procs, nil }
+	processGroup = func(pid int) int {
+		if pid >= 500 && pid < 600 {
+			return 500 // the shard's group: 500 and its children
+		}
+		return pid
+	}
+	gpuCheckWait = 0
+	t.Cleanup(func() { gpuProcesses, processGroup, gpuCheckWait = oldProcs, oldGroup, oldWait })
+
+	a := &Agent{log: slog.Default()}
+	spec := engines.ShardSpec{ShardID: "s", GPUIndices: []int{0, 1}}
+	eng := fallbackEngine{}
+
+	// On no GPU at all: refused, saying what the engine sees.
+	err := a.onItsGPUs(context.Background(), eng, spec, 500)
+	if err == nil || !strings.Contains(err.Error(), "computing on the CPU") || !strings.Contains(err.Error(), "lists no GPU") {
+		t.Fatalf("a shard on no GPU was let through: %v", err)
+	}
+	// On one of its two: refused, naming the one it is missing.
+	procs[0] = []int{500}
+	if err := a.onItsGPUs(context.Background(), eng, spec, 500); err == nil || !strings.Contains(err.Error(), "GPU 1 ") {
+		t.Fatalf("a shard on half its GPUs: %v", err)
+	}
+	// Another process on GPU 1 is not the shard.
+	procs[1] = []int{900}
+	if err := a.onItsGPUs(context.Background(), eng, spec, 500); err == nil {
+		t.Fatal("another process's memory was taken for the shard's")
+	}
+	// A child of the shard holding GPU 1 is the shard.
+	procs[1] = []int{900, 512}
+	if err := a.onItsGPUs(context.Background(), eng, spec, 500); err != nil {
+		t.Fatalf("a shard on both its GPUs: %v", err)
+	}
+
+	// An engine that fails rather than falling back is not checked, nor is a
+	// shard with no GPUs.
+	procs = map[int][]int{}
+	if err := a.onItsGPUs(context.Background(), struct{ engines.Engine }{}, spec, 500); err != nil {
+		t.Errorf("checked an engine that does not fall back: %v", err)
+	}
+	if err := a.onItsGPUs(context.Background(), eng, engines.ShardSpec{}, 500); err != nil {
+		t.Errorf("checked a CPU shard: %v", err)
+	}
+}
+
+func TestTheCheckWaitsForTheShardToShowUpOnItsGPU(t *testing.T) {
+	calls := 0
+	oldProcs, oldWait := gpuProcesses, gpuCheckWait
+	gpuProcesses = func(context.Context, string) (map[int][]int, error) {
+		calls++
+		if calls < 2 {
+			return map[int][]int{}, nil
+		}
+		return map[int][]int{0: {77}}, nil
+	}
+	gpuCheckWait = 5 * time.Second
+	t.Cleanup(func() { gpuProcesses, gpuCheckWait = oldProcs, oldWait })
+
+	a := &Agent{log: slog.Default()}
+	if err := a.onItsGPUs(context.Background(), fallbackEngine{}, engines.ShardSpec{GPUIndices: []int{0}}, 77); err != nil {
+		t.Fatalf("nvidia-smi lagging by a second failed the shard: %v", err)
+	}
+}
+
+func TestForeignGPUMemoryLeavesOutTheAgentsOwnShards(t *testing.T) {
+	// cuda01: ComfyUI and one of our engines on the same card. Only ComfyUI's
+	// share — and whatever no listed process accounts for — is foreign.
+	oldMem, oldGroup := gpuMemory, processGroup
+	gpuMemory = func(context.Context, string) ([]discovery.GPUMemory, error) {
+		return []discovery.GPUMemory{
+			{UsedMB: 15000, Procs: []discovery.GPUProcess{{PID: 71315, UsedMB: 4932}, {PID: 512, UsedMB: 9500}}},
+			{UsedMB: 300},
+		}, nil
+	}
+	processGroup = func(pid int) int {
+		if pid >= 500 && pid < 600 {
+			return 500
+		}
+		return pid
+	}
+	t.Cleanup(func() { gpuMemory, processGroup = oldMem, oldGroup })
+
+	a := &Agent{log: slog.Default()}
+	foreign, used := a.foreignGPUMemory(context.Background(), []int{500})
+	if !slices.Equal(foreign, []int32{5500, 300}) || !slices.Equal(used, []int32{15000, 300}) {
+		t.Errorf("foreign %v, used %v; want [5500 300] and [15000 300]", foreign, used)
+	}
+
+	// No nvidia-smi to ask is no reading, not an empty card.
+	gpuMemory = func(context.Context, string) ([]discovery.GPUMemory, error) { return nil, nil }
+	if foreign, _ := a.foreignGPUMemory(context.Background(), nil); foreign != nil {
+		t.Errorf("no reading came back as %v", foreign)
+	}
+}
+
+func TestLlamaCppsOwnWordOnTheCPUIsEnoughToRefuse(t *testing.T) {
+	eng := fallbackEngine{}
+	// Without nvidia-smi to ask, the engine's own output says it.
+	c, said, err := engineCompute(eng, []int{0}, []string{
+		"warning: no usable GPU found, --gpu-layers option will be ignored",
+		"load_tensors: offloaded 0/49 layers to GPU"})
+	if err == nil || !said || !strings.Contains(err.Error(), "computing on the CPU") || c.Backend != "CPU" {
+		t.Fatalf("a GPU shard llama.cpp put on the CPU: %v %+v", err, c)
+	}
+	c, said, err = engineCompute(eng, []int{0}, []string{
+		"llama_model_load_from_file_impl: using device CUDA0 (Quadro RTX 6000) - 23800 MiB free",
+		"load_tensors: offloaded 49/49 layers to GPU"})
+	if err != nil || !said || c.Backend != "CUDA" || c.Offloaded != 49 || computeToWire(&c).GetLayersOffloaded() != 49 {
+		t.Errorf("on its GPU: %v %+v", err, c)
+	}
+	// A CPU shard is not refused for being on the CPU, and says so.
+	if c, _, err := engineCompute(eng, nil, []string{"load_tensors: offloaded 0/49 layers to GPU"}); err != nil || c.Backend != "CPU" {
+		t.Errorf("a CPU shard: %v %+v", err, c)
+	}
+	// An engine that said nothing says nothing.
+	if _, said, err := engineCompute(eng, []int{0}, []string{"listening"}); err != nil || said {
+		t.Errorf("nothing said: %v", err)
+	}
+}
+
+func TestNvidiaSMISaysWhereAShardComputes(t *testing.T) {
+	oldMem, oldGroup := gpuMemory, processGroup
+	t.Cleanup(func() { gpuMemory, processGroup = oldMem, oldGroup })
+	processGroup = func(pid int) int { return pid }
+	gpuMemory = func(context.Context, string) ([]discovery.GPUMemory, error) {
+		return []discovery.GPUMemory{
+			{Index: 0, UsedMB: 20000, Procs: []discovery.GPUProcess{{PID: 700, UsedMB: 2048}, {PID: 900, UsedMB: 17000}}},
+			{Index: 1, UsedMB: 0},
+		}, nil
+	}
+	a := &Agent{log: slog.Default()}
+	if c, ok := a.gpuCompute(context.Background(), []int{0}, 700); !ok || c.Backend != "CUDA" ||
+		len(c.Devices) != 1 || c.Devices[0] != "GPU 0: 2.0 GB" {
+		t.Errorf("on GPU 0: %+v %v", c, ok)
+	}
+	if c, ok := a.gpuCompute(context.Background(), []int{1}, 700); !ok || c.Backend != "CPU" {
+		t.Errorf("placed on GPU 1, holding none of it: %+v", c)
+	}
+	if c, ok := a.gpuCompute(context.Background(), nil, 700); !ok || c.Backend != "CPU" {
+		t.Errorf("a CPU shard: %+v", c)
+	}
+	gpuMemory = func(context.Context, string) ([]discovery.GPUMemory, error) { return nil, nil }
+	if _, ok := a.gpuCompute(context.Background(), []int{0}, 700); ok {
+		t.Error("no nvidia-smi read as an answer")
+	}
+}

internal/agent/kv.go

@@ -0,0 +1,86 @@
+package agent
+
+import (
+	"context"
+	"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/control/agentsvc"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/kvevents"
+)
+
+// kvFlushInterval is how often KV cache changes go up the stream. Often
+// enough that a prefix cached by one request is known before the next few
+// arrive; seldom enough that a busy engine's churn is sent as its net effect.
+const kvFlushInterval = 250 * time.Millisecond
+
+// listenKV starts receiving a shard's KV cache events, when its profile asks
+// for them and this rank publishes any, and records the port in the spec for
+// the engine's arguments. port is the one to reuse, or 0 for any.
+//
+// A failure is logged and the engine started without events: the router then
+// routes the replica by tier 1, which is what it did before, rather than the
+// replica not starting at all for want of an optimisation.
+func (a *Agent) listenKV(spec *engines.ShardSpec, port int) {
+	if !spec.Profile.KVEvents || spec.Profile.Engine != "vllm" || !spec.Leader() {
+		return
+	}
+	a.mu.Lock()
+	if sub, ok := a.kvSubs[spec.ShardID]; ok {
+		a.mu.Unlock()
+		// A repeated start command: the shard already has its listener.
+		spec.KVEventsPort = sub.Port()
+		return
+	}
+	a.mu.Unlock()
+
+	sub, err := kvevents.Listen(spec.ReplicaID, port, a.kv, a.log)
+	if err != nil {
+		a.log.Warn("cannot receive kv cache events; the router will route this replica without them",
+			"shard", spec.ShardID, "replica", spec.ReplicaID, "err", err)
+		return
+	}
+	a.mu.Lock()
+	a.kvSubs[spec.ShardID] = sub
+	a.mu.Unlock()
+	spec.KVEventsPort = sub.Port()
+}
+
+// stopKV stops a shard's listener and tells the control plane its replica
+// holds nothing any more.
+func (a *Agent) stopKV(shardID, replicaID string) {
+	a.mu.Lock()
+	sub, ok := a.kvSubs[shardID]
+	delete(a.kvSubs, shardID)
+	a.mu.Unlock()
+	if !ok {
+		return
+	}
+	sub.Close()
+	a.kv.Remove(replicaID)
+}
+
+// forwardKV sends KV cache changes up one session's stream until it ends,
+// beginning with a full copy of every replica: the control plane at the other
+// end may have just started, or just taken over, and know nothing.
+func (a *Agent) forwardKV(ctx context.Context, out chan<- *llmgwv1.AgentMessage) {
+	s := a.kv.Open()
+	defer s.Close()
+	t := time.NewTicker(kvFlushInterval)
+	defer t.Stop()
+	for {
+		for _, u := range s.Drain() {
+			select {
+			case out <- agentsvc.KVEventsMessage(u):
+			case <-ctx.Done():
+				return
+			}
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+		}
+	}
+}

internal/agent/kv_test.go

@@ -0,0 +1,103 @@
+package agent
+
+import (
+	"context"
+	"encoding/binary"
+	"fmt"
+	"log/slog"
+	"testing"
+	"time"
+
+	"github.com/go-zeromq/zmq4"
+	"github.com/vmihailenco/msgpack/v5"
+
+	llmgwv1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/engines"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/kvevents"
+)
+
+func kvAgent() *Agent {
+	return &Agent{log: slog.New(slog.DiscardHandler), kv: kvevents.NewMirror(),
+		kvSubs: map[string]*kvevents.Subscriber{}}
+}
+
+// TestAnEnginesEventsReachTheControlPlaneStream runs the agent's half end to
+// end: a listener for the shard, a publisher standing in for vLLM connecting
+// to the port the engine would be given, and the stream to the control plane
+// carrying the result.
+func TestAnEnginesEventsReachTheControlPlaneStream(t *testing.T) {
+	a := kvAgent()
+	spec := engines.ShardSpec{ReplicaID: "r1", ShardID: "r1-0", NNodes: 1,
+		Profile: engines.Profile{Engine: "vllm", KVEvents: true}}
+	a.listenKV(&spec, 0)
+	if spec.KVEventsPort == 0 {
+		t.Fatal("the shard should have been given a port to publish to")
+	}
+	defer a.stopKV(spec.ShardID, spec.ReplicaID)
+
+	pub := zmq4.NewPub(context.Background())
+	defer func() { _ = pub.Close() }()
+	if err := pub.Dial(fmt.Sprintf("tcp://127.0.0.1:%d", spec.KVEventsPort)); err != nil {
+		t.Fatal(err)
+	}
+	tokens := make([]int, 32)
+	for i := range tokens {
+		tokens[i] = 500 + i
+	}
+	hs := kvevents.BlockHashes(tokens, 16, 0)
+	payload, _ := msgpack.Marshal([]any{1.0, []any{map[string]any{
+		"type": "BlockStored", "block_hashes": []any{hs[0], hs[1]}, "parent_block_hash": nil,
+		"token_ids": tokens, "block_size": 16, "lora_id": nil, "medium": "GPU",
+	}}})
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	out := make(chan *llmgwv1.AgentMessage, 16)
+	go a.forwardKV(ctx, out)
+
+	deadline := time.After(5 * time.Second)
+	var seq uint64
+	for {
+		// Sent until it arrives: a subscription reaches the publisher after
+		// the connection, and what is published before it is dropped.
+		var s [8]byte
+		binary.BigEndian.PutUint64(s[:], seq)
+		seq++
+		_ = pub.Send(zmq4.NewMsgFrom([]byte("kv-events"), s[:], payload))
+		select {
+		case m := <-out:
+			kv := m.GetKvEvents()
+			if kv == nil || kv.GetReplicaId() != "r1" || kv.GetBlockSize() != 16 || len(kv.GetStored()) != 2 {
+				t.Fatalf("message %v", m)
+			}
+			return
+		case <-deadline:
+			t.Fatal("nothing reached the stream")
+		case <-time.After(50 * time.Millisecond):
+		}
+	}
+}
+
+func TestAShardWithoutKVEventsGetsNoListener(t *testing.T) {
+	a := kvAgent()
+	spec := engines.ShardSpec{ReplicaID: "r1", ShardID: "r1-0", NNodes: 1,
+		Profile: engines.Profile{Engine: "vllm"}}
+	a.listenKV(&spec, 0)
+	if spec.KVEventsPort != 0 || len(a.kvSubs) != 0 {
+		t.Fatal("kv_events is opt-in")
+	}
+}
+
+func TestARepeatedStartReusesTheShardsListener(t *testing.T) {
+	a := kvAgent()
+	spec := engines.ShardSpec{ReplicaID: "r1", ShardID: "r1-0", NNodes: 1,
+		Profile: engines.Profile{Engine: "vllm", KVEvents: true}}
+	a.listenKV(&spec, 0)
+	defer a.stopKV(spec.ShardID, spec.ReplicaID)
+	again := spec
+	again.KVEventsPort = 0
+	a.listenKV(&again, 0)
+	if again.KVEventsPort != spec.KVEventsPort || len(a.kvSubs) != 1 {
+		t.Fatal("a start command repeated must not open a second listener")
+	}
+}

internal/agent/mig_test.go

@@ -0,0 +1,40 @@
+package agent
+
+import (
+	"testing"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/discovery"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/engines"
+)
+
+func TestAShardPlacedOnAMIGInstanceIsLaunchedWithItsUUID(t *testing.T) {
+	// The control plane sends device 1001: card 0's instance 1, by the number
+	// placement gives it. Only this node knows the instance's UUID, which is
+	// the one thing CUDA will open it by.
+	a := &Agent{}
+	a.inv.GPUs = []discovery.GPU{
+		{Index: 1000, UUID: "MIG-aaa", MIG: &discovery.MIGDevice{ParentIndex: 0, Device: 0, Profile: "3g.40gb"}},
+		{Index: 1001, UUID: "MIG-bbb", MIG: &discovery.MIGDevice{ParentIndex: 0, Device: 1, Profile: "3g.40gb"}},
+		{Index: 1, UUID: "GPU-whole"},
+	}
+
+	spec := engines.ShardSpec{GPUIndices: []int{1001}}
+	a.localizeSpec(&spec)
+	if got := engines.NCCLEnv(spec)["CUDA_VISIBLE_DEVICES"]; got != "MIG-bbb" {
+		t.Errorf("CUDA_VISIBLE_DEVICES=%q, want MIG-bbb", got)
+	}
+
+	// A whole card is given by index, as it always was.
+	whole := engines.ShardSpec{GPUIndices: []int{1}}
+	a.localizeSpec(&whole)
+	if whole.GPUUUIDs != nil || engines.NCCLEnv(whole)["CUDA_VISIBLE_DEVICES"] != "1" {
+		t.Errorf("a whole card was given as %v / %q", whole.GPUUUIDs, engines.NCCLEnv(whole)["CUDA_VISIBLE_DEVICES"])
+	}
+
+	// A device this node does not have is not guessed at.
+	gone := engines.ShardSpec{GPUIndices: []int{1002}}
+	a.localizeSpec(&gone)
+	if gone.GPUUUIDs != nil {
+		t.Errorf("an unknown device was named %v", gone.GPUUUIDs)
+	}
+}