v0.15.0: changelog and README

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.gitea/workflows/ci.yml

@@ -34,11 +34,23 @@ jobs:
         run: go vet ./...
 
       - name: Test with the race detector
-        run: go test -race ./...
+        # Under the job's limit, so a package that hangs panics with the
+        # test it was in and where every goroutine waited, rather than the
+        # job ending at its deadline with nothing said: from 2026-10-15 every
+        # run did, printing nothing after internal/release.
+        run: go test -race -timeout 12m ./...
 
       - name: Build
         run: go build ./...
 
+      # llmgw-kb runs on people's own machines, Windows included, which no
+      # test here runs on: building it for each catches a Unix-only call.
+      - name: Build llmgw-kb for every system
+        run: |
+          for target in windows/amd64 windows/arm64 darwin/amd64 darwin/arm64 linux/amd64 linux/arm64; do
+            CGO_ENABLED=0 GOOS="${target%/*}" GOARCH="${target#*/}" go build -o /dev/null ./cmd/llmgw-kb
+          done
+
       # 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

.gitea/workflows/release.yml

@@ -55,6 +55,21 @@ jobs:
             (cd dist && sha256sum "${name}" >> checksums.txt)
           done
 
+          # llmgw-kb, which people run on their own machines to put their
+          # documents into a knowledge base: Windows too, which llmgw itself
+          # does not build for.
+          for target in windows/amd64 windows/arm64 darwin/amd64 darwin/arm64 linux/amd64 linux/arm64; do
+            os="${target%/*}"; arch="${target#*/}"
+            ext=""; [ "$os" = windows ] && ext=".exe"
+            name="llmgw-kb-${version}-${os}-${arch}${ext}"
+            echo "building $name"
+            CGO_ENABLED=0 GOOS="$os" GOARCH="$arch" go build \
+              -trimpath \
+              -ldflags "-s -w -X gitea.mynodes.xyz/ilker/llmgw/internal/version.Version=${version}" \
+              -o "dist/${name}" ./cmd/llmgw-kb
+            (cd dist && sha256sum "${name}" >> checksums.txt)
+          done
+
           # The reverse proxy configurations, so a release page carries
           # everything install.md asks for and the repository is not needed.
           for f in deploy/proxy/Caddyfile deploy/proxy/nginx.conf; do
@@ -91,6 +106,7 @@ jobs:
           # test the cross-compiled ones, which is why the native build is
           # checked rather than assumed.
           ./dist/llmgw-${version}-linux-amd64 --version
+          ./dist/llmgw-kb-${version}-linux-amd64 --version
           cat dist/checksums.txt
 
       # Signed, so a machine that trusts the key built into it installs

.gitignore

@@ -9,3 +9,5 @@ coverage.out
 /terraform-provider-llmgw/terraform-provider-llmgw
 /terraform-provider-llmgw/examples/.terraform*
 /terraform-provider-llmgw/examples/terraform.tfstate*
+# What a development server run from the checkout writes beside it.
+/secrets/

Makefile

@@ -6,6 +6,7 @@ LDFLAGS := -X '$(MODULE)/internal/version.Version=$(VERSION)'
 
 build:
 	go build -ldflags "$(LDFLAGS)" -o bin/llmgw ./cmd/llmgw
+	go build -ldflags "$(LDFLAGS)" -o bin/llmgw-kb ./cmd/llmgw-kb
 
 test:
 	go test ./...

README.md

@@ -3,8 +3,9 @@
 A single-binary LLM gateway for clusters with multiple InfiniBand fabrics,
 NVLink domains and heterogeneous GPUs.
 
-It serves LLMs running on your own GPU servers (vLLM / SGLang) behind one
-OpenAI-compatible endpoint. Design document: [llmgw-plan.md](llmgw-plan.md).
+It serves LLMs running on your own GPU and CPU servers (vLLM, SGLang,
+llama.cpp, TensorRT-LLM) behind one OpenAI- and Anthropic-compatible
+endpoint, and answers from your own documents. Design document: [llmgw-plan.md](llmgw-plan.md).
 
 ## Getting started
 
@@ -29,7 +30,7 @@ Releases track the roadmap phases; see [CHANGELOG.md](CHANGELOG.md).
 | v0.1.0 | 0 | Skeleton and sim-engine | released |
 | v0.2.0 | 1 | Static router (filter/score/pick, streaming proxy) | released |
 | v0.3.0 | 1.5 | Admission control (priority bands) | released |
-| v0.4.0 | 2 | Agent: GPU/IB discovery, engine supervision | released |
+| v0.4.0 | 2 | Agent: GPU/IB discovery, engine supervision | released as part of v0.5.0 |
 | v0.5.0 | 3 | Control plane: catalog, placement, reconciler, ctl | released |
 | v0.6.0 | 4 | Multi-node placement and fabric awareness | released |
 | v0.7.0 | — | Conversations, agent memory, disk management | released |
@@ -37,45 +38,118 @@ Releases track the roadmap phases; see [CHANGELOG.md](CHANGELOG.md).
 | 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 |
+| v0.12.0 | — | The cluster's settings in the store, in force when changed; the firewall switch; wipe | released |
+| v0.13.0 | — | The whole system stopped and started from one command; Qwen3Guard judges, on a GPU and CPUs together | released |
+| v0.14.0 | — | Knowledge bases: documents from people's own machines, kept apart per tenant, answered from | released (v0.14.1: adapters, the tree over the API, the firewall on every machine; v0.14.2: pictures from ComfyUI; v0.14.3: 3D models as jobs; v0.14.4: any ComfyUI workflow as a job, presets, licences; v0.14.5: picture and 3D models that add themselves; v0.14.6: setup that explains every part and lets it be chosen, the gateway on all three HA machines; v0.14.7: the judge sized for its machine; v0.14.8: sign-in with Active Directory, several keys for one outside provider; v0.14.9: sign-in set up from the console, a node's console that shows the machine) |
+| v0.15.0 | — | The company's MCP tools and VS Code through the gateway; guardrails that ask outside services and put redacted values back; answers to similar questions | released |
+| v1.0.0 | 5 | What phase 5 has left: precise KV routing proven on vLLM, the block cost picker, defragmentation across NVLink domains, prefill/decode disaggregation | planned |
 
 As of v0.6.0 a cluster runs unattended: agents report their hardware, the
 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.
 
-Since v0.11.0, not yet released (see [CHANGELOG.md](CHANGELOG.md),
-"Unreleased"):
+Since v0.11.0 (each release's detail is in [CHANGELOG.md](CHANGELOG.md)):
 
-- **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:
+- **Setup that explains, and high availability that is whole** (v0.14.6).
+  `sudo llmgw` lists the parts of an install, each with what it is for and
+  what is missing without it, and every one can be turned off or set: the
+  starter model and its context, the mirror's directory, the judge's
+  categories and what it does when it does not answer, limits, the
+  portal's language, pictures and 3D. With three machines each runs the
+  control plane, with a floating address on the leader, and any one can
+  be lost: on three VMs, cutting the store primary's power lost no
+  request. One ComfyUI serves an environment's models, pictures, 3D and
+  workflows are MCP tools, and `/v1/messages` gives a model's reasoning as
+  thinking blocks.
+- **Picture and 3D models that add themselves** (v0.14.5). Where a node's
+  card fits flux-schnell or triposr and the catalog makes nothing of that
+  kind, the leader adds it on demand, so a new cluster's portal has its
+  Images and 3D pages; the cluster page and the console show each preset
+  and add it by hand, and `presets.auto` turns it off. Stable Fast 3D's
+  colours can be brought to the picture's (`albedo_match`), and every mesh
+  carries its whole licence.
+- **Any ComfyUI workflow, and models by name** (v0.14.4). `POST
+  /v1/workflows/runs` runs a ComfyUI model's workflow as a job, its inputs
+  (text, numbers, choices, images, masks, audio, video, files) declared in
+  the catalog and listed in `/v1/models`. `llmgw ctl model add triposr` or
+  `flux-schnell` adds a tested model with no YAML; a profile may name the
+  card it needs instead of a class, and ComfyUI now installs on V100s. A
+  licence carries what a machine can match, and a person can leave
+  licences out on the profile page so no key of theirs reaches such a
+  model. A 3D job waiting for the one card says what holds it and for
+  about how long.
+- **3D models as jobs** (v0.14.3). `POST /v1/3d/generations` answers with a
+  job, asked after until its mesh is ready to download. ComfyUI makes it on
+  the cluster's own cards, TripoSR being the tested model. The job says how
+  far along it is, the model's licence is written into the GLB, and
+  `per_mesh` prices it. People make them at `/3d` on the portal; `llmgw ctl
+  3d` shows every owner's jobs. A model profile may also load weights of
+  its own, and an admission band may wait longer than the rest, for bulk
+  work.
+- **Pictures from ComfyUI** (v0.14.2). `POST /v1/images/generations` is made
+  by ComfyUI, behind a gate that demands the replica's key, as an engine the
+  agents install from its source checked against a digest. `per_image`
+  prices it, and people make pictures at `/images` on the portal.
+- **Adapters, and the tenancy tree over the API** (v0.14.1). `llmgw ctl
+  kb dataset` and `llmgw ctl train` make a LoRA adapter from a collection
+  on a node's spare GPU memory, kept on the mirror and seen only by its
+  owner. Organizations, teams, projects, keys and memberships are in the
+  admin API and the Terraform provider. The agents' settings are edited
+  with the cluster's, on the portal too, and the firewall setting reaches
+  every machine.
+- **Knowledge bases** (v0.14.0). People put a company's documents in from
+  their own machines with `llmgw-kb`, a separate download for Windows,
+  macOS and Linux that reads PDF, Office, OpenDocument, mail and many more
+  formats and sends text and vectors, never the files. Collections are kept
+  apart per tenant, down to row-level security in PostgreSQL. A chat
+  request, or a part of the tree by default, is answered from them with
+  its sources: [docs/knowledge.md](docs/knowledge.md).
+- **One command for the whole system** (v0.13.0): `llmgw stop`, `start` and
+  `restart`. Qwen3Guard is the guardrails' judge, on a GPU and on CPUs
+  together.
+- **Settings that apply when changed** (v0.12.0). The cluster's
+  configuration lives in the store, the same on every control plane and in
+  force within seconds (`llmgw ctl config`, the console's Settings). The
+  firewall can be switched on and off for the whole cluster.
+- **Security hardening** (v0.11.2): 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** (v0.11.2). Policies check requests and answers for PII,
+  secrets, prompt injection, deny patterns, and with a judge model; they
+  observe or enforce, and attach 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.
+- **Administration** (v0.11.2):
+  - 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** (v0.11.2): webhooks, signed or Slack-shaped, for a
+  model parked, a node lost, a budget spent and new weights published, and
+  Alertmanager receiver templates.
+- **Traffic and models** (v0.11.2):
+  - request tags, canaries of new weights with automatic rollback, and
+    quality suites gating updates;
+  - a response cache, kept and replayed requests, and batches;
+  - Anthropic's Messages API, and more of OpenAI's (structured output,
+    images, rerank, audio, moderations);
+  - scaling by the clock, and SLO-aware admission;
+  - TensorRT-LLM, MIG, and models imported from Ollama;
+  - routing by what each vLLM replica's cache holds, and LoRA adapters
+    loaded on demand;
+  - other llmgw clusters as providers, and placement that knows racks,
+    PDUs and power caps.
+- **Operations** (v0.11.2):
+  - `server restore`, off-machine backup copies, and secrets in Vault;
+  - forgetting a person, and keeping a project's requests in the cluster;
+  - offline installs from a bundle, and a Helm chart;
+  - tracing from the control plane to the engines;
+  - the admin API in OpenAPI, with a Terraform provider;
+  - 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).
@@ -110,6 +184,8 @@ Every page is also in the binary: `llmgw docs`, or **Manual** in the console.
   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/kong.md](docs/kong.md) — llmgw behind Kong Gateway, or Kong behind
+  llmgw: the configuration, what Kong counts, and which to choose
 - [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
@@ -124,6 +200,9 @@ Every page is also in the binary: `llmgw docs`, or **Manual** in the console.
   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/knowledge.md](docs/knowledge.md) — knowledge bases: collections,
+  who may read them, `llmgw-kb` on people's machines, and answers from
+  documents
 - [docs/choosing-models.md](docs/choosing-models.md) — which models to run,
   how many of each, and where the weights should live
 
@@ -152,7 +231,7 @@ Every page is also in the binary: `llmgw docs`, or **Manual** in the console.
 ## Building
 
 ```sh
-make build      # bin/llmgw
+make build      # bin/llmgw and bin/llmgw-kb
 make test       # unit tests
 make race       # with the race detector
 ```
@@ -169,6 +248,7 @@ 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
+llmgw ctl kb list                    # knowledge-base collections, grants, defaults
 ```
 
 Bare `llmgw` opens the console, which does all of this from one screen.
@@ -180,6 +260,33 @@ Add `--json` to any command for machine-readable output.
 says nothing about which of six constraints bit, so it prints every candidate
 considered and the reason it was rejected.
 
+## What llmgw adds to a request
+
+Measured with `llmgw ctl bench overhead`. It starts an engine that answers
+at once and a gateway in front of it, in one process on loopback. It sends
+the same load straight to the engine and through the gateway, and reports
+what the gateway added. Run on an Apple M5 (10 CPUs, load about 2) on
+2026-10-16, 10 s a step, 72,000 requests with none failed:
+
+| Through the gateway | added at p50 | added at p99 |
+|---|---|---|
+| bare | 0.06–0.24 ms | 0.10–0.33 ms |
+| with authentication and usage accounting | 0.05–0.32 ms | 0.09–0.37 ms |
+| with the guardrails' pattern checks as well | 0.10–0.42 ms | 0.15–0.49 ms |
+
+The range is across 100 to 2,000 requests a second. The overhead was
+*lowest* at 2,000, most likely because a busier processor keeps its cores
+awake. The guardrails' judge model is not in these figures: a judgment
+takes seconds on CPUs (see [install.md](docs/install.md)) and is a model's
+time, not the gateway's.
+
+The command also prints the gateway's CPU per thousand requests. Gateway,
+engine and load share one process there, so that figure is rough (0.04 to
+0.65 s per thousand in the run above); the latency is the one to quote.
+Figures from a VM on a busy host move with the host: run it where you will
+deploy, and keep the load it prints beside the result. CI runs a one-second
+version on every change (`TestTheGatewaysOverheadIsMeasured`).
+
 ## Running the router
 
 ```sh
@@ -207,8 +314,9 @@ within 1.24x of idle while 500 concurrent batch requests run, against 58x with
 admission off.
 
 Routing profiles select how endpoints are scored: `chat` favours session
-affinity, `batch` favours the shortest queue, `long-context` favours free KV
-cache. Pick one per model in the config, or per request with the
+affinity and the replica that has been answering soonest (its time to first
+token, smoothed), `batch` favours the shortest queue, `long-context` favours
+free KV cache. Pick one per model in the config, or per request with the
 `x-llmgw-profile` header.
 
 ## sim-engine

api/proto/llmgw/v1/agent.proto

@@ -28,6 +28,8 @@ message AgentMessage {
     FabricTestReply fabric_test = 6;
     UpgradeReply upgrade = 7;
     KVEvents kv_events = 8;
+    TrainStatus train_status = 9;
+    TrainArtifact train_artifact = 10;
   }
 }
 
@@ -72,6 +74,10 @@ message ControlMessage {
     UpgradeAgent upgrade = 10;
     ControlPlanes control_planes = 11;
     Firewall firewall = 13;
+    RestartAgent restart_agent = 14;
+    AgentSettings agent_settings = 15;
+    TrainStart train_start = 16;
+    TrainCancel train_cancel = 17;
   }
   // 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
@@ -81,6 +87,12 @@ message ControlMessage {
   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
@@ -96,6 +108,17 @@ message Firewall {
   int32 engine_ports_to = 4;
 }
 
+// AgentSettings is what the cluster's settings say of this node's agent
+// (agents.default, with agents.nodes.<id> over it), sent when it registers
+// and whenever they change. The agent keeps it beside agent.yaml, which
+// holds only what it needs to start; over that file, it is what the agent
+// runs on. A change from what it runs on has the agent start again on it,
+// its engines serving throughout.
+message AgentSettings {
+  // yaml is agent.yaml's keys, as YAML; empty for none.
+  string yaml = 1;
+}
+
 // 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
@@ -266,6 +289,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 {
@@ -605,6 +633,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;
@@ -626,6 +666,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;
@@ -844,3 +888,55 @@ message LoraAdapter {
   string name = 1;
   string source = 2;
 }
+
+// TrainStart has a node train a LoRA adapter (BACKLOG F4): on a base model's
+// weights from its registry, on question/answer pairs, with a Python trainer
+// the agent carries, in an environment it makes over an installed engine's.
+// One at a time per node.
+message TrainStart {
+  string job_id = 1;
+  // base_repo and base_revision name the base model's weights on its
+  // registry (Hugging Face): safetensors, not the GGUF a catalog may serve.
+  string base_repo = 2;
+  string base_revision = 3;
+  // data is the training pairs, NDJSON of {"q", "a"}.
+  bytes data = 4;
+  // params is the trainer's settings as JSON: rank, alpha, epochs, lr,
+  // batch, max_len.
+  string params = 5;
+  // gpu_memory_mib is what the job needs of a card; the agent starts it
+  // only when one has that much free, which lets it run beside an engine.
+  int32 gpu_memory_mib = 6;
+  // gguf asks for the adapter in llama.cpp's format too.
+  bool gguf = 7;
+}
+
+// TrainCancel stops a training job.
+message TrainCancel {
+  string job_id = 1;
+}
+
+// TrainStatus is how a training job is going, sent as it changes.
+message TrainStatus {
+  string job_id = 1;
+  // state is preparing, running, done or failed.
+  string state = 2;
+  int32 step = 3;
+  int32 steps = 4;
+  double loss = 5;
+  // message is what is being done, or why it failed.
+  string message = 6;
+  // peak_mib is the most the job held of the card.
+  int32 peak_mib = 7;
+}
+
+// TrainArtifact is a piece of what a training job made, sent before its
+// final status: a gzipped tar of the PEFT adapter (kind peft), or the GGUF
+// adapter (kind gguf).
+message TrainArtifact {
+  string job_id = 1;
+  string kind = 2;
+  int32 seq = 3;
+  bytes data = 4;
+  bool last = 5;
+}

cmd/llmgw-kb/main.go

@@ -0,0 +1,467 @@
+// Command llmgw-kb puts a person's documents into an llmgw knowledge base
+// from their own machine (BACKLOG F2): it reads the files there, cuts them
+// into chunks, has the gateway embed them with the person's key, and sends
+// the text and vectors — only for what changed since the last run, which a
+// ledger on the machine remembers.
+//
+// Its own binary, for Windows, macOS and Linux: it carries none of the
+// server, agent or setup code that llmgw does.
+package main
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"strings"
+	"text/tabwriter"
+	"time"
+
+	"github.com/spf13/cobra"
+	"golang.org/x/term"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/kb/extract"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/kb/kbsync"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/version"
+)
+
+func main() {
+	if err := root().Execute(); err != nil {
+		fmt.Fprintln(os.Stderr, "error:", err)
+		os.Exit(1)
+	}
+}
+
+// config is what `login` keeps: the gateway, the key, and for a personal key
+// the project it acts in.
+type config struct {
+	Gateway string `json:"gateway"`
+	Key     string `json:"key"`
+	Project string `json:"project,omitempty"`
+	CA      string `json:"ca,omitempty"`
+}
+
+func configPath() (string, error) {
+	dir, err := os.UserConfigDir()
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(dir, "llmgw-kb", "config.json"), nil
+}
+
+// loadConfig reads the saved configuration, with the environment over it:
+// LLMGW_URL, LLMGW_API_KEY, LLMGW_PROJECT.
+func loadConfig() (config, error) {
+	var c config
+	if p, err := configPath(); err == nil {
+		if b, err := os.ReadFile(p); err == nil {
+			if err := json.Unmarshal(b, &c); err != nil {
+				return c, fmt.Errorf("%s: %w", p, err)
+			}
+		}
+	}
+	for env, dst := range map[string]*string{"LLMGW_URL": &c.Gateway, "LLMGW_API_KEY": &c.Key, "LLMGW_PROJECT": &c.Project} {
+		if v := strings.TrimSpace(os.Getenv(env)); v != "" {
+			*dst = v
+		}
+	}
+	return c, nil
+}
+
+func client(flags *globalFlags) (*kbsync.Client, error) {
+	c, err := loadConfig()
+	if err != nil {
+		return nil, err
+	}
+	if flags.gateway != "" {
+		c.Gateway = flags.gateway
+	}
+	if flags.project != "" {
+		c.Project = flags.project
+	}
+	if flags.ca != "" {
+		c.CA = flags.ca
+	}
+	if c.Gateway == "" || c.Key == "" {
+		return nil, errors.New("no gateway or key: run `llmgw-kb login`, or set LLMGW_URL and LLMGW_API_KEY")
+	}
+	h, err := kbsync.NewHTTP(c.CA)
+	if err != nil {
+		return nil, err
+	}
+	return &kbsync.Client{Base: c.Gateway, Key: c.Key, Project: c.Project, HTTP: h}, nil
+}
+
+type globalFlags struct {
+	gateway, project, ca, ledger string
+}
+
+func (g *globalFlags) openLedger(ctx context.Context) (*kbsync.Ledger, error) {
+	p := g.ledger
+	if p == "" {
+		var err error
+		if p, err = kbsync.DefaultLedgerPath(); err != nil {
+			return nil, err
+		}
+	}
+	return kbsync.OpenLedger(ctx, p)
+}
+
+func root() *cobra.Command {
+	g := &globalFlags{}
+	cmd := &cobra.Command{
+		Use:   "llmgw-kb",
+		Short: "Put your documents into an llmgw knowledge base, from this machine",
+		Long: `llmgw-kb reads documents on this machine, cuts them into chunks, has the
+gateway embed them with your key, and sends the text and vectors to a
+knowledge base. Files are never uploaded. Run it as often as you like: a
+ledger on this machine remembers what was sent, and only what changed is
+read and sent again.`,
+		Version:       version.Version,
+		SilenceUsage:  true,
+		SilenceErrors: true,
+	}
+	cmd.PersistentFlags().StringVar(&g.gateway, "gateway", "", "the gateway's address (default: from login, or LLMGW_URL)")
+	cmd.PersistentFlags().StringVar(&g.project, "project", "", "the project a personal key acts in (default: from login, or LLMGW_PROJECT)")
+	cmd.PersistentFlags().StringVar(&g.ca, "ca", "", "a PEM file of certificates to trust besides the system's")
+	cmd.PersistentFlags().StringVar(&g.ledger, "ledger", "", "the ledger file (default: in your configuration directory)")
+	cmd.AddCommand(loginCmd(g), collectionsCmd(g), syncCmd(g), statusCmd(g), historyCmd(g), formatsCmd())
+	return cmd
+}
+
+func loginCmd(g *globalFlags) *cobra.Command {
+	return &cobra.Command{
+		Use:   "login",
+		Short: "Save the gateway's address and your key",
+		Long: `Asks for the gateway's address and your API key, checks them, and saves them
+in your configuration directory, readable by you only. The key is typed
+without being shown, so it does not end up in your shell's history.`,
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			c, _ := loadConfig()
+			in := bufio.NewReader(os.Stdin)
+			ask := func(q, def string) string {
+				if def != "" {
+					fmt.Fprintf(cmd.OutOrStdout(), "%s [%s]: ", q, def)
+				} else {
+					fmt.Fprintf(cmd.OutOrStdout(), "%s: ", q)
+				}
+				s, _ := in.ReadString('\n')
+				if s = strings.TrimSpace(s); s == "" {
+					return def
+				}
+				return s
+			}
+			c.Gateway = strings.TrimRight(ask("Gateway address (https://…)", or(g.gateway, c.Gateway)), "/")
+			fmt.Fprint(cmd.OutOrStdout(), "API key: ")
+			var key string
+			if term.IsTerminal(int(os.Stdin.Fd())) {
+				b, err := term.ReadPassword(int(os.Stdin.Fd()))
+				fmt.Fprintln(cmd.OutOrStdout())
+				if err != nil {
+					return err
+				}
+				key = strings.TrimSpace(string(b))
+			} else {
+				key, _ = in.ReadString('\n')
+				key = strings.TrimSpace(key)
+			}
+			if key != "" {
+				c.Key = key
+			}
+			c.Project = ask("Project, for a personal key (empty for a project's key)", or(g.project, c.Project))
+			if g.ca != "" {
+				c.CA = g.ca
+			}
+			h, err := kbsync.NewHTTP(c.CA)
+			if err != nil {
+				return err
+			}
+			cl := &kbsync.Client{Base: c.Gateway, Key: c.Key, Project: c.Project, HTTP: h, Wait: time.Second}
+			ctx, cancel := context.WithTimeout(cmd.Context(), 30*time.Second)
+			defer cancel()
+			cs, err := cl.Collections(ctx)
+			if err != nil {
+				return fmt.Errorf("the gateway refused: %w", err)
+			}
+			p, err := configPath()
+			if err != nil {
+				return err
+			}
+			if err := os.MkdirAll(filepath.Dir(p), 0o700); err != nil {
+				return err
+			}
+			b, _ := json.MarshalIndent(c, "", "  ")
+			if err := os.WriteFile(p, b, 0o600); err != nil {
+				return err
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "Saved in %s. This key reaches %d collection(s); `llmgw-kb collections` lists them.\n", p, len(cs))
+			return nil
+		},
+	}
+}
+
+func or(a, b string) string {
+	if a != "" {
+		return a
+	}
+	return b
+}
+
+func collectionsCmd(g *globalFlags) *cobra.Command {
+	return &cobra.Command{
+		Use:   "collections",
+		Short: "List the collections your key may read, and which it may add to",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			c, err := client(g)
+			if err != nil {
+				return err
+			}
+			cs, err := c.Collections(cmd.Context())
+			if err != nil {
+				return err
+			}
+			if len(cs) == 0 {
+				fmt.Fprintln(cmd.OutOrStdout(), "No collections. An administrator creates them and grants access (llmgw ctl kb).")
+				return nil
+			}
+			tw := tabwriter.NewWriter(cmd.OutOrStdout(), 2, 4, 2, ' ', 0)
+			fmt.Fprintln(tw, "NAME\tACCESS\tOWNER\tEMBEDDED BY")
+			for _, x := range cs {
+				access := "read"
+				if x.Writable {
+					access = "read, write"
+				}
+				fmt.Fprintf(tw, "%s\t%s\t%s\t%s (%d)\n", x.Name, access, or(x.OwnerName, x.Owner), x.EmbedModel, x.Dims)
+			}
+			return tw.Flush()
+		},
+	}
+}
+
+func syncCmd(g *globalFlags) *cobra.Command {
+	var o kbsync.Options
+	var verbose bool
+	var ocr string
+	var maxMiB int64
+	cmd := &cobra.Command{
+		Use:   "sync COLLECTION PATH...",
+		Short: "Send a collection what changed in these folders and files",
+		Long: `Reads the files under each PATH that the collection does not already have as
+they are, and sends their text and vectors. Run it again whenever you like;
+unchanged files are not even read.
+
+Documents are named by their path under PATH, with forward slashes; with
+several PATHs, each folder's own name comes first.
+
+  --dry-run   reads and cuts everything, sends nothing, and says what would
+              leave this machine
+  --delete    removes documents this machine sent whose files are gone
+              (only under these PATHs; nothing anybody else sent)
+  --retry     reads again files skipped before (after installing LibreOffice
+              or Tesseract, say)
+
+Without --include, every file of a known format is read (llmgw-kb formats);
+hidden files, version control folders and Office lock files are not.`,
+		Args: cobra.MinimumNArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := client(g)
+			if err != nil {
+				return err
+			}
+			ctx, stop := signal.NotifyContext(cmd.Context(), os.Interrupt)
+			defer stop()
+			l, err := g.openLedger(ctx)
+			if err != nil {
+				return err
+			}
+			defer l.Close()
+			o.Collection, o.Roots = args[0], args[1:]
+			o.Extract = extract.Options{Helpers: extract.FindHelpers(), OCRLanguages: ocr, MaxBytes: maxMiB << 20}
+			out := cmd.OutOrStdout()
+			c.Waiting = func(why string, d time.Duration) {
+				fmt.Fprintf(out, "  ..       waiting %s: %s\n", d, why)
+			}
+			start := time.Now()
+			rep, err := kbsync.Sync(ctx, c, l, o, func(e kbsync.Event) {
+				switch e.Kind {
+				case "unchanged":
+					if !verbose {
+						return
+					}
+					fmt.Fprintf(out, "  =        %s\n", e.Name)
+				case "sent", "would-send":
+					fmt.Fprintf(out, "  %-8s %s (%d chunks, %s)\n", label(e.Kind), e.Name, e.Chunks, size(e.Bytes))
+				default:
+					line := fmt.Sprintf("  %-8s %s", label(e.Kind), e.Name)
+					if e.Detail != "" {
+						line += ": " + e.Detail
+					}
+					fmt.Fprintln(out, line)
+				}
+			})
+			if rep.Collection.Name != "" {
+				verb := "sent"
+				if o.DryRun {
+					verb = "would send"
+				}
+				fmt.Fprintf(out, "\n%s: %d files; %s %d (%d chunks, %s), %d unchanged, %d skipped, %d failed, %d deleted, in %s\n",
+					rep.Collection.Name, rep.Files, verb, rep.Sent, rep.Chunks, size(rep.Bytes), rep.Unchanged,
+					rep.Skipped, rep.Failed, rep.Deleted, time.Since(start).Round(time.Second))
+			}
+			if err != nil {
+				return err
+			}
+			if rep.Failed > 0 {
+				return fmt.Errorf("%d document(s) failed; run again to retry them", rep.Failed)
+			}
+			return nil
+		},
+	}
+	f := cmd.Flags()
+	f.StringSliceVar(&o.Include, "include", nil, "read only files matching these globs (\"*.pdf,docs/**/*.md\")")
+	f.StringSliceVar(&o.Exclude, "exclude", nil, "never read files matching these globs")
+	f.BoolVar(&o.Hidden, "hidden", false, "read hidden files and folders too")
+	f.BoolVar(&o.DryRun, "dry-run", false, "send nothing; say what would be sent")
+	f.BoolVar(&o.Delete, "delete", false, "remove documents this machine sent whose files are gone")
+	f.BoolVar(&o.Retry, "retry", false, "read again files skipped before")
+	f.IntVar(&o.Workers, "workers", 4, "files read and sent at once")
+	f.StringVar(&ocr, "ocr-languages", "tur+eng", "Tesseract's languages for images and scanned pages")
+	f.Int64Var(&maxMiB, "max-size", 256, "skip files larger than this many MiB")
+	f.BoolVarP(&verbose, "verbose", "v", false, "list unchanged files too")
+	return cmd
+}
+
+func label(kind string) string {
+	switch kind {
+	case "would-send":
+		return "send"
+	case "would-delete":
+		return "delete"
+	}
+	return kind
+}
+
+func size(b int64) string {
+	switch {
+	case b >= 1<<20:
+		return fmt.Sprintf("%.1f MiB", float64(b)/(1<<20))
+	case b >= 1<<10:
+		return fmt.Sprintf("%.0f KiB", float64(b)/(1<<10))
+	}
+	return fmt.Sprintf("%d B", b)
+}
+
+func statusCmd(g *globalFlags) *cobra.Command {
+	var all bool
+	return &cobra.Command{
+		Use:   "status COLLECTION",
+		Short: "Show what this machine has sent to a collection, and what it skipped",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := client(g)
+			if err != nil {
+				return err
+			}
+			m, err := c.Manifest(cmd.Context(), args[0])
+			if err != nil {
+				return err
+			}
+			l, err := g.openLedger(cmd.Context())
+			if err != nil {
+				return err
+			}
+			defer l.Close()
+			es, err := l.Entries(cmd.Context(), strings.TrimRight(c.Base, "/"), m.Collection.ID)
+			if err != nil {
+				return err
+			}
+			counts := map[kbsync.State]int{}
+			tw := tabwriter.NewWriter(cmd.OutOrStdout(), 2, 4, 2, ' ', 0)
+			fmt.Fprintln(tw, "STATE\tDOCUMENT\tCHUNKS\tWHEN\tWHY")
+			for _, e := range es {
+				counts[e.State]++
+				if e.State == kbsync.Sent && !all {
+					continue
+				}
+				fmt.Fprintf(tw, "%s\t%s\t%d\t%s\t%s\n", e.State, e.Name, e.Chunks, e.At.Format("2006-01-02 15:04"), e.Reason)
+			}
+			_ = tw.Flush()
+			fmt.Fprintf(cmd.OutOrStdout(), "\n%s holds %d documents; from this machine %d sent, %d skipped, %d failed.",
+				m.Collection.Name, len(m.Documents), counts[kbsync.Sent], counts[kbsync.Skipped], counts[kbsync.Failed])
+			if !all {
+				fmt.Fprint(cmd.OutOrStdout(), " (--all lists the sent ones too)")
+			}
+			fmt.Fprintln(cmd.OutOrStdout())
+			return nil
+		},
+	}
+}
+
+func historyCmd(g *globalFlags) *cobra.Command {
+	return &cobra.Command{
+		Use:   "history",
+		Short: "List the latest syncs from this machine",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			l, err := g.openLedger(cmd.Context())
+			if err != nil {
+				return err
+			}
+			defer l.Close()
+			runs, err := l.Runs(cmd.Context(), 20)
+			if err != nil {
+				return err
+			}
+			tw := tabwriter.NewWriter(cmd.OutOrStdout(), 2, 4, 2, ' ', 0)
+			fmt.Fprintln(tw, "STARTED\tTOOK\tCOLLECTION\tSENT\tUNCHANGED\tSKIPPED\tFAILED\tDELETED")
+			for _, r := range runs {
+				took := "unfinished"
+				if !r.Finished.IsZero() {
+					took = r.Finished.Sub(r.Started).Round(time.Second).String()
+				}
+				fmt.Fprintf(tw, "%s\t%s\t%s\t%d\t%d\t%d\t%d\t%d\n", r.Started.Format("2006-01-02 15:04"), took,
+					r.Collection, r.Sent, r.Unchanged, r.Skipped, r.Failed, r.Delete)
+			}
+			return tw.Flush()
+		},
+	}
+}
+
+func formatsCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "formats",
+		Short: "List the formats read, and the helpers found on this machine",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			builtIn, helper := extract.Supported()
+			out := cmd.OutOrStdout()
+			fmt.Fprintf(out, "Read here:\n%s\n\n", wrap(builtIn))
+			fmt.Fprintf(out, "Read with a helper program:\n%s\n\n", wrap(helper))
+			fmt.Fprintln(out, "Helpers:")
+			for _, l := range extract.FindHelpers().Describe() {
+				fmt.Fprintln(out, "  "+l)
+			}
+			return nil
+		},
+	}
+}
+
+func wrap(words []string) string {
+	var b strings.Builder
+	line := "  "
+	for _, w := range words {
+		if len(line)+len(w) > 78 {
+			b.WriteString(strings.TrimRight(line, " ") + "\n")
+			line = "  "
+		}
+		line += w + " "
+	}
+	b.WriteString(strings.TrimRight(line, " "))
+	return b.String()
+}

cmd/llmgw-kb/main_test.go

@@ -0,0 +1,24 @@
+package main
+
+import (
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+// The client goes onto employees' laptops: none of the server, agent, store
+// or setup code may come with it, and it must build where llmgw does not.
+func TestTheClientCarriesNoServerCode(t *testing.T) {
+	out, err := exec.Command("go", "list", "-deps", ".").Output()
+	if err != nil {
+		t.Skipf("go list: %v", err)
+	}
+	for _, dep := range strings.Fields(string(out)) {
+		for _, banned := range []string{"/internal/store", "/internal/router", "/internal/agent", "/internal/control",
+			"/internal/cli", "/internal/guard", "github.com/jackc/pgx"} {
+			if strings.Contains(dep, banned) {
+				t.Errorf("llmgw-kb depends on %s", dep)
+			}
+		}
+	}
+}

deploy/ha/README.md

@@ -1,4 +1,4 @@
-# Two control planes
+# More than one control plane
 
 llmgw handles the hard half of this itself: only one control plane places work,
 and agents find whichever one is leading. What it does not do is move client
@@ -37,7 +37,7 @@ nothing in front of the two had moved.
 So something has to. The options, in the order most people should consider
 them:
 
-**A load balancer you already run.** Health-check `/ready` on each control
+**A load balancer you already run.** Health-check `/leader` on each control
 plane and send traffic to whichever answers. This is the right answer if you
 have one, and it needs nothing else from this directory.
 
@@ -50,25 +50,50 @@ in whatever your resolvers actually honour rather than what you set, which on
 a bad day is minutes. Fine for a cluster people use interactively, wrong for
 one an agent is driving.
 
-## Check `/ready`, not `/health`
+## Check `/leader`, not `/health`
 
 This is the one thing to get right, and the obvious choice is the wrong one.
 
-`/health` says the process is up. It says nothing about whether it can serve,
+`/health` says the process is up. It says nothing about whether it leads,
 and a standby is exactly that case: alive, answering, and holding no endpoints
 at all — its reconciler placed nothing and it has no agent streams to adopt
-from. A load balancer checking `/health` would send it half the traffic, and
-half the traffic would be a 503.
+from. A standby passes client requests on to the leader, so traffic sent to
+one still works — until the leader is the machine that was lost, and there
+is nobody to pass them to.
+
+`/leader` is 200 on the control plane that leads and 503 on a standby. It is
+what keepalived follows for the floating address, and what a load balancer
+should send traffic by: to the one machine that answers 200.
+
+`/ready` is narrower: 200 only when this process has somewhere to send a
+request, so 503 on a standby and also on a leader with no model running yet.
+Checking it takes the portal and the admin pages away with the models — on a
+new cluster with no node yet, nobody can sign in to add one. Use it to stop
+sending inference only, if your load balancer can tell the paths apart.
 
-`/ready` says this process has somewhere to send a request. It is 503 on a
-standby, 503 on a leader whose replicas have all failed, and 200 when there is
-something to serve — which is the question a load balancer is actually asking.
 Both are open, because a load balancer has no key.
 
-During a failover neither passes for about the length of the lease handover:
+During a failover nothing passes for about the length of the lease handover:
 three seconds when the leader is stopped cleanly, up to the lease TTL when it
-is not. That gap is real and there is no way to have it both ways — traffic
-cannot go to a control plane that has nothing to route to.
+is not. A proxy that waits that long for a healthy machine rather than
+failing at once (Caddy's `lb_try_duration`) hides it from clients.
+
+**Caddy**, in front of three control planes — the end of
+[deploy/proxy/Caddyfile](../proxy/Caddyfile) has it with the rest of the
+settings:
+
+```
+reverse_proxy 10.0.0.157:8080 10.0.0.158:8080 10.0.0.159:8080 {
+	lb_policy first
+	health_uri /leader
+	health_interval 2s
+	lb_try_duration 15s
+	flush_interval -1
+}
+```
+
+With a floating address the address already follows the leader: give Caddy
+that one address instead.
 
 Not the admin port, for a different reason: it serves pprof, and pprof can
 dump the process heap, where API keys sit in plaintext.

deploy/ha/keepalived.conf.example

@@ -41,7 +41,9 @@ vrrp_instance llmgw {
     # MASTER on the machine you would rather serve; BACKUP on the other.
     state MASTER
     interface eth0
-    # Any number both machines agree on and nothing else on the segment uses.
+    # Any number both machines agree on and nothing else on the segment uses:
+    # another cluster's keepalived with the same one reads as an invalid
+    # password. `llmgw server add --vip` derives one from the address.
     virtual_router_id 51
     # The higher one wins while both are healthy. The weight above is enough
     # to invert this when the preferred machine's gateway is not answering.

deploy/monitoring/prometheus.yml

@@ -21,11 +21,18 @@ scrape_configs:
   # The control plane's dedicated metrics port. Not its admin listener: that one
   # is loopback because it also serves pprof, and pprof can dump the heap where
   # API keys sit in plaintext.
+  #
+  # Every control plane, one line each: the leader moves on restarts and the
+  # router's metrics are the leading one's, so scraping one alone leaves gaps
+  # — and alerts on them — whenever another leads.
   - job_name: llmgw
     static_configs:
       - targets: ['10.0.0.140:9091']
         labels:
-          instance: control-plane
+          instance: control-plane-140
+      # - targets: ['10.0.0.150:9091']
+      #   labels:
+      #     instance: control-plane-150
 
   # Every machine of the cluster, for its node exporter: network and disk
   # traffic, filesystems, CPU time. The control plane lists them — nodes,
@@ -33,10 +40,15 @@ scrape_configs:
   # 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.
+  # Asked of every control plane too: a standby lists only the control
+  # planes and the store, and they label every machine alike, so the same
+  # target from two of them is scraped once.
   - job_name: nodes
     http_sd_configs:
       - url: http://10.0.0.140:9091/prometheus/targets
         refresh_interval: 1m
+      # - url: http://10.0.0.150:9091/prometheus/targets
+      #   refresh_interval: 1m
 
   - job_name: prometheus
     static_configs:

deploy/proxy/Caddyfile

@@ -14,6 +14,7 @@ llm.example.com {
 		max_size 32MB
 	}
 
+	# One control plane. With more than one, see the end of this file.
 	reverse_proxy 127.0.0.1:8080 {
 		# Tokens are written the moment they are generated. Without this a
 		# streamed reply can arrive in bursts, and a client measuring time to
@@ -39,3 +40,36 @@ llm.example.com {
 	# Access log to stderr, which under systemd is the journal.
 	log
 }
+
+# More than one control plane (server init --standbys, server add): one of
+# them leads, the others stand by. Name them all and send to the one that
+# leads — /leader is 200 there and 503 on a standby. Not /ready: that is 503
+# on a leader with no model running yet, and would take the portal away with
+# it. A standby would pass a request on to the leader anyway, but not while
+# there is none, and the hop is for nothing.
+#
+# With a floating address (--vip) the address already follows the leader:
+# give reverse_proxy that one address instead, and keep the rest as above.
+#
+# llm.example.com {
+# 	request_body {
+# 		max_size 32MB
+# 	}
+# 	reverse_proxy 10.0.0.157:8080 10.0.0.158:8080 10.0.0.159:8080 {
+# 		# The first that is healthy: the leader, whichever it is.
+# 		lb_policy first
+# 		health_uri /leader
+# 		health_interval 2s
+# 		health_timeout 2s
+# 		# While leadership moves — a few seconds when a leader is lost —
+# 		# none is healthy; a request waits that long for one rather than
+# 		# failing at once.
+# 		lb_try_duration 15s
+# 		lb_try_interval 250ms
+# 		flush_interval -1
+# 		transport http {
+# 			response_header_timeout 15m
+# 		}
+# 	}
+# 	log
+# }

docs.go

@@ -39,7 +39,7 @@ func (d Doc) Source() string {
 // 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",
+	"clients", "guardrails", "knowledge", "choosing-models", "fabrics", "facility-aware-placement", "data",
 	"reference", "development"}
 
 // Manual is every document, in reading order: those docOrder names, then any
@@ -96,6 +96,12 @@ func titleOf(src, path string) string {
 //go:embed docs/admin-api.openapi.json
 var AdminOpenAPI []byte
 
+// ClientOpenAPI is the client API described in OpenAPI 3.1, generated from
+// internal/clientapi's route table and served at /v1/openapi.json.
+//
+//go:embed docs/client-api.openapi.json
+var ClientOpenAPI []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.
 //

docs/admin-api.md

@@ -8,8 +8,9 @@ description is.
 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.
+quotas, attaches guardrail policies, adds organizations, teams and projects,
+issues and revokes API keys, puts people in the tree, and reads the fleet,
+usage and the audit log.
 
 ## Reaching it
 
@@ -99,6 +100,14 @@ curl -s "${H[@]}" -X POST $API/models/qwen-small/scale -d '{"min": 0, "max": 2,
 # A team's capacity quota.
 curl -s "${H[@]}" -X PUT $API/quotas -d '{"scope": "team:Acme/ml", "limit": {"gpus": 8}}'
 
+# An organization, a team in it and a project in that; then a key for the
+# project. The answer holds the key once: only its hash is kept.
+curl -s "${H[@]}" -X POST $API/orgs -d '{"name": "Acme"}'
+curl -s "${H[@]}" -X POST $API/teams -d '{"name": "ml", "in": "Acme"}'
+curl -s "${H[@]}" -X POST $API/projects -d '{"name": "search", "in": "Acme/ml"}'
+curl -s "${H[@]}" -X POST $API/keys -d '{"name": "ci", "project": "Acme/ml/search", "expires_in": "720h"}'
+curl -s "${H[@]}" -X POST $API/users/ayse@example.com/memberships -d '{"target": "team:Acme/ml"}'
+
 # Remove the model; a DELETE carries the content type too.
 curl -s "${H[@]}" -X DELETE $API/models/qwen-small
 ```
@@ -149,11 +158,11 @@ 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.
+- **Making people's accounts.** People sign up, are invited, or come from
+  the identity provider (OIDC, SCIM); the API lists them and puts them in
+  the tree, and `llmgw users` approves, disables and deletes them. Key
+  lifetime limits and spending limits are `llmgw keys ttl` and `llmgw keys
+  limits`.
 - **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

docs/clients.md

@@ -38,6 +38,14 @@ export ANTHROPIC_BASE_URL=https://llm.example.com
 export ANTHROPIC_API_KEY=$LLMGW_API_KEY
 ```
 
+### The API described
+
+Every endpoint is described in OpenAPI 3.1 at `/v1/openapi.json`. It needs
+no key, so a client generator can be pointed at it. `/docs/api` shows it in
+Swagger UI, where *Authorize* takes a key and *Try it out* sends a request to
+the gateway. People with a part in running the gateway also find the admin
+API's document there.
+
 ## A first request
 
 ### curl
@@ -526,6 +534,73 @@ curl https://llm.example.com/mcp \
   -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
 ```
 
+**Pictures, 3D models, vision and workflows.** Where the gateway has the
+models for them, the same server offers more tools — only those it has a
+model for:
+
+| Tool | Does |
+|---|---|
+| `generate_image` | A picture from a prompt. `style` adds what a picture for a mesh wants: `concept` (one object, three-quarter view, grey background), `side` (an exact side view), `texture` (a seamless tile) or `none`. Answers the PNG's `file_id`, `url` and `seed`, with a 512 px preview to look at. |
+| `generate_mesh` | A GLB from a picture — `image` is a `file-…` id (a `generate_image` result, say), a data URL or base64 — or from a `prompt`, for which a concept picture is made first. `seed`, `resolution`, `texture_resolution`, and any other input the model's workflow declares in `inputs`. Answers the GLB's `file_id`, `url` and licence. |
+| `review_images` | Asks a vision model about one to four pictures (each shrunk to 1280 px on its long side); `json_schema` makes it answer that JSON. |
+| `run_workflow` | Runs a ComfyUI workflow from the inputs its catalog entry declares, and answers its result file. |
+| `job_status` | Where a mesh or a workflow run stands, and its file when done; `wait_seconds` waits for it. |
+| `gateway_status` | The picture, 3D, vision and workflow models, whether each is loaded on a GPU now, a workflow's inputs, and your last jobs. |
+
+Each tool makes its request of the gateway under your key, so your
+allowlist, limits, left-out licences and budget apply, and it is charged
+and listed like any other request. What it makes is kept as your file for
+as long as job results are: fetch it from `url` with the same key (`curl -H
+"Authorization: Bearer $LLMGW_API_KEY" -o rock.glb <url>`). A tool server
+over HTTP cannot write to your disk, so an agent that needs the file
+locally — to import it in Blender — fetches it, or goes through a small
+local bridge that does.
+
+A picture can be uploaded once and named by its id after: `POST /v1/files`
+with `purpose=vision` (or `user_data`) keeps it, for as long as job results
+are kept, as a file of yours that `generate_mesh`, `review_images` and a
+workflow's file inputs take as `file-…`. A call is at most 64 MB.
+
+A model that is not loaded is waited for: a picture or a look at one whose
+model is starting, or waiting for another to give up the GPU, waits as a
+mesh does, saying so, rather than failing with "model loading".
+
+A mesh takes from half a minute to a few minutes. A client that takes the
+answer as a stream (`Accept: text/event-stream`, as Claude Code does) is
+answered that way: `notifications/progress` for the call's
+`progressToken` while it runs — queued, waiting for the GPU, the node and
+its percent — then the result, and the call waits up to ten minutes. One
+answered in one piece waits 50 seconds; a job not done by then is answered
+with its `job_id`, to ask after with `job_status`. `wait_seconds` (up to
+900) sets either.
+
+```
+claude mcp add --transport http llmgw https://llm.example.com/mcp \
+  --header "Authorization: Bearer $LLMGW_API_KEY"
+```
+
+**Your company's tools.** Where an administrator has registered the
+company's own MCP servers (Jira, a file server, a database) and your key is
+granted their tools, the same `/mcp` lists them too, each as `server.tool`
+(`jira.search`). Give your agent only llmgw's `/mcp` and your key: the
+servers' own credentials stay with llmgw. A tool your key is not granted is
+not listed, and calling it by name is refused. Each call is in the audit
+log under your key: which tool, the size of what was sent, how it ended and
+how long it took, never what it said.
+
+### Licences you leave out
+
+A model's licence is in `/v1/models` (`license`: its `id`, `name`, whether
+it allows commercial use and the regions it grants nothing in). On your
+profile page, under **Licences**, you can leave licences out: one by one,
+every licence that forbids commercial use, or every licence that grants
+nothing in a region you name (`EU` for the union). The rules cover models
+added later too. From then on those models are not listed to your keys and
+a request for one is refused with 403 and the code `licence_excluded`,
+naming the choice that left it out — on every key you own and on the
+portal's pages, whatever a key's own allowlist says. A change reaches keys
+already in use within a minute.
+
 ### Headers llmgw sends back
 
 | Header | Says |
@@ -545,9 +620,10 @@ its usual exception with the gateway's message in it. The ones worth knowing:
 |---|---|
 | 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. |
+| 403 | The key may not use that model; with the code `licence_excluded`, its licence is one you left out on your profile page. |
 | 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. |
+| 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 queue is full. The SDKs retry by themselves; a name that is not served will not start to be. |
+| 504 | Every replica was busy for as long as the key's band may wait. `Retry-After` says when to send it again. |
 
 ## Priority
 

docs/console.md

@@ -2,8 +2,8 @@
 
 `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
+console described here; on a node, the node's own console, which shows
+what runs on that machine and 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.
 
@@ -164,6 +164,15 @@ which): requests, tokens, errors and spend.
 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.
 
+**Knowledge** lists the knowledge-base collections: each one's owner, the
+model that embeds it, how many documents and chunks it holds and who else it
+is granted to. **A** makes one. On a row: its **Documents**, **Grant…** a
+project, team, organization, person or key read or write access, **Revoke**
+a grant, **Answer from it by default…** for a part of the tree, **Try a
+search…** as an administrator, or **Delete…** it. People
+fill collections from their own machines with `llmgw-kb`
+([knowledge.md](knowledge.md)). Off on a SQLite store, and says why.
+
 **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
@@ -237,6 +246,28 @@ long a key made there may live, and is the expiry of one made without any
 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.
 
+**Sign-in** — how people get in besides a password kept here: single
+sign-on, Active Directory and provisioning, each on or off, with the
+directory's last sync (how many people, accounts kept in step, suspended,
+reinstated).
+- **E** sets up Entra ID. Give the tenant ID, the client ID and secret,
+  and the groups for administrators and operators. A provider other than
+  Entra takes its issuer URL in place of the tenant. The form shows the
+  redirect address to register.
+- **D** sets up Active Directory: the servers, where people are, the
+  service account and its password, the domain's CA certificate as a PEM
+  file on this machine, the group whose members may sign in, and groups
+  for roles and teams.
+- Before it is kept, the directory is tried from the control plane: each
+  server reached and bound, how many people may sign in, how many are in
+  each group. If any step fails, nothing is kept and the steps are shown.
+  **T** tries the settings in force.
+- On the provisioning row, Enter makes a SCIM token, shown once.
+- The password, the client secret and the token are kept in the store,
+  sealed by the master key when one is set. The settings name them as
+  `store:auth/…`, so each control plane has them with no file put on it.
+  The CA is written into the settings themselves.
+
 **Guardrails…** on a row lists the guardrail policies server.yaml defines.
 Each policy is marked in one of three ways:
 
@@ -326,5 +357,18 @@ to restart it.
 
 ## 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.
+On a node, `sudo llmgw` opens on **Overview**: what this machine is doing, read
+on the machine itself, so it works without an admin token and while the control
+plane is out of reach. Refreshed every three seconds, it shows
+
+- llmgw-agent's state and since when, and the version of llmgw;
+- each control plane the agent dials, from `agent.yaml` and the list the
+  leader last sent, and whether it can be reached;
+- each GPU: how busy, its memory, its heat, and the models on it;
+- the engines running here, from the agent's own records: replica, model,
+  engine, GPUs, port, whether the process is still there, and for how long;
+- the free space where weights and engines are kept;
+- the agent's warnings and errors of the last hour.
+
+Below it, `agent.yaml` in the same settings view, and the manual. The cluster
+is watched and changed from a control plane.

docs/data.md

@@ -72,7 +72,9 @@ 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
+policy. A project that reuses answers to similar questions (`--similar`)
+also has each question's last user message embedded, and the vector kept
+beside its answer, in the same memory and for as long. 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.
 

docs/guardrails.md

@@ -4,7 +4,7 @@ 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 Llama Guard 3 1B as its judge on a CPU; see
+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
@@ -15,6 +15,19 @@ checked and nothing costs anything. With one, every request is judged once it is
 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
@@ -78,6 +91,21 @@ guard:
   value is the same placeholder throughout a request).
 - **`block`** stops it.
 
+**Putting them back.** With `restore: true` in a policy's `input`, the
+values a request had redacted are put back in its answer: the model reads
+"write to [PERSON_1] at [EMAIL_1]", the client reads the name and address
+it sent. Streamed answers too — a placeholder split across two events is
+held until it is whole. Only that request's own values, only into its
+answer; the map is kept in memory for the request and nowhere else. The
+output rules then read the answer as the client will, so a policy that
+redacts personal data in answers still does.
+
+```yaml
+input:
+  pii: {email: redact, phone: redact}
+  restore: true
+```
+
 **Shapes.**
 
 - `system_prompt` is put first.
@@ -101,44 +129,136 @@ guard:
 
 ## A judge model
 
-Patterns find what has a shape. For what does not — violence, self-harm,
-abuse, whatever a moderation model was trained on — a policy can have a
-**judge model on the cluster** read the text:
+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: llama-guard-3-1b
-  source: http://mirror:8081/llama-guard-3-1b/…/Llama-Guard-3-1B-Q4_K_M.gguf
+- name: qwen3guard-0.6b
+  source: http://mirror:8081/qwen3guard-0.6b/…/Qwen3Guard-Gen-0.6B.Q8_0.gguf
   role: guard
   guard:
-    format: llamaguard3        # llamaguard3, shieldgemma or json
-    categories: [Violent Crimes, Non-Violent Crimes, Sex-Related Crimes, …]  # names for S1, S2, …
+    format: qwen3guard         # qwen3guard, llamaguard3, shieldgemma or json
   scaling: {min: 2, max: 2}
   profiles: [{name: cpu, engine: llamacpp}]
 
 # in a guard policy
 judge:
-  model: llama-guard-3-1b
+  models: [qwen3guard-0.6b]    # or model: one judge
   input: block                 # flag or block; empty does not ask about input
   output: flag
-  categories: [S1, S10]        # only these count; empty: any unsafe verdict
-  latency_budget: 250ms        # then the policy's fail: open serves (flagged), closed refuses
+  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 is `critical` by default and must always run — on demand is refused.
-  Give it two replicas on different nodes, because every judged request
-  waits on it.
+- 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:**
-  - `llamaguard3` reads Meta's "safe" / "unsafe
-S1,S10".
+  - `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": [...]}`.
@@ -148,8 +268,44 @@ S1,S10".
     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.
 
+## An outside service
+
+A site required to use a particular guardrail — Azure Content Safety,
+Lakera Guard, NeMo Guardrails, a classifier of its own — names it in a
+policy's `services`. It is asked over HTTP beside the patterns and before
+the judge; its "unsafe" blocks or flags like theirs, and a service that does
+not answer is what the policy's `fail` says.
+
+```yaml
+policies:
+  strict:
+    fail: closed
+    services:
+      - name: lakera
+        url: https://api.lakera.ai/v2/guard
+        header_files: {Authorization: /etc/llmgw/secrets/lakera}   # "Bearer …", read each call
+        body: '{"messages": [{"role": "user", "content": {{json .Text}}}]}'
+        blocked: flagged                 # where the answer says unsafe
+        reason: breakdown.0.detector_type
+        on: both                         # input, output or both
+        action: block                    # or flag
+        timeout: 2s
+```
+
+`body` is a template given `.Text` (`{{json .Text}}` writes it as a JSON
+string; empty sends `{"input": …}`). `blocked` and `reason` are dotted paths
+into the JSON answer, numbers for list items; true, a number above zero, a
+non-empty list or a string other than "false" is unsafe. On input the
+service reads the latest user turn; on output the whole answer, once, at its
+end — a streamed answer released a sentence at a time is then stopped or
+flagged as the judge's is. The rule recorded is `service:<name>:<reason>`.
+The service is told the text only, never who sent it.
+
 ## Where a policy applies
 
 `guard.default` applies everywhere. Others are attached to a part of the

docs/install.md

@@ -89,13 +89,36 @@ CGO_ENABLED=0 go build -o llmgw ./cmd/llmgw
 
 **The short way is the screens.** On the machine that will be the control
 plane, run `sudo llmgw` with nothing after it. With nothing installed it asks
-whether this is one machine or three for high availability; for three, it asks
-for the other two — address, user, and an ssh key, the ssh agent, or a
-password, and the sudo password if sudo asks for one; or, for a machine
-nothing may log into, a join code to run there with `sudo llmgw join <code>`,
-which dials out to this one on port 7444 — checks all three before
-installing anything (system, room, clock, ports, internet, whether they reach
-one another), shows the plan, and installs. Passwords are held in memory for
+whether this is one machine or three for high availability, then lists what
+an install is made of, each part with what it is for and what is missing
+without it:
+
+| Part | | Its settings (Enter) |
+|---|---|---|
+| Control plane | always | the administrator, other names for the certificate, the portal's language, the sign-up form |
+| Store | always | SQLite or PostgreSQL on this machine; with three machines, PostgreSQL under Patroni on the other two |
+| Control plane on all three | three machines, on | a floating address for whichever leads |
+| Model mirror | on | here, and in which directory, or on another machine |
+| This machine as a node | on for one machine | |
+| Starter model | on for one machine | which: Qwen2.5 0.5B, 1.5B or 3B, Qwen3 4B, 8B or 14B, or any GGUF on Hugging Face; its context |
+| Pictures and 3D | off | |
+| Guardrails' judge | on | refuse or serve flagged when it does not answer; copies; how long it is waited for; what it refuses |
+| Firewall | on | |
+| Notifications | off | the webhooks |
+| Limits and keys | always | requests and tokens a minute; the longest a key lives |
+| Taking turns on a card | always | how long an on-demand model goes unused, and is safe after loading |
+| Offline bundle | off | the bundle and its sha256 |
+
+Space turns a part on or off; Enter opens its settings, which say more. What
+cannot go together is said before anything is done — a starter model with no
+mirror to fetch it into — and closing the message opens the setting that is
+wrong. For three machines it then asks for the other two — address, user, and
+an ssh key, the ssh agent, or a password, and the sudo password if sudo asks
+for one; or, for a machine nothing may log into, a join code to run there
+with `sudo llmgw join <code>`, which dials out to this one on port 7444 —
+checks all three before installing anything (system, room, clock, ports,
+internet, whether they reach one another). Last it shows the plan, part by
+part, what is left out and what that costs, and installs. Passwords are held in memory for
 the run only; a sudo password lets the user sudo without one until the install
 finishes, and is then taken back. At the end it shows the administrator's
 password and the command that does the same from a script.
@@ -129,14 +152,24 @@ That is the whole step. In order, it:
    `nvidia-smi` finds any, on CPU otherwise — and waits for it to install its
    engine
 9. closes llmgw's internal ports to everything but the cluster's networks
-10. fetches Llama Guard 3 1B, the guardrails' judge, and runs two replicas
-    on the CPUs of nodes with room — this one, or the first that join
+10. fetches Qwen3Guard-Gen 0.6B, the guardrails' judge, and runs it on
+    CPUs: one replica on up to four cores when this machine is the only
+    node, two on two cores each on the nodes of a larger cluster ([guardrails.md](guardrails.md#a-judge-model) has one on a GPU too)
 11. fetches Qwen2.5 0.5B into the mirror and serves it on this node, so the
     first thing anyone opens `/chat` to find is a model that answers. A
     machine without room for it is told so within two minutes, and why.
 
 `--no-mirror` and `--no-node` leave out 7 and 8, `--no-firewall` 9,
-`--no-guard-model` 10 and `--no-model` 11. An NVIDIA card with no working
+`--no-guard-model` 10 and `--no-model` 11. Every setting the screens ask for
+is a flag too, and the plan shows the command with them: `--starter qwen3-8b`
+(or `hf:<owner>/<repo>/<file>.gguf`) and `--starter-context`, `--mirror-dir`,
+`--judge-fail open`, `--judge-categories`, `--judge-replicas`,
+`--judge-budget`, `--language tr`, `--signup-open`, `--default-rpm`,
+`--default-tpm`, `--max-key-ttl`, `--media` (pictures and 3D: ComfyUI on the
+nodes, and `presets.auto`), `--evict-after-idle` and `--min-lifetime`. They
+go into `server.yaml` as init writes it, and become the cluster's first
+settings when it starts; a `server.yaml` already there is never overwritten,
+so run again they change nothing — the settings page does. An NVIDIA card with no working
 driver is reported rather than silently ignored; install the driver and run
 init again to serve on it.
 
@@ -154,15 +187,43 @@ demonstration one:
 | Requests | every key limited (60 a minute, 200 000 tokens a minute) and priced, so budgets bind |
 | Guardrails | the `baseline` policy on every request: secrets in prompts and answers refused, card numbers masked, injection attempts recorded, and the judge refusing violence, crime, weapons, child abuse, privacy violations, hate, self-harm and sexual content, in prompts and answers |
 
-The judge runs as two replicas, each on a CPU — about half a second for a
-short text on any CPU with AVX2 — and reads a streamed answer every 600
-characters. The policy fails **closed**: a request the judge cannot read
-within 5 seconds is refused with 503 rather than served unjudged, and
-`judge_unavailable` goes to the notification webhooks. Two replicas are what
-make that bearable; on one small machine, or a VM without AVX2 (see
+The judge runs on CPUs. A judgment of about 280 tokens took 2.3 s on four
+cores, 4.2 s on two and 8.0 s on one (a 4-core VM). It also reads a
+streamed answer every 600 characters. The policy fails **closed**: a request
+the judge cannot read within 5 seconds is refused with 503 rather than
+served unjudged, and `judge_unavailable` goes to the notification webhooks.
+So a judge gets cores of its own: on one machine one replica on up to four,
+and on a larger cluster two replicas of two cores each, spread over its nodes
+so that losing one leaves the other. On a machine of fewer than four cores,
+a busy one, or a VM without AVX2 (see
 [step 6](#6-setting-the-nodes-cpu-model-if-it-is-a-vm)), the judge is the
-first thing to fail, so `fail: open` — serve it, recorded as flagged — or
-`--no-guard-model` is the choice there. Defamation, specialized advice,
+first thing to fail. The choices there are a longer `latency_budget`,
+`fail: open` (serve the request, recorded as flagged), the judge on a GPU,
+or `--no-guard-model`.
+
+init times the judge once it is up. If a judgment takes more than half the
+wait, or more than the wait when several come at once, it says so before the
+next steps, with what to do. The wait itself is not changed without being
+asked. `llmgw ctl guard judge check` does the same at any time:
+
+```
+qwen3guard-0.6b, 2 replica(s) ready, a request waits 5.0 s for it
+  alone:    2.4, 2.3, 2.3 s
+  4 at once: slowest 6.1 s; about 0.7 judgments a second, so about 0.3 requests a second with short answers
+tight: a busy moment passes the budget
+```
+
+In a three-machine install the judges are better on machines of their own.
+On a 4-core control plane that was also a node, 38 of 60 requests under load
+were refused for want of a judgment. With the judges on a node of their own
+(4 cores, two judges of two cores each), 2 were refused. The setup screen asks
+for up to two **judge machines** after the store's two, or give
+`--judge-node user@host` to `server init`, once for each. Each is added as a
+node labelled `llmgw.role: judge`, and the judge's profile selects that
+label, so the judges run only there and nothing else does. Four cores and
+8 GB are enough for two judges.
+
+Defamation, specialized advice,
 intellectual property and elections are left out of what it refuses: they
 catch too much ordinary work. [guardrails.md](guardrails.md) has the rest.
 
@@ -200,6 +261,16 @@ this by running the same command again, on the control plane that holds the
 authority: etcd is rebuilt on TLS with Patroni in maintenance mode, so
 PostgreSQL serves throughout and no failover happens.
 
+Each member's PostgreSQL is sized to the machine's memory, read each time
+the command runs: a quarter of it as cache (`shared_buffers`), three quarters
+counted on for the planner, and room to sort and build indexes, all capped. A
+member that also runs a control plane or an agent gets less: about 15% as
+cache, so the gateway is not pushed into swap. A knowledge base's vector
+index is searched well only from memory, so give a store machine more RAM and
+run the command again. The new cache takes a PostgreSQL restart, which Patroni
+does one member at a time, the leader last. The leader's restart costs a few
+seconds without writes, and there is no failover.
+
 Every step looks before it acts. Running it again finishes an install that
 stopped halfway and changes nothing on one that did not; it never overwrites
 `server.yaml`, the authority, or an existing account's password.
@@ -257,8 +328,14 @@ llmgw ctl config history                 # who changed what, when, and why
 llmgw ctl config rollback 4              # back to version 4, as a new version
 ```
 
-or on the console's **Settings** screen. A change is checked before it is
-kept — one that would not load is refused — and recorded in the audit log.
+or on the console's **Settings** screen, or in a browser on the portal's
+**Settings** page (`/admin/settings`, for administrators only: the document
+can hold webhook secrets). The page edits the same document, lists its
+history, and puts an earlier version back. A change is checked before it is
+kept, so one that would not load is refused. A change made from a version
+someone else has replaced since is refused too, rather than overwriting
+theirs. Every change is recorded in the audit log, with the document's size
+but not its contents.
 Guardrails change live; anything else has every control plane start again on
 the new settings, the standbys first and the leader half a minute later, so
 one of them is always serving. Engines keep running through it.
@@ -268,6 +345,33 @@ cluster keys — with a `baseline` guard policy, if the file had none — and
 from then on those keys in any server.yaml are not read (the server says so
 when it starts).
 
+**The nodes' agents** are set the same way, under `agents`. `agents.default`
+is for every node, and `agents.nodes.<node-id>` is for one node, laid over
+the default:
+
+```
+llmgw ctl config set agents.default.heartbeat_interval 5s
+llmgw ctl config set agents.nodes.cuda01.labels.gpu rtx6000
+llmgw ctl config edit                    # fabrics, engines, supervisor, discovery…
+```
+
+Each node's `agent.yaml` then needs only what its agent must know before it
+can be told anything: `node_id`, `server` or `servers`, `hostname`,
+`mgmt_addr` and `tls`. Those keys are refused under `agents`.
+
+- **Precedence.** Anything else in the file is still read, with the
+  cluster's settings over it.
+- **Applying a change.** The control plane sends each node its settings, a
+  second apart. An agent whose settings changed keeps them beside its
+  `agent.yaml` (in `/var/lib/llmgw-agent/agent-settings.yaml`) and starts
+  again on them, its engines serving throughout.
+- **Bad settings.** Settings that would not load are refused when they are
+  saved. If they somehow do not load beside one node's own file, that agent
+  keeps running on what it has and logs why.
+- **Editing `agent.yaml` itself.** The agent notices the change within ten
+  seconds and starts again on it. If the edited file does not load, the
+  agent reports it and keeps running on what it had.
+
 **This machine's own keys** stay in `/etc/llmgw/server.yaml`: `listen`,
 `admin_listen`, `metrics_listen`, `agent_listen`, `agent_tls`, `auth.store`,
 `secrets`, `tracing`, `monitoring`, `mirror.api` and `mirror.tls`, the backup
@@ -287,7 +391,11 @@ by itself. Three things are worth knowing before you edit it:
 - `default_rpm`, `default_tpm` and `default_price` are what make limits and
   budgets mean anything. Without a price every request costs zero and a budget
   never binds; without the defaults, a project created without limits is
-  metered by nothing at all.
+  metered by nothing at all. A price may set `cached_per_1k` beside
+  `prompt_per_1k`: the prompt tokens the engine or provider read from its
+  cache (the answer's `cached_tokens`) are charged at it, the rest at the
+  prompt rate. A provider that bills cached reads at a tenth is
+  `{prompt_per_1k: 2500, cached_per_1k: 250, completion_per_1k: 10000}`.
 - `control.enabled: true` is what makes this a control plane while its catalog
   is empty. Without it, a file with no models is refused as having nothing to
   serve.
@@ -994,6 +1102,27 @@ qwen2.5-coder-3b-instruct  yes      1/1       ready    coder
 No restart, and it survives one: models added this way are stored, while
 anything in `server.yaml` is declarative and returns on every start.
 
+A profile may load weights of its own. An embedding model, for example, can
+be served by vLLM from its repository on a card and by llama.cpp from a GGUF
+on CPUs, as one model:
+
+```yaml
+name: qwen3-embed-4b
+source: Qwen/Qwen3-Embedding-4B          # what a profile loads unless it says
+capabilities: { embeddings: true }
+profiles:
+  - name: gpu
+    engine: vllm
+    gpu_class: 6000-24g
+    args: ["--runner", "pooling"]
+  - name: cpu
+    engine: llamacpp
+    source: hf:Qwen/Qwen3-Embedding-4B-GGUF/Qwen3-Embedding-4B-Q8_0.gguf
+```
+
+Updates and canaries move the model's `source`; a profile with its own keeps
+it.
+
 ### Models that load when someone asks
 
 A cluster with more models than GPUs can hold every model in its catalog and
@@ -1222,10 +1351,185 @@ catalog, and a key rotated in the file is used within seconds. A model whose key
 file cannot be read is not offered. Everything else applies as to any model:
 prices and budgets, rate limits, usage records, and key allowlists.
 
+A provider's limits are per key. With several keys, one answering 429 need not
+hold up the model: give them all, each with an optional weight (its share
+against the others'), in place of `api_key_file`:
+
+```yaml
+  external:
+    url: https://api.openai.com
+    model: gpt-4o-mini
+    api_key_files:
+      - {file: /etc/llmgw/secrets/openai-1.key, weight: 2}
+      - {file: /etc/llmgw/secrets/openai-2.key}
+```
+
+Each key is an endpoint of its own, `external:cloud-mini#1`, `#2`. A key that
+answers 429 is passed over while its breaker is open, and the request goes to
+another. One that answers 401 (revoked, expired, mistyped) is passed over too,
+and `external_key_refused` goes to the notification webhooks, naming the
+endpoint and never the key. The usage records say which key answered by the
+same name. A key whose file cannot be read is left out, and the others stay.
+
 **Its prompts leave the cluster.** Decide who may send them: a key or project
 whose allowlist leaves the external model out cannot reach it, as a fallback or
 by name. The cluster page and `ctl models` mark it `external`.
 
+### Pictures from ComfyUI
+
+Clients ask for pictures at OpenAI's `/v1/images/generations`. llmgw has them
+made by ComfyUI: it fills a ComfyUI workflow with the request, queues it,
+waits, and sends the pictures back as `b64_json`.
+
+**On the cluster's own cards.** Use engine `comfyui`. The model is placed on a
+GPU node like any other, started when asked for, and stopped when unused.
+
+**The short way: a preset.** Some models come with llmgw, with their
+workflow, custom nodes, packages and licence already found and tried:
+
+```
+llmgw ctl model presets
+llmgw ctl model add flux-schnell     # pictures, Apache 2.0, a card of 24 GB, Volta or newer
+llmgw ctl model add triposr          # 3D models from a picture, MIT, a card of 8 GB
+```
+
+A preset's profile says the card it needs, not a class, so it places on
+whatever cards the site has. When the cluster's settings name no ComfyUI,
+adding one sets `engines.comfyui` to the version this release installs, and
+every node with an NVIDIA GPU installs it; a cluster that names a version,
+or `""` for none, keeps it; the control planes then start again on that
+setting, standbys first.
+
+They also come by themselves. Once a node has a card that fits one, and the
+catalog has nothing that makes what it makes, the leader adds it, on demand —
+where the cluster already installs ComfyUI; it never sets `engines.comfyui`
+by itself. A preset somebody removes stays out until it is added again.
+`llmgw ctl model presets auto off` (the setting `presets.auto`) stops it.
+
+The cluster page on the portal has a **Pictures and 3D models** card under
+the models: each preset, the classes of card here it fits, whether it is in
+the catalog and who added it, why the leader has not, an **Add** button (one
+that would also install ComfyUI says so first) and the switch for adding
+them by themselves. In the console, the models screen shows the same: **A**
+adds one, **P** turns adding them by themselves on or off.
+`llmgw ctl model presets` prints it. The rest of this section is for a model
+of your own.
+
+The node must offer the engine. Ask for it in the cluster's settings, and every
+node with an NVIDIA GPU installs it:
+
+```
+llmgw ctl config set engines.comfyui 0.39.2
+```
+
+The agent fetches ComfyUI's source from GitHub and checks it against the
+digest llmgw holds for that version. GitHub publishes none for a tag's archive,
+so a version llmgw does not know is refused. The agent then builds a Python
+environment beside the source, under `/opt/llmgw/engines/comfyui/`. Its
+dependencies are resolved as PyPI stood the day after the release. torch comes
+from PyPI (CUDA 13), from PyTorch's CUDA 12.9 build where the driver is older
+than 580, or from its CUDA 12.6 build on cards older than Turing (a V100):
+torch's CUDA 12.8 and newer builds have no kernels for them. The install is
+checked on the node's GPU, and takes about 10 GB.
+`engine_overrides` can keep it off nodes that should not have it.
+
+Alternatively, install ComfyUI by hand. You need a directory with `main.py` and
+its environment in `.venv`, readable by the user engines run as
+(`llmgw-engine`). Name it in that node's `agent.yaml`; a node with one named
+there is not given the installed one:
+
+```yaml
+engines:
+  comfyui:
+    dir: /opt/comfyui            # python: defaults to /opt/comfyui/.venv/bin/python
+```
+
+Then add the model:
+
+```yaml
+- name: flux-schnell
+  source: hf:Comfy-Org/flux1-schnell/flux1-schnell-fp8.safetensors
+  comfyui:
+    workflow: flux-schnell       # or flux-dev, or a JSON file
+  scaling: {min: 0, max: 1, idle_timeout: 15m}
+  profiles:
+    - name: gpu
+      engine: comfyui
+      gpu_class: 6000-24g
+      tp: 1
+```
+
+The source is fetched as for any model. It can be one file, such as the
+single-file checkpoints the built-in workflows load. It can also be a mirror
+set (a URL ending in `/`) for a model in several files, such as a diffusion
+model, its text encoders and its VAE. ComfyUI sees every file of a set by its
+own name, so a workflow of your own can load each one. A set must name the
+file that `{{checkpoint}}` stands for in `comfyui.checkpoint`. A single file
+is named by its own file name.
+
+ComfyUI asks nobody for a key. The agent therefore starts it behind a gate
+(`llmgw comfyui-gate`). ComfyUI listens on the node's loopback only. The gate
+listens on the replica's port, demands the replica's key, and lets through only
+what the router asks: queueing, waiting, fetching a picture and cancelling.
+Uploads and node installs are refused. Each replica has its own directory,
+`~llmgw-engine/comfyui/REPLICA`, and ComfyUI's output can be read with `llmgw
+ctl logs NODE --source SHARD`. A profile's `args` go to `main.py`.
+`--disable-smart-memory` frees the card between pictures, at the cost of loading
+the model again for each one.
+
+**On a ComfyUI server outside the cluster.** Make it an external model with
+`api: comfyui`:
+
+```yaml
+- name: flux-schnell
+  source: external
+  external:
+    url: http://10.0.0.147:8188                  # ComfyUI, started with --listen
+    model: flux1-schnell-fp8.safetensors         # the checkpoint, as ComfyUI lists it
+    api: comfyui
+    workflow: flux-schnell                       # or flux-dev, or a JSON file
+```
+
+Like any external model, its requests count as leaving the cluster.
+
+`flux-schnell` (the default) and `flux-dev` are built in. They suit the
+single-file FLUX checkpoints that ComfyUI loads with `CheckpointLoaderSimple`.
+For any other model, export the workflow from ComfyUI with **Save (API)** and
+name the file. In the file, put placeholders where the request's values go:
+
+- `{{prompt}}` and `{{negative_prompt}}` are the prompts.
+- `{{width}}` and `{{height}}` are the size.
+- `{{n}}` is the batch size.
+- `{{seed}}` is the seed.
+- `{{steps|4}}` and `{{guidance|3.5}}` take the value after the `|` when the
+  request leaves them out.
+- `{{checkpoint}}` is the `model` above.
+
+A request is OpenAI's: `prompt`, `n` (at most 4), `size` (each side a multiple
+of 16, from 256 to 2048) and `response_format: b64_json`. Beyond those, it may
+send `seed`, `steps`, `negative_prompt` and `guidance`. The seed used comes
+back in `x-llmgw-seed`. `url` is not offered, because pictures are kept
+nowhere. ComfyUI also writes the workflow into each PNG; llmgw strips it
+before the picture is sent.
+
+Requests for pictures pass the same checks as any other request: keys,
+allowlists, limits, admission, and the guardrails on the prompt. A client that
+leaves takes its workflow off the ComfyUI queue.
+
+Each request's usage row records how many pictures it made (`llmgw ctl request
+ID` shows them). A picture's price is set with `per_image`, in micro-units like
+the other prices, and is charged on top of the prompt's tokens:
+
+```yaml
+auth:
+  pricing:
+    flux-schnell: {prompt_per_1k: 0, per_image: 20000}
+```
+
+An external ComfyUI on a card that llmgw also places models on should be
+started with `--disable-smart-memory`. Without it, ComfyUI keeps the model on
+the card after each picture, and llmgw sees that memory as somebody else's.
+
 ### Federating clusters
 
 Another llmgw cluster — another site, another team's GPUs — can be a provider
@@ -1506,6 +1810,7 @@ and accounting exactly as an API call does.
 | `POST /v1/audio/transcriptions`, `/v1/audio/translations` | the multipart form passed through as it came, to an engine that serves speech to text: vLLM with Whisper |
 | `POST /v1/moderations` | answered by the guardrails' judge model (`role: guard`): `flagged`, and the judge's own categories |
 | `/v1/files`, `/v1/batches` | batches; see [Batches](#batches) |
+| `/v1/3d/generations` | 3D models, as jobs asked after; see [Jobs](#jobs-3d-models) |
 | `GET /v1/models` | the models this key may use |
 
 ## Watching it
@@ -1606,6 +1911,23 @@ same event about the same thing is sent at most once an hour, so a budget that
 refuses a thousand requests is one message. `llmgw ctl notify test` sends a
 test event to each webhook and says how each answered.
 
+Setup asks for them: **Notification webhooks** on its first page, or
+`--webhook` to `llmgw server init`, as often as there are webhooks:
+
+```
+sudo llmgw server init --admin ops@example.com \
+  --webhook https://hooks.slack.com/services/… \
+  --webhook json:https://ops.example.com/llmgw
+```
+
+An address of Slack's, or one with `/hooks/` in it (Mattermost, Rocket.Chat)
+or ending in `/slack`, is sent Slack's `{"text": …}`; any other the event as
+JSON; `slack:` or `json:` in front says which. They are added to the
+cluster's settings beside any already there — run again, nothing is added
+twice — and once the control plane runs on them, each is sent a test, whose
+answer setup prints. Events to choose and a signing secret are set in the
+settings afterwards (`llmgw ctl config edit`).
+
 ### Tracing
 
 Metrics say that a model took four minutes to start; a trace says where they
@@ -1639,6 +1961,18 @@ So "why did qwen take four minutes to start" is one trace: find `replica start`
 with `llmgw.model` = qwen, and the node's spans beneath it say whether the
 time went to the download, the launch or the engine loading.
 
+An inference request and each `upstream` attempt also carry the
+[OpenTelemetry GenAI conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/),
+so a tool that reads them — Grafana, Jaeger, Langfuse, Arize Phoenix — shows
+llmgw's calls as model calls without a dashboard made for llmgw:
+`gen_ai.operation.name` (`chat`, `text_completion`, `embeddings`),
+`gen_ai.request.model`, `gen_ai.request.max_tokens`, `temperature` and `top_p`
+when the client set them, `gen_ai.conversation.id` (the session),
+`gen_ai.response.model`, and `gen_ai.usage.input_tokens`, `output_tokens` and
+`cache_read.input_tokens`. On an `upstream` span `gen_ai.provider.name` is the
+engine that answered (`vllm`, `llamacpp`, `external`, …). What was asked and
+what was answered are never in a span.
+
 A node follows the control plane's decision: a start the control plane kept is
 traced on the node whatever the agent's own `sample_ratio`, and one it sampled
 out is not; the agent's ratio decides only for what arrives with no trace, as
@@ -1702,9 +2036,11 @@ the file again.
 
 On a machine that also runs the control plane, PostgreSQL's defaults assume it
 owns the box. A gateway swapped out to give the database cache is a worse
-outcome than a smaller cache, so cap it: `shared_buffers = 96MB` and
-`max_connections = 40` are enough for a store whose working set is measured in
-megabytes.
+outcome than a smaller cache, so size it to the machine. `server init` does this
+for a PostgreSQL it installs: `shared_buffers` about 15% of memory (at least
+96MB), `effective_cache_size` half, `work_mem` and `maintenance_work_mem`
+scaled to it, and `max_connections = 40`. A store with a large knowledge base
+wants a machine of its own, where its vector index fits in memory.
 
 ## Tagging requests
 
@@ -1822,8 +2158,46 @@ router:
     max_entry_bytes: 2097152 # 2 MB
 ```
 
-`llmgw_cache_requests_total{model,result}` counts hits, misses and
-bypasses, `llmgw_cache_bytes` and `llmgw_cache_entries` what is held. The
+### Similar questions
+
+A help desk asked "how do I reset my password" in forty wordings asks the
+model forty times under the exact cache. `--similar` also gives a chat
+question the answer to one like it:
+
+```
+llmgw keys cache --project Acme/support/desk --ttl 24h --similar 0.95
+```
+
+```yaml
+router:
+  cache:
+    embedding_model: bge-m3   # an embedding model in the catalog
+```
+
+- **What is compared:** the last user message, embedded by
+  `router.cache.embedding_model`, against the questions already answered
+  in the same conversation — the same system prompt, the same earlier turns,
+  tools, `response_format` and sampling settings, the same model and
+  project. A like question in another conversation, or after a tool's
+  result, is not taken for this one. The exact cache is asked first, and an
+  exact hit embeds nothing.
+- **How alike:** the cosine similarity of the two embeddings, at least the
+  project's `--similar`. 0.95 is strict; below 0.9 different questions start
+  to meet. A question that differs only in a number or a name ("2+2" and
+  "2+3") can be closer than that, so a project whose questions turn on
+  figures should not use it. A question over 2,000 characters is reused only
+  when it is the same.
+- **Said:** `x-llmgw-cache: similar`, with `x-llmgw-cache-similarity`
+  and `Age`. Recorded and charged as a hit. The same rules as a hit decide
+  which answers are reused and kept; guardrails judge the request before.
+- **The embedding** is asked of the model by the gateway on its own account,
+  as a judge is, within 2 seconds; every miss waits for it. Without the
+  model, or when it does not answer, only the same request is reused. The
+  vectors are kept in memory with their answers and counted in
+  `router.cache.max_bytes`.
+
+`llmgw_cache_requests_total{model,result}` counts hits, similar hits, misses
+and bypasses, `llmgw_cache_bytes` and `llmgw_cache_entries` what is held. The
 console has it as **Cache answers…** on a project.
 
 ## Batches
@@ -1862,6 +2236,142 @@ Each line of the file is `{"custom_id": …, "method": "POST", "url":
   or past their retention — a project under a guardrails policy with
   `no_store` is refused it.
 
+## Jobs: 3D models
+
+A 3D model from a picture takes minutes on a card that first has to be
+emptied of whatever else was on it. No client should hold a connection for
+that, so it is a job: queued, answered with an id, asked after, its result
+downloaded.
+
+```
+curl http://gateway:8080/v1/3d/generations -H "Authorization: Bearer $LLMGW_API_KEY" \
+  -d '{"model": "trellis2", "image": "<base64>"}'
+# → 202 {"id": "job_…", "status": "queued", …}
+curl http://gateway:8080/v1/3d/generations/job_… -H "Authorization: Bearer $LLMGW_API_KEY"
+# → {"status": "completed", "output_file_id": "file-…", "content_type": "model/gltf-binary", "usage": {…}}
+curl http://gateway:8080/v1/files/file-…/content -H "Authorization: Bearer $LLMGW_API_KEY" -o model.glb
+curl -X POST http://gateway:8080/v1/3d/generations/job_…/cancel -H "Authorization: Bearer $LLMGW_API_KEY"
+```
+
+- **Status:** `queued`, `running`, `completed`, `failed` (with `error`),
+  `cancelling`, `cancelled`, `expired` (not finished within 24 h).
+  `progress` carries what the engine said of the work so far, once it says
+  anything; `GET /v1/3d/generations` lists the caller's jobs. While the
+  model waits for another on-demand model to give up the card,
+  `progress` is `{"state":"waiting_gpu","held_by":"flux-schnell","eta_seconds":N}`:
+  N is when the holder is stopped (idle and old enough to evict, or at its
+  idle timeout) plus how long the model's last start took, and is left out
+  when that is not known. A request made directly gets the same as a 503
+  with `X-Llmgw-Waiting-For`, `X-Llmgw-Eta-Seconds` and `Retry-After`.
+- **Refused at the door:** no key, a model that is not there or not in the
+  key's allowlist, a request the model cannot serve. Refused when served,
+  and said as the job's error: a spent budget, the guardrails, a model
+  that will not come up.
+- **How it is served:** the request is kept as it was sent and replayed by
+  whichever gateway holds the job's lease, through the same path a
+  client's request takes — limits, admission in the key's band, guardrails,
+  accounting — by the leading control plane, since a standby has nothing
+  to send it to. A model said to fit nowhere is asked for again for five
+  minutes before that is the job's error: an agent re-registering says so
+  for a few seconds. It is one usage record under the job's id, tagged
+  `job=<id>`, charged like any request; `GET` shows the usage once it is
+  done. A model still loading, a rate limit or a full queue is waited out
+  for as long as the job has: nobody is holding a connection, which is the
+  point.
+- **Surviving a restart:** a gateway that stops hands its jobs to another
+  within two minutes; a job it was running is run again from the start.
+- **What it keeps:** the request as sent, and the result as a file owned
+  by the key's project, kept `router.batch.retain_days` (30) like a batch's
+  files; the job's record goes with it. A project under a `no_store`
+  policy is refused jobs, as it is batches.
+
+A request may also send `seed` and `resolution` (the model's own grid, a
+multiple of 32 from 64 to 2048). The picture should show one object on a
+plain background: the model makes a mesh of what it sees, background
+included.
+
+### A model that makes them
+
+A 3D model is made by a ComfyUI model whose `comfyui.output` is `meshes`
+(see [Pictures from ComfyUI](#pictures-from-comfyui) for engine `comfyui`).
+Its workflow is a JSON file in ComfyUI's API format: `{{image}}` is the
+uploaded picture, which a `LoadImage` node reads; `{{seed}}`,
+`{{resolution|256}}` and `{{checkpoint}}` are as for pictures. The node that
+saves the mesh may save a GLB or an OBJ; an OBJ leaves the gateway as a GLB,
+vertex colours kept.
+
+TripoSR (MIT), on any card of 8 GB, comes with llmgw: `llmgw ctl model add
+triposr`. What that adds is this entry, and its workflow is built in:
+
+```yaml
+- name: triposr
+  source: hf:stabilityai/TripoSR/model.ckpt
+  comfyui:
+    workflow: triposr              # built in; a model of your own names a JSON file on every control plane
+    output: meshes
+    nodes:
+      - repo: https://github.com/flowtyone/ComfyUI-Flowty-TripoSR
+        commit: a0c94ac60a7cc062604f61aeeea6d0d493521de3
+        requirements: [omegaconf, trimesh, scikit-image, imageio,
+                       "transformers>=4.50.3,<5", "huggingface-hub<1", tokenizers,
+                       rembg, onnxruntime]
+  license:
+    id: MIT
+    name: MIT
+    commercial: true
+    url: https://huggingface.co/stabilityai/TripoSR/blob/main/LICENSE
+    notice: "Made with TripoSR (Stability AI and Tripo AI, MIT). ..."
+  scaling: {min: 0, max: 1, idle_timeout: 10m}
+  profiles:
+    - {name: gpu, engine: comfyui, tp: 1, gpu: {min_compute_capability: 7.0, min_memory_gb: 8}}
+```
+
+```json
+{
+  "1": {"class_type": "LoadImage", "inputs": {"image": "{{image}}"}},
+  "5": {"class_type": "LLMGWPrepareForMesh", "inputs": {"image": ["1", 0], "mask": ["1", 1],
+        "foreground_ratio": 0.85, "background": 0.5, "remove_background": "auto", "rembg_model": "u2net"}},
+  "2": {"class_type": "TripoSRModelLoader", "inputs": {"model": "{{checkpoint}}", "chunk_size": 8192}},
+  "3": {"class_type": "TripoSRSampler", "inputs": {"model": ["2", 0], "reference_image": ["5", 0],
+        "geometry_resolution": "{{resolution|256}}", "threshold": 25.0}},
+  "4": {"class_type": "TripoSRViewer", "inputs": {"mesh": ["3", 0]}}
+}
+```
+
+`LLMGWPrepareForMesh` comes with the gate: it cuts the object out — by the
+picture's alpha, or by rembg where it has none — and centres it on a plain
+background, without which the background becomes geometry.
+
+- **Custom nodes** are named by https repository and full commit (a branch
+  is refused: it moves). The gate puts each in the replica's own
+  `custom_nodes` and installs its `requirements` beside the replica, never
+  into ComfyUI's environment. A package named there is installed at the
+  range named; every other one at the version ComfyUI already runs. A
+  package named is first on ComfyUI's path, so its range must suit ComfyUI
+  as well. TripoSR's checkpoint loads with transformers 4, which ComfyUI's
+  `>=4.50.3` allows.
+- **Progress:** the gate listens to ComfyUI's websocket and the router
+  writes what it hears into the job: `{"state": "queued", "ahead": 2}`,
+  then `{"state": "running", "node_class": "KSampler", "step": 12,
+  "steps": 30, "percent": 40}` for a node that counts its steps, and
+  `done` at the end.
+- **Licence:** a model's `license` is shown in `/v1/models`, in the job and
+  on the portal, and written into the GLB's `asset.extras.license`, since
+  the file travels without the API. Choose the model for its licence before
+  its quality when what it makes is shipped. TRELLIS.2 needs Meta's gated
+  DINOv3 and, as published, a background remover under a non-commercial
+  licence; Hunyuan3D's licence excludes the EU, the UK and South Korea.
+- **Price:** `per_mesh` in `auth.pricing`, beside `per_image`; each usage
+  row says how many meshes it made (`meshes`).
+- **Cards:** the strongest models today (TRELLIS.2, Direct3D-S2) need
+  flash-attention, which runs on Ampere and newer. A Turing card such as
+  the RTX 6000 runs TripoSR.
+
+People make them at `/3d` on the portal: they choose a picture and watch
+the job, and the mesh is shown in a viewer (model-viewer, served from the
+gateway) with a download link and the licence. `llmgw ctl 3d list`, `get`
+and `cancel` show and stop every owner's jobs.
+
 ## Conversations across models
 
 Off everywhere until a project asks. llmgw otherwise stores no message content
@@ -1943,6 +2453,33 @@ Without authentication, `threads.store` and `threads.retain_hours` in
 `server.yaml` keep both conversations and notes in one shared pool. That is for
 one trusted machine only; see [development.md](development.md).
 
+## Three machines, each a control plane
+
+The screens' three machines are high availability for the gateway as well as
+the store: the two database machines are made control planes too, standing
+by while the first leads — what `server add`, below, does for one machine.
+By command, `--standbys` with `--patroni`, and `--vip` for the floating
+address:
+
+```
+sudo --preserve-env=SSH_AUTH_SOCK llmgw server init --admin you@example.com \
+    --patroni ubuntu@10.0.0.6 --patroni ubuntu@10.0.0.7 \
+    --standbys --vip 10.0.0.160/24 --no-node --no-model
+```
+
+| Machine | Runs |
+|---|---|
+| the first | control plane, leading at first; model mirror; etcd |
+| the other two | control plane, standing by; PostgreSQL under Patroni; etcd |
+
+etcd votes on all three and PostgreSQL is on two, so any one machine can be
+lost: a standby leads within seconds, Patroni promotes the standby database
+if it was the primary, and the floating address follows whichever leads. The
+mirror's management API answers the three control planes' addresses, not
+only its own machine's, so a standby that comes to lead can still fetch and
+add models. The mirror itself stays on the first machine: while it is down,
+models the nodes already have keep serving, and new ones wait for it.
+
 ## Two control planes
 
 Once the store is replicated (`server init --patroni`, above), one command on
@@ -1959,8 +2496,12 @@ and lets it into the store; it starts there as a standby. Every node is told
 of it within half a minute and fails over to it without being touched.
 `--vip` keeps a floating address on whichever control plane leads, with
 keepalived on both: that is the address to give clients, or a proxy in front.
-Without it, put a load balancer in front that checks `/ready` — not
-`/health`, which is 200 on a standby that would refuse every request.
+Without it, put a proxy in front that sends to whichever answers `/leader`
+with 200 — not `/health`, which is 200 on a standby too, and not `/ready`,
+which is 503 on a leader with no model yet and would take the portal away
+with it. The end of [deploy/proxy/Caddyfile](../deploy/proxy/Caddyfile) has
+Caddy doing that for three control planes, and
+[deploy/ha/](../deploy/ha/README.md#check-leader-not-health) why.
 
 - **What a failover costs.** Measured on the reference cluster, stopping the
   leader: the standby led within five seconds, every node had moved to it
@@ -2021,6 +2562,79 @@ the same files and keys as `locales/en/`, and its `_meta.*` entries saying how
 it writes numbers and dates. The tests refuse a catalogue that lacks a key a
 page uses.
 
+## The company's MCP servers
+
+llmgw's `/mcp` can serve the company's own MCP servers beside its own tools.
+Each server, a ticket system, a file server or a database, is registered once.
+Its credentials stay on the control planes, and people's agents are given only
+`/mcp` and their llmgw key.
+
+```
+llmgw ctl mcp add jira --url https://jira.internal/mcp \
+    --description "Acme Jira" --secret-file Authorization=/root/jira-token
+llmgw ctl mcp test jira          # its tools, asked with its credentials
+llmgw keys limits --scope team --id Acme/support --tools 'jira.*'
+```
+
+- **Credentials:**
+  - `--secret-file NAME=FILE` reads a header's value once and keeps it in
+    the store, sealed by the master key, so no file has to be on each
+    control plane.
+  - `--header-ref NAME=REF` reads it at each call from a file, `env:`,
+    `vault:` or `store:` instead.
+  - `--header NAME=VALUE` is for what is not secret.
+- **Who may call what:** tools are named `server.tool` and granted as
+  patterns (`jira.*`, `db.query`) at any level of the tenancy tree, as
+  models are.
+  - A level that names any narrows what is above it.
+  - Unlike models, **none granted anywhere is none**: a tool reaches into a
+    company system, so it is granted, never assumed.
+  - The console's limits form has the same field.
+- **The server is told who calls:** `X-Llmgw-Key`, and `X-Llmgw-User` and
+  `X-Llmgw-Project` where there are some. It is called with llmgw's
+  credentials, never the caller's key.
+- **Bounds:** a call has 60 seconds (`--timeout`) and an answer 4 MB. A
+  server's progress is passed on to a client that takes a stream. `--rate N`
+  allows each caller N calls a minute to a server's tools.
+- **Guardrails, both ways:** the caller's policies read a tool's answer as
+  the prompt it becomes.
+  - An instruction planted in a ticket is caught as a pasted one would be
+    (`injection: block`).
+  - Personal data is redacted or refused as the policy says. A refused
+    answer does not reach the agent.
+  - The arguments are read before they leave, so a secret pasted into one
+    does not reach the company system.
+- **A server that keeps failing:** five calls failing in a row take a server
+  out for a minute. Its tools leave the list, and a call is answered at once.
+- **Record:** every call is in `llmgw ctl audit`, with its arguments' size
+  and a digest, never their text. `llmgw_mcp_tool_calls_total` and
+  `llmgw_mcp_tool_call_seconds` count them by server, tool and outcome.
+- **Changes:** a server added, changed or removed on one control plane is
+  served by every one within half a minute; its tool list is read again
+  every five minutes. `--disabled` keeps a server but serves none of its
+  tools.
+
+**This cluster's own, read only.** `llmgw ctl mcp add llmgw --url
+llmgw:admin` registers the cluster itself as a server: tools that say what
+`llmgw ctl` does, and change nothing. It is answered in the control plane's
+own process, with no address and no token to give.
+
+| Tool | Says |
+|---|---|
+| `llmgw.cluster_status` | control planes, store, nodes, models against what they asked for, GPUs, what is unhealthy |
+| `llmgw.list_nodes` | each node's state, GPUs, load, fabrics, agent version and engines |
+| `llmgw.list_models` | each model's replicas ready against wanted, profiles, why one is parked |
+| `llmgw.list_replicas` | each replica's shards: node, GPUs, state (`model` for one model's) |
+| `llmgw.explain_placement` | why a model is not placed, node by node |
+| `llmgw.node_logs` | a node's last agent log lines, or an engine's (`source`) |
+
+Grant it as any other: `llmgw keys limits --scope key --id KEY-ID --tools
+'llmgw.*'`. It is the same as an administrator's view, so grant it to the
+people who would have `ctl`.
+
+Servers over HTTP only for now (the streamable HTTP transport). A server
+that runs as a local process (stdio) is planned.
+
 ## Single sign-on
 
 People can sign in through your identity provider — Keycloak, Entra ID,
@@ -2028,8 +2642,10 @@ Google, Okta, Authentik, anything that speaks OpenID Connect.
 
 1. Register a client there with the redirect address
    `https://<gateway>/login/oidc/callback`.
-2. Put its secret in a file only root reads.
-3. Add to `server.yaml`:
+2. Put its secret in a file the llmgw user reads, on every control plane.
+3. Add this to the cluster's settings with `llmgw ctl config edit`. On a
+   cluster with a store, `auth` is the cluster's: the same block in
+   `server.yaml` is not read, and the log says so.
 
 ```yaml
 auth:
@@ -2078,6 +2694,99 @@ and point it at `https://<gateway>/scim/v2` with that token as the bearer.
   join and leave them. Membership in a group is removed when someone leaves
   it.
 
+### Entra ID
+
+The console sets this up: `sudo llmgw`, People → Sign-in, **E**. What
+follows is what it writes, and what to do in Entra.
+
+Entra ID is an OpenID Connect provider like the others, with two things to
+set in the app registration:
+
+1. **Redirect URI:** under Authentication, add a Web platform with
+   `https://<gateway>/login/oidc/callback`. The issuer is
+   `https://login.microsoftonline.com/<tenant-id>/v2.0`.
+2. **Groups in the token:** under Token configuration, add a groups claim.
+   Choose **Groups assigned to the application**, and assign the groups you
+   map in `roles` and `memberships` to the enterprise application. Entra
+   sends groups by object id unless you choose to emit names
+   (`sAMAccountName` for groups synced from AD), so write them the same way
+   in the mapping.
+
+Entra leaves the groups out of the token for someone in more than 200 of
+them and sends a pointer to Graph instead. llmgw then keeps that person's
+role and memberships as they were, rather than reading it as no groups, and
+logs an error saying so. "Groups assigned to the application" avoids this.
+So does SCIM below, which Entra also speaks: in the enterprise application
+under Provisioning, set the tenant URL to `https://<gateway>/scim/v2` and
+the secret token to the contents of `auth.scim.token_file`.
+
+## Active Directory
+
+With an on-premises Active Directory, people sign in on the gateway's own
+form with their AD username (`ada`, `CORP\ada`, `ada@corp.example`) and
+password. The gateway checks them with the domain controllers over LDAPS.
+
+The console sets this up and tries it first: `sudo llmgw`, People →
+Sign-in, **D**. It keeps the service account's password in the store
+(`bind_password_file: store:auth/ldap-bind`) and writes the CA into the
+settings (`ca:`), so nothing has to be copied to each control plane.
+By hand it is this block in the cluster's settings (`llmgw ctl config
+edit`), where files it names must then be on every control plane:
+
+```yaml
+auth:
+  enabled: true
+  ldap:
+    urls: [ldaps://dc1.corp.example, ldaps://dc2.corp.example]   # tried in order
+    ca_file: /etc/llmgw/corp-ca.pem         # the domain's CA, when not in the system's
+    bind_dn: CN=svc-llmgw,OU=Service,DC=corp,DC=example
+    bind_password_file: /etc/llmgw/secrets/ldap-bind   # root-only
+    base_dn: OU=Staff,DC=corp,DC=example    # where people are
+    user_filter: (memberOf:1.2.840.113556.1.4.1941:=CN=llmgw-users,OU=Groups,DC=corp,DC=example)
+    label: Acme                             # "Sign in with your Acme account"
+    create_accounts: true
+    roles:                                  # by group CN or full DN; nested groups count
+      admin: [llmgw-admins]
+      operator: [llmgw-ops]
+    memberships:
+      ml-engineers: "team:Acme/ml"
+    sync_interval: 15m                      # negative turns the sync off
+```
+
+- **Service account:** an ordinary domain user is enough: it only reads.
+  It finds the person and reads their groups. The person's password is
+  checked by binding as them, and is never stored.
+- **Encryption:** `ldaps://`, or `ldap://` with `start_tls: true`.
+  Plaintext LDAP is refused, since passwords would cross the network.
+- **Certificate:** the domain controller's certificate must name it in
+  its subject alternative names: a name in the CN only is refused, as are
+  certificates with a negative serial number. Samba's own autogenerated
+  certificate is both, so a Samba DC needs one from a CA (`tls certfile`
+  in smb.conf). A CA file a control plane cannot read turns directory
+  sign-in off on that control plane, said in its log. Local accounts still
+  sign in.
+- **Who may sign in:** enabled user objects under `base_dn` that match
+  `user_filter`. The example admits members of `llmgw-users`, nested groups
+  included.
+- **Accounts:** an account is tied to the person's `objectGUID`, so a changed
+  mail or name is still the same account. An account that already exists
+  with the person's mail is taken over. Without `create_accounts`, only
+  people who already have an account can sign in. Local accounts, such as
+  the administrator `server init` made, keep signing in with their own
+  password.
+- **Sync:** every `sync_interval` the leader reads the directory.
+  - Someone disabled or deleted in AD is suspended and their sessions
+    end.
+  - When they are enabled again they are reinstated. An account an
+    administrator suspended by hand stays suspended.
+  - Roles follow groups, and memberships the directory gave are taken away
+    when the person leaves the group.
+  - A sync that would suspend more than half of the directory's accounts is
+    refused and logged, rather than locking everyone out over a wrong
+    `base_dn` or filter.
+- **Passwords:** a person's password is changed in AD. The gateway sends no
+  reset link for these accounts.
+
 ## Secrets in Vault
 
 Every setting that names a file holding a secret — the store's `@address`,
@@ -2150,13 +2859,29 @@ llmgw ctl config set firewall.enabled false   # every machine's table taken out
 llmgw ctl config set firewall.enabled true    # and put back as it was
 ```
 
-It is in force within seconds: each node's agent takes its table out or puts
-it back, and each control plane's `llmgw-firewall-sync.path` (installed by
-`server init` and `server add`; `sudo llmgw firewall sync --install` on one
-set up before) does the same there. The rules files stay, so turning it back
-on restores them. Nodes added while it is off get none. A separate mirror
-machine and the store's members keep theirs for now. `firewall_networks`
-changes reach the nodes the same way.
+It is in force on every machine within a minute, each in its own way:
+
+- **nodes**: the agent takes its table out or puts it back;
+- **control planes**: `llmgw-firewall-sync.path`, installed by `server
+  init` and `server add` (`sudo llmgw firewall sync --install` on one set up
+  before);
+- **a separate mirror machine**: the leading control plane tells the mirror,
+  which writes it to `.firewall.json` in its directory, and the same path
+  unit applies it. `mirror init` installs it; on a mirror set up before, run
+  `sudo llmgw mirror init` again with the same flags;
+- **store members that are nothing else**: they run no llmgw, so
+  `llmgw-firewall-follow.timer` reads what the leading control plane keeps in
+  the store, from the member's own copy, once a minute. `server init
+  --patroni` installs it; run it again on a cluster set up before.
+
+The rules files stay, so turning it back on restores them. Nodes added while
+it is off get none. Networks added to `firewall_networks` reach every machine
+the same way. One taken out of it stays let in until it is taken out of
+`/etc/llmgw/firewall.nft` by hand: the rules are only ever added to.
+
+The leading control plane also tells the mirror machine where every node and
+control plane is, so a node on a network the mirror had not let in can fetch
+its weights without a `firewall_networks` entry.
 
 Only those ports are touched. The table's policy is to accept, so whatever
 else the machine serves — and whatever firewall it already has — is left as
@@ -2294,6 +3019,43 @@ A cluster set up online becomes offline the same way: `bundle import` on the
 mirror and control plane, then the `offline:` block in `server.yaml` and a
 restart.
 
+## Stopping and starting the system
+
+From a control plane:
+
+```
+llmgw status                     # does it serve; its control planes, nodes, models, store
+llmgw stop --note "maintenance"  # every model taken down, every request answered 503
+llmgw start                      # every model back as its catalog entry asks
+sudo llmgw restart               # every agent and control plane started again, engines serving throughout
+```
+
+`llmgw stop` frees every GPU and answers requests for a model with 503
+(`system_stopped`, with Retry-After) until `llmgw start`. The control planes,
+agents and mirror keep running, so the console, the admin pages and `llmgw
+start` keep working, and no model's definition changes. It is the cluster's
+setting `serving.stopped`, so a restart does not undo it, and it is in the
+audit with its note. `--wait` waits until every replica is down, or every
+model has its replicas again.
+
+`llmgw restart` restarts every node's agent, then the other control planes
+over ssh (`--ssh-user`, the one sudo was run by), then this one — the leader
+last, so it hands over to a standby already restarted. Engines keep serving
+and are taken over again; nothing is placed anew.
+
+One machine's own services are `llmgw service`:
+
+```
+sudo llmgw service status
+sudo llmgw service stop          # agent, control plane, mirror — whichever this machine has
+sudo llmgw service start
+sudo llmgw service restart agent # or name one: server, agent, mirror
+```
+
+Stopping a node's agent leaves its engines serving — the agent takes them
+over again when it starts — unless `llmgw service stop --engines` stops them
+too, and the control plane then places their replicas elsewhere.
+
 ## Removing llmgw from a machine
 
 ```
@@ -2596,6 +3358,8 @@ requests. On a slow model, set `timeouts.generation` higher.
 
 - `docs/choosing-models.md` — which models to run and how many, if the answer
   to "we have GPUs, now what" is not already obvious
+- `docs/large-models.md` — a model on several cards or several nodes: how it
+  is split, what each way needs of a card, and bringing one up on a fabric
 - `docs/data.md` — what is stored and what leaves the machine, for the review
   that happens before this is allowed near anyone's documents
 - `docs/reference.md` — every configuration key, generated from the source, so

docs/knowledge.md

@@ -0,0 +1,426 @@
+# Knowledge bases
+
+A knowledge base is a collection of a company's documents that the cluster
+can answer from. People put their documents into it from their own machines
+with `llmgw-kb`. The tool reads the files on that machine, cuts them into
+passages ("chunks"), has the gateway embed each passage with the person's own
+key, and sends the text and the vectors. The files themselves never leave
+the machine.
+
+## Why retrieval, and not training
+
+Retrieval is the tool for *knowledge*: policies, procedures, contracts. The
+answer can name its source, a changed document is sent again in minutes, and
+a passage only ever reaches people allowed to read its collection.
+
+Training a model on the documents (LoRA) changes how it *writes*, not what it
+reliably *knows*. It has no access control: whatever goes into the weights
+is available to everyone who may use them.
+
+## What it needs
+
+- **The PostgreSQL store with pgvector.** On a SQLite store knowledge bases
+  are off, and `llmgw ctl kb list` and the console say why.
+  - `llmgw server init` and the high-availability database setup install
+    pgvector and enable it.
+  - A cluster set up before this build needs it by hand, once:
+    1. Install the package on every database machine:
+       `sudo apt-get install postgresql-16-pgvector` (use the server's
+       version number).
+    2. On the leader, enable it in llmgw's database:
+       `sudo -u postgres psql -d llmgw -c 'CREATE EXTENSION vector'`.
+    3. Restart the control planes: `llmgw restart`.
+- **An embedding model in the catalog**, with `capabilities.embeddings`.
+  Two good choices handle Turkish and run on CPUs: `BAAI/bge-m3` (1024
+  dimensions) and `Qwen/Qwen3-Embedding-0.6B`.
+
+  Add it as any model is added (**Serve a model** in the console, or the
+  catalog), with its entry saying that it embeds:
+
+  ```yaml
+  capabilities:
+    embeddings: true
+  ```
+
+  A collection stays with the model it was made with: vectors from two
+  models cannot be compared.
+
+  Some embedding models are trained with an instruction before the
+  question and none before the documents. Give it as the entry's
+  `query_prefix`; llmgw puts it before questions only. For
+  Qwen3-Embedding:
+
+  ```yaml
+  query_prefix: "Instruct: Given a web search query, retrieve relevant passages that answer the query\nQuery: "
+  ```
+
+  With pgvector 0.7 or later a collection's index is kept at half
+  precision (`halfvec`), which halves its memory and takes models of up to
+  4000 dimensions; with an older pgvector the limit is 2000. A collection
+  keeps the kind it was made with.
+
+## For administrators
+
+### Make a collection
+
+A collection belongs to one part of the tenancy tree: an organization, a
+team, a project or a person. Whoever is in the owner, at any level below it,
+may read it and add to it.
+
+```sh
+llmgw ctl kb create team:Acme/hr policies bge-m3
+llmgw ctl kb create user:USER-ID notes bge-m3 --org Acme
+```
+
+The model's dimension is asked of the model itself, so the model has to be
+able to serve when the collection is made. `--dims 1024` gives it instead.
+
+In the console: **Knowledge**, then **A**.
+
+### Who may read and add
+
+The owner, and everything below it, may read and add. A **grant** gives the
+same to another part of the same organization, to a person, or to one key:
+
+```sh
+llmgw ctl kb grant Acme/policies project:Acme/sales/crm           # read
+llmgw ctl kb grant Acme/policies team:Acme/legal --write          # read and add
+llmgw ctl kb revoke Acme/policies project:Acme/sales/crm
+```
+
+How access works:
+
+- **Grants add up down the tree.** A grant to a team reaches its projects
+  and their keys.
+- **Nothing crosses organizations.** A grant to another organization's
+  team, project, key or person is refused.
+- **A person's own key** (a key with no project) reads nothing by itself.
+  The person names the project they act in (`llmgw-kb login` asks for it,
+  or `--project`) and must be a member of it. Joining a second team
+  therefore does not quietly widen what every key of theirs can read.
+- **No access looks like no collection.** A collection a key may not read
+  is answered exactly as one that does not exist, so even its name does not
+  leak.
+
+### Answer from collections by default
+
+Clients that cannot add a header still get answers from the documents when
+their part of the tree has a default:
+
+```sh
+llmgw ctl kb default team:Acme/hr Acme/policies Acme/forms
+llmgw ctl kb default key:KEY-ID Acme/policies
+llmgw ctl kb default team:Acme/hr --clear
+```
+
+- **Which default applies.** The narrowest one: a key's over its project's,
+  a project's over its team's, a team's over its organization's.
+- **A request can override it.** A request that names collections uses
+  those instead, and `X-Llmgw-Knowledge: none` turns the default off for
+  that request.
+- **A default never refuses a request.** A collection the caller may not
+  read is left out for them. If the search fails (the embedding model is
+  down, say), the request is answered without passages and the failure is
+  logged.
+- **Changes take effect within 30 seconds.**
+
+In the console: **Knowledge**, Enter on a collection, then **Answer from it
+by default…**.
+
+### Look after it
+
+```sh
+llmgw ctl kb list                          # collections, owners, documents, grants
+llmgw ctl kb docs Acme/policies            # its documents, who added each and when
+llmgw ctl kb rm Acme/policies old/form.pdf # one document out
+llmgw ctl kb search Acme/policies how many days of annual leave
+llmgw ctl kb delete Acme/policies          # the collection, its documents and grants
+```
+
+Rules that apply:
+
+- A project, team or organization that owns a collection is not deleted
+  until its collections are. This is the same rule as for one with members.
+- A person's own collections go with their account (`users delete`,
+  `users forget`).
+- Every document added or removed is in the audit log (`llmgw ctl audit`),
+  by name. The text is never recorded.
+
+### A large import
+
+A few thousand documents ask the embedding model for far more than it can
+answer at once. Give the key that sends them a band of its own, below the
+people's, that may wait for room for minutes rather than the 30 seconds the
+others wait:
+
+```sh
+llmgw ctl config set router.admission.bands '[{name: gold, priority: 300, saturation_ceiling: 0.85},
+  {name: bronze, priority: 100, saturation_ceiling: 0.3}, {name: bulk, priority: 50, saturation_ceiling: 0.3, queue_ttl: 5m}]'
+llmgw keys create import --project Acme/docs --band bulk
+```
+
+The people's questions then go first, and the import waits behind them. A
+request that waits as long as its band allows is answered 504 with
+`Retry-After`, and `llmgw-kb` sends it again rather than counting the
+passage as failed. It gives up after 15 minutes.
+
+## For everyone: `llmgw-kb`
+
+### Get it
+
+Download `llmgw-kb` for your system from the release page, next to `llmgw`:
+
+| System | File |
+|---|---|
+| Windows (Intel/AMD) | `llmgw-kb-VERSION-windows-amd64.exe` |
+| Windows (ARM) | `llmgw-kb-VERSION-windows-arm64.exe` |
+| macOS (Apple silicon) | `llmgw-kb-VERSION-darwin-arm64` |
+| macOS (Intel) | `llmgw-kb-VERSION-darwin-amd64` |
+| Linux | `llmgw-kb-VERSION-linux-amd64` / `-arm64` |
+
+Rename it to `llmgw-kb` (`llmgw-kb.exe` on Windows) and put it somewhere on
+your PATH. You do not need to install anything else.
+
+On macOS, a downloaded program that is not signed is stopped the first time.
+Either right-click it and choose Open, or run
+`xattr -d com.apple.quarantine llmgw-kb`.
+
+### Log in once
+
+```sh
+llmgw-kb login
+```
+
+It asks for three things, checks them, and saves them where only you can
+read them:
+
+- **The gateway's address.**
+- **Your API key.** It is typed without being shown.
+- **A project.** Needed only for a personal key.
+
+Instead of logging in you can set `LLMGW_URL`, `LLMGW_API_KEY` and
+`LLMGW_PROJECT`.
+
+```sh
+llmgw-kb collections        # what your key may read, and which you may add to
+```
+
+### Send your documents
+
+```sh
+llmgw-kb sync policies ~/Documents/HR
+llmgw-kb sync policies "C:\Users\ayse\Documents\İK" --include "*.pdf,*.docx"
+llmgw-kb sync policies ./handbook ./forms --exclude "drafts/**"
+```
+
+Run it as often as you like. The first run sends everything. Later runs
+send only what changed, and do not even read files whose size and time have
+not changed.
+
+| Option | What it does |
+|---|---|
+| `--dry-run` | Reads and cuts everything, sends nothing, and lists what would leave the machine and how much. |
+| `--delete` | Also removes documents whose files are gone. Only those this machine sent, from these folders; never anything someone else sent. |
+| `--retry` | Reads again files skipped before, for example after installing LibreOffice. |
+| `--include`, `--exclude` | Glob patterns. `*.pdf` matches a file name; `reports/**/*.xlsx` matches a path. |
+| `--hidden` | Reads hidden files and folders too (left out by default). |
+| `-v` | Lists unchanged files too. |
+
+Documents are named by their path under the folder, with forward slashes,
+on every system. With several folders, each folder's own name comes first.
+
+```sh
+llmgw-kb status policies    # what this machine sent and skipped, and why
+llmgw-kb history            # the latest runs
+llmgw-kb formats            # what can be read here
+```
+
+### What it reads
+
+| Read here | Formats |
+|---|---|
+| Documents | PDF (text), Word (`.docx`), Excel (`.xlsx`), PowerPoint (`.pptx`, with speaker notes), OpenDocument (`.odt`, `.ods`, `.odp`), RTF, EPUB |
+| Web and mail | HTML, MHTML, e-mail (`.eml`, with its attachments) |
+| Text | Markdown, plain text, CSV, JSON, YAML, XML, subtitles, notebooks (`.ipynb`), source code |
+| Archives | ZIP, with every file inside it read in turn |
+
+| Read with a helper on your machine | Helper |
+|---|---|
+| Word, Excel and PowerPoint 97–2003 (`.doc`, `.xls`, `.ppt`), Pages, Numbers, Keynote and others | [LibreOffice](https://www.libreoffice.org) |
+| Images and scanned PDFs | [Tesseract](https://tesseract-ocr.github.io) (with the Turkish language data), plus Poppler's `pdftoppm` for PDFs |
+| PDFs the built-in reader cannot parse | Poppler's `pdftotext` |
+
+`llmgw-kb formats` says which helpers it found. Text in UTF-8, UTF-16, or
+the Windows Turkish and Western code pages is read correctly.
+
+A file that cannot be read is skipped with the reason, and the run goes on.
+Reasons include a locked Office file, a format with no helper, and a
+scanned page with no OCR.
+
+### What leaves your machine
+
+For each new or changed document, two things leave the machine, both over
+the gateway's TLS connection:
+
+- **The passages, to be embedded.** They go through `/v1/embeddings` like
+  any request of yours. Your key's limits, budget and guardrails apply.
+- **The document itself.** Its name, its file's SHA-256 digest and size,
+  and the passages with their vectors.
+
+The file itself is never sent. `--dry-run` shows exactly what would be.
+
+### The ledger
+
+`llmgw-kb` keeps a small SQLite database of what it did with every
+document: the file it came from, its size, time and digest, and whether it
+was sent, skipped or failed, with the reason.
+
+| System | Where it is |
+|---|---|
+| Windows | `%AppData%\llmgw-kb\ledger.db` |
+| macOS | `~/Library/Application Support/llmgw-kb/ledger.db` |
+| Linux | `~/.config/llmgw-kb/ledger.db` |
+
+Deleting the ledger is safe: the next run hashes every file once, finds what
+the collection already has, and sends nothing that is unchanged. `--ledger`
+uses another file.
+
+## Asking questions of a collection
+
+A chat request names the collections to answer from in a header. Any client
+that can add a header can do it: the OpenAI and Anthropic SDKs, Continue, or
+curl.
+
+```sh
+curl https://llm.example.com/v1/chat/completions \
+  -H "Authorization: Bearer $LLMGW_API_KEY" \
+  -H "X-Llmgw-Knowledge: politikalar" \
+  -d '{"model": "qwen2.5-coder-14b-instruct",
+       "messages": [{"role": "user", "content": "Kaç gün yıllık iznim var?"}]}'
+```
+
+```python
+client.chat.completions.create(
+    model="qwen2.5-coder-14b-instruct",
+    messages=[{"role": "user", "content": "Kaç gün yıllık iznim var?"}],
+    extra_headers={"X-Llmgw-Knowledge": "politikalar"},
+)
+```
+
+What the gateway does with such a request:
+
+1. **It finds the collections.** It looks up the ones named, by name or ID,
+   among those the key may read. A collection it may not read is answered
+   404, the same as one that does not exist.
+2. **It embeds the question.** The last user message is embedded by the
+   collection's model, on the caller's own account: their limits, budget and
+   guardrails apply.
+3. **It searches.** The collections are searched by meaning and by words
+   (below).
+4. **It adds the passages.** The best passages are numbered and added to the
+   system message, with an instruction to answer from them, cite them as
+   [1], [2], and say so when they do not hold the answer. The system message
+   is created if the request has none. Passages that would not fit the
+   model's context are left out, the weakest first.
+5. **It judges and sends the request.** The request, passages included, then
+   goes through the guardrails and to the model as usual. A document
+   carrying instructions aimed at its reader is judged like anything else
+   the model reads.
+
+On the portal's chat page, **Documents** picks a collection the person may
+read in the chosen project, the default, or none. Under each answer, the
+sources it was given are listed by number.
+
+How it is shaped:
+
+| | |
+|---|---|
+| `X-Llmgw-Knowledge` | Collections, comma separated; `none` for no passages, whatever the default. |
+| `X-Llmgw-Knowledge-K` | How many passages, 1 to 20; 5 by default. |
+| `X-Llmgw-Project` | For a personal key: the project it acts in. |
+| `x-llmgw-sources` (answer) | The passages given, as `document#chunk`, in their numbered order; empty when nothing matched. |
+
+Behaviour to know about:
+
+- **No passages matched.** The model is told that nothing in the documents
+  answers the question, and asked to say so rather than answer from general
+  knowledge.
+- **Other APIs.** Requests through `/v1/responses` and `/v1/messages`
+  (Codex, Claude Code) work the same way, since they are answered as chat
+  completions.
+- **Separate prefix caches.** On vLLM replicas, a request given passages
+  carries a `cache_salt` derived from the collections they came from.
+  Requests that could be given the same passages still share cached blocks,
+  and no one else's do: not another organization's, nor another team's of
+  the same one. How fast an answer starts therefore says nothing about what
+  someone else asked.
+- **No answer cache.** Answers from knowledge bases are never served from
+  the answer cache, because two keys of one project can read different
+  collections.
+
+### How a passage is chosen
+
+Each passage scores the following, and the highest scores win:
+
+- its similarity in meaning to the question (cosine, 0 to 1), plus
+- up to 0.3 for the share of the question's words it contains.
+
+Words almost every passage has ("ne", "için", "the", "of") are not counted.
+The meaning does most of the work: "how much leave do fathers get" finds the
+paternity page, not the annual-leave page that shares more of its words.
+The word match helps with what meaning cannot carry, such as a form number,
+a product code or a name.
+
+Metrics: `llmgw_kb_retrievals_total{result}` (found, nothing, refused) and
+`llmgw_kb_retrieval_seconds`.
+
+## Training an adapter on a collection
+
+An adapter (LoRA) changes how a model *writes*: the organisation's words,
+format and tone. It does not reliably teach facts. On the PoC, a small
+model trained on nine policy documents answered 4 of 9 rephrased questions
+right and mixed facts up on the rest, while the same questions through the
+knowledge base got 9 of 9. Use both: the knowledge base for what answers
+say, an adapter for how they sound.
+
+```sh
+# 1. Questions and answers from the collection, written by a model of the
+#    cluster. Read the file through and correct it.
+llmgw ctl kb dataset Acme/policies --model qwen2.5-coder-14b-instruct --out policies.jsonl
+
+# 2. Train on a node. --gpu-memory is what the job needs of a card; it
+#    runs beside an engine when the engine leaves that much free.
+llmgw ctl train start policies-tone --model qwen2.5-0.5b-instruct \
+  --base-repo Qwen/Qwen2.5-0.5B-Instruct --node cuda01 --gpu-memory 2300 --data policies.jsonl
+llmgw ctl train show JOB --follow
+
+# 3. Make it the model's adapter, kept on the mirror.
+llmgw ctl train publish JOB --restart
+```
+
+The node trains with its installed vLLM's torch and a small overlay (peft
+and accelerate), as the engines' user. For a model llama.cpp serves, it also
+converts the adapter to GGUF with the installed llama.cpp's own code. What
+it makes is kept by the control plane (`llmgw ctl train download`).
+
+An adapter is private like its collection:
+
+- **It has an owner.** An adapter trained on a collection carries some of
+  what the collection says in its weights, so it belongs to a part of the
+  tree.
+  - By default the owner is the collection's owner.
+  - `--owner` names another, which must be able to read every collection
+    the pairs came from.
+  - Only callers in the owner's part of the tree see the adapter. To anyone
+    else it is a model that does not exist, absent from `/v1/models` too.
+- **It is public only by choice.** `--public` makes an adapter every
+  caller's. It is refused for pairs from a knowledge base, so it is only for
+  pairs written by hand.
+
+## How it is kept apart
+
+Passages live in PostgreSQL, partitioned by organization, with an index per
+collection. Every search and every write names the organization and the
+collections the caller may use. On top of that, row-level security on the
+table checks the same thing again, so a query that forgot its filter
+returns nothing rather than another tenant's passages.

docs/kong.md

@@ -0,0 +1,95 @@
+# llmgw and Kong
+
+For a site that already runs Kong. The two meet over plain HTTP: Kong in
+front of llmgw, as one more API it governs, or Kong behind llmgw, as an
+OpenAI-compatible provider. Nothing of either is built into the other.
+
+Tried with Kong Gateway 3.9 (`kong:3.9`, the last open-source release; 3.10
+and later need a Kong licence) in DB-less mode, in front of llmgw.
+
+## Kong in front of llmgw
+
+Two ways, both tried.
+
+**A plain route.** Kong forwards the request as it came. Tried with chat
+completions, streamed and not; llmgw's other APIs — Anthropic's
+`/v1/messages`, `/v1/responses`, embeddings, pictures — go the same way,
+since Kong does not read them. Kong adds its own authentication, rate limits
+and logging; llmgw still checks the key, the budget and the guardrails.
+
+```yaml
+_format_version: "3.0"
+services:
+- name: llmgw
+  url: https://llm.example.com          # llmgw's client port
+  routes:
+  - name: llmgw
+    paths: [/llmgw]                      # /llmgw/v1/chat/completions → /v1/chat/completions
+```
+
+**Kong's `ai-proxy` plugin**, for Kong's own token statistics on a chat
+route. llmgw is an OpenAI provider whose `upstream_url` is llmgw:
+
+```yaml
+services:
+- name: llmgw-chat
+  url: https://llm.example.com
+  routes:
+  - name: chat
+    paths: [/chat]
+  plugins:
+  - name: ai-proxy
+    config:
+      route_type: llm/v1/chat
+      logging: {log_statistics: true, log_payloads: false}
+      model:
+        provider: openai
+        name: qwen-coder                 # a model llmgw serves
+        options:
+          upstream_url: https://llm.example.com/v1/chat/completions
+```
+
+**Keys.** Without an `auth` block, `ai-proxy` passes the client's
+`Authorization` header on: each team keeps its own llmgw key, and llmgw's
+budgets, limits, guardrails and usage stay per team. With
+`auth: {header_name: Authorization, header_value: "Bearer sk-llmgw-…"}` Kong
+sends one key of its own instead, and llmgw sees every caller as that key —
+then budgets per team are Kong's to keep.
+
+**What Kong counts.** For a whole answer Kong reads llmgw's `usage` and
+records prompt and completion tokens as llmgw did. For a streamed answer
+Kong 3.9 records an estimate of the prompt tokens and no completion tokens,
+even with `stream_options.include_usage` set — the usage chunk reaches it
+and is not read. llmgw's own accounting counts both; use its usage export
+(`llmgw ctl usage export`) or `/admin/usage` for figures to bill by.
+
+**Timeouts.** A long answer from a model still loading outlasts Kong's
+60-second defaults: set the service's `read_timeout` to the time a model may
+take to start, as for nginx in [install.md](install.md).
+
+## Kong behind llmgw
+
+Not tried here. Kong's AI routes speak OpenAI's API, so llmgw reaches models Kong fronts as
+it reaches any provider: a model whose source is `external`.
+
+```yaml
+- name: kong-gpt
+  source: external
+  external:
+    url: https://kong.example.com/openai     # Kong's route, without /v1
+    model: gpt-4o-mini
+    api_key_file: /etc/llmgw/secrets/kong-consumer.key
+```
+
+The key is the one Kong's own authentication asks of a consumer. As a
+fallback (`fallbacks: [kong-gpt]`) it is used only when the cluster has no
+room.
+
+## Which to choose
+
+Kong in front when the site's API policy says every API goes through Kong:
+llmgw is then one more upstream, and its per-team accounting still holds
+when each team keeps its own key. Kong behind when the site already reaches
+outside providers through Kong and llmgw should too. llmgw does not need
+Kong for anything it does itself — keys, budgets, guardrails, routing to
+its own replicas.

docs/large-models.md

@@ -0,0 +1,145 @@
+# Large models: several cards, several nodes
+
+A model too big for one card runs on several. llmgw chooses how from the
+model's own figures and the cluster as it is; this page is the rules it
+follows, the commands, and what to look at when a first one is brought up
+on new hardware.
+
+## How a model is split
+
+In order, the first that fits:
+
+1. **One card.** Nothing to split.
+2. **Several cards of one node, tensor parallel.** Every layer is cut
+   across the cards, so they talk for every token: they must be on one
+   NVLink domain. The agent reads `nvidia-smi topo -m` and gives a replica
+   the cards with the most NVLink between them
+   ([install.md](install.md#nvlink-if-your-gpus-have-it)).
+3. **Several nodes, pipeline parallel between them.** Each node holds a
+   run of layers on all its cards (tensor parallel inside it), and only a
+   layer's output crosses to the next node. The nodes must share one
+   InfiniBand or RoCE fabric: a replica never spans two, and never a node
+   with none. Any number of nodes, not only two or four.
+
+The plan takes the fewest cards, then the fewest nodes, then the better
+precision up to eight bits.
+
+**Tensor width and the KV heads.** The cards split the model's KV heads
+among them, or past their number each card holds a copy of one. So the
+width divides the KV heads or is a multiple of them: a model with 8 KV
+heads runs 2, 4, 8 or 16 wide, not 12. Qwen3-235B has 4 and runs on 8.
+
+**Mixture of experts.** A model of experts (Qwen3-235B-A22B, DeepSeek-V3,
+Llama 4, Mixtral) on more than one card is served with vLLM's
+`--enable-expert-parallel`: each card holds whole experts rather than a
+slice of every one, which is less traffic per token. It is read from
+`config.json` (`num_experts`, `n_routed_experts`, `num_local_experts`).
+
+**When it does not fit.** A smaller precision first: an FP8 or AWQ
+repository of the same model, or a GGUF quantisation on llama.cpp if one
+node's cards hold it. Then more nodes. `llmgw ctl model plan REPO
+--precision bf16,fp8` shows each precision's fit from the model's config.
+
+## What a way needs
+
+Each way the plan offers says what a replica needs of each card, part by
+part, and of all its cards together:
+
+```
+$ llmgw ctl model plan meta-llama/Llama-3.3-70B-Instruct --format safetensors --context 32768
+FILE      SIZE    BEST WAY        A CARD   OF     ALL CARDS  NOW
+original  131 GB  4 × h100-80g    37.4 GB  72 GB  150 GB     free
+
+Best: original on 4 × h100-80g: 37.4 GB a card (weights 32.9 + context 2.5 + engine 2.0) of 72 usable; 150 GB on 4 cards.
+The context costs 0.31 GB per 1000 tokens, the whole model (--context to plan another).
+```
+
+- **weights:** the files, divided over the cards.
+- **context:** the KV cache for the context planned, divided likewise.
+- **engine:** the engine's own: 2 GB and a fiftieth of the weights for vLLM.
+- **usable:** 90% of a card; the rest is the driver's and fragmentation's.
+
+The console's **Serve a model** shows the same for every way a file runs.
+A context longer than planned is checked against it before anything is
+fetched.
+
+## Serving one
+
+Without flags the plan's best way is taken:
+
+```
+llmgw ctl model serve Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 --format safetensors --context-length 32768
+```
+
+Or a way given by hand, for instance two nodes of eight:
+
+```
+llmgw ctl model serve meta-llama/Llama-3.3-70B-Instruct --format safetensors \
+    --gpu-class h100-80g --gpus 8 --nodes 2 --env NCCL_DEBUG=INFO
+```
+
+`--gpus` is the cards on each node and `--nodes` the nodes. The pipeline
+is the nodes and the tensor width the cards of each.
+
+`--env KEY=VALUE` goes into the engine's environment on every node:
+`NCCL_DEBUG=INFO` while bringing a cluster up, `NCCL_IB_*` to steer it.
+Only the variables engines are tuned with are taken. llmgw already sets
+these:
+- `NCCL_IB_HCA` to the fabric's adapters;
+- `NCCL_IB_GID_INDEX` on RoCE;
+- `NCCL_SOCKET_IFNAME` to the management network;
+- for an NVLink domain spanning nodes, `NCCL_MNNVL_ENABLE`.
+
+The job's first step says what it needs of each card. The weights then
+come to the mirror once and from it to each node. The startup timeout (20
+minutes unless the profile's `startup_timeout` says otherwise) runs from
+when a node's download last moved. So a model of hundreds of gigabytes is
+not failed while it is still arriving, and one whose download stops is
+failed that long after.
+
+## Watching it come up
+
+| What | Where |
+|---|---|
+| The replica and its shards, one per node, each with its download | `llmgw ctl replicas` |
+| Why it is not placed | `llmgw ctl explain-placement MODEL` |
+| A node's engine output (NCCL's lines with `NCCL_DEBUG=INFO`) | `llmgw ctl logs NODE --source SHARD` |
+| The bandwidth between two nodes, rail by rail | `llmgw ctl fabric-test NODE NODE` |
+| Each node's GPUs, NVLink and adapters | `llmgw doctor` on the node; its page under /admin |
+| Every step of a start, across nodes | the `replica start` trace ([install.md](install.md)) |
+
+With `NCCL_DEBUG=INFO`, NCCL says which transport it took between nodes:
+`NET/IB` is the fabric. `NET/Socket` means it fell back to TCP, and the
+model will run, slowly.
+
+## Bringing it up on new hardware
+
+A first run on a fabric, in order. Each step is worth its output if
+something goes wrong.
+
+1. **The nodes.** Add each with its fabric:
+   `llmgw node add host --fabric ib-a:mlx5_0,mlx5_1`. Then
+   `llmgw ctl nodes` shows every node ready, on `ib-a`.
+2. **The fabric.** `llmgw ctl fabric-test node1 node2`: each rail at its
+   rated speed (a 400 Gb/s rail near 45 GB/s).
+3. **One node, several cards.** A dense 70B at bf16 on four or eight
+   cards of one node, by the plan:
+   `llmgw ctl model serve meta-llama/Llama-3.3-70B-Instruct --format safetensors`.
+   Ready, then a question answered.
+4. **Two nodes.** The same model forced over two:
+   `--gpu-class CLASS --gpus 8 --nodes 2 --env NCCL_DEBUG=INFO`, under
+   another `--name`. Ready, answering, and `NET/IB` in both shards' logs.
+5. **Experts.** A mixture-of-experts model on one node's eight cards,
+   for instance `Qwen/Qwen3-235B-A22B-Instruct-2507-FP8`: its profile
+   carries `--enable-expert-parallel` (`llmgw ctl models`, or its
+   definition from the admin API).
+6. **A node lost.** With the two-node replica serving, stop one node's
+   agent (`systemctl stop llmgw-agent`): the replica fails and is placed
+   again once the node is back or another has room. Nothing is left
+   holding cards.
+
+For each, worth keeping:
+- the time from serve to ready;
+- tokens a second from `llmgw ctl bench`;
+- the plan's per-card figure against what `nvidia-smi` shows once loaded;
+- anything it said that was wrong.

docs/onboarding.md

@@ -54,10 +54,20 @@ on the page that creates it and never again.
 
 ### Connecting an editor
 
-The account page's **Connect your editor** makes a key for Continue, Codex or
-Cline and shows what the tool needs with that key, this gateway's address and a
-model already in it:
+The account page's **Connect your editor** makes a key for VS Code, Continue,
+Codex or Cline and shows what the tool needs with that key, this gateway's
+address and a model already in it:
 
+- **VS Code** — llmgw's own extension, downloaded from the gateway at
+  `/setup/vscode/llmgw.vsix` with this gateway's address already in it. It
+  offers every chat model the key may use to VS Code itself: the chat's model
+  picker, agent mode, and any extension that asks VS Code for a language model
+  (Cline's "VS Code LM API" provider among them), with no setup of their own.
+  **llmgw: Sign In** in VS Code opens this page with VS Code chosen; the page's
+  **Open in VS Code** link hands the key back, and the extension keeps it in
+  VS Code's secret storage. A link the extension did not ask for is confirmed
+  first, with the gateway's address shown, since it decides where code is sent.
+  **llmgw: Enter API Key** takes a pasted one instead.
 - **Continue** — an assistant file of its own, `~/.continue/assistants/llmgw.yaml`,
   so their `config.yaml` is not touched.
 - **Codex** — a provider and a profile in `~/.codex/config.toml`, run with
@@ -379,16 +389,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
 

docs/quick-install.md

@@ -8,7 +8,7 @@ explains every choice.
 
 | | |
 |---|---|
-| **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. |
+| **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 — 12 GB RAM when it is also a node running the starter model and the two judges, which setup checks before it installs anything; four cores or more, or the judges on machines of their own, keep a judgment within its wait. |
 | **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`). |
@@ -52,7 +52,7 @@ install:
 - 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;
-- guardrails on every request, with a judge model (Llama Guard 3 1B, two
+- 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).
 

go.mod

@@ -12,12 +12,14 @@ require (
 	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-ldap/ldap/v3 v3.4.15
 	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
 	github.com/knadh/koanf/providers/file v1.2.1
 	github.com/knadh/koanf/v2 v2.3.6
+	github.com/ledongthuc/pdf v0.0.0-20260907135840-6c8c28e0e8a0
 	github.com/mattn/go-isatty v0.0.24
 	github.com/prometheus/client_golang v1.24.1
 	github.com/prometheus/client_model v0.6.3
@@ -34,6 +36,8 @@ require (
 	golang.org/x/net v0.59.0
 	golang.org/x/oauth2 v0.37.0
 	golang.org/x/sync v0.23.0
+	golang.org/x/sys v0.48.0
+	golang.org/x/term v0.46.0
 	golang.org/x/text v0.42.0
 	google.golang.org/protobuf v1.36.12
 	modernc.org/sqlite v1.59.0
@@ -42,6 +46,7 @@ require (
 require (
 	filippo.io/edwards25519 v1.2.0 // indirect
 	filippo.io/hpke v0.4.0 // indirect
+	github.com/Azure/go-ntlmssp v0.1.1 // 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
@@ -54,6 +59,7 @@ require (
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
 	github.com/fsnotify/fsnotify v1.9.0 // indirect
+	github.com/go-asn1-ber/asn1-ber v1.5.8 // indirect
 	github.com/go-logr/logr v1.4.4 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
@@ -86,7 +92,6 @@ require (
 	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
-	golang.org/x/sys v0.48.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

@@ -8,8 +8,12 @@ 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/Azure/go-ntlmssp v0.1.1 h1:l+FM/EEMb0U9QZE7mKNEDw5Mu3mFiaa2GKOoTSsNDPw=
+github.com/Azure/go-ntlmssp v0.1.1/go.mod h1:NYqdhxd/8aAct/s4qSYZEerdPuH1liG2/X9DiVTbhpk=
 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/alexbrainman/sspi v0.0.0-20250919150558-7d374ff0d59e h1:4dAU9FXIyQktpoUAgOJK3OTFc/xug0PCXYCqU0FgDKI=
+github.com/alexbrainman/sspi v0.0.0-20250919150558-7d374ff0d59e/go.mod h1:cEWa1LVoE5KvSD9ONXsZrj0z6KqySlCCNKHlLzbqAt4=
 github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
 github.com/aymanbagabas/go-osc52/v2 v2.0.1/go.mod h1:uYgXzlJ7ZpABp8OJ+exZzJJhRNQ2ASbcXHWsFqH8hp8=
 github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
@@ -46,8 +50,12 @@ 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-asn1-ber/asn1-ber v1.5.8 h1:H9AZkK22UOmfX8J84ubyaZxKJZ3FMHVwn8swoMML7iQ=
+github.com/go-asn1-ber/asn1-ber v1.5.8/go.mod h1:hEBeB/ic+5LoWskz+yKT7vGhhPYkProFKoKdwZRWMe0=
 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-ldap/ldap/v3 v3.4.15 h1:eRB4f4Ecn1POL1mO86+uUDlecmyWsdiJwh60bAUS4UY=
+github.com/go-ldap/ldap/v3 v3.4.15/go.mod h1:jeD0c98EdZQCKKKKe4kTWs5aCf6y+j8KuYsYLznZSQk=
 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=
@@ -69,6 +77,8 @@ github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.30.0 h1:/Tnpcb2E0Pz/tN9s3bfEY2Q8ePCEX9iuS+cneUwncnw=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.30.0/go.mod h1:zOBXOsUaBSjKgmH4OGzV1esUpR3oUSCPYVd2cUBjKYY=
+github.com/hashicorp/go-uuid v1.0.3 h1:2gKiV6YVmrJ1i2CKKa9obLvRieoRGviZFL26PcT/Co8=
+github.com/hashicorp/go-uuid v1.0.3/go.mod h1:6SBZvOh/SIDV7/2o3Jml5SYk/TvGqwFJ/bN7x4byOro=
 github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
 github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
@@ -81,6 +91,18 @@ github.com/jackc/pgx/v5 v5.11.0 h1:IzBBtyK9AHqf98cctWFifYSci2hgQR/cd56wB4p+ogg=
 github.com/jackc/pgx/v5 v5.11.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
 github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
 github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
+github.com/jcmturner/aescts/v2 v2.0.0 h1:9YKLH6ey7H4eDBXW8khjYslgyqG2xZikXP0EQFKrle8=
+github.com/jcmturner/aescts/v2 v2.0.0/go.mod h1:AiaICIRyfYg35RUkr8yESTqvSy7csK90qZ5xfvvsoNs=
+github.com/jcmturner/dnsutils/v2 v2.0.0 h1:lltnkeZGL0wILNvrNiVCR6Ro5PGU/SeBvVO/8c/iPbo=
+github.com/jcmturner/dnsutils/v2 v2.0.0/go.mod h1:b0TnjGOvI/n42bZa+hmXL+kFJZsFT7G4t3HTlQ184QM=
+github.com/jcmturner/gofork v1.7.6 h1:QH0l3hzAU1tfT3rZCnW5zXl+orbkNMMRGJfdJjHVETg=
+github.com/jcmturner/gofork v1.7.6/go.mod h1:1622LH6i/EZqLloHfE7IeZ0uEJwMSUyQ/nDd82IeqRo=
+github.com/jcmturner/goidentity/v6 v6.0.1 h1:VKnZd2oEIMorCTsFBnJWbExfNN7yZr3EhJAxwOkZg6o=
+github.com/jcmturner/goidentity/v6 v6.0.1/go.mod h1:X1YW3bgtvwAXju7V3LCIMpY0Gbxyjn/mY9zx4tFonSg=
+github.com/jcmturner/gokrb5/v8 v8.4.4 h1:x1Sv4HaTpepFkXbt2IkL29DXRf8sOfZXo8eRKh687T8=
+github.com/jcmturner/gokrb5/v8 v8.4.4/go.mod h1:1btQEpgT6k+unzCwX1KdWMEwPPkkgBtP+F6aCACiMrs=
+github.com/jcmturner/rpc/v2 v2.0.3 h1:7FXXj8Ti1IaVFpSAziCZWNzbNuZmnvw/i6CqLNdWfZY=
+github.com/jcmturner/rpc/v2 v2.0.3/go.mod h1:VUJYCIDm3PVOEHw8sgt091/20OJjskO/YJki3ELg/Hc=
 github.com/klauspost/compress v1.19.1 h1:VsB4HPswih7mmZ8WleSFQ75c/Ui1M4trX5oAsJnhSlk=
 github.com/klauspost/compress v1.19.1/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
 github.com/knadh/koanf/maps v0.1.2 h1:RBfmAW5CnZT+PJ1CVc1QSJKf4Xu9kxfQgYVQSu8hpbo=
@@ -95,6 +117,8 @@ github.com/knadh/koanf/v2 v2.3.6 h1:JoQPSJmvS4aP0xNc8xMDr5tcrkSEInL23/Il7pITAKo=
 github.com/knadh/koanf/v2 v2.3.6/go.mod h1:gRb40VRAbd4iJMYYD5IxZ6hfuopFcXBpc9bbQpZwo28=
 github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
 github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
+github.com/ledongthuc/pdf v0.0.0-20260907135840-6c8c28e0e8a0 h1:7Q+xNAZFmnfYOMweHN3c/PDFUKKfY1pVJ26K++QvVfU=
+github.com/ledongthuc/pdf v0.0.0-20260907135840-6c8c28e0e8a0/go.mod h1:1fEHWurg7pvf5SG6XNE5Q8UZmOwex51Mkx3SLhrW5B4=
 github.com/lucasb-eyer/go-colorful v1.3.0 h1:2/yBRLdWBZKrf7gB40FoiKfAWYQ0lqNcbuQwVHXptag=
 github.com/lucasb-eyer/go-colorful v1.3.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
 github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI=

internal/account/account_test.go

@@ -448,3 +448,40 @@ func TestAHashThatCannotGetATurnSaysTheServerIsBusy(t *testing.T) {
 		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/directory_test.go

@@ -0,0 +1,63 @@
+package account
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
+)
+
+type fakeDirectory struct {
+	asked []string
+	u     store.User
+	err   error
+}
+
+func (f *fakeDirectory) SignIn(_ context.Context, login, _ string) (store.User, error) {
+	f.asked = append(f.asked, login)
+	return f.u, f.err
+}
+
+// With a directory, a name the store has no password for is the
+// directory's to check; an account with a password here — the
+// administrator init made — is still checked here, so a directory that is
+// down locks nobody out.
+func TestPasswordsKeptElsewhereAreTheDirectorysToCheck(t *testing.T) {
+	svc, st := newService(t)
+	ctx := t.Context()
+	hash, _ := HashPassword("local-secret")
+	admin := store.User{ID: "usr-admin", Email: "admin@example.com", Name: "a", PasswordHash: hash,
+		State: store.UserActive, CreatedAt: time.Now()}
+	ada := store.User{ID: "usr-ada", Email: "ada@corp.example", Name: "Ada", PasswordHash: "!ldap",
+		State: store.UserActive, CreatedAt: time.Now()}
+	for _, u := range []store.User{admin, ada} {
+		if err := st.CreateUser(ctx, u); err != nil {
+			t.Fatal(err)
+		}
+	}
+	dir := &fakeDirectory{u: ada}
+	svc.SetDirectory(dir)
+
+	if _, _, err := svc.SignIn(ctx, "admin@example.com", "local-secret"); err != nil || len(dir.asked) != 0 {
+		t.Fatalf("the local administrator: %v, directory asked %v", err, dir.asked)
+	}
+	// A name, not an address, and an account kept by the directory.
+	for _, login := range []string{`CORP\ada`, "ada@corp.example"} {
+		if tok, _, err := svc.SignIn(ctx, login, "ad-secret"); err != nil || tok == "" {
+			t.Errorf("%s: %v", login, err)
+		}
+	}
+	if len(dir.asked) != 2 || dir.asked[0] != `CORP\ada` {
+		t.Errorf("the directory was asked %v", dir.asked)
+	}
+	dir.err = ErrBadCredentials
+	if _, _, err := svc.SignIn(ctx, "ada", "wrong"); !errors.Is(err, ErrBadCredentials) {
+		t.Errorf("a password the directory refused: %v", err)
+	}
+	// A reset link would give a directory's account a password here.
+	if _, _, err := svc.RequestReset(ctx, st, "ada@corp.example"); !errors.Is(err, ErrNoReset) {
+		t.Errorf("a directory's account was sent a reset link: %v", err)
+	}
+}

internal/account/service.go

@@ -80,8 +80,26 @@ type Service struct {
 
 	mu       sync.Mutex
 	attempts map[string]*attemptWindow
+
+	// dir checks the passwords of accounts this store keeps none for.
+	dir Directory
 }
 
+// Directory checks a password against an outside directory — Active
+// Directory over LDAP — and answers the account to sign in: made or kept in
+// step with the directory. Its errors are this package's ErrBadCredentials
+// and ErrSuspended for the person's own, and anything else for the
+// directory's.
+type Directory interface {
+	SignIn(ctx context.Context, login, password string) (store.User, error)
+}
+
+// SetDirectory has passwords for accounts with none here, and names that are
+// not addresses, checked by the directory. An account with a password here
+// — the administrator init made — is still checked here, so a directory that
+// is down locks nobody out.
+func (s *Service) SetDirectory(d Directory) { s.dir = d }
+
 type attemptWindow struct {
 	count int
 	since time.Time
@@ -137,6 +155,7 @@ func (s *Service) SignUp(ctx context.Context, email, name, password string) erro
 // SignIn checks a password and opens a session, returning the session token and
 // 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) {
+	login := strings.TrimSpace(email)
 	email = store.NormalizeEmail(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
@@ -151,6 +170,15 @@ func (s *Service) SignIn(ctx context.Context, email, password string) (token, cs
 	}
 
 	u, err := s.store.UserByEmail(ctx, email)
+	// No password kept here — the directory's, or nobody's — and a
+	// directory to ask: it decides.
+	if s.dir != nil && (errors.Is(err, store.ErrNotFound) || (err == nil && strings.HasPrefix(u.PasswordHash, "!"))) {
+		if u, err = s.dir.SignIn(ctx, login, password); err != nil {
+			return "", "", err
+		}
+		s.clearAttempts(byClient)
+		return s.open(ctx, u)
+	}
 	if errors.Is(err, store.ErrNotFound) {
 		// Verify anyway, against a hash that cannot match. Returning early here
 		// would let a stopwatch enumerate every account on the system.
@@ -180,7 +208,11 @@ func (s *Service) SignIn(ctx context.Context, email, password string) (token, cs
 	case store.UserSuspended:
 		return "", "", ErrSuspended
 	}
+	return s.open(ctx, u)
+}
 
+// open makes a session for a person whose password was right.
+func (s *Service) open(ctx context.Context, u store.User) (token, csrf string, err error) {
 	if token, err = store.NewSessionToken(); err != nil {
 		return "", "", err
 	}
@@ -373,3 +405,66 @@ 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)
+	// An account whose password is kept elsewhere — "!oidc", "!scim",
+	// "!ldap" — gets no link: setting one here would give it a second way
+	// in that its directory knows nothing of, and outlives its leaving.
+	if err != nil || u.PasswordHash == "" || strings.HasPrefix(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/accounting/accounting.go

@@ -323,7 +323,7 @@ func (a *Accountant) Record(res Reservation, u store.Usage) {
 	if u.ServedModel != "" && u.ServedModel != u.Model && a.pricing != nil {
 		price = a.pricing.For(u.ServedModel)
 	}
-	u.CostMicros = price.Cost(u.PromptTokens, u.CompletionTokens)
+	u.CostMicros = price.Cost(u.PromptTokens, u.CachedTokens, u.CompletionTokens, u.Images, u.Meshes)
 	for _, b := range res.Budgets {
 		a.budgets.Add(b.Counter, b.Period, u.CostMicros)
 	}

internal/accounting/accounting_test.go

@@ -39,17 +39,44 @@ func TestCostRoundsUpSoSmallRequestsAreNotFree(t *testing.T) {
 	// Rounding down would make a stream of tiny requests cost nothing, which is
 	// exactly the traffic shape a quota exists to bound.
 	p := Price{PromptPer1k: 1000, CompletionPer1k: 3000}
-	if got := p.Cost(1, 0); got != 1 {
+	if got := p.Cost(1, 0, 0, 0, 0); got != 1 {
 		t.Errorf("one prompt token cost %d", got)
 	}
-	if got := p.Cost(1000, 1000); got != 4000 {
+	if got := p.Cost(1000, 0, 1000, 0, 0); got != 4000 {
 		t.Errorf("a thousand of each cost %d, want 4000", got)
 	}
-	if got := p.Cost(0, 0); got != 0 {
+	if got := p.Cost(0, 0, 0, 0, 0); got != 0 {
 		t.Errorf("an empty request cost %d", got)
 	}
 }
 
+func TestACachedPromptCostsTheCachedRate(t *testing.T) {
+	p := Price{PromptPer1k: 1000, CachedPer1k: 100, CompletionPer1k: 3000}
+	// 10,000 prompt tokens of which 9,000 were read from the cache: 1,000 at
+	// the prompt rate and 9,000 at the cached one.
+	if got, want := p.Cost(10000, 9000, 0, 0, 0), int64(1000+900); got != want {
+		t.Errorf("a 90%% cached prompt cost %d, want %d", got, want)
+	}
+	// More cached than prompt is an engine's miscount, not a refund.
+	if got := p.Cost(100, 500, 0, 0, 0); got != 10 {
+		t.Errorf("cached beyond the prompt cost %d, want 10", got)
+	}
+	// No cached rate: cached tokens cost what any prompt token does.
+	if got := (Price{PromptPer1k: 1000}).Cost(10000, 9000, 0, 0, 0); got != 10000 {
+		t.Errorf("without a cached rate a cached prompt cost %d, want 10000", got)
+	}
+}
+
+func TestAPictureCostsItsPriceOnTopOfItsPrompt(t *testing.T) {
+	p := Price{PromptPer1k: 1000, PerImage: 50000}
+	if got := p.Cost(20, 0, 0, 3, 0); got != 20+150000 {
+		t.Errorf("three pictures from a 20-token prompt cost %d", got)
+	}
+	if (Price{PerImage: 1}).Zero() {
+		t.Error("a model priced per picture reads as free, and would pass a spent budget")
+	}
+}
+
 func TestZeroPricedModelsStayAvailableWhenTheBudgetIsSpent(t *testing.T) {
 	// This is what makes budget fallback work: a key with nothing left can
 	// still be served something that costs nothing.

internal/accounting/cost.go

@@ -18,6 +18,18 @@ import (
 type Price struct {
 	PromptPer1k     int64 `koanf:"prompt_per_1k"`
 	CompletionPer1k int64 `koanf:"completion_per_1k"`
+	// CachedPer1k is what a prompt token costs that the engine or provider
+	// read from its cache instead of computing: the part of prompt_tokens
+	// the answer counts as cached_tokens. Zero charges those at
+	// PromptPer1k, as before there was a rate for them.
+	CachedPer1k int64 `koanf:"cached_per_1k"`
+	// PerImage is what one picture costs, for a model that makes them: a
+	// picture's cost is the card's time, which its prompt's few tokens do
+	// not measure.
+	PerImage int64 `koanf:"per_image"`
+	// PerMesh is what one 3D model costs: minutes of a card, which no
+	// token count measures.
+	PerMesh int64 `koanf:"per_mesh"`
 }
 
 // Zero reports whether this model spends nothing.
@@ -25,14 +37,26 @@ type Price struct {
 // It matters beyond arithmetic: a zero-cost model stays available to a key
 // whose budget is spent, which is what makes the plan's budget fallback work
 // (§7.7).
-func (p Price) Zero() bool { return p.PromptPer1k == 0 && p.CompletionPer1k == 0 }
+func (p Price) Zero() bool {
+	return p.PromptPer1k == 0 && p.CompletionPer1k == 0 && p.CachedPer1k == 0 && p.PerImage == 0 && p.PerMesh == 0
+}
 
 // Cost computes what a request spent, rounding up.
 //
 // Up rather than to nearest: rounding down would make a stream of tiny requests
 // free, which is exactly the shape of traffic a quota exists to bound.
-func (p Price) Cost(promptTokens, completionTokens int64) int64 {
-	return divUp(promptTokens*p.PromptPer1k, 1000) + divUp(completionTokens*p.CompletionPer1k, 1000)
+//
+// cachedTokens are counted within promptTokens, as OpenAI's usage counts
+// them, and are charged at the cached rate instead of the prompt rate.
+func (p Price) Cost(promptTokens, cachedTokens, completionTokens, images, meshes int64) int64 {
+	cachedTokens = min(max(cachedTokens, 0), max(promptTokens, 0))
+	cachedRate := p.CachedPer1k
+	if cachedRate == 0 {
+		cachedRate = p.PromptPer1k
+	}
+	return divUp((promptTokens-cachedTokens)*p.PromptPer1k+cachedTokens*cachedRate, 1000) +
+		divUp(completionTokens*p.CompletionPer1k, 1000) +
+		max(images, 0)*p.PerImage + max(meshes, 0)*p.PerMesh
 }
 
 func divUp(n, d int64) int64 {

internal/agent/agent.go

@@ -6,6 +6,7 @@ import (
 	"crypto/sha256"
 	"crypto/tls"
 	"encoding/hex"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
@@ -34,6 +35,7 @@ import (
 	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/engines"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/provision"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/supervisor"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/train"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/weights"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/control/agentsvc"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/firewall"
@@ -136,6 +138,13 @@ type Agent struct {
 	// by mu.
 	kv     *kvevents.Mirror
 	kvSubs map[string]*kvevents.Subscriber
+
+	// settingsCheck says whether the cluster's settings for this agent
+	// would load beside its agent.yaml; see SetSettingsCheck.
+	settingsCheck func([]byte) error
+
+	// trainer runs LoRA training jobs, one at a time (BACKLOG F4).
+	trainer *train.Runner
 }
 
 // connectHTTPClient is the HTTP client connect uses; an interface so tests can
@@ -182,6 +191,18 @@ func New(cfg Config, httpClient connectHTTPClient, log *slog.Logger) (*Agent, er
 		kvSubs:       map[string]*kvevents.Subscriber{},
 	}
 	a.prov = &provision.Installer{Root: cfg.EnginesDir, Log: log, OnStatus: a.provisionStatus}
+	runAs := cfg.Superv.RunAs
+	if runAs == "" {
+		runAs = supervisor.DefaultRunAs
+	}
+	// Where the engines are, as the installer has it when the file says
+	// nothing.
+	enginesDir := cfg.EnginesDir
+	if enginesDir == "" {
+		enginesDir = provision.DefaultRoot
+	}
+	a.trainer = train.New(train.Env{EnginesDir: enginesDir, WorkDir: filepath.Join(cfg.Superv.WorkDir, "trainer"),
+		RunAs: runAs, Log: log})
 	return a, nil
 }
 
@@ -371,6 +392,12 @@ func (a *Agent) settleAdopted(sh *supervisor.Shard, o supervisor.Orphan) {
 		_ = 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)
 }
@@ -411,6 +438,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() {
@@ -436,6 +474,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),
 		})
@@ -564,8 +603,9 @@ func (a *Agent) session(ctx context.Context, server string) error {
 		a.sendLoop(ctx, stream, out)
 	}()
 	defer wg.Wait()
-	go a.watchExits(ctx, out)
+	go a.watchExits(ctx, out, unready(reg.RunningShards))
 	go a.forwardKV(ctx, out)
+	go a.reportCompute(ctx, out)
 
 	for {
 		msg, err := stream.Receive()
@@ -861,6 +901,20 @@ func (a *Agent) handle(ctx context.Context, msg *llmgwv1.ControlMessage, out cha
 		a.setControlPlanes(m.ControlPlanes)
 	case *llmgwv1.ControlMessage_Firewall:
 		go a.applyFirewall(m.Firewall)
+	case *llmgwv1.ControlMessage_AgentSettings:
+		go a.applySettings(m.AgentSettings)
+	case *llmgwv1.ControlMessage_TrainStart:
+		go a.trainJob(ctx, m.TrainStart, out)
+	case *llmgwv1.ControlMessage_TrainCancel:
+		a.trainer.Cancel(m.TrainCancel.GetJobId())
+	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
@@ -1078,6 +1132,31 @@ func (a *Agent) startShard(ctx context.Context, m *llmgwv1.StartShard, out chan<
 		stop()
 		spec.Profile.ModelPath = path
 	}
+	// A shared ComfyUI replica's members' weights, each fetched like the
+	// model's, and handed to the gate where they landed.
+	if raw := spec.Profile.Env[engines.SharedModelsEnv]; raw != "" {
+		var ms []map[string]string
+		if err := json.Unmarshal([]byte(raw), &ms); err != nil {
+			report(supervisor.Failed, "the shared replica's models are not readable: "+err.Error(), nil)
+			return
+		}
+		for i, m := range ms {
+			stop := a.watchFetch(m["source"], func(p weights.Progress) {
+				send(&llmgwv1.ShardStatus{State: agentsvc.StateToWire(supervisor.Starting),
+					Fetch: &llmgwv1.FetchProgress{Source: p.Source, BytesDone: p.BytesDone, BytesTotal: p.BytesTotal}})
+			})
+			path, err := a.weights().Ensure(ctx, m["source"])
+			stop()
+			if err != nil {
+				report(supervisor.Failed, fmt.Sprintf("model %s: %v", m["name"], err), nil)
+				return
+			}
+			ms[i]["path"] = path
+		}
+		b, _ := json.Marshal(ms)
+		spec.Profile.Env = maps.Clone(spec.Profile.Env)
+		spec.Profile.Env[engines.SharedModelsEnv] = string(b)
+	}
 	// 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.
@@ -1130,6 +1209,14 @@ func (a *Agent) startShard(ctx context.Context, m *llmgwv1.StartShard, out chan<
 	} 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 {
@@ -1142,7 +1229,19 @@ func (a *Agent) startShard(ctx context.Context, m *llmgwv1.StartShard, out chan<
 		report(supervisor.Failed, err.Error(), sh.Logs(20))
 		return
 	}
-	report(supervisor.Ready, "", nil)
+	// 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.
 }
 
@@ -1155,7 +1254,14 @@ func (a *Agent) startShard(ctx context.Context, m *llmgwv1.StartShard, out chan<
 // 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.
-func (a *Agent) watchExits(ctx context.Context, out chan<- *llmgwv1.AgentMessage) {
+//
+// 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{}
@@ -1164,6 +1270,24 @@ func (a *Agent) watchExits(ctx context.Context, out chan<- *llmgwv1.AgentMessage
 			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
@@ -1293,11 +1417,14 @@ func Client(cfg tlsconf.Config, timeout time.Duration) (*http.Client, error) {
 // 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.
+// seconds and the node stayed with the dead one. An HTTP/2 ping after five
+// quiet seconds, given three to answer, finds it in eight: by the time the
+// standby leads, as it does within the lease's ten seconds, the node is on
+// its way to it. At fifteen, with the lease at fifteen too, the new leader
+// went without its nodes, and so its judges, for half a minute.
 const (
-	streamIdle = 10 * time.Second
-	streamPing = 5 * time.Second
+	streamIdle = 5 * time.Second
+	streamPing = 3 * time.Second
 )
 
 // localizeSpec fills in what only this node knows.
@@ -1373,3 +1500,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/config.go

@@ -103,6 +103,11 @@ type Config struct {
 	Tracing obs.Tracing `koanf:"tracing"`
 
 	Version string
+
+	// Settings is the cluster's settings for this agent it was started on,
+	// as the control plane sent them: what a newly sent version is
+	// compared with.
+	Settings string `koanf:"-"`
 }
 
 // DefaultConfig returns sensible defaults.

internal/agent/discovery/host.go

@@ -3,6 +3,7 @@ package discovery
 import (
 	"bufio"
 	"os"
+	"regexp"
 	"runtime"
 	"strconv"
 	"strings"
@@ -142,17 +143,29 @@ func cpuFlagsFrom(path string) []string {
 // nvidiaDriverFrom reads the loaded kernel module's version, which exists
 // exactly when a driver is loaded — unlike nvidia-smi, which can be installed
 // on a machine whose module failed to load.
+var driverVersion = regexp.MustCompile(`^[0-9]+\.[0-9]+(\.[0-9]+)?$`)
+
 func nvidiaDriverFrom(path string) string {
 	b, err := os.ReadFile(path) //nolint:gosec // a fixed system path
 	if err != nil {
 		return ""
 	}
-	// "NVRM version: NVIDIA UNIX x86_64 Kernel Module  570.86.15  Thu ..."
+	// "NVRM version: NVIDIA UNIX x86_64 Kernel Module  570.86.15  Thu ...", or
+	// for the open module, the default since 560, "NVIDIA UNIX Open Kernel
+	// Module for x86_64  580.82.07  Release Build ...": the first version
+	// after "Module", not the word after it. Read as "for", the driver was
+	// unknown, and every build was tried whatever driver it needs.
 	fields := strings.Fields(string(b))
 	for i, f := range fields {
-		if f == "Module" && i+1 < len(fields) {
-			return fields[i+1]
+		if f != "Module" {
+			continue
 		}
+		for _, v := range fields[i+1:] {
+			if driverVersion.MatchString(v) {
+				return v
+			}
+		}
+		return ""
 	}
 	return ""
 }

internal/agent/discovery/host_driver_test.go

@@ -0,0 +1,25 @@
+package discovery
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestNVIDIADriverFrom(t *testing.T) {
+	for _, tc := range []struct{ text, want string }{
+		{"NVRM version: NVIDIA UNIX x86_64 Kernel Module  570.86.15  Thu Jan 23 21:30:38 UTC 2025\nGCC version:  gcc version 12.2.0\n", "570.86.15"},
+		{"NVRM version: NVIDIA UNIX Open Kernel Module for x86_64  580.82.07  Release Build  (dvs-builder@U16-I3-B03-4-3)  Wed Aug 27 00:51:12 UTC 2025\n", "580.82.07"},
+		{"NVRM version: NVIDIA UNIX Open Kernel Module for aarch64  580.95.05  Release Build\n", "580.95.05"},
+		{"NVRM version: NVIDIA UNIX x86_64 Kernel Module  535.54  Mon\n", "535.54"},
+		{"something else\n", ""},
+	} {
+		p := filepath.Join(t.TempDir(), "version")
+		if err := os.WriteFile(p, []byte(tc.text), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if got := nvidiaDriverFrom(p); got != tc.want {
+			t.Errorf("%q: got %q, want %q", tc.text, got, tc.want)
+		}
+	}
+}

internal/agent/discovery/sensors.go

@@ -74,6 +74,13 @@ func NewSensorSampler() *SensorSampler {
 	return &SensorSampler{sys: "/sys", smi: runSMI, now: time.Now}
 }
 
+// SampleGPUs reads every card's heat, power and how busy it is now, without
+// a sampler's ten seconds of memory: for a screen that asks every few seconds
+// and wants what it asked for. Nil on a machine without nvidia-smi or a card.
+func SampleGPUs(ctx context.Context) []GPUSensor {
+	return (&SensorSampler{smi: runSMI}).gpus(ctx)
+}
+
 func runSMI(ctx context.Context, fields string) ([]byte, error) {
 	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
 	defer cancel()

internal/agent/engines/comfyui.go

@@ -0,0 +1,151 @@
+package engines
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"sync/atomic"
+)
+
+// ComfyUIConfig locates a ComfyUI installation.
+type ComfyUIConfig struct {
+	// Dir is ComfyUI's directory, where main.py is. Readable by the user
+	// engines run as.
+	Dir string `koanf:"dir"`
+	// Python is the interpreter of its environment; Dir's .venv when unset.
+	Python string `koanf:"python"`
+}
+
+// ComfyUI runs ComfyUI as an engine, behind llmgw's gate (llmgw
+// comfyui-gate): ComfyUI asks for no key, so it listens on the loopback and
+// the gate, which does, on the replica's port. Its replicas make pictures
+// for /v1/images/generations.
+type ComfyUI struct {
+	cfg       ComfyUIConfig
+	installed atomic.Pointer[string]
+}
+
+// Name identifies the engine in the catalog.
+func (*ComfyUI) Name() string { return "comfyui" }
+
+// HealthPath is the gate's, which answers once ComfyUI does.
+func (*ComfyUI) HealthPath() string { return "/health" }
+
+// MetricsPath is empty: ComfyUI publishes no metrics, and the router reads
+// none from it.
+func (*ComfyUI) MetricsPath() string { return "" }
+
+// ServesHTTP is true: a ComfyUI replica is one process on one node.
+func (*ComfyUI) ServesHTTP(ShardSpec) bool { return true }
+
+// UseInstalled points the engine at the environment the agent installed:
+// its interpreter, with ComfyUI's code beside its bin, in comfyui/.
+func (c *ComfyUI) UseInstalled(python string) { c.installed.Store(&python) }
+
+// Configured reports whether the configuration names a ComfyUI.
+func (c *ComfyUI) Configured() bool { return c.cfg.Dir != "" }
+
+func (c *ComfyUI) dir() string {
+	if p := c.installed.Load(); p != nil {
+		return filepath.Join(filepath.Dir(filepath.Dir(*p)), "comfyui")
+	}
+	return c.cfg.Dir
+}
+
+func (c *ComfyUI) python() string {
+	if p := c.installed.Load(); p != nil {
+		return *p
+	}
+	if c.cfg.Python != "" {
+		return c.cfg.Python
+	}
+	return filepath.Join(c.cfg.Dir, ".venv", "bin", "python")
+}
+
+var comfyVersion = regexp.MustCompile(`__version__\s*=\s*"([^"]+)"`)
+
+// Probe reports ComfyUI's version, from the file its build writes it to:
+// importing ComfyUI to ask would load torch and look for cards.
+func (c *ComfyUI) Probe(context.Context) (string, error) {
+	dir := c.dir()
+	if dir == "" {
+		return "", fmt.Errorf("no ComfyUI directory is configured")
+	}
+	if _, err := os.Stat(filepath.Join(dir, "main.py")); err != nil {
+		return "", fmt.Errorf("%s is not ComfyUI: %w", dir, err)
+	}
+	b, err := os.ReadFile(filepath.Join(dir, "comfyui_version.py"))
+	if err != nil {
+		return Unknown, nil //nolint:nilerr // installed, of a version it does not say
+	}
+	if m := comfyVersion.FindSubmatch(b); m != nil {
+		return string(m[1]), nil
+	}
+	return Unknown, nil
+}
+
+// Validate checks the profile: one card, on one node. ComfyUI runs a
+// workflow on one device and has no tensor parallelism to spread it by.
+func (*ComfyUI) Validate(p Profile, gpus []GPUInfo) error {
+	if p.Nodes > 1 || p.TP > 1 || p.PP > 1 || p.GPUsPerNode > 1 {
+		return fmt.Errorf("profile %q: ComfyUI runs on one GPU of one node", p.Name)
+	}
+	return validateCommon(p, gpus)
+}
+
+// Commands is the gate, which starts ComfyUI itself.
+func (c *ComfyUI) Commands(s ShardSpec) ([]Command, error) {
+	dir := c.dir()
+	if dir == "" {
+		return nil, fmt.Errorf("comfyui: no ComfyUI directory is configured (engines.comfyui.dir)")
+	}
+	bin, err := os.Executable()
+	if err != nil {
+		return nil, err
+	}
+	p := s.Profile
+	args := []string{"comfyui-gate",
+		"--listen", net.JoinHostPort(s.Host(), strconv.Itoa(s.HTTPPort)),
+		"--model", p.ServedModelName,
+		"--weights", p.ModelPath,
+		// Relative to where engines run — their user's home — so it is
+		// theirs to write.
+		"--state", filepath.Join("comfyui", s.ReplicaID),
+		"--python", c.python(),
+		"--comfyui", dir,
+		"--",
+	}
+	args = append(args, p.Args...)
+	env := baseEnv(s)
+	if s.APIKey != "" {
+		env["LLMGW_ENGINE_KEY"] = s.APIKey
+	}
+	// A model's custom nodes and the repository a node loads its weights by,
+	// which only the catalog sets — a profile's env may not name them — and
+	// so taken before baseEnv drops them. Without the repository the gate
+	// links no Hugging Face cache, and sf3d's node went to the network for
+	// its gated repository and was refused with a 401.
+	for _, k := range []string{comfyNodesEnv, comfyHFRepoEnv, SharedModelsEnv} {
+		if v := p.Env[k]; v != "" {
+			env[k] = v
+		}
+	}
+	return []Command{{Name: "comfyui", Path: bin, Args: args, Env: materializeEnv(env)}}, nil
+}
+
+// comfyNodesEnv is the custom nodes the catalog gives a ComfyUI model, as
+// JSON; catalog.NodesEnv and comfy.NodesEnv by the same name.
+const comfyNodesEnv = "LLMGW_COMFYUI_NODES"
+
+// comfyHFRepoEnv is the repository a custom node loads the weights by name
+// from; catalog.HFRepoEnv and comfy.HFRepoEnv by the same name.
+const comfyHFRepoEnv = "LLMGW_COMFYUI_HF_REPO"
+
+// SharedModelsEnv is a shared replica's members — name, source, and the
+// path the agent fetched it to — as JSON; catalog.SharedModelsEnv and
+// comfy.SharedModelsEnv by the same name.
+const SharedModelsEnv = "LLMGW_COMFYUI_MODELS"

internal/agent/engines/comfyui_test.go

@@ -0,0 +1,99 @@
+package engines
+
+import (
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"testing"
+)
+
+func TestComfyUIRunsBehindTheGateWithItsKeyOutOfSight(t *testing.T) {
+	c := &ComfyUI{cfg: ComfyUIConfig{Dir: "/opt/comfyui"}}
+	cmds, err := c.Commands(ShardSpec{
+		ReplicaID: "r-flux-1", HTTPPort: 8100, BindAddr: "10.0.0.147", APIKey: "sekret", GPUIndices: []int{0},
+		Profile: Profile{Name: "p", Engine: "comfyui", ModelPath: "/w/flux.safetensors", ServedModelName: "flux",
+			Args: []string{"--disable-smart-memory"}},
+	})
+	if err != nil || len(cmds) != 1 {
+		t.Fatalf("%v %v", cmds, err)
+	}
+	args := strings.Join(cmds[0].Args, " ")
+	for _, want := range []string{"comfyui-gate", "--listen 10.0.0.147:8100", "--model flux", "--weights /w/flux.safetensors",
+		"--state comfyui/r-flux-1", "--python /opt/comfyui/.venv/bin/python", "--comfyui /opt/comfyui", "-- --disable-smart-memory"} {
+		if !strings.Contains(args, want) {
+			t.Errorf("%q not in %q", want, args)
+		}
+	}
+	if strings.Contains(args, "sekret") {
+		t.Error("the key is on the command line, where every user can read it")
+	}
+	if !slices.Contains(cmds[0].Env, "LLMGW_ENGINE_KEY=sekret") || !slices.Contains(cmds[0].Env, "CUDA_VISIBLE_DEVICES=0") {
+		t.Error("the key or the card is not in the environment")
+	}
+}
+
+func TestTheGateIsToldTheNodesAndTheRepositoryTheCatalogGives(t *testing.T) {
+	// The repository was dropped on the way: sf3d's node went to the network
+	// for its gated repository, with no cache linked, and got a 401.
+	c := &ComfyUI{cfg: ComfyUIConfig{Dir: "/opt/comfyui"}}
+	cmds, err := c.Commands(ShardSpec{
+		ReplicaID: "r-sf3d-1", HTTPPort: 8100, BindAddr: "10.0.0.147", GPUIndices: []int{0},
+		Profile: Profile{Name: "p", Engine: "comfyui", ModelPath: "/w/sf3d/", ServedModelName: "sf3d",
+			Env: map[string]string{comfyNodesEnv: `[{"repo":"x"}]`, comfyHFRepoEnv: "stabilityai/stable-fast-3d"}},
+	})
+	if err != nil || len(cmds) != 1 {
+		t.Fatalf("%v %v", cmds, err)
+	}
+	for _, want := range []string{comfyNodesEnv + `=[{"repo":"x"}]`, comfyHFRepoEnv + "=stabilityai/stable-fast-3d"} {
+		if !slices.Contains(cmds[0].Env, want) {
+			t.Errorf("%q not in the gate's environment", want)
+		}
+	}
+}
+
+func TestComfyUIRunsOnOneCard(t *testing.T) {
+	c := &ComfyUI{}
+	if err := c.Validate(Profile{Name: "p", ModelPath: "/w", TP: 2}, h100(2)); err == nil {
+		t.Error("a two-card ComfyUI profile was accepted")
+	}
+	if err := c.Validate(Profile{Name: "p", ModelPath: "/w", TP: 1}, h100(1)); err != nil {
+		t.Error(err)
+	}
+	if _, err := c.Commands(ShardSpec{Profile: Profile{ModelPath: "/w"}}); err == nil {
+		t.Error("commands without a ComfyUI directory")
+	}
+}
+
+func TestComfyUIIsOfferedByTheVersionItsBuildWrote(t *testing.T) {
+	dir := t.TempDir()
+	c := &ComfyUI{cfg: ComfyUIConfig{Dir: dir}}
+	if _, err := c.Probe(t.Context()); err == nil {
+		t.Error("a directory without main.py passed for ComfyUI")
+	}
+	_ = os.WriteFile(filepath.Join(dir, "main.py"), nil, 0o644)
+	_ = os.WriteFile(filepath.Join(dir, "comfyui_version.py"), []byte("__version__ = \"0.39.2\"\n"), 0o644)
+	if v, err := c.Probe(t.Context()); err != nil || v != "0.39.2" {
+		t.Errorf("%q %v", v, err)
+	}
+	if got := NewRegistry(Config{ComfyUI: ComfyUIConfig{Dir: dir}}).ProbeConfigured(t.Context()); got["comfyui"] != "0.39.2" {
+		t.Errorf("a configured ComfyUI is reported as %v", got)
+	}
+	if err := UnsafeArgs("comfyui", []string{"--enable-manager"}); err == nil {
+		t.Error("a profile may install ComfyUI nodes")
+	}
+}
+
+func TestAnInstalledComfyUIIsFoundBesideItsInterpreter(t *testing.T) {
+	c := &ComfyUI{cfg: ComfyUIConfig{Dir: "/opt/by-hand"}}
+	c.UseInstalled("/opt/llmgw/engines/comfyui/0.39.2-cu13/bin/python")
+	cmds, err := c.Commands(ShardSpec{ReplicaID: "r", HTTPPort: 1, Profile: Profile{ModelPath: "/w", ServedModelName: "m"}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	args := strings.Join(cmds[0].Args, " ")
+	if !strings.Contains(args, "--python /opt/llmgw/engines/comfyui/0.39.2-cu13/bin/python") ||
+		!strings.Contains(args, "--comfyui /opt/llmgw/engines/comfyui/0.39.2-cu13/comfyui") {
+		t.Errorf("the installed ComfyUI is not what runs: %s", args)
+	}
+}

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

@@ -114,6 +114,10 @@ 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.
@@ -210,6 +214,7 @@ func NewRegistry(cfg Config) *Registry {
 	r.Add(&LlamaCpp{cfg: cfg.LlamaCpp})
 	r.Add(&TRTLLM{cfg: cfg.TRTLLM})
 	r.Add(&Sim{cfg: cfg.Sim})
+	r.Add(&ComfyUI{cfg: cfg.ComfyUI})
 	return r
 }
 
@@ -258,6 +263,8 @@ type Config struct {
 	// offers it only when its interpreter is named here.
 	TRTLLM TRTLLMConfig `koanf:"trtllm"`
 	Sim    SimConfig    `koanf:"sim"`
+	// ComfyUI makes pictures; offered by a node whose ComfyUI is named here.
+	ComfyUI ComfyUIConfig `koanf:"comfyui"`
 }
 
 // --- shared helpers ---

internal/agent/engines/engines_test.go

@@ -477,7 +477,7 @@ func TestValidateRequiresModelPath(t *testing.T) {
 
 func TestRegistry(t *testing.T) {
 	r := NewRegistry(Config{})
-	if got := r.Names(); !slices.Equal(got, []string{"llamacpp", "sglang", "sim", "trtllm", "vllm"}) {
+	if got := r.Names(); !slices.Equal(got, []string{"comfyui", "llamacpp", "sglang", "sim", "trtllm", "vllm"}) {
 		t.Errorf("registry contents: %v", got)
 	}
 	if _, err := r.Get("vllm"); err != nil {

internal/agent/engines/llamacpp.go

@@ -277,6 +277,9 @@ 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

internal/agent/engines/unsafeenv.go

@@ -119,6 +119,19 @@ var flagsNever = map[string]map[string]string{
 		"--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",
 	},
+	// ComfyUI's main.py, behind the gate that sets where it listens and
+	// where its files are.
+	"comfyui": {
+		"--listen": "is set by the agent", "--base-directory": "is set by the agent",
+		"--extra-model-paths-config": "is set by the agent",
+		"--output-directory":         "writes files", "--temp-directory": "writes files",
+		"--input-directory": "reads files", "--user-directory": "writes files",
+		"--database-url": "writes a database elsewhere", "--front-end-root": "serves a directory",
+		"--enable-cors-header": "lets other sites' pages call it",
+		"--enable-manager":     "installs nodes, which run Python",
+		"--tls-keyfile":        "reads a file", "--tls-certfile": "reads a file",
+		"--comfy-api-base": "sends work to another service",
+	},
 	// trtllm-serve spells its flags with underscores, so the shared list's
 	// hyphenated names do not reach them.
 	"trtllm": {

internal/agent/gpucheck.go

@@ -4,10 +4,12 @@ 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"
 )
@@ -153,3 +155,70 @@ func joinIndices(is []int) string {
 	}
 	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

@@ -122,3 +122,55 @@ func TestForeignGPUMemoryLeavesOutTheAgentsOwnShards(t *testing.T) {
 		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/provision/comfyui_test.go

@@ -0,0 +1,177 @@
+package provision
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/discovery"
+)
+
+// comfyuiSource is a ComfyUI release archive as GitHub makes one, and the
+// recipe pointed at it.
+func comfyuiSource(t *testing.T, in *Installer, rel *release, digest string) {
+	t.Helper()
+	archive := tarGz(t, map[string]string{
+		"ComfyUI-0.39.2/main.py":            "print('comfy')\n",
+		"ComfyUI-0.39.2/comfyui_version.py": "__version__ = \"0.39.2\"\n",
+		"ComfyUI-0.39.2/requirements.txt": "comfyui-frontend-package==1.53.10\ntorch\ntorchvision\n" +
+			"numpy>=1.25.0\n\n#non essential dependencies:\nkornia>=0.7.1\n",
+	}, nil)
+	rel.assets["v0.39.2.tar.gz"] = archive
+	sum := sha256.Sum256(archive)
+	if digest == "" {
+		digest = hex.EncodeToString(sum[:])
+	}
+	old := comfyuiReleases
+	comfyuiReleases = map[string]struct {
+		sha256    string
+		published string
+	}{"0.39.2": {digest, "2026-10-07T21:58:07Z"}}
+	t.Cleanup(func() { comfyuiReleases = old })
+}
+
+var turingNode = discovery.Host{OSID: "ubuntu", OSVersion: "24.04", Arch: "amd64",
+	NVIDIADriver: "580.82.07", MinComputeCapability: 7.5}
+
+func TestComfyUIIsInstalledFromItsSourceCheckedAgainstTheRecipe(t *testing.T) {
+	sys := &fakePython{fakeSystem: fakeSystem{installed: map[string]bool{}}}
+	in, rel := pythonInstaller(t, turingNode, sys)
+	comfyuiSource(t, in, rel, "")
+
+	got := in.Converge(t.Context(), []Want{{Engine: "comfyui", Version: "0.39.2"}})
+	if got[0].State != Ready {
+		t.Fatalf("not ready: %+v", got[0])
+	}
+	dir := filepath.Join(in.Root, "comfyui", "0.39.2-cu13")
+	if got[0].Binary != filepath.Join(dir, "bin", "python") {
+		t.Errorf("binary %s, want the environment's interpreter", got[0].Binary)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "comfyui", "main.py")); err != nil {
+		t.Errorf("ComfyUI's code is not beside the interpreter: %v", err)
+	}
+	all := strings.Join(sys.commands, "\n")
+	for _, want := range []string{
+		// Not PyPI's date, which ComfyUI has none of: the recipe's, a day on.
+		"--exclude-newer 2026-10-08T21:58:07Z",
+		"comfyui-frontend-package==1.53.10", "numpy>=1.25.0", "kornia>=0.7.1", "torch",
+		"--require-hashes",
+	} {
+		if !strings.Contains(all, want) {
+			t.Errorf("no %q in:\n%s", want, all)
+		}
+	}
+	if strings.Contains(all, "/pypi/") {
+		t.Error("PyPI was asked when ComfyUI was published")
+	}
+}
+
+func TestComfyUIOnAnOlderDriverTakesPyTorchsCUDA12Torch(t *testing.T) {
+	sys := &fakePython{fakeSystem: fakeSystem{installed: map[string]bool{}}}
+	host := turingNode
+	host.NVIDIADriver = "550.163.01"
+	in, rel := pythonInstaller(t, host, sys)
+	comfyuiSource(t, in, rel, "")
+	got := in.Converge(t.Context(), []Want{{Engine: "comfyui", Version: "0.39.2"}})
+	if got[0].State != Ready || got[0].Variant != "cu129" {
+		t.Fatalf("got %+v", got[0])
+	}
+	var project string
+	for _, c := range sys.commands {
+		if strings.HasPrefix(c, "pyproject: ") {
+			project = c
+		}
+	}
+	// torch from PyTorch's index alone, named once, as the build names it.
+	if !strings.Contains(project, `torch = { index = "extra" }`) || strings.Count(project, `"torch"`) != 1 {
+		t.Errorf("torch is not from PyTorch's index alone:\n%s", project)
+	}
+}
+
+// A V100 on driver 580: CUDA 13 runs on the driver, but neither its torch
+// nor CUDA 12.9's has kernels for Volta. Tried in turn, each was installed,
+// 10 GB at a time, and failed on the card.
+func TestComfyUIOnAVoltaTakesPyTorchsCUDA126Torch(t *testing.T) {
+	sys := &fakePython{fakeSystem: fakeSystem{installed: map[string]bool{}}}
+	host := turingNode
+	host.MinComputeCapability = 7.0
+	in, rel := pythonInstaller(t, host, sys)
+	comfyuiSource(t, in, rel, "")
+	got := in.Converge(t.Context(), []Want{{Engine: "comfyui", Version: "0.39.2"}})
+	if got[0].State != Ready || got[0].Variant != "cu126" {
+		t.Fatalf("got %+v", got[0])
+	}
+	all := strings.Join(sys.commands, "\n")
+	if !strings.Contains(all, pytorchCU126) || strings.Contains(all, pytorchCU129) {
+		t.Errorf("torch is not CUDA 12.6's:\n%s", all)
+	}
+}
+
+func TestComfyUIWhoseSourceIsNotTheOneTheRecipeNamesIsNotInstalled(t *testing.T) {
+	sys := &fakePython{fakeSystem: fakeSystem{installed: map[string]bool{}}}
+	in, rel := pythonInstaller(t, turingNode, sys)
+	comfyuiSource(t, in, rel, strings.Repeat("ab", 32))
+	got := in.Converge(t.Context(), []Want{{Engine: "comfyui", Version: "0.39.2"}})
+	if got[0].State != Failed || !strings.Contains(got[0].Detail, "does not match") {
+		t.Fatalf("got %s %q", got[0].State, got[0].Detail)
+	}
+	for _, c := range sys.commands {
+		if strings.Contains(c, "pip install") {
+			t.Errorf("installed from a source that did not match: %s", c)
+		}
+	}
+}
+
+func TestComfyUIIsInstalledOnlyWhereItCanRun(t *testing.T) {
+	sys := &fakePython{fakeSystem: fakeSystem{installed: map[string]bool{}}}
+	in, _ := pythonInstaller(t, ubuntu, sys)
+	if got := in.Converge(t.Context(), []Want{{Engine: "comfyui", Version: "0.39.2"}}); got[0].State != Skipped {
+		t.Errorf("a node with no GPU: %+v", got[0])
+	}
+	in, _ = pythonInstaller(t, turingNode, sys)
+	got := in.Converge(t.Context(), []Want{{Engine: "comfyui", Version: "0.1.0"}})
+	if got[0].State != Unsupported || !strings.Contains(got[0].Detail, "knows the source digest of ComfyUI 0.39.2") {
+		t.Errorf("a version without a digest: %s %q", got[0].State, got[0].Detail)
+	}
+}
+
+func TestARequirementsFileIsReadForPackagesAndNothingElse(t *testing.T) {
+	got, err := requirementsIn("torch\ntorchvision>=0.20\nPillow\n# a comment\naiohttp>=3.11 # inline\n", pytorchPackages)
+	if err != nil || strings.Join(got, ",") != "Pillow,aiohttp>=3.11" {
+		t.Errorf("%v %v", got, err)
+	}
+	for _, bad := range []string{"-r other.txt", "--index-url https://evil", "x @ https://evil/x.whl", "-e ."} {
+		if _, err := requirementsIn(bad+"\n", nil); err == nil {
+			t.Errorf("%q was accepted", bad)
+		}
+	}
+}
+
+// A card every build runs on keeps the order it had: a Turing node's
+// installed cu13 is still the first found, and is not installed again
+// because a build for older cards was added after it.
+func TestComfyUIBuildsAreTriedBestFirst(t *testing.T) {
+	variants := func(h discovery.Host) string {
+		builds, err := comfyuiCandidates("0.39.2", "", h)
+		if err != nil {
+			return err.Error()
+		}
+		var v []string
+		for _, b := range builds {
+			v = append(v, b.Variant)
+		}
+		return strings.Join(v, ",")
+	}
+	volta := turingNode
+	volta.MinComputeCapability = 7.0
+	older := turingNode
+	older.NVIDIADriver = "550.163.01"
+	for h, want := range map[*discovery.Host]string{&turingNode: "cu13,cu129,cu126", &volta: "cu126", &older: "cu129,cu126"} {
+		if got := variants(*h); got != want {
+			t.Errorf("cc %.1f driver %s: %s, want %s", h.MinComputeCapability, h.NVIDIADriver, got, want)
+		}
+	}
+}

internal/agent/provision/python.go

@@ -66,12 +66,17 @@ func (in *Installer) installPython(ctx context.Context, r Recipe, w Want, b Buil
 		return fmt.Errorf("installing uv, which installs %s: %s", w.Engine, uv.Detail)
 	}
 
-	in.progress(st, "asking PyPI when %s %s was published", r.PyPI, w.Version)
-	published, err := in.published(ctx, r.PyPI, w.Version)
-	if err != nil {
-		return err
+	var asOf string
+	if !b.AsOf.IsZero() {
+		asOf = b.AsOf.UTC().Format(time.RFC3339)
+	} else {
+		in.progress(st, "asking PyPI when %s %s was published", r.PyPI, w.Version)
+		published, err := in.published(ctx, r.PyPI, w.Version)
+		if err != nil {
+			return err
+		}
+		asOf = published.Add(24 * time.Hour).UTC().Format(time.RFC3339)
 	}
-	asOf := published.Add(24 * time.Hour).UTC().Format(time.RFC3339)
 
 	cache := filepath.Join(in.root(), ".uv-cache")
 	env := []string{
@@ -96,7 +101,14 @@ func (in *Installer) installPython(ctx context.Context, r Recipe, w Want, b Buil
 	}
 	python := filepath.Join(tmp, "bin", "python")
 
-	reqs := b.Requirements
+	reqs := slices.Clone(b.Requirements)
+	if b.Source != nil {
+		more, err := in.unpackSource(ctx, w, b, tmp, st)
+		if err != nil {
+			return err
+		}
+		reqs = append(reqs, more...)
+	}
 	if b.Wheel != nil {
 		// The engine from its GitHub release, pinned to the digest GitHub
 		// publishes for the file: the same trust as an archive, and uv
@@ -320,3 +332,68 @@ func (in *Installer) gpuCheck(ctx context.Context, python string, w Want, b Buil
 	}
 	return nil
 }
+
+// unpackSource fetches an engine's source archive, checks it against the
+// digest the recipe holds, puts its code in the environment, and returns the
+// requirements its requirements file names — less the packages a second
+// index gives, which the build names itself.
+func (in *Installer) unpackSource(ctx context.Context, w Want, b Build, env string, st *Status) ([]string, error) {
+	src := b.Source
+	url := src.URL
+	if strings.HasPrefix(url, "/") {
+		url = strings.TrimSuffix(in.downloadBase(), "/") + url
+	}
+	scratch := env + ".source"
+	_ = os.RemoveAll(scratch)
+	if err := os.MkdirAll(scratch, 0o755); err != nil {
+		return nil, err
+	}
+	defer os.RemoveAll(scratch) //nolint:errcheck // scratch
+	archive := filepath.Join(scratch, "source.tar.gz")
+	name := w.Engine + " " + w.Version + "'s source"
+	if err := in.download(ctx, url, name, archive, src.SHA256, st); err != nil {
+		return nil, err
+	}
+	in.progress(st, "unpacking %s", name)
+	if err := untarGz(archive, scratch); err != nil {
+		return nil, fmt.Errorf("unpacking %s: %w", name, err)
+	}
+	dst := filepath.Join(env, src.Dir)
+	if err := os.Rename(filepath.Join(scratch, src.Top), dst); err != nil {
+		return nil, fmt.Errorf("%s has no %s at its top: %w", name, src.Top, err)
+	}
+	if src.Requirements == "" {
+		return nil, nil
+	}
+	f, err := os.ReadFile(filepath.Join(dst, src.Requirements))
+	if err != nil {
+		return nil, fmt.Errorf("%s: %w", name, err)
+	}
+	return requirementsIn(string(f), b.IndexPackages)
+}
+
+// requirementsIn reads a requirements file's lines. Options (-r, -e, --index-url
+// and the like) are refused: they would fetch from somewhere other than PyPI,
+// or install what the lock never saw.
+func requirementsIn(text string, skip []string) ([]string, error) {
+	var out []string
+	for _, line := range strings.Split(text, "\n") {
+		line, _, _ = strings.Cut(line, "#")
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+		if strings.HasPrefix(line, "-") || strings.Contains(line, "://") || strings.Contains(line, " @ ") {
+			return nil, fmt.Errorf("the requirements name %q, which is not a package from PyPI", line)
+		}
+		name := strings.ToLower(line)
+		if i := strings.IndexAny(name, "<>=!~;[ "); i >= 0 {
+			name = name[:i]
+		}
+		if slices.Contains(skip, name) {
+			continue
+		}
+		out = append(out, line)
+	}
+	return out, nil
+}

internal/agent/provision/python_test.go

@@ -53,6 +53,7 @@ func (f *fakePython) run(ctx context.Context, env []string, name string, args ..
 			return []byte("error: Hash mismatch for torch\n"), errExit
 		}
 		venv := filepath.Dir(filepath.Dir(args[slices.Index(args, "--python")+1]))
+		_ = os.WriteFile(filepath.Join(venv, "bin", "python"), []byte("#!/bin/sh\n"), 0o755)
 		return nil, os.WriteFile(filepath.Join(venv, "bin", "vllm"), []byte("#!/bin/sh\n"), 0o755)
 	case strings.HasSuffix(name, "/bin/vllm") && args[0] == "--version":
 		return []byte("0.30.0\n"), nil

internal/agent/provision/recipe.go

@@ -13,6 +13,7 @@ import (
 	"fmt"
 	"slices"
 	"strings"
+	"time"
 
 	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/discovery"
 )
@@ -68,12 +69,31 @@ type Build struct {
 	// Note says why this build, when it is not the plain one: shown beside
 	// it wherever the installation is.
 	Note string
+	// Source, for a Python engine that is not on PyPI, is its own code: an
+	// archive pinned by its digest, unpacked into the environment, whose
+	// requirements file is installed with Requirements. AsOf is then the
+	// date its dependencies are resolved as of — the day after its version
+	// was published, which PyPI cannot be asked for.
+	Source *Source
+	AsOf   time.Time
 	// FreeGB is the disk space the installation needs before it starts: a
 	// Python engine is several gigabytes, and one that fills the disk halfway
 	// leaves the node worse off than one that never began.
 	FreeGB int
 }
 
+// Source is an engine's code as an archive.
+type Source struct {
+	// URL is fetched as is; SHA256 is what it must hash to, written into
+	// the recipe because a project's source archives come with no published
+	// digest of their own.
+	URL, SHA256 string
+	// Top is the archive's one top directory, put in the environment as Dir.
+	Top, Dir string
+	// Requirements is the requirements file, in Dir.
+	Requirements string
+}
+
 // Wheel is a package published as a GitHub release asset: the asset whose
 // name starts with Prefix and ends with Suffix.
 type Wheel struct {
@@ -104,6 +124,7 @@ var Recipes = map[string]Recipe{
 	"llamacpp": {Repo: "ggml-org/llama.cpp", Candidates: llamaCppCandidates},
 	"vllm":     {PyPI: "vllm", Candidates: vllmCandidates},
 	"sglang":   {PyPI: "sglang", Candidates: sglangCandidates},
+	"comfyui":  {Candidates: comfyuiCandidates},
 	"uv":       {Repo: "astral-sh/uv", Candidates: uvCandidates},
 }
 
@@ -556,3 +577,98 @@ func orUnknown(s string) string {
 	}
 	return s
 }
+
+// --- ComfyUI ---
+
+// comfyuiReleases are the ComfyUI versions this agent installs: each source
+// archive's digest, taken when it was added here and confirmed from a second
+// machine, and when the version was published. GitHub publishes no digest
+// for a tag's archive, so a version not listed is refused rather than
+// installed unchecked.
+var comfyuiReleases = map[string]struct {
+	sha256    string
+	published string
+}{
+	"0.39.2": {"1d655e22cf546700fc1d6d2536e27701695c5832a51f63bb16c41866ac09be0b", "2026-10-07T21:58:07Z"},
+}
+
+// ComfyUIVersion is the newest ComfyUI this agent installs: what a cluster
+// is set to when a model first needs it.
+func ComfyUIVersion() string {
+	newest := ""
+	for v := range comfyuiReleases {
+		if newest == "" || versionBefore(newest, v) {
+			newest = v
+		}
+	}
+	return newest
+}
+
+// ComfyUIRepo is where ComfyUI's source is published.
+const ComfyUIRepo = "Comfy-Org/ComfyUI"
+
+// comfyuiDir is where ComfyUI's code is put in its environment: main.py is
+// <environment>/comfyui/main.py, beside bin/python.
+const comfyuiDir = "comfyui"
+
+// pytorchCU126 is PyTorch's CUDA 12.6 build: the last that carries kernels
+// for Volta and Pascal. From torch 2.8 its CUDA 12.8 and 12.9 builds start
+// at Turing (7.5), as CUDA 13 does, so a V100 has no torch but this one.
+const pytorchCU126 = "https://download.pytorch.org/whl/cu126"
+
+// comfyuiCandidates are the ComfyUI builds for a machine: its source, in a
+// Python environment with the torch for the node's driver and cards —
+// PyPI's, built for CUDA 13; PyTorch's CUDA 12.9 build for a driver CUDA 13
+// does not run on; and its CUDA 12.6 build for cards older than Turing.
+func comfyuiCandidates(version, variant string, h discovery.Host) ([]Build, error) {
+	if _, err := gpuArch("ComfyUI", h); err != nil {
+		return nil, err
+	}
+	rel, ok := comfyuiReleases[version]
+	if !ok {
+		known := make([]string, 0, len(comfyuiReleases))
+		for v := range comfyuiReleases {
+			known = append(known, v)
+		}
+		slices.Sort(known)
+		return nil, fmt.Errorf("this agent knows the source digest of ComfyUI %s, not of %s; "+
+			"install that one by hand and name it in agent.yaml (engines.comfyui.dir)",
+			strings.Join(known, ", "), version)
+	}
+	published, err := time.Parse(time.RFC3339, rel.published)
+	if err != nil {
+		return nil, err
+	}
+	build := func(variant string) Build {
+		return Build{
+			Variant: variant,
+			Python:  pythonForEngines,
+			Source: &Source{
+				URL:    "/" + ComfyUIRepo + "/archive/refs/tags/v" + version + ".tar.gz",
+				SHA256: rel.sha256, Top: "ComfyUI-" + version, Dir: comfyuiDir,
+				Requirements: "requirements.txt",
+			},
+			AsOf: published.Add(24 * time.Hour),
+			// ComfyUI is started as a script, so what the agent is given is
+			// the environment's interpreter; the proof is importing what it
+			// imports first, from where its code is.
+			Binary: "python",
+			VersionArgs: []string{"-c", `import os, sys, torch, aiohttp, safetensors
+d = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(sys.executable))), "` + comfyuiDir + `")
+assert os.path.isfile(os.path.join(d, "main.py")), d + " has no main.py"
+print("comfyui version", "` + version + `", "on torch", torch.__version__)`},
+			Packages: compilerPackages,
+			FreeGB:   15,
+			GPUCheck: true,
+		}
+	}
+	cu129 := build("cu129")
+	cu129.ExtraIndex, cu129.IndexPackages = pytorchCU129, pytorchPackages
+	cu126 := build("cu126")
+	cu126.ExtraIndex, cu126.IndexPackages = pytorchCU126, pytorchPackages
+	return pick("ComfyUI "+version, variant, []candidate{
+		{build("cu13"), gpuNeeds{minDriverForCUDA13, 7.5}, "ComfyUI " + version + " on CUDA 13's torch"},
+		{cu129, gpuNeeds{minDriverForCUDA12, 7.5}, "ComfyUI " + version + " on CUDA 12.9's torch"},
+		{cu126, gpuNeeds{minDriverForCUDA12, 5.0}, "ComfyUI " + version + " on CUDA 12.6's torch"},
+	}, h)
+}

internal/agent/settings.go

@@ -0,0 +1,109 @@
+package agent
+
+import (
+	"context"
+	"crypto/sha256"
+	"os"
+	"path/filepath"
+	"time"
+
+	llmgwv1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1"
+)
+
+// The cluster's settings for this agent (BACKLOG E3): what agent.yaml can
+// say but the agent's id, control planes, address and certificate, kept by
+// the control planes and sent over the stream. Kept here beside agent.yaml,
+// which then holds only what the agent needs to start; at start the two are
+// read together, these over the file.
+
+// SettingsFile keeps the settings the control plane last sent.
+var SettingsFile = "/var/lib/llmgw-agent/agent-settings.yaml"
+
+// ReadSettings is what SettingsFile holds, nil when nothing.
+func ReadSettings() []byte {
+	b, err := os.ReadFile(SettingsFile)
+	if err != nil {
+		return nil
+	}
+	return b
+}
+
+// SetSettingsCheck says how to tell whether settings would load beside this
+// agent's own file; settings that would not are not taken.
+func (a *Agent) SetSettingsCheck(f func([]byte) error) { a.settingsCheck = f }
+
+// applySettings takes the settings the control plane sent: nothing when they
+// are what this agent runs on, and otherwise kept and started again on.
+func (a *Agent) applySettings(m *llmgwv1.AgentSettings) {
+	next := m.GetYaml()
+	if next == a.cfg.Settings {
+		return
+	}
+	if a.settingsCheck != nil {
+		if err := a.settingsCheck([]byte(next)); err != nil {
+			// Kept running on what it has: settings that will not load
+			// here must not take the node out of service.
+			a.log.Error("the cluster's settings for this agent do not load beside its agent.yaml; running on what it has",
+				"err", err)
+			return
+		}
+	}
+	if err := os.MkdirAll(filepath.Dir(SettingsFile), 0o755); err != nil {
+		a.log.Error("could not keep the cluster's settings for this agent", "err", err)
+		return
+	}
+	tmp := SettingsFile + ".new"
+	if err := os.WriteFile(tmp, []byte(next), 0o600); err != nil {
+		a.log.Error("could not keep the cluster's settings for this agent", "err", err)
+		return
+	}
+	if err := os.Rename(tmp, SettingsFile); err != nil {
+		a.log.Error("could not keep the cluster's settings for this agent", "err", err)
+		return
+	}
+	a.log.Info("the cluster's settings for this agent changed; starting again on them, the engines keep serving")
+	time.Sleep(300 * time.Millisecond)
+	exitForUpgrade()
+}
+
+// WatchFile starts the agent again when its configuration file changes and
+// still loads: agent.yaml is read only at start, and a change to it that
+// waited for somebody to restart the agent was a change nobody saw take
+// effect.
+func (a *Agent) WatchFile(ctx context.Context, path string, loads func() error) {
+	if path == "" {
+		return
+	}
+	sum := func() [32]byte {
+		b, _ := os.ReadFile(path) //nolint:gosec // the agent's own configuration
+		return sha256.Sum256(b)
+	}
+	was := sum()
+	t := time.NewTicker(watchEvery)
+	defer t.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+		}
+		now := sum()
+		if now == was {
+			continue
+		}
+		if err := loads(); err != nil {
+			// Once per change: an editor saving halfway must not stop the
+			// agent, and a broken file is reported, not restarted into.
+			a.log.Error("agent.yaml changed and does not load; running on what it had", "path", path, "err", err)
+			was = now
+			continue
+		}
+		a.log.Info("agent.yaml changed; starting again on it, the engines keep serving", "path", path)
+		time.Sleep(300 * time.Millisecond)
+		exitForUpgrade()
+		return
+	}
+}
+
+// watchEvery is how often agent.yaml is looked at.
+var watchEvery = 10 * time.Second

internal/agent/settings_test.go

@@ -0,0 +1,88 @@
+package agent
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	llmgwv1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1"
+)
+
+func settingsAgent(t *testing.T, running string) (*Agent, chan struct{}) {
+	t.Helper()
+	oldFile, oldExit := SettingsFile, exitForUpgrade
+	SettingsFile = filepath.Join(t.TempDir(), "agent-settings.yaml")
+	exited := make(chan struct{}, 1)
+	exitForUpgrade = func() { exited <- struct{}{} }
+	t.Cleanup(func() { SettingsFile, exitForUpgrade = oldFile, oldExit })
+	cfg := Config{Server: "127.0.0.1:7443", NodeID: "n1", WeightsCache: t.TempDir(), EnginesDir: t.TempDir(), Settings: running}
+	cfg.Superv.WorkDir = t.TempDir()
+	a, err := New(cfg, nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return a, exited
+}
+
+// exitedSoon is whether the agent exited within a second: it waits a
+// moment for its log line to leave first.
+func exitedSoon(ch chan struct{}) bool {
+	select {
+	case <-ch:
+		return true
+	case <-time.After(time.Second):
+		return false
+	}
+}
+
+func TestAnAgentOnItsSettingsStaysAndOneOffThemStartsAgain(t *testing.T) {
+	a, exited := settingsAgent(t, "heartbeat_interval: 5s\n")
+	a.applySettings(&llmgwv1.AgentSettings{Yaml: "heartbeat_interval: 5s\n"})
+	if exitedSoon(exited) || ReadSettings() != nil {
+		t.Error("settings it already runs on restarted it")
+	}
+	a.applySettings(&llmgwv1.AgentSettings{Yaml: "heartbeat_interval: 2s\n"})
+	if !exitedSoon(exited) || string(ReadSettings()) != "heartbeat_interval: 2s\n" {
+		t.Errorf("new settings: kept %q", ReadSettings())
+	}
+}
+
+func TestSettingsThatWouldNotLoadAreNotTaken(t *testing.T) {
+	a, exited := settingsAgent(t, "")
+	a.SetSettingsCheck(func([]byte) error { return errors.New("fabric ib-a lists no HCAs") })
+	a.applySettings(&llmgwv1.AgentSettings{Yaml: "fabrics: [{name: ib-a}]\n"})
+	if exitedSoon(exited) || ReadSettings() != nil {
+		t.Error("settings that do not load were taken")
+	}
+}
+
+func TestAChangedAgentYamlThatLoadsStartsTheAgentAgain(t *testing.T) {
+	a, exited := settingsAgent(t, "")
+	old := watchEvery
+	watchEvery = 10 * time.Millisecond
+	t.Cleanup(func() { watchEvery = old })
+	p := filepath.Join(t.TempDir(), "agent.yaml")
+	_ = os.WriteFile(p, []byte("node_id: n1\n"), 0o600)
+	var loads atomic.Bool
+	check := func() error {
+		if loads.Load() {
+			return nil
+		}
+		return errors.New("broken")
+	}
+	go a.WatchFile(t.Context(), p, check)
+	time.Sleep(30 * time.Millisecond)
+	// Saved broken: reported, not restarted into.
+	_ = os.WriteFile(p, []byte("node_id: [\n"), 0o600)
+	if exitedSoon(exited) {
+		t.Fatal("a broken agent.yaml restarted the agent")
+	}
+	loads.Store(true)
+	_ = os.WriteFile(p, []byte("node_id: n1\nlabels: {a: b}\n"), 0o600)
+	if !exitedSoon(exited) {
+		t.Error("a changed agent.yaml did not restart the agent")
+	}
+}

internal/agent/supervisor/outputfile.go

@@ -0,0 +1,139 @@
+package supervisor
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+// An engine's output goes to a file of its own, not to a pipe of the
+// agent's. A pipe has one reader, and that reader is the agent that
+// started the engine: when that agent restarts, the engine it left running
+// — and adopts a moment later — writes to a pipe nobody reads, and its next
+// write past the pipe's buffer fails with EPIPE. A Python engine's progress
+// bar then raises, and takes the request it was reporting on with it. A
+// file has no reader to lose: the engine appends to it, every agent reads
+// it, and the output from before a restart is there for the one after.
+
+// maxOutputBytes bounds one process's file: past it the file is emptied and
+// the process goes on appending to it. A progress bar rewriting itself for
+// an hour would otherwise fill the disk.
+const maxOutputBytes = 64 << 20
+
+// outputPath is where a shard's process writes.
+func (s *Supervisor) outputPath(shardID, name string) string {
+	if name != "" {
+		return filepath.Join(s.cfg.WorkDir, "shard-"+shardID+"."+name+".log")
+	}
+	return filepath.Join(s.cfg.WorkDir, "shard-"+shardID+".log")
+}
+
+// openOutput is the file a process is started with: new, for a process
+// that is new.
+func (s *Supervisor) openOutput(shardID, name string) (*os.File, error) {
+	return os.OpenFile(s.outputPath(shardID, name), os.O_CREATE|os.O_WRONLY|os.O_APPEND|os.O_TRUNC, 0o600) //nolint:gosec // the agent's own directory
+}
+
+// follow reads a process's file into the shard's log as it is written,
+// until the shard's output is stopped and the file has been read to its
+// end. A file an earlier agent began is read from the start, so the output
+// from before a restart is in the log too.
+func (s *Supervisor) follow(sh *Shard, path, name string) {
+	defer sh.outDone.Done()
+	f, err := os.Open(path) //nolint:gosec // the agent's own directory
+	if err != nil {
+		sh.logs.add("[" + name + "] output unavailable: " + err.Error())
+		return
+	}
+	defer f.Close()
+	var offset int64
+	var rest []byte
+	buf := make([]byte, 64<<10)
+	read := func() {
+		for {
+			st, err := f.Stat()
+			if err != nil {
+				return
+			}
+			if st.Size() < offset {
+				// Emptied, by this agent or another: begin again.
+				offset, rest = 0, nil
+			}
+			if st.Size() > maxOutputBytes {
+				_ = os.Truncate(path, 0)
+				offset, rest = 0, nil
+				continue
+			}
+			n, err := f.ReadAt(buf, offset)
+			if n > 0 {
+				offset += int64(n)
+				rest = append(rest, buf[:n]...)
+				for {
+					i := bytes.IndexByte(rest, '\n')
+					if i < 0 {
+						break
+					}
+					s.addLine(sh, name, rest[:i])
+					rest = rest[i+1:]
+				}
+				// A progress bar is a line rewritten with \r and never ended:
+				// its latest state is what is wanted, not a line a megabyte
+				// long. Kept, as llama.cpp and tqdm write them.
+				if len(rest) > 1<<20 {
+					s.addLine(sh, name, rest)
+					rest = nil
+				}
+			}
+			if err != nil || n == 0 {
+				return
+			}
+		}
+	}
+	t := time.NewTicker(200 * time.Millisecond)
+	defer t.Stop()
+	for {
+		select {
+		case <-sh.outStop:
+			read()
+			if len(rest) > 0 {
+				s.addLine(sh, name, rest)
+			}
+			return
+		case <-t.C:
+			read()
+		}
+	}
+}
+
+func (s *Supervisor) addLine(sh *Shard, name string, b []byte) {
+	// The last state of a line rewritten with \r, as a terminal would show.
+	if i := bytes.LastIndexByte(b, '\r'); i >= 0 {
+		b = b[i+1:]
+	}
+	line := string(b)
+	if name != "" {
+		// Prefixed so the two processes of a Ray shard stay distinguishable
+		// in a single log tail.
+		line = "[" + name + "] " + line
+	}
+	sh.logs.add(line)
+	s.log.Debug("engine", "shard", sh.ID, "line", line)
+}
+
+// removeOutput drops a shard's files once nothing writes to them.
+func (s *Supervisor) removeOutput(shardID string) {
+	matches, _ := filepath.Glob(filepath.Join(s.cfg.WorkDir, "shard-"+shardID+".*log"))
+	for _, m := range matches {
+		_ = os.Remove(m)
+	}
+	_ = os.Remove(s.outputPath(shardID, ""))
+}
+
+// stopOutput has every follower read what is left and stop. Called once
+// the process has ended, before the shard is done, so what it wrote last
+// is in the log by the time anyone reads the log for why it ended.
+func (s *Supervisor) stopOutput(sh *Shard) {
+	sh.outOnce.Do(func() { close(sh.outStop) })
+	sh.outDone.Wait()
+}

internal/agent/supervisor/runas.go

@@ -3,6 +3,7 @@ package supervisor
 import (
 	"fmt"
 	"os"
+	"os/exec"
 	"os/user"
 	"path/filepath"
 	"strconv"
@@ -90,3 +91,25 @@ func credentialFor(u *user.User, workDir string) (*runAs, error) {
 func (r *runAs) env() []string {
 	return []string{"HOME=" + r.home, "XDG_CACHE_HOME=" + filepath.Join(r.home, ".cache"), "USER=" + r.name, "LOGNAME=" + r.name}
 }
+
+// AsEngineUser has cmd run as the engine user, as an engine would, with its
+// home under workDir: for work the agent does that is not an engine but
+// reads what an engine reads — training an adapter. It answers that home
+// and a way to hand a path to the user, or why it runs as this process.
+func AsEngineUser(cmd *exec.Cmd, name, workDir string) (home string, give func(path string) error, why string) {
+	r, why := resolveRunAs(name, workDir)
+	if r == nil {
+		return "", func(string) error { return nil }, why
+	}
+	cmd.SysProcAttr = &syscall.SysProcAttr{Credential: r.cred, Setpgid: true}
+	cmd.Env = append(cmd.Env, r.env()...)
+	uid, gid := int(r.cred.Uid), int(r.cred.Gid)
+	return r.home, func(path string) error {
+		return filepath.WalkDir(path, func(p string, _ os.DirEntry, err error) error {
+			if err != nil {
+				return err
+			}
+			return os.Lchown(p, uid, gid)
+		})
+	}, ""
+}

internal/agent/supervisor/supervisor.go

@@ -1,12 +1,10 @@
 package supervisor
 
 import (
-	"bufio"
 	"context"
 	"encoding/json"
 	"errors"
 	"fmt"
-	"io"
 	"log/slog"
 	"net"
 	"os"
@@ -104,6 +102,12 @@ type Shard struct {
 	ID   string
 	Spec engines.ShardSpec
 
+	// outStop ends the followers of the processes' output files, and
+	// outDone is their having read to the end.
+	outStop chan struct{}
+	outOnce sync.Once
+	outDone sync.WaitGroup
+
 	mu       sync.Mutex
 	state    State
 	pid      int
@@ -113,7 +117,10 @@ type Shard struct {
 	exitCode int
 
 	logs *ringBuffer
-	cmd  *exec.Cmd
+	// cmdline is an adopted engine's command line, from its state file: it
+	// has no cmd of this agent's to read it from.
+	cmdline []string
+	cmd     *exec.Cmd
 	// sidecars are the shard's supporting processes, torn down with it.
 	sidecars []*exec.Cmd
 	cancel   context.CancelFunc
@@ -245,6 +252,7 @@ func (s *Supervisor) Start(ctx context.Context, id string, spec engines.ShardSpe
 		logs:    newRingBuffer(s.cfg.LogLines),
 		started: time.Now(),
 		done:    make(chan struct{}),
+		outStop: make(chan struct{}),
 	}
 	s.shards[id] = sh
 	s.mu.Unlock()
@@ -312,14 +320,15 @@ func (s *Supervisor) launch(ctx context.Context, sh *Shard, cmds []engines.Comma
 	// CommandContext kills only the leader, so replace that with a group kill.
 	c.Cancel = func() error { return killGroup(c.Process.Pid, syscall.SIGKILL) }
 
-	stdout, err := c.StdoutPipe()
+	out, err := s.openOutput(sh.ID, "")
 	if err != nil {
 		cancel()
 		return err
 	}
-	c.Stderr = c.Stdout.(io.Writer) // interleave, as the engine writes them
-
-	if err := c.Start(); err != nil {
+	c.Stdout, c.Stderr = out, out // interleaved, as the engine writes them
+	err = c.Start()
+	out.Close() // the process holds its own
+	if err != nil {
 		cancel()
 		return fmt.Errorf("starting %s: %w", cmd.Path, err)
 	}
@@ -336,7 +345,8 @@ func (s *Supervisor) launch(ctx context.Context, sh *Shard, cmds []engines.Comma
 			"shard", sh.ID, "err", err)
 	}
 
-	go s.pump(sh, stdout, cmd.Name)
+	sh.outDone.Add(1)
+	go s.follow(sh, s.outputPath(sh.ID, ""), cmd.Name)
 	go s.wait(sh)
 	return nil
 }
@@ -350,16 +360,18 @@ func (s *Supervisor) spawn(ctx context.Context, sh *Shard, c engines.Command) (*
 	s.dropTo(proc)
 	proc.Cancel = func() error { return killGroup(proc.Process.Pid, syscall.SIGKILL) }
 
-	stdout, err := proc.StdoutPipe()
+	out, err := s.openOutput(sh.ID, c.Name)
 	if err != nil {
 		return nil, err
 	}
-	proc.Stderr = proc.Stdout.(io.Writer)
-
-	if err := proc.Start(); err != nil {
+	proc.Stdout, proc.Stderr = out, out
+	err = proc.Start()
+	out.Close()
+	if err != nil {
 		return nil, fmt.Errorf("starting %s: %w", c.Path, err)
 	}
-	go s.pump(sh, stdout, c.Name)
+	sh.outDone.Add(1)
+	go s.follow(sh, s.outputPath(sh.ID, c.Name), c.Name)
 	// Reaped so it does not become a zombie; its exit does not end the shard.
 	go func() { _ = proc.Wait() }()
 	return proc, nil
@@ -392,24 +404,6 @@ func waitForPort(ctx context.Context, addr string, timeout time.Duration) (err e
 }
 
 // pump copies a process's output into the ring buffer and the log.
-func (s *Supervisor) pump(sh *Shard, r io.Reader, name string) {
-	sc := bufio.NewScanner(r)
-	// Engine tracebacks and progress bars produce long lines; the default
-	// 64 KiB limit truncates them exactly when they matter.
-	sc.Buffer(make([]byte, 0, 64<<10), 1<<20)
-
-	for sc.Scan() {
-		line := sc.Text()
-		if name != "" {
-			// Prefixed so the two processes of a Ray shard stay distinguishable
-			// in a single log tail.
-			line = "[" + name + "] " + line
-		}
-		sh.logs.add(line)
-		s.log.Debug("engine", "shard", sh.ID, "line", line)
-	}
-}
-
 // wait reaps the process and records why it ended.
 func (s *Supervisor) wait(sh *Shard) {
 	defer close(sh.done)
@@ -437,6 +431,7 @@ func (s *Supervisor) wait(sh *Shard) {
 	final, code := sh.state, sh.exitCode
 	sh.mu.Unlock()
 
+	s.stopOutput(sh)
 	s.removeState(sh)
 	if final == Failed {
 		s.log.Error("shard failed", "shard", sh.ID, "exit_code", code, "err", err,
@@ -644,6 +639,32 @@ func (s *Supervisor) Get(id string) (*Shard, error) {
 	return sh, nil
 }
 
+// SetCompute records where a shard's engine said it put the model, with the
+// shard's state on disk.
+func (s *Supervisor) SetCompute(id string, c engines.Compute) {
+	s.mu.Lock()
+	sh, ok := s.shards[id]
+	if ok {
+		sh.Spec.Compute = &c
+	}
+	s.mu.Unlock()
+	if ok && sh.pid > 0 {
+		_ = s.writeState(sh)
+	}
+}
+
+// ComputeOf is where a shard's engine was found to compute, nil when not
+// yet known.
+func (s *Supervisor) ComputeOf(id string) *engines.Compute {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if sh, ok := s.shards[id]; ok && sh.Spec.Compute != nil {
+		c := *sh.Spec.Compute
+		return &c
+	}
+	return nil
+}
+
 // Remove forgets a terminated shard.
 func (s *Supervisor) Remove(id string) {
 	s.mu.Lock()
@@ -703,11 +724,17 @@ type shardState struct {
 
 // writeState records everything needed to recognise and describe the process later.
 func (s *Supervisor) writeState(sh *Shard) error {
+	// An adopted engine was started by an earlier agent: its command line
+	// is the one its state file kept.
+	cmdline := sh.cmdline
+	if sh.cmd != nil {
+		cmdline = sh.cmd.Args
+	}
 	b, err := json.Marshal(shardState{
 		ShardID:   sh.ID,
 		ReplicaID: sh.Spec.ReplicaID,
 		PID:       sh.pid,
-		Cmdline:   sh.cmd.Args,
+		Cmdline:   cmdline,
 		StartedAt: sh.started,
 		Spec:      sh.Spec,
 	})
@@ -725,6 +752,7 @@ func (s *Supervisor) writeState(sh *Shard) error {
 
 func (s *Supervisor) removeState(sh *Shard) {
 	_ = os.Remove(s.statePath(sh.ID))
+	s.removeOutput(sh.ID)
 }
 
 // Orphan is an engine process left behind by a previous agent.
@@ -803,14 +831,18 @@ func (s *Supervisor) Adopt(o Orphan) (*Shard, error) {
 		logs:    newRingBuffer(s.cfg.LogLines),
 		started: o.StartedAt,
 		done:    make(chan struct{}),
+		outStop: make(chan struct{}),
 		adopted: true,
+		cmdline: o.Cmdline,
 	}
 	s.shards[o.ShardID] = sh
 	s.mu.Unlock()
 
-	// Output is gone with the previous agent; say so rather than presenting an
-	// empty log as if the engine had been silent.
-	sh.logs.add("[adopted from a previous agent; earlier output is not available]")
+	// Its output file is read from the start: what it wrote under the
+	// previous agent is there, and what it writes now goes on arriving.
+	sh.logs.add("[adopted from a previous agent]")
+	sh.outDone.Add(1)
+	go s.follow(sh, s.outputPath(sh.ID, ""), "")
 
 	go s.poll(sh)
 	return sh, nil
@@ -838,6 +870,7 @@ func (s *Supervisor) poll(sh *Shard) {
 		}
 		sh.mu.Unlock()
 
+		s.stopOutput(sh)
 		s.removeState(sh)
 		s.log.Info("adopted shard exited", "shard", sh.ID, "expected", expected)
 		return
@@ -864,6 +897,7 @@ func (s *Supervisor) KillOrphan(o Orphan) error {
 	}
 	// An already-missing state file is success: the previous agent may have
 	// reaped the process itself between the scan and this call.
+	s.removeOutput(o.ShardID)
 	if err := os.Remove(s.statePath(o.ShardID)); err != nil && !errors.Is(err, os.ErrNotExist) {
 		return err
 	}

internal/agent/supervisor/supervisor_test.go

@@ -1,6 +1,7 @@
 package supervisor
 
 import (
+	"bytes"
 	"context"
 	"errors"
 	"fmt"
@@ -848,3 +849,135 @@ func eventually(t *testing.T, limit time.Duration, msg string, cond func() bool)
 		time.Sleep(10 * time.Millisecond)
 	}
 }
+
+func TestWhatAShardComputesOnSurvivesTheAgent(t *testing.T) {
+	s, _ := newSupervisor(t)
+	spec := engines.ShardSpec{ReplicaID: "rep-1", ShardID: "a", HTTPPort: 20100}
+	sh, err := s.Start(t.Context(), "a", spec, shellCommand("sleep 30"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = s.Stop(context.Background(), "a") })
+	_ = sh
+	s.SetCompute("a", engines.Compute{Backend: "CUDA", Offloaded: 49, Total: 49})
+
+	s2, err := New(Config{WorkDir: s.cfg.WorkDir, StopTimeout: 2 * time.Second},
+		&scriptedHealth{}, slog.New(slog.DiscardHandler))
+	if err != nil {
+		t.Fatal(err)
+	}
+	orphans, err := s2.FindOrphans()
+	if err != nil || len(orphans) != 1 {
+		t.Fatalf("%v %d", err, len(orphans))
+	}
+	if c := orphans[0].Spec.Compute; c == nil || c.Backend != "CUDA" || c.Offloaded != 49 {
+		t.Errorf("not kept: %+v", c)
+	}
+}
+
+func TestAnAdoptedShardsComputeIsKeptWithoutCrashing(t *testing.T) {
+	s, _ := newSupervisor(t)
+	spec := engines.ShardSpec{ReplicaID: "rep-1", ShardID: "a", HTTPPort: 20100}
+	if _, err := s.Start(t.Context(), "a", spec, shellCommand("sleep 30")); err != nil {
+		t.Fatal(err)
+	}
+	// An agent restart: the engine is adopted by a new supervisor, which did
+	// not start it and has no command of its own for it.
+	s2, err := New(Config{WorkDir: s.cfg.WorkDir, StopTimeout: 2 * time.Second},
+		&scriptedHealth{}, slog.New(slog.DiscardHandler))
+	if err != nil {
+		t.Fatal(err)
+	}
+	orphans, _ := s2.FindOrphans()
+	if len(orphans) != 1 {
+		t.Fatalf("%d orphans", len(orphans))
+	}
+	if _, err := s2.Adopt(orphans[0]); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = s2.Stop(context.Background(), "a") })
+	s2.SetCompute("a", engines.Compute{Backend: "CPU"})
+
+	// And a third agent still finds it, with its command line and compute.
+	s3, _ := New(Config{WorkDir: s.cfg.WorkDir, StopTimeout: 2 * time.Second},
+		&scriptedHealth{}, slog.New(slog.DiscardHandler))
+	again, _ := s3.FindOrphans()
+	if len(again) != 1 || len(again[0].Cmdline) == 0 || again[0].Spec.Compute == nil {
+		t.Fatalf("lost: %+v", again)
+	}
+}
+
+func TestAnAdoptedEngineGoesOnWritingAndItsEarlierOutputIsKept(t *testing.T) {
+	// An engine's output went to a pipe of the agent's. The agent that
+	// restarted and adopted the engine left that pipe with no reader, and
+	// the engine's next write past the pipe's buffer failed with EPIPE —
+	// which, in a Python engine, raised inside whatever was being reported
+	// on and failed the request. Output goes to a file now: a reader is not
+	// something a file can lose, and the lines from before the restart are
+	// there for the agent after it.
+	s, _ := newSupervisor(t)
+	// 256 KiB at once outgrows a pipe's buffer; a reader gone means EPIPE.
+	sh, err := s.Start(t.Context(), "a", engines.ShardSpec{ReplicaID: "r"},
+		shellCommand(`echo before-restart; sleep 1; head -c 262144 /dev/zero | tr '\0' x; echo; echo after-restart-done; sleep 30`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	eventually(t, 3*time.Second, "the first line was never captured", func() bool {
+		return strings.Contains(strings.Join(sh.Logs(10), "\n"), "before-restart")
+	})
+	// The agent goes away without stopping the engine: nothing reads the
+	// output between here and the adoption.
+	pid := sh.Status().PID
+	sh.outOnce.Do(func() { close(sh.outStop) })
+	sh.outDone.Wait()
+
+	s2, err := New(Config{WorkDir: s.cfg.WorkDir, StopTimeout: 3 * time.Second, LogLines: 64},
+		&scriptedHealth{}, slog.New(slog.DiscardHandler))
+	if err != nil {
+		t.Fatal(err)
+	}
+	orphans, _ := s2.FindOrphans()
+	adopted, err := s2.Adopt(orphans[0])
+	if err != nil {
+		t.Fatal(err)
+	}
+	eventually(t, 5*time.Second, "the engine's output after the restart never arrived: "+strings.Join(adopted.Logs(5), " | "), func() bool {
+		return strings.Contains(strings.Join(adopted.Logs(64), "\n"), "after-restart-done")
+	})
+	if !strings.Contains(strings.Join(adopted.Logs(64), "\n"), "before-restart") {
+		t.Error("the output from before the restart is not in the adopted log")
+	}
+	if !processAlive(pid) {
+		t.Fatal("the engine died writing output nobody was reading")
+	}
+	if err := s2.Stop(t.Context(), "a"); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(s2.outputPath("a", "")); !errors.Is(err, os.ErrNotExist) {
+		t.Errorf("the output file was not removed with the shard: %v", err)
+	}
+}
+
+func TestAnOutputFileIsEmptiedPastItsBound(t *testing.T) {
+	s, _ := newSupervisor(t)
+	path := s.outputPath("a", "")
+	// A file already past the bound, as a long-running engine leaves one.
+	big, _ := os.OpenFile(path, os.O_CREATE|os.O_WRONLY, 0o644)
+	_, _ = big.Write(bytes.Repeat([]byte("x"), maxOutputBytes+1))
+	big.Close()
+	sh := &Shard{ID: "a", logs: newRingBuffer(8), done: make(chan struct{}), outStop: make(chan struct{})}
+	sh.outDone.Add(1)
+	go s.follow(sh, path, "")
+	time.Sleep(300 * time.Millisecond)
+	f, _ := os.OpenFile(path, os.O_WRONLY|os.O_APPEND, 0o644)
+	_, _ = f.WriteString("still here\n")
+	f.Close()
+	s.stopOutput(sh)
+	st, _ := os.Stat(path)
+	if st.Size() > 1024 {
+		t.Errorf("the file was not emptied: %d bytes", st.Size())
+	}
+	if !strings.Contains(strings.Join(sh.Logs(8), "\n"), "still here") {
+		t.Errorf("a line written after the file was emptied was lost: %v", sh.Logs(8))
+	}
+}

internal/agent/train/runner.go

@@ -0,0 +1,574 @@
+// Package train runs LoRA training jobs on a node (BACKLOG F4): with an
+// installed engine's Python — its torch and transformers, already matched to
+// the node's CUDA — and a small overlay of what training needs besides, so a
+// node that serves can train without a second multi-gigabyte environment.
+package train
+
+import (
+	"archive/tar"
+	"bufio"
+	"bytes"
+	"compress/gzip"
+	"context"
+	"crypto/sha256"
+	_ "embed"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"syscall"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/supervisor"
+)
+
+//go:embed trainer.py
+var trainerPy []byte
+
+// overlayPackages are what training needs besides an engine's Python, pinned
+// and installed without their dependencies: those are the engine's own, and
+// letting an installer resolve them pulled a second torch.
+var overlayPackages = []string{"peft==0.21.2", "accelerate==1.15.0"}
+
+// Job is one training job, as the control plane sent it.
+type Job struct {
+	ID           string
+	BaseRepo     string
+	BaseRevision string
+	// Data is NDJSON of {"q", "a"}.
+	Data []byte
+	// Params is the trainer's settings as JSON.
+	Params       string
+	GPUMemoryMiB int
+	GGUF         bool
+}
+
+// Status is how a job is going.
+type Status struct {
+	State   string
+	Message string
+	Step    int
+	Steps   int
+	Loss    float64
+	PeakMiB int
+}
+
+// Env is where a node keeps what training needs.
+type Env struct {
+	// EnginesDir is where engines are installed (the agent's engines_dir).
+	EnginesDir string
+	// WorkDir is the trainer's own directory: its overlay, the llama.cpp
+	// conversion code, and each job's files while it runs.
+	WorkDir string
+	// RunAs is the user jobs run as: the engines' user.
+	RunAs string
+	Log   *slog.Logger
+	// Python, UV, ConvDir and GPUs replace what would be found, for tests.
+	Python, UV, ConvDir string
+	GPUs                func(ctx context.Context) ([]GPU, error)
+}
+
+// GPU is one card and how much of it is free.
+type GPU struct {
+	Index   int
+	FreeMiB int
+}
+
+// Runner runs one job at a time.
+type Runner struct {
+	env    Env
+	mu     sync.Mutex
+	cancel context.CancelFunc
+	job    string
+}
+
+// New is a runner.
+func New(env Env) *Runner {
+	if env.Log == nil {
+		env.Log = slog.New(slog.DiscardHandler)
+	}
+	return &Runner{env: env}
+}
+
+// Cancel stops a job if it is the one running.
+func (r *Runner) Cancel(id string) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.job == id && r.cancel != nil {
+		r.cancel()
+	}
+}
+
+// ErrBusy is a node already training.
+var ErrBusy = errors.New("this node is already training")
+
+// Run runs a job to its end, telling status as it goes and artifact each
+// piece of what it made. It answers the error it failed with.
+func (r *Runner) Run(ctx context.Context, job Job, status func(Status), artifact func(kind string, seq int, data []byte, last bool) error) error {
+	r.mu.Lock()
+	if r.job != "" {
+		r.mu.Unlock()
+		return ErrBusy
+	}
+	ctx, cancel := context.WithCancel(ctx)
+	r.job, r.cancel = job.ID, cancel
+	r.mu.Unlock()
+	defer func() {
+		cancel()
+		r.mu.Lock()
+		r.job, r.cancel = "", nil
+		r.mu.Unlock()
+	}()
+
+	status(Status{State: "preparing", Message: "preparing the trainer"})
+	py, err := r.python()
+	if err != nil {
+		return err
+	}
+	overlay, err := r.overlay(ctx, py)
+	if err != nil {
+		return fmt.Errorf("installing %s: %w", strings.Join(overlayPackages, ", "), err)
+	}
+	conv := ""
+	if job.GGUF {
+		if conv, err = r.conversion(ctx); err != nil {
+			return fmt.Errorf("fetching llama.cpp's conversion code: %w", err)
+		}
+	}
+	gpu, err := r.pickGPU(ctx, job.GPUMemoryMiB)
+	if err != nil {
+		return err
+	}
+
+	dir := filepath.Join(r.env.WorkDir, "jobs", job.ID)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return err
+	}
+	defer os.RemoveAll(dir)
+	out := filepath.Join(dir, "adapter")
+	var params map[string]any
+	if job.Params != "" {
+		if err := json.Unmarshal([]byte(job.Params), &params); err != nil {
+			return fmt.Errorf("the job's params: %w", err)
+		}
+	}
+	spec, _ := json.Marshal(map[string]any{"base_repo": job.BaseRepo, "base_revision": job.BaseRevision,
+		"data": filepath.Join(dir, "data.jsonl"), "out": out, "params": params})
+	for name, b := range map[string][]byte{"data.jsonl": job.Data, "job.json": spec, "trainer.py": trainerPy} {
+		if err := os.WriteFile(filepath.Join(dir, name), b, 0o644); err != nil {
+			return err
+		}
+	}
+
+	var baseDir string
+	err = r.python3(ctx, py, dir, []string{"PYTHONPATH=" + overlay, "CUDA_VISIBLE_DEVICES=" + strconv.Itoa(gpu)},
+		[]string{filepath.Join(dir, "trainer.py"), filepath.Join(dir, "job.json")},
+		func(line map[string]any) {
+			s := Status{State: str(line["state"]), Message: str(line["message"]), Step: num(line["step"]),
+				Steps: num(line["steps"]), PeakMiB: num(line["peak_mib"])}
+			if v, ok := line["loss"].(float64); ok {
+				s.Loss = v
+			}
+			if b := str(line["base_dir"]); b != "" {
+				baseDir = b
+			}
+			if s.State == "trained" {
+				s.State = "running"
+				s.Message = "trained; packing the adapter"
+			}
+			status(s)
+		})
+	if err != nil {
+		return err
+	}
+
+	if job.GGUF {
+		status(Status{State: "running", Message: "converting the adapter to GGUF for llama.cpp"})
+		gguf := filepath.Join(dir, "adapter.gguf")
+		err := r.python3(ctx, py, dir, []string{"PYTHONPATH=" + strings.Join([]string{filepath.Join(conv, "gguf-py"), conv, overlay}, ":")},
+			[]string{filepath.Join(conv, "convert_lora_to_gguf.py"), "--base", baseDir, "--outtype", "f16", "--outfile", gguf, out}, nil)
+		if err != nil {
+			return fmt.Errorf("converting to GGUF: %w", err)
+		}
+		if err := sendFile(gguf, "gguf", artifact); err != nil {
+			return err
+		}
+	}
+	var tgz bytes.Buffer
+	if err := tarGz(&tgz, out); err != nil {
+		return err
+	}
+	return sendBytes(tgz.Bytes(), "peft", artifact)
+}
+
+func str(v any) string {
+	s, _ := v.(string)
+	return s
+}
+
+func num(v any) int {
+	f, _ := v.(float64)
+	return int(f)
+}
+
+// python3 runs a Python script as the engines' user, passing each JSON line
+// it prints to line, and answers the last of what it wrote to stderr when it
+// fails.
+func (r *Runner) python3(ctx context.Context, py, dir string, env, args []string, line func(map[string]any)) error {
+	cmd := exec.CommandContext(ctx, py, args...)
+	cmd.Dir = dir
+	cmd.Env = append(os.Environ(), "PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True", "TOKENIZERS_PARALLELISM=false",
+		"HF_HUB_DISABLE_PROGRESS_BARS=1", "PYTHONUNBUFFERED=1")
+	cmd.Env = append(cmd.Env, env...)
+	home, give, why := supervisor.AsEngineUser(cmd, r.env.RunAs, r.env.WorkDir)
+	if why != "" {
+		r.env.Log.Warn(why)
+	}
+	if home != "" {
+		cmd.Env = append(cmd.Env, "HF_HOME="+filepath.Join(home, ".cache", "huggingface"))
+	} else {
+		cmd.Env = append(cmd.Env, "HF_HOME="+filepath.Join(r.env.WorkDir, "hf"))
+	}
+	if err := give(dir); err != nil {
+		return fmt.Errorf("handing %s to %s: %w", dir, r.env.RunAs, err)
+	}
+	// The whole process group goes when the job is cancelled: torch starts
+	// workers of its own.
+	if cmd.SysProcAttr == nil {
+		cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	}
+	cmd.Cancel = func() error { return syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL) }
+	stdout, err := cmd.StdoutPipe()
+	if err != nil {
+		return err
+	}
+	var stderr tailBuffer
+	cmd.Stderr = &stderr
+	if err := cmd.Start(); err != nil {
+		return err
+	}
+	sc := bufio.NewScanner(stdout)
+	sc.Buffer(make([]byte, 64<<10), 1<<20)
+	for sc.Scan() {
+		var m map[string]any
+		if line != nil && json.Unmarshal(sc.Bytes(), &m) == nil {
+			line(m)
+		}
+	}
+	err = cmd.Wait()
+	if ctx.Err() != nil {
+		return errors.New("cancelled")
+	}
+	if err != nil {
+		return fmt.Errorf("%v: %s", err, stderr.last())
+	}
+	return nil
+}
+
+// tailBuffer keeps the end of what a process wrote: the reason it failed is
+// at the end, and the rest is progress bars.
+type tailBuffer struct{ b []byte }
+
+func (t *tailBuffer) Write(p []byte) (int, error) {
+	t.b = append(t.b, p...)
+	if len(t.b) > 16<<10 {
+		t.b = t.b[len(t.b)-16<<10:]
+	}
+	return len(p), nil
+}
+
+func (t *tailBuffer) last() string {
+	lines := strings.Split(strings.TrimSpace(string(t.b)), "\n")
+	if len(lines) > 3 {
+		lines = lines[len(lines)-3:]
+	}
+	return strings.Join(lines, " | ")
+}
+
+// python is the newest installed vLLM's interpreter: its torch is built for
+// this node's CUDA.
+func (r *Runner) python() (string, error) {
+	if r.env.Python != "" {
+		return r.env.Python, nil
+	}
+	found, _ := filepath.Glob(filepath.Join(r.env.EnginesDir, "vllm", "*", "bin", "python3"))
+	if len(found) == 0 {
+		return "", errors.New("training needs vLLM installed on this node (its torch is what trains); " +
+			"llmgw ctl engine-build, or serving any vLLM model here, installs it")
+	}
+	sort.Strings(found)
+	return found[len(found)-1], nil
+}
+
+func (r *Runner) uv() (string, error) {
+	if r.env.UV != "" {
+		return r.env.UV, nil
+	}
+	var found []string
+	_ = filepath.WalkDir(filepath.Join(r.env.EnginesDir, "uv"), func(p string, d os.DirEntry, err error) error {
+		if err == nil && !d.IsDir() && d.Name() == "uv" {
+			found = append(found, p)
+		}
+		return nil
+	})
+	if len(found) == 0 {
+		return "", errors.New("no uv under " + filepath.Join(r.env.EnginesDir, "uv"))
+	}
+	sort.Strings(found)
+	return found[len(found)-1], nil
+}
+
+// overlay installs the pinned packages once per Python and set of pins.
+func (r *Runner) overlay(ctx context.Context, py string) (string, error) {
+	sum := sha256.Sum256([]byte(py + "\x00" + strings.Join(overlayPackages, " ")))
+	dir := filepath.Join(r.env.WorkDir, "overlay-"+hex.EncodeToString(sum[:6]))
+	if _, err := os.Stat(filepath.Join(dir, ".done")); err == nil {
+		return dir, nil
+	}
+	uv, err := r.uv()
+	if err != nil {
+		return "", err
+	}
+	tmp := dir + ".new"
+	_ = os.RemoveAll(tmp)
+	args := append([]string{"pip", "install", "--quiet", "--python", py, "--no-deps", "--target", tmp}, overlayPackages...)
+	cmd := exec.CommandContext(ctx, uv, args...)
+	if out, err := cmd.CombinedOutput(); err != nil {
+		return "", fmt.Errorf("%v: %s", err, strings.TrimSpace(string(out)))
+	}
+	_ = os.WriteFile(filepath.Join(tmp, ".done"), nil, 0o644)
+	_ = os.RemoveAll(dir)
+	if err := os.Rename(tmp, dir); err != nil {
+		return "", err
+	}
+	// Readable by the engines' user, which runs the trainer.
+	_ = filepath.WalkDir(dir, func(p string, d os.DirEntry, err error) error {
+		if err == nil {
+			mode := os.FileMode(0o644)
+			if d.IsDir() {
+				mode = 0o755
+			}
+			_ = os.Chmod(p, mode)
+		}
+		return nil
+	})
+	return dir, nil
+}
+
+// llamaCppTag is the release of the newest llama.cpp installed: its
+// conversion code is the one whose GGUF that llama.cpp reads.
+func (r *Runner) llamaCppTag() (string, error) {
+	found, _ := filepath.Glob(filepath.Join(r.env.EnginesDir, "llamacpp", "b*"))
+	if len(found) == 0 {
+		return "", errors.New("a GGUF adapter needs llama.cpp installed on this node, to match its release")
+	}
+	sort.Strings(found)
+	tag, _, _ := strings.Cut(filepath.Base(found[len(found)-1]), "-")
+	return tag, nil
+}
+
+// conversionSource is where llama.cpp's source is fetched from, by tag.
+var conversionSource = "https://codeload.github.com/ggml-org/llama.cpp/tar.gz/refs/tags/"
+
+// conversion fetches llama.cpp's LoRA conversion code for the installed
+// release, once.
+func (r *Runner) conversion(ctx context.Context) (string, error) {
+	if r.env.ConvDir != "" {
+		return r.env.ConvDir, nil
+	}
+	tag, err := r.llamaCppTag()
+	if err != nil {
+		return "", err
+	}
+	dir := filepath.Join(r.env.WorkDir, "llama.cpp-"+tag)
+	if _, err := os.Stat(filepath.Join(dir, "convert_lora_to_gguf.py")); err == nil {
+		return dir, nil
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, conversionSource+tag, nil)
+	if err != nil {
+		return "", err
+	}
+	res, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return "", err
+	}
+	defer res.Body.Close()
+	if res.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("%s answered %s", conversionSource+tag, res.Status)
+	}
+	tmp := dir + ".new"
+	_ = os.RemoveAll(tmp)
+	if err := untarConversion(res.Body, tmp); err != nil {
+		return "", err
+	}
+	_ = os.RemoveAll(dir)
+	return dir, os.Rename(tmp, dir)
+}
+
+// untarConversion keeps, of llama.cpp's source, the conversion scripts and
+// the Python packages they import.
+func untarConversion(r io.Reader, dir string) error {
+	gz, err := gzip.NewReader(r)
+	if err != nil {
+		return err
+	}
+	tr := tar.NewReader(gz)
+	kept := 0
+	for {
+		h, err := tr.Next()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			return err
+		}
+		_, rel, ok := strings.Cut(h.Name, "/")
+		if !ok || h.Typeflag != tar.TypeReg || strings.Contains(rel, "..") {
+			continue
+		}
+		if rel != "convert_lora_to_gguf.py" && rel != "convert_hf_to_gguf.py" &&
+			!strings.HasPrefix(rel, "conversion/") && !strings.HasPrefix(rel, "gguf-py/") {
+			continue
+		}
+		p := filepath.Join(dir, filepath.FromSlash(rel))
+		if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+			return err
+		}
+		f, err := os.OpenFile(p, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o644)
+		if err != nil {
+			return err
+		}
+		_, err = io.Copy(f, io.LimitReader(tr, 64<<20))
+		f.Close()
+		if err != nil {
+			return err
+		}
+		kept++
+	}
+	if kept == 0 {
+		return errors.New("no conversion code in llama.cpp's source")
+	}
+	return nil
+}
+
+// pickGPU is the card with the most memory free, if that is enough.
+func (r *Runner) pickGPU(ctx context.Context, need int) (int, error) {
+	list := r.env.GPUs
+	if list == nil {
+		list = nvidiaSMI
+	}
+	gpus, err := list(ctx)
+	if err != nil {
+		return 0, fmt.Errorf("reading the cards' free memory: %w", err)
+	}
+	if len(gpus) == 0 {
+		return 0, errors.New("this node has no GPU to train on")
+	}
+	best := gpus[0]
+	for _, g := range gpus[1:] {
+		if g.FreeMiB > best.FreeMiB {
+			best = g
+		}
+	}
+	if best.FreeMiB < need {
+		return 0, fmt.Errorf("no card here has %d MiB free (the most free is GPU %d with %d MiB); "+
+			"a smaller base, or a card freed for it, would do", need, best.Index, best.FreeMiB)
+	}
+	return best.Index, nil
+}
+
+func nvidiaSMI(ctx context.Context) ([]GPU, error) {
+	ctx, cancel := context.WithTimeout(ctx, 15*time.Second)
+	defer cancel()
+	out, err := exec.CommandContext(ctx, "nvidia-smi", "--query-gpu=index,memory.free", "--format=csv,noheader,nounits").Output()
+	if err != nil {
+		return nil, err
+	}
+	return parseGPUs(string(out)), nil
+}
+
+func parseGPUs(s string) []GPU {
+	var out []GPU
+	for _, line := range strings.Split(strings.TrimSpace(s), "\n") {
+		a, b, ok := strings.Cut(line, ",")
+		if !ok {
+			continue
+		}
+		i, err1 := strconv.Atoi(strings.TrimSpace(a))
+		f, err2 := strconv.Atoi(strings.TrimSpace(b))
+		if err1 == nil && err2 == nil {
+			out = append(out, GPU{Index: i, FreeMiB: f})
+		}
+	}
+	return out
+}
+
+// tarGz packs a directory.
+func tarGz(w io.Writer, dir string) error {
+	gz := gzip.NewWriter(w)
+	tw := tar.NewWriter(gz)
+	err := filepath.WalkDir(dir, func(p string, d os.DirEntry, err error) error {
+		if err != nil || d.IsDir() {
+			return err
+		}
+		rel, _ := filepath.Rel(dir, p)
+		info, err := d.Info()
+		if err != nil {
+			return err
+		}
+		if err := tw.WriteHeader(&tar.Header{Name: filepath.ToSlash(rel), Mode: 0o644, Size: info.Size(), ModTime: info.ModTime()}); err != nil {
+			return err
+		}
+		f, err := os.Open(p)
+		if err != nil {
+			return err
+		}
+		defer f.Close()
+		_, err = io.Copy(tw, f)
+		return err
+	})
+	if err != nil {
+		return err
+	}
+	if err := tw.Close(); err != nil {
+		return err
+	}
+	return gz.Close()
+}
+
+// artifactChunk is how much of an artifact goes in one message.
+const artifactChunk = 1 << 20
+
+func sendFile(path, kind string, send func(string, int, []byte, bool) error) error {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return err
+	}
+	return sendBytes(b, kind, send)
+}
+
+func sendBytes(b []byte, kind string, send func(string, int, []byte, bool) error) error {
+	seq := 0
+	for {
+		n := min(artifactChunk, len(b))
+		last := n == len(b)
+		if err := send(kind, seq, b[:n], last); err != nil {
+			return err
+		}
+		if last {
+			return nil
+		}
+		b = b[n:]
+		seq++
+	}
+}

internal/agent/train/runner_test.go

@@ -0,0 +1,164 @@
+package train
+
+import (
+	"archive/tar"
+	"bytes"
+	"compress/gzip"
+	"context"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+)
+
+// fakePython stands in for an engine's interpreter: as the trainer it
+// prints progress and writes an adapter; as the converter it writes a GGUF;
+// told to fail, it fails.
+const fakePython = `#!/bin/sh
+case "$1" in
+*trainer.py)
+  out=$(sed -n 's/.*"out": *"\([^"]*\)".*/\1/p' "$2")
+  grep -q FAIL "$(dirname "$2")/data.jsonl" && { echo "CUDA out of memory" >&2; exit 1; }
+  echo '{"state":"preparing","message":"fetching base"}'
+  echo '{"state":"running","step":5,"steps":10,"loss":0.9,"peak_mib":1900}'
+  mkdir -p "$out"; echo '{"r":16}' > "$out/adapter_config.json"; echo weights > "$out/adapter_model.safetensors"
+  echo '{"state":"trained","step":10,"steps":10,"peak_mib":2100,"base_dir":"/base"}'
+  ;;
+*convert_lora_to_gguf.py)
+  while [ $# -gt 0 ]; do [ "$1" = "--outfile" ] && echo GGUF > "$2"; shift; done
+  ;;
+esac
+`
+
+func runner(t *testing.T, free int) *Runner {
+	t.Helper()
+	dir := t.TempDir()
+	py := filepath.Join(dir, "python3")
+	_ = os.WriteFile(py, []byte(fakePython), 0o755)
+	uv := filepath.Join(dir, "uv")
+	_ = os.WriteFile(uv, []byte("#!/bin/sh\nwhile [ $# -gt 0 ]; do [ \"$1\" = \"--target\" ] && mkdir -p \"$2\"; shift; done\n"), 0o755)
+	return New(Env{WorkDir: filepath.Join(dir, "work"), Python: py, UV: uv, ConvDir: dir,
+		GPUs: func(context.Context) ([]GPU, error) { return []GPU{{0, 500}, {1, free}}, nil }})
+}
+
+type sink struct {
+	mu       sync.Mutex
+	statuses []Status
+	parts    map[string][]byte
+	lasts    int
+}
+
+func (s *sink) status(st Status) { s.mu.Lock(); s.statuses = append(s.statuses, st); s.mu.Unlock() }
+func (s *sink) artifact(kind string, _ int, b []byte, last bool) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.parts == nil {
+		s.parts = map[string][]byte{}
+	}
+	s.parts[kind] = append(s.parts[kind], b...)
+	if last {
+		s.lasts++
+	}
+	return nil
+}
+
+func TestAJobTrainsOnTheFreestCardAndSendsWhatItMade(t *testing.T) {
+	r := runner(t, 3000)
+	s := &sink{}
+	err := r.Run(context.Background(), Job{ID: "j1", BaseRepo: "Qwen/x", Data: []byte(`{"q":"a","a":"b"}`), GPUMemoryMiB: 2500, GGUF: true},
+		s.status, s.artifact)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var running bool
+	for _, st := range s.statuses {
+		if st.State == "running" && st.Step == 5 && st.Steps == 10 && st.PeakMiB == 1900 {
+			running = true
+		}
+	}
+	if !running {
+		t.Errorf("statuses %+v", s.statuses)
+	}
+	if string(s.parts["gguf"]) != "GGUF\n" || s.lasts != 2 {
+		t.Errorf("gguf %q, lasts %d", s.parts["gguf"], s.lasts)
+	}
+	files := map[string]string{}
+	gz, err := gzip.NewReader(bytes.NewReader(s.parts["peft"]))
+	if err != nil {
+		t.Fatal(err)
+	}
+	tr := tar.NewReader(gz)
+	for {
+		h, err := tr.Next()
+		if err != nil {
+			break
+		}
+		b, _ := io.ReadAll(tr)
+		files[h.Name] = string(b)
+	}
+	if files["adapter_model.safetensors"] != "weights\n" || files["adapter_config.json"] == "" {
+		t.Errorf("peft archive %v", files)
+	}
+	// Nothing of the job is left on the node.
+	if entries, _ := os.ReadDir(filepath.Join(r.env.WorkDir, "jobs")); len(entries) != 0 {
+		t.Errorf("left behind: %v", entries)
+	}
+}
+
+func TestAJobWaitsForNoCardItDoesNotFit(t *testing.T) {
+	r := runner(t, 1000)
+	err := r.Run(context.Background(), Job{ID: "j1", Data: []byte(`{"q":"a","a":"b"}`), GPUMemoryMiB: 2500}, (&sink{}).status, (&sink{}).artifact)
+	if err == nil || !strings.Contains(err.Error(), "no card here has 2500 MiB free") {
+		t.Errorf("got %v", err)
+	}
+}
+
+func TestATrainerThatFailsSaysWhy(t *testing.T) {
+	r := runner(t, 3000)
+	err := r.Run(context.Background(), Job{ID: "j1", Data: []byte(`{"q":"FAIL","a":"b"}`)}, (&sink{}).status, (&sink{}).artifact)
+	if err == nil || !strings.Contains(err.Error(), "CUDA out of memory") {
+		t.Errorf("got %v", err)
+	}
+}
+
+func TestOneJobAtATime(t *testing.T) {
+	r := runner(t, 3000)
+	r.job = "other"
+	if err := r.Run(context.Background(), Job{ID: "j2"}, (&sink{}).status, (&sink{}).artifact); err != ErrBusy {
+		t.Errorf("got %v", err)
+	}
+}
+
+func TestCardsAreReadFromNvidiaSMI(t *testing.T) {
+	got := parseGPUs("0, 2310\n1, 80000\nbad line\n")
+	if len(got) != 2 || got[1].FreeMiB != 80000 || got[0].Index != 0 {
+		t.Errorf("parsed %+v", got)
+	}
+}
+
+func TestOnlyTheConversionCodeIsKeptOfLlamaCpp(t *testing.T) {
+	var buf bytes.Buffer
+	gz := gzip.NewWriter(&buf)
+	tw := tar.NewWriter(gz)
+	for _, name := range []string{"llama.cpp-b1/convert_lora_to_gguf.py", "llama.cpp-b1/conversion/qwen.py",
+		"llama.cpp-b1/gguf-py/gguf/__init__.py", "llama.cpp-b1/src/llama.cpp", "llama.cpp-b1/../evil"} {
+		_ = tw.WriteHeader(&tar.Header{Name: name, Mode: 0o644, Size: 1, Typeflag: tar.TypeReg})
+		_, _ = tw.Write([]byte("x"))
+	}
+	_ = tw.Close()
+	_ = gz.Close()
+	dir := filepath.Join(t.TempDir(), "conv")
+	if err := untarConversion(&buf, dir); err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{"convert_lora_to_gguf.py", "conversion/qwen.py", "gguf-py/gguf/__init__.py"} {
+		if _, err := os.Stat(filepath.Join(dir, want)); err != nil {
+			t.Errorf("%s not kept", want)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(dir, "src")); err == nil {
+		t.Error("the rest of llama.cpp was kept")
+	}
+}

internal/agent/train/trainer.py

@@ -0,0 +1,101 @@
+# llmgw's LoRA trainer (BACKLOG F4), run by the node agent with an installed
+# engine's Python (its torch and transformers) and a small overlay (peft,
+# accelerate). Reads a job, trains, writes the PEFT adapter, and says how it
+# goes as one JSON object a line on standard output.
+import json, math, os, random, sys, threading, subprocess, time
+
+def say(**kw):
+    print(json.dumps(kw), flush=True)
+
+job = json.load(open(sys.argv[1], encoding="utf-8"))
+p = {"rank": 16, "alpha": 32, "dropout": 0.05, "epochs": 6, "lr": 2e-4, "batch": 4, "max_len": 512, "seed": 0}
+p.update(job.get("params") or {})
+
+say(state="preparing", message="loading libraries")
+import torch
+from huggingface_hub import snapshot_download
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import LoraConfig, get_peft_model
+
+random.seed(p["seed"]); torch.manual_seed(p["seed"])
+if not torch.cuda.is_available():
+    raise SystemExit("no CUDA device is visible to the trainer")
+
+say(state="preparing", message="fetching " + job["base_repo"])
+base_dir = snapshot_download(job["base_repo"], revision=job.get("base_revision") or None,
+                             allow_patterns=["*.json", "*.safetensors", "*.txt", "*.model", "*.tiktoken"])
+say(state="preparing", message="loading the base model", base_dir=base_dir)
+
+# bf16 where the card has it; fp16 with a loss scaler where it does not
+# (Turing and older).
+bf16 = torch.cuda.is_bf16_supported()
+dtype = torch.bfloat16 if bf16 else torch.float16
+tok = AutoTokenizer.from_pretrained(base_dir)
+if tok.pad_token_id is None:
+    tok.pad_token = tok.eos_token
+model = AutoModelForCausalLM.from_pretrained(base_dir, dtype=dtype).to("cuda")
+
+rows = [json.loads(l) for l in open(job["data"], encoding="utf-8") if l.strip()]
+rows = [r for r in rows if r.get("q") and r.get("a")]
+if not rows:
+    raise SystemExit("no {q, a} pairs in the data")
+
+def encode(r):
+    prompt = tok.apply_chat_template([{"role": "user", "content": r["q"]}], add_generation_prompt=True, tokenize=False)
+    full = tok.apply_chat_template([{"role": "user", "content": r["q"]}, {"role": "assistant", "content": r["a"]}], tokenize=False)
+    pi = tok(prompt, add_special_tokens=False)["input_ids"]
+    fi = tok(full, add_special_tokens=False)["input_ids"][: p["max_len"]]
+    return fi, ([-100] * len(pi) + fi[len(pi):])[: len(fi)]
+
+data = [encode(r) for r in rows]
+
+model.gradient_checkpointing_enable()
+model.enable_input_require_grads()
+model = get_peft_model(model, LoraConfig(r=int(p["rank"]), lora_alpha=int(p["alpha"]), lora_dropout=float(p["dropout"]),
+    task_type="CAUSAL_LM", target_modules=["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"]))
+trainable = [x for x in model.parameters() if x.requires_grad]
+for x in trainable:  # fp32 trainable weights, so a loss scaler can unscale them
+    x.data = x.data.float()
+
+peak = {"mib": 0}
+stop = threading.Event()
+def watch():
+    while not stop.is_set():
+        try:
+            out = subprocess.run(["nvidia-smi", "--query-compute-apps=pid,used_memory", "--format=csv,noheader,nounits"],
+                                 capture_output=True, text=True, timeout=5).stdout
+            for line in out.splitlines():
+                pid, mib = [v.strip() for v in line.split(",")]
+                if int(pid) == os.getpid():
+                    peak["mib"] = max(peak["mib"], int(mib))
+        except Exception:
+            pass
+        time.sleep(0.5)
+threading.Thread(target=watch, daemon=True).start()
+
+opt = torch.optim.AdamW(trainable, lr=float(p["lr"]), weight_decay=0.0)
+scaler = torch.amp.GradScaler("cuda", enabled=not bf16)
+bs, epochs = int(p["batch"]), int(p["epochs"])
+steps = epochs * math.ceil(len(data) / bs)
+warm = max(1, steps // 10)
+sched = torch.optim.lr_scheduler.LambdaLR(opt, lambda s: min(1.0, (s + 1) / warm) * max(0.0, 1 - s / steps))
+model.train(); step = 0; last = time.time()
+for ep in range(epochs):
+    random.shuffle(data)
+    for i in range(0, len(data), bs):
+        batch = data[i:i + bs]; n = max(len(x[0]) for x in batch)
+        ids = torch.tensor([x[0] + [tok.pad_token_id] * (n - len(x[0])) for x in batch], device="cuda")
+        lab = torch.tensor([x[1] + [-100] * (n - len(x[1])) for x in batch], device="cuda")
+        att = torch.tensor([[1] * len(x[0]) + [0] * (n - len(x[0])) for x in batch], device="cuda")
+        with torch.autocast("cuda", dtype=dtype):
+            loss = model(input_ids=ids, attention_mask=att, labels=lab).loss
+        scaler.scale(loss).backward(); scaler.unscale_(opt)
+        torch.nn.utils.clip_grad_norm_(trainable, 1.0)
+        scaler.step(opt); scaler.update(); opt.zero_grad(set_to_none=True); sched.step(); step += 1
+        if time.time() - last > 2 or step == steps:
+            last = time.time()
+            say(state="running", message="training", step=step, steps=steps, loss=round(loss.item(), 4), peak_mib=peak["mib"])
+
+model.save_pretrained(job["out"])
+stop.set()
+say(state="trained", step=step, steps=steps, peak_mib=peak["mib"], base_dir=base_dir)

internal/agent/trainjob.go

@@ -0,0 +1,46 @@
+package agent
+
+import (
+	"context"
+
+	llmgwv1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/train"
+)
+
+// trainJob runs a training job the control plane sent, telling it how the
+// job goes and sending what it made. A stream that ends ends the job: the
+// control plane, which sees the node go, marks it failed, and it is started
+// again from the beginning rather than resumed.
+func (a *Agent) trainJob(ctx context.Context, m *llmgwv1.TrainStart, out chan<- *llmgwv1.AgentMessage) {
+	id := m.GetJobId()
+	send := func(msg *llmgwv1.AgentMessage) bool {
+		select {
+		case out <- msg:
+			return true
+		case <-ctx.Done():
+			return false
+		}
+	}
+	status := func(s train.Status) {
+		send(&llmgwv1.AgentMessage{Msg: &llmgwv1.AgentMessage_TrainStatus{TrainStatus: &llmgwv1.TrainStatus{
+			JobId: id, State: s.State, Message: s.Message, Step: int32(s.Step), Steps: int32(s.Steps), //nolint:gosec // counts
+			Loss: s.Loss, PeakMib: int32(s.PeakMiB)}}}) //nolint:gosec // MiB
+	}
+	artifact := func(kind string, seq int, data []byte, last bool) error {
+		if !send(&llmgwv1.AgentMessage{Msg: &llmgwv1.AgentMessage_TrainArtifact{TrainArtifact: &llmgwv1.TrainArtifact{
+			JobId: id, Kind: kind, Seq: int32(seq), Data: data, Last: last}}}) { //nolint:gosec // chunk count
+			return ctx.Err()
+		}
+		return nil
+	}
+	a.log.Info("training an adapter", "job", id, "base", m.GetBaseRepo())
+	err := a.trainer.Run(ctx, train.Job{ID: id, BaseRepo: m.GetBaseRepo(), BaseRevision: m.GetBaseRevision(),
+		Data: m.GetData(), Params: m.GetParams(), GPUMemoryMiB: int(m.GetGpuMemoryMib()), GGUF: m.GetGguf()}, status, artifact)
+	if err != nil {
+		a.log.Warn("training failed", "job", id, "err", err)
+		status(train.Status{State: "failed", Message: err.Error()})
+		return
+	}
+	a.log.Info("trained an adapter", "job", id)
+	status(train.Status{State: "done"})
+}

internal/agent/watchexits_test.go

@@ -10,6 +10,7 @@ import (
 	llmgwv1 "gitea.mynodes.xyz/ilker/llmgw/api/gen/llmgw/v1"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/engines"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/supervisor"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/agentsvc"
 )
 
 type alwaysReady struct{}
@@ -40,7 +41,7 @@ func TestAnAdoptedEngineThatDiesIsReported(t *testing.T) {
 	out := make(chan *llmgwv1.AgentMessage, 4)
 	ctx, cancel := context.WithCancel(t.Context())
 	defer cancel()
-	go a.watchExits(ctx, out)
+	go a.watchExits(ctx, out, nil)
 	time.Sleep(1500 * time.Millisecond) // seen ready
 	_ = cmd.Process.Kill()
 
@@ -54,3 +55,50 @@ func TestAnAdoptedEngineThatDiesIsReported(t *testing.T) {
 		t.Fatal("the adopted engine died and nothing was reported")
 	}
 }
+
+// Registered while its health check still ran: the ready that follows is
+// reported, or the control plane keeps the replica starting while it serves.
+func TestAShardRegisteredStartingIsReportedReady(t *testing.T) {
+	sup, err := supervisor.New(supervisor.Config{WorkDir: t.TempDir(), RunAs: "-"}, alwaysReady{}, slog.New(slog.DiscardHandler))
+	if err != nil {
+		t.Fatal(err)
+	}
+	cmd := exec.Command("sleep", "60")
+	if err := cmd.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = cmd.Process.Kill(); _ = cmd.Wait() }()
+	sh, err := sup.Adopt(supervisor.Orphan{ShardID: "m-r0", ReplicaID: "m", PID: cmd.Process.Pid,
+		Spec: engines.ShardSpec{ReplicaID: "m", ShardID: "m-r0", HTTPPort: 1}, Alive: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	a := &Agent{sup: sup, log: slog.New(slog.DiscardHandler)}
+	pending := unready(a.runningShards())
+	if !pending["m-r0"] {
+		t.Fatalf("registration reported it ready already: %v", pending)
+	}
+	out := make(chan *llmgwv1.AgentMessage, 4)
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+	go a.watchExits(ctx, out, pending)
+	if err := sup.WaitReady(t.Context(), sh, "http://127.0.0.1:1", "m", 5*time.Second); err != nil {
+		t.Fatal(err)
+	}
+
+	select {
+	case m := <-out:
+		s := m.GetShard()
+		if s.GetShardId() != "m-r0" || s.GetState() != agentsvc.StateToWire(supervisor.Ready) {
+			t.Errorf("reported %+v", s)
+		}
+	case <-time.After(10 * time.Second):
+		t.Fatal("it became ready and nothing was reported")
+	}
+	select {
+	case m := <-out:
+		t.Errorf("reported twice: %+v", m.GetShard())
+	case <-time.After(2500 * time.Millisecond):
+	}
+}

internal/audit/audit.go

@@ -12,6 +12,7 @@ import (
 	"net/http"
 	"net/url"
 	"regexp"
+	"slices"
 	"sort"
 	"strings"
 	"time"
@@ -110,11 +111,16 @@ func (w *statusWriter) Flush() {
 	}
 }
 
+// notChanges are POSTs that change nothing and carry text that must not be
+// kept: asking a judge about a sentence.
+var notChanges = []string{"/api/v1/guard/judges/ask"}
+
 // API records every change to the admin API: a request that is not a GET or
 // HEAD, under /api/. actor says who made it.
 func API(sink Sink, actor func(*http.Request) string, log *slog.Logger, next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.Method == http.MethodGet || r.Method == http.MethodHead || !strings.HasPrefix(r.URL.Path, "/api/") {
+		if r.Method == http.MethodGet || r.Method == http.MethodHead || !strings.HasPrefix(r.URL.Path, "/api/") ||
+			slices.Contains(notChanges, r.URL.Path) {
 			next.ServeHTTP(w, r)
 			return
 		}

internal/audit/audit_test.go

@@ -72,3 +72,13 @@ func TestABodyLargerThanWhatIsRecordedReachesTheHandlerWhole(t *testing.T) {
 		t.Errorf("the handler was given %d of %d bytes", got, len(big))
 	}
 }
+
+func TestAskingAJudgeKeepsNoText(t *testing.T) {
+	sink := &memSink{}
+	h := API(sink, func(*http.Request) string { return "ilker" }, nil, http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}))
+	h.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest("POST", "/api/v1/guard/judges/ask",
+		strings.NewReader(`{"text":"something a user wrote"}`)))
+	if len(sink.got) != 0 {
+		t.Errorf("a judge's question was recorded: %+v", sink.got)
+	}
+}

internal/cli/agent.go

@@ -40,10 +40,23 @@ func newAgentCmd() *cobra.Command {
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			log := logger()
 
-			cfg, err := config.LoadAgent(configPath)
+			// The cluster's settings for this agent over its file, as the
+			// control plane last sent them. Settings that no longer load
+			// beside the file are set aside rather than keeping the agent
+			// from starting: the control plane sends them again, and says
+			// why they are refused.
+			settings := agent.ReadSettings()
+			cfg, err := config.LoadAgentWith(configPath, settings)
+			if err != nil && settings != nil {
+				log.Warn("the cluster's settings kept for this agent do not load beside its agent.yaml; starting without them",
+					"err", err)
+				settings = nil
+				cfg, err = config.LoadAgent(configPath)
+			}
 			if err != nil {
 				return err
 			}
+			cfg.Settings = string(settings)
 			if server != "" {
 				cfg.Server = server
 			}
@@ -89,9 +102,17 @@ func newAgentCmd() *cobra.Command {
 			if err != nil {
 				return err
 			}
+			a.SetSettingsCheck(func(b []byte) error {
+				_, err := config.LoadAgentWith(configPath, b)
+				return err
+			})
 
 			ctx, stop := signal.NotifyContext(cmd.Context(), syscall.SIGINT, syscall.SIGTERM)
 			defer stop()
+			go a.WatchFile(ctx, configPath, func() error {
+				_, err := config.LoadAgentWith(configPath, agent.ReadSettings())
+				return err
+			})
 
 			log.Info("agent starting",
 				"node", cfg.NodeID, "server", cfg.Server,

internal/cli/answercache.go

@@ -5,6 +5,8 @@ import (
 	"time"
 
 	"github.com/spf13/cobra"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
 )
 
 func newAnswerCacheCmd(open opener) *cobra.Command {
@@ -12,6 +14,7 @@ func newAnswerCacheCmd(open opener) *cobra.Command {
 		project   string
 		ttl       time.Duration
 		anyAnswer bool
+		similar   float64
 		off       bool
 	)
 	cmd := &cobra.Command{
@@ -28,15 +31,25 @@ func newAnswerCacheCmd(open opener) *cobra.Command {
 			"a request continuing a stored conversation or under a guardrails no_store\n" +
 			"policy. The guardrails judge a reused answer as they judge any other.\n\n" +
 			"Off for every project until this is run. Without --ttl or --off, says how\n" +
-			"it stands. The answers are held in memory, router.cache bounds how much.",
+			"it stands. The answers are held in memory, router.cache bounds how much.\n\n" +
+			"--similar also answers a chat question that is like one already answered:\n" +
+			"its last user message embedded by router.cache.embedding_model, and given\n" +
+			"the answer whose question reaches that cosine similarity (0.95 is strict,\n" +
+			"0.9 looser), as x-llmgw-cache: similar. The system prompt, the earlier\n" +
+			"turns, tools and the sampling settings must still be the same.",
 		Example: "  llmgw keys cache --project Acme/ml/train --ttl 1h\n" +
 			"  llmgw keys cache --project Acme/ml/eval --ttl 24h --any\n" +
+			"  llmgw keys cache --project Acme/support/desk --ttl 24h --similar 0.95\n" +
 			"  llmgw keys cache --project Acme/ml/train --off",
 		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			switch {
-			case off && (ttl != 0 || anyAnswer):
-				return fmt.Errorf("--off, or --ttl with --any: not both")
+			case off && (ttl != 0 || anyAnswer || similar != 0):
+				return fmt.Errorf("--off, or --ttl with --any or --similar: not both")
+			case similar < 0 || similar > 1:
+				return fmt.Errorf("--similar is a cosine similarity between 0 and 1, like 0.95")
+			case similar != 0 && ttl == 0:
+				return fmt.Errorf("--similar goes with --ttl: say how long answers are reused")
 			case ttl < 0:
 				return fmt.Errorf("--ttl is how long an answer is reused, like 1h")
 			case ttl > 0 && ttl < time.Second:
@@ -54,7 +67,7 @@ func newAnswerCacheCmd(open opener) *cobra.Command {
 				return err
 			}
 			if off || ttl > 0 {
-				if err := s.SetAnswerCache(cmd.Context(), p.ID, ttl, anyAnswer); err != nil {
+				if err := s.SetAnswerCache(cmd.Context(), p.ID, store.AnswerCache{TTL: ttl, Any: anyAnswer, Similar: similar}); err != nil {
 					return err
 				}
 			}
@@ -71,6 +84,9 @@ func newAnswerCacheCmd(open opener) *cobra.Command {
 				fmt.Fprintf(cmd.OutOrStdout(), "%s reuses answers for %s: those asked at temperature 0 or with a seed, "+
 					"and embeddings, rerank and score.\n", p.Path, c.TTL)
 			}
+			if c.TTL > 0 && c.Similar > 0 {
+				fmt.Fprintf(cmd.OutOrStdout(), "Chat questions reaching %.2f similarity to one answered get its answer too.\n", c.Similar)
+			}
 			if off || ttl > 0 {
 				fmt.Fprintln(cmd.OutOrStdout(), "Gateways see the change within 30 seconds.")
 			}
@@ -80,6 +96,7 @@ func newAnswerCacheCmd(open opener) *cobra.Command {
 	cmd.Flags().StringVar(&project, "project", "", "project: id, path or unique name")
 	cmd.Flags().DurationVar(&ttl, "ttl", 0, "how long an answer is reused, like 1h")
 	cmd.Flags().BoolVar(&anyAnswer, "any", false, "reuse sampled answers too, not only reproducible ones")
+	cmd.Flags().Float64Var(&similar, "similar", 0, "also answer chat questions this similar to one answered, like 0.95")
 	cmd.Flags().BoolVar(&off, "off", false, "stop reusing answers for this project")
 	return cmd
 }

internal/cli/backup.go

@@ -249,7 +249,14 @@ func pgEnv(dsn string) ([]string, error) {
 		set("PGPASSWORD", pw)
 	}
 	set("PGDATABASE", strings.TrimPrefix(u.Path, "/"))
-	set("PGSSLMODE", u.Query().Get("sslmode"))
+	// The TLS settings go with the mode: verify-full without the cluster's
+	// authority sent libpq looking for ~/.postgresql/root.crt, and the dump
+	// failed on every control plane whose store is replicated.
+	q := u.Query()
+	set("PGSSLMODE", q.Get("sslmode"))
+	set("PGSSLROOTCERT", q.Get("sslrootcert"))
+	set("PGSSLCERT", q.Get("sslcert"))
+	set("PGSSLKEY", q.Get("sslkey"))
 	// A standby if there is one, else whichever answers — not the address's
 	// read-write: a dump only reads, it need not load the primary, and one
 	// that insists on the primary fails exactly while the cluster is failing

internal/cli/backup_test.go

@@ -238,3 +238,17 @@ func TestAStoreOfSeveralHostsIsGivenToPgDumpAsLibpqLists(t *testing.T) {
 		t.Error("an empty host in the list was accepted")
 	}
 }
+
+func TestPgDumpIsGivenTheClusterAuthorityAlongWithVerifyFull(t *testing.T) {
+	// Without it libpq looked for ~/.postgresql/root.crt and the dump failed.
+	env, err := pgEnv("postgres://llmgw:p@10.0.0.149:5432,10.0.0.150:5432/llmgw?sslmode=verify-full&sslrootcert=%2Fetc%2Fllmgw%2Fpki%2Fca.crt&target_session_attrs=read-write")
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := strings.Join(env, " ")
+	for _, want := range []string{"PGSSLMODE=verify-full", "PGSSLROOTCERT=/etc/llmgw/pki/ca.crt"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("%s is not in %s", want, got)
+		}
+	}
+}

internal/cli/bench.go

@@ -150,6 +150,7 @@ func newBenchCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
 	f.DurationVar(&cfg.SLO.TPOTp99, "tpot-p99", cfg.SLO.TPOTp99, "per-output-token target")
 	f.BoolVar(&save, "save", false,
 		"record the capacity against the model and profile, so the number outlives this terminal")
+	cmd.AddCommand(newBenchOverheadCmd(asJSON))
 	return cmd
 }
 

internal/cli/bench_overhead.go

@@ -0,0 +1,421 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log/slog"
+	"net"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"slices"
+	"sort"
+	"strings"
+	"sync"
+	"syscall"
+	"text/tabwriter"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/config"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/guard"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/router"
+	storepkg "gitea.mynodes.xyz/ilker/llmgw/internal/store"
+)
+
+// What llmgw adds to a request, measured: the same load straight at an
+// engine that answers at once, and through the gateway in front of it —
+// bare, with authentication and usage accounting, and with the guardrails'
+// pattern checks besides. The engine's own time is the same on both paths,
+// so what differs is the gateway's.
+//
+// Everything runs in this process, on loopback: no cluster, no GPU, and the
+// numbers are this machine's. On a machine shared with other work (a VM on
+// an oversubscribed host) they move with it; compare modes run together,
+// not figures from different runs.
+
+// overheadMode is one way a request reaches the engine.
+type overheadMode struct {
+	name        string
+	gateway     bool
+	auth, guard bool
+}
+
+var overheadModes = []overheadMode{
+	{name: "direct"},
+	{name: "gateway", gateway: true},
+	{name: "gateway+auth", gateway: true, auth: true},
+	{name: "gateway+auth+guard", gateway: true, auth: true, guard: true},
+}
+
+// overheadStep is one mode at one request rate.
+type overheadStep struct {
+	Mode     string        `json:"mode"`
+	Rate     int           `json:"rate"`
+	Sent     int           `json:"sent"`
+	Failed   int           `json:"failed"`
+	P50      time.Duration `json:"p50"`
+	P99      time.Duration `json:"p99"`
+	AddedP50 time.Duration `json:"added_p50"`
+	AddedP99 time.Duration `json:"added_p99"`
+	// CPUPer1k is the process's CPU time per thousand requests beyond what
+	// the direct mode spent at the same rate: the gateway's.
+	CPUPer1k time.Duration `json:"cpu_per_1k"`
+	cpu      time.Duration
+}
+
+func newBenchOverheadCmd(asJSON *bool) *cobra.Command {
+	var (
+		rates []int
+		each  time.Duration
+	)
+	cmd := &cobra.Command{
+		Use:   "overhead",
+		Short: "Measure what the gateway adds to a request, against an engine that answers at once",
+		Long: "Runs an engine that answers at once and a gateway in front of it, in this\n" +
+			"process on loopback, and sends the same load at each rate straight to the\n" +
+			"engine and through the gateway: bare, with authentication and usage\n" +
+			"accounting, and with the guardrails' pattern checks too. Reports each\n" +
+			"request's latency at p50 and p99, what the gateway added to it, and the\n" +
+			"gateway's CPU time per thousand requests.\n\n" +
+			"Needs no cluster. The figures are this machine's: on one shared with other\n" +
+			"work they move with it, so compare the modes of one run, and note the\n" +
+			"machine's load beside any figure you keep.",
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			steps, err := runOverhead(cmd.Context(), rates, each)
+			if err != nil {
+				return err
+			}
+			if *asJSON {
+				return json.NewEncoder(cmd.OutOrStdout()).Encode(steps)
+			}
+			printOverhead(cmd.OutOrStdout(), steps)
+			return nil
+		},
+	}
+	f := cmd.Flags()
+	f.IntSliceVar(&rates, "rates", []int{100, 500, 1000, 2000}, "requests a second to send, one step each")
+	f.DurationVar(&each, "each", 3*time.Second, "how long each step sends for")
+	return cmd
+}
+
+func printOverhead(w io.Writer, steps []overheadStep) {
+	tw := tabwriter.NewWriter(w, 0, 0, 2, ' ', 0)
+	fmt.Fprintln(tw, "MODE\tRATE/S\tSENT\tFAILED\tP50\tP99\t+P50\t+P99\tCPU/1K REQ")
+	for _, s := range steps {
+		added := func(d time.Duration) string {
+			if s.Mode == "direct" {
+				return "-"
+			}
+			return msOf(d)
+		}
+		cpu := "-"
+		if s.Mode != "direct" {
+			cpu = msOf(s.CPUPer1k)
+		}
+		fmt.Fprintf(tw, "%s\t%d\t%d\t%d\t%s\t%s\t%s\t%s\t%s\n", s.Mode, s.Rate, s.Sent, s.Failed,
+			msOf(s.P50), msOf(s.P99), added(s.AddedP50), added(s.AddedP99), cpu)
+	}
+	_ = tw.Flush()
+	fmt.Fprintf(w, "\n%d CPUs, %s. Loopback, in one process: the figures are this machine's.\n",
+		runtime.NumCPU(), loadAverage())
+}
+
+func msOf(d time.Duration) string { return fmt.Sprintf("%.2fms", float64(d)/float64(time.Millisecond)) }
+
+// loadAverage is the machine's, where it can be read, to keep beside the
+// figures.
+func loadAverage() string {
+	if b, err := os.ReadFile("/proc/loadavg"); err == nil {
+		if f := strings.Fields(string(b)); len(f) >= 3 {
+			return "load " + strings.Join(f[:3], " ")
+		}
+	}
+	// macOS: "{ 1.23 1.10 0.98 }".
+	if b, err := exec.Command("sysctl", "-n", "vm.loadavg").Output(); err == nil {
+		if f := strings.Fields(strings.Trim(strings.TrimSpace(string(b)), "{}")); len(f) >= 3 {
+			return "load " + strings.Join(f[:3], " ")
+		}
+	}
+	return "load not read"
+}
+
+// runOverhead measures every mode at every rate.
+func runOverhead(ctx context.Context, rates []int, each time.Duration) ([]overheadStep, error) {
+	engine, err := instantEngine()
+	if err != nil {
+		return nil, err
+	}
+	defer engine.Close()
+	dir, err := os.MkdirTemp("", "llmgw-overhead-")
+	if err != nil {
+		return nil, err
+	}
+	defer os.RemoveAll(dir)
+
+	type target struct {
+		url, key string
+		stop     func()
+	}
+	targets := map[string]target{}
+	defer func() {
+		for _, t := range targets {
+			if t.stop != nil {
+				t.stop()
+			}
+		}
+	}()
+	for _, m := range overheadModes {
+		if !m.gateway {
+			targets[m.name] = target{url: engine.URL}
+			continue
+		}
+		url, key, stop, err := overheadGateway(ctx, engine.URL, filepath.Join(dir, m.name+".db"), m)
+		if err != nil {
+			return nil, fmt.Errorf("%s: %w", m.name, err)
+		}
+		targets[m.name] = target{url: url, key: key, stop: stop}
+	}
+
+	client := &http.Client{Transport: &http.Transport{MaxIdleConns: 1024, MaxIdleConnsPerHost: 1024}, Timeout: 30 * time.Second}
+	var out []overheadStep
+	for _, rate := range rates {
+		var direct overheadStep
+		for _, m := range overheadModes {
+			t := targets[m.name]
+			s := loadStep(ctx, client, t.url, t.key, rate, each)
+			s.Mode = m.name
+			if m.name == "direct" {
+				direct = s
+			} else {
+				s.AddedP50, s.AddedP99 = max(0, s.P50-direct.P50), max(0, s.P99-direct.P99)
+				if s.Sent > 0 {
+					s.CPUPer1k = max(0, s.cpu-direct.cpu) * 1000 / time.Duration(s.Sent)
+				}
+			}
+			out = append(out, s)
+		}
+	}
+	return out, nil
+}
+
+// loadStep sends rate requests a second for d, each in its own goroutine,
+// and measures each one's latency and the process's CPU meanwhile.
+func loadStep(ctx context.Context, client *http.Client, url, key string, rate int, d time.Duration) overheadStep {
+	s := overheadStep{Rate: rate}
+	body := []byte(`{"model":"bench","max_tokens":8,"messages":[{"role":"user","content":"What is the capital of France?"}]}`)
+	var (
+		mu    sync.Mutex
+		lat   []time.Duration
+		wg    sync.WaitGroup
+		total = int(float64(rate) * d.Seconds())
+	)
+	interval := time.Second / time.Duration(max(rate, 1))
+	cpu0 := processCPU()
+	start := time.Now()
+	for i := range total {
+		if ctx.Err() != nil {
+			break
+		}
+		if wait := time.Until(start.Add(time.Duration(i) * interval)); wait > 0 {
+			time.Sleep(wait)
+		}
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			req, _ := http.NewRequestWithContext(ctx, http.MethodPost, url+"/v1/chat/completions", bytes.NewReader(body))
+			req.Header.Set("Content-Type", "application/json")
+			if key != "" {
+				req.Header.Set("Authorization", "Bearer "+key)
+			}
+			t := time.Now()
+			resp, err := client.Do(req)
+			ok := err == nil && resp.StatusCode == http.StatusOK
+			if resp != nil {
+				_, _ = io.Copy(io.Discard, resp.Body)
+				resp.Body.Close()
+			}
+			el := time.Since(t)
+			mu.Lock()
+			s.Sent++
+			if ok {
+				lat = append(lat, el)
+			} else {
+				s.Failed++
+			}
+			mu.Unlock()
+		}()
+	}
+	wg.Wait()
+	s.cpu = processCPU() - cpu0
+	s.P50, s.P99 = percentile(lat, 0.50), percentile(lat, 0.99)
+	return s
+}
+
+func percentile(ds []time.Duration, p float64) time.Duration {
+	if len(ds) == 0 {
+		return 0
+	}
+	ds = slices.Clone(ds)
+	sort.Slice(ds, func(i, j int) bool { return ds[i] < ds[j] })
+	i := int(p * float64(len(ds)-1))
+	return ds[i]
+}
+
+// processCPU is the CPU time this process has used, user and system.
+func processCPU() time.Duration {
+	var ru syscall.Rusage
+	if err := syscall.Getrusage(syscall.RUSAGE_SELF, &ru); err != nil {
+		return 0
+	}
+	return time.Duration(ru.Utime.Nano() + ru.Stime.Nano())
+}
+
+// instantEngine is an OpenAI-compatible engine that answers at once, with
+// the metrics the router scrapes.
+func instantEngine() (*httpServer, error) {
+	mux := http.NewServeMux()
+	mux.HandleFunc("GET /metrics", func(w http.ResponseWriter, _ *http.Request) {
+		fmt.Fprint(w, "# TYPE vllm:num_requests_running gauge\nvllm:num_requests_running 0\n"+
+			"# TYPE vllm:num_requests_waiting gauge\nvllm:num_requests_waiting 0\n"+
+			"# TYPE vllm:kv_cache_usage_perc gauge\nvllm:kv_cache_usage_perc 0.1\n")
+	})
+	mux.HandleFunc("GET /health", func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(http.StatusOK) })
+	mux.HandleFunc("POST /v1/chat/completions", func(w http.ResponseWriter, r *http.Request) {
+		_, _ = io.Copy(io.Discard, r.Body)
+		w.Header().Set("Content-Type", "application/json")
+		fmt.Fprint(w, `{"id":"b","object":"chat.completion","model":"bench","choices":[{"index":0,"message":{"role":"assistant","content":"Paris."},"finish_reason":"stop"}],"usage":{"prompt_tokens":14,"completion_tokens":2,"total_tokens":16}}`)
+	})
+	return serveLoopback(mux)
+}
+
+// httpServer is a handler served on a loopback port.
+type httpServer struct {
+	URL string
+	srv *http.Server
+}
+
+func (s *httpServer) Close() { _ = s.srv.Close() }
+
+func serveLoopback(h http.Handler) (*httpServer, error) {
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		return nil, err
+	}
+	srv := &http.Server{Handler: h, ReadHeaderTimeout: 10 * time.Second}
+	go func() { _ = srv.Serve(ln) }()
+	return &httpServer{URL: "http://" + ln.Addr().String(), srv: srv}, nil
+}
+
+// overheadGateway starts a gateway in front of the engine as the mode asks,
+// and returns its address and, with auth, a key.
+func overheadGateway(ctx context.Context, engineURL, storePath string, m overheadMode) (string, string, func(), error) {
+	cfg := config.Default()
+	cfg.Listen = "127.0.0.1:0"
+	cfg.Router.ScrapeInterval = 200 * time.Millisecond
+	cfg.Endpoints = []config.Endpoint{{ID: "bench", URL: engineURL, Models: []string{"bench"}}}
+	key := ""
+	if m.auth {
+		var err error
+		if key, err = overheadKey(ctx, storePath); err != nil {
+			return "", "", nil, err
+		}
+		cfg.Auth.Enabled, cfg.Auth.Store = true, storePath
+		// Limits would measure themselves refusing: off.
+		cfg.Auth.DefaultRPM, cfg.Auth.DefaultTPM = 0, 0
+	}
+	rt, err := router.New(cfg, slog.New(slog.DiscardHandler))
+	if err != nil {
+		return "", "", nil, err
+	}
+	if m.guard {
+		g, err := baselineGuard()
+		if err != nil {
+			return "", "", nil, err
+		}
+		rt.SetGuard(g)
+	}
+	rctx, cancel := context.WithCancel(ctx)
+	rt.Start(rctx)
+	srv, err := serveLoopback(rt.Handler())
+	if err != nil {
+		cancel()
+		return "", "", nil, err
+	}
+	stop := func() { srv.Close(); cancel(); rt.Stop() }
+	// Ready once a request goes through: the endpoint is scraped first.
+	deadline := time.Now().Add(10 * time.Second)
+	for {
+		body := `{"model":"bench","messages":[{"role":"user","content":"hi"}]}`
+		req, _ := http.NewRequestWithContext(ctx, http.MethodPost, srv.URL+"/v1/chat/completions", strings.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		if key != "" {
+			req.Header.Set("Authorization", "Bearer "+key)
+		}
+		resp, err := http.DefaultClient.Do(req)
+		if err == nil {
+			_, _ = io.Copy(io.Discard, resp.Body)
+			resp.Body.Close()
+			if resp.StatusCode == http.StatusOK {
+				return srv.URL, key, stop, nil
+			}
+		}
+		if time.Now().After(deadline) {
+			stop()
+			status := "no answer"
+			if err == nil {
+				status = resp.Status
+			}
+			return "", "", nil, fmt.Errorf("the gateway did not serve within 10s (%s)", status)
+		}
+		time.Sleep(100 * time.Millisecond)
+	}
+}
+
+// overheadKey makes a store with one project and a key in it.
+func overheadKey(ctx context.Context, path string) (string, error) {
+	st, err := storepkg.Open(ctx, path)
+	if err != nil {
+		return "", err
+	}
+	defer st.Close()
+	org, err := st.CreateOrg(ctx, "bench")
+	if err != nil {
+		return "", err
+	}
+	team, err := st.CreateTeam(ctx, org, "bench")
+	if err != nil {
+		return "", err
+	}
+	project, err := st.CreateProject(ctx, team, "bench")
+	if err != nil {
+		return "", err
+	}
+	secret, k, err := storepkg.NewKey("key-bench", "bench", project)
+	if err != nil {
+		return "", err
+	}
+	k.CreatedAt = time.Now()
+	return secret, st.CreateKey(ctx, k)
+}
+
+// baselineGuard is the policy init installs, without its judge: the pattern
+// checks every request passes.
+func baselineGuard() (guard.Guard, error) {
+	m, err := config.Parse([]byte(guardSection(false)))
+	if err != nil {
+		return nil, err
+	}
+	cfg, err := config.FromMap(m)
+	if err != nil {
+		return nil, err
+	}
+	return guard.NewGate(cfg.Guard, nil, slog.New(slog.DiscardHandler))
+}

internal/cli/bench_overhead_test.go

@@ -0,0 +1,33 @@
+package cli
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+	"time"
+)
+
+// The short version, so CI sees the gateway's overhead on every change: every
+// mode answers every request, and what the gateway adds is measured, not
+// guessed. No bound is asserted on it, as CI's machines vary; the table is
+// in the test's log.
+func TestTheGatewaysOverheadIsMeasured(t *testing.T) {
+	steps, err := runOverhead(t.Context(), []int{50}, time.Second)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(steps) != len(overheadModes) {
+		t.Fatalf("%d steps for %d modes", len(steps), len(overheadModes))
+	}
+	for _, s := range steps {
+		if s.Sent == 0 || s.Failed > 0 || s.P50 <= 0 || s.P99 < s.P50 {
+			t.Errorf("%s: sent %d failed %d p50 %s p99 %s", s.Mode, s.Sent, s.Failed, s.P50, s.P99)
+		}
+	}
+	var b bytes.Buffer
+	printOverhead(&b, steps)
+	if !strings.Contains(b.String(), "gateway+auth+guard") {
+		t.Errorf("table:\n%s", b.String())
+	}
+	t.Logf("\n%s", b.String())
+}

internal/cli/clustersettings.go

@@ -237,8 +237,16 @@ func (w *settingsWatch) check(ctx context.Context) {
 // again: what it reads at every use, or not at all.
 var liveSettings = []string{
 	"guard",
+	// Stopping and starting the service (llmgw stop, llmgw start).
+	"serving",
 	// Sent to the nodes and this machine's firewall unit as they change.
 	"firewall", "firewall_networks",
+	// Sent to the nodes' agents as they change.
+	"agents",
+	// Read by the leader's presets pass each time it runs.
+	"presets",
+	// Handed to the reconciler as they change.
+	"on_demand",
 	// Read by server init, node add and backups, not by the server.
 	"backup_recipients", "backup_copy_to",
 }

internal/cli/comfyuigate.go

@@ -0,0 +1,49 @@
+package cli
+
+import (
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/spf13/cobra"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/comfy"
+)
+
+// comfyKeyEnv carries the replica's key to the gate: the environment, which
+// only the engine's user and root can read, rather than the command line,
+// which every user on the node can.
+const comfyKeyEnv = "LLMGW_ENGINE_KEY"
+
+func newComfyUIGateCmd() *cobra.Command {
+	var cfg comfy.GateConfig
+	cmd := &cobra.Command{
+		Use:    "comfyui-gate [flags] [-- main.py flags]",
+		Short:  "Run ComfyUI as an engine: behind a key, on the loopback (started by the agent)",
+		Hidden: true,
+		Long: "Started by the node agent for a replica whose engine is comfyui. ComfyUI asks\n" +
+			"nobody for a key, so it listens on the loopback only and this gate on the\n" +
+			"replica's port, letting through, with the replica's key, only what the router\n" +
+			"asks of it. It also lays the fetched weights out where ComfyUI looks for them.",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			ctx, stop := signal.NotifyContext(cmd.Context(), syscall.SIGINT, syscall.SIGTERM)
+			defer stop()
+			cfg.Key = os.Getenv(comfyKeyEnv)
+			_ = os.Unsetenv(comfyKeyEnv)
+			cfg.Args = args
+			cfg.Log = logger()
+			return comfy.RunGate(ctx, cfg)
+		},
+	}
+	f := cmd.Flags()
+	f.StringVar(&cfg.Listen, "listen", "", "the replica's address")
+	f.StringVar(&cfg.Model, "model", "", "the model's name, for /v1/models")
+	f.StringVar(&cfg.Weights, "weights", "", "the fetched weights: a file or a directory")
+	f.StringVar(&cfg.State, "state", "", "the replica's own directory")
+	f.StringVar(&cfg.Python, "python", "python3", "the interpreter of ComfyUI's environment")
+	f.StringVar(&cfg.Dir, "comfyui", "", "ComfyUI's directory, where main.py is")
+	for _, n := range []string{"listen", "weights", "state", "comfyui"} {
+		_ = cmd.MarkFlagRequired(n)
+	}
+	return cmd
+}

internal/cli/ctl.go

@@ -116,6 +116,18 @@ func (c *ctlClient) do(ctx context.Context, method, path string, body, out any)
 	if out == nil {
 		return nil
 	}
+	// A stream, as it comes: NDJSON a long run writes line by line.
+	if w, ok := out.(io.Writer); ok {
+		_, err := io.Copy(w, resp.Body)
+		return err
+	}
+	// An older control plane answers a path it does not know with its
+	// dashboard: a page, which read as JSON said only "invalid character '<'".
+	if strings.HasPrefix(resp.Header.Get("Content-Type"), "text/html") {
+		return fmt.Errorf("%s %s answered with a page, not the API: the control plane answering "+
+			"(the leader, through a standby) does not know it — is it on an older release? "+
+			"llmgw ctl status says which it runs", method, path)
+	}
 	return json.NewDecoder(resp.Body).Decode(out)
 }
 
@@ -166,13 +178,17 @@ func newCtlCmd() *cobra.Command {
 		newRetryCmd(client),
 		newUpgradeCmd(client),
 		newJobsCmd(client, &asJSON),
+		newMeshJobsCmd(client, &asJSON),
 		newEngineCheckCmd(),
 		newEngineBuildCmd(client),
-		newToolCheckCmd(),
+		newToolCheckCmd(client),
 		newWeightsCmd(client, &asJSON),
 		newCapacityCmd(client, &asJSON),
 		newQuotaCmd(client, &asJSON),
 		newGuardCmd(client, &asJSON),
+		newMCPCmd(client, &asJSON),
+		newKBCmd(client, &asJSON),
+		newTrainCmd(client, &asJSON),
 		newConfigCmd(client, &asJSON),
 		newAuditCmd(client, &asJSON),
 		newNotifyCmd(client, &asJSON),
@@ -225,8 +241,8 @@ func newNodesCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
 					// What the node can run, which is the first thing to look
 					// at when a model will not place and the hardware looks
 					// fine.
-					join(n.Engines),
-					classesColumn(n), join(n.Fabrics), n.Replicas, n.LastSeenAgo)
+					enginesColumn(n),
+					classesColumn(n), fabricsColumn(n), n.Replicas, n.LastSeenAgo)
 			}
 			_ = w.Flush()
 
@@ -317,6 +333,9 @@ func modelStatus(m adminapi.ModelView) string {
 		return "stopped"
 	case m.Ready >= m.Min && m.Min > 0:
 		return "ready"
+	case m.Min == 0 && m.Ready > 0 && m.Ready >= m.Total:
+		// Asked for, and up until it goes unused for long enough.
+		return "ready (on demand)"
 	case m.Total > m.Ready:
 		return "starting"
 	default:
@@ -443,7 +462,7 @@ func newReplicasCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
 			}
 
 			w := tab()
-			fmt.Fprintln(w, "REPLICA\tMODEL\tSTATE\tPOOL\tNODES\tAGE\tIDLE\tENDPOINT")
+			fmt.Fprintln(w, "REPLICA\tMODEL\tSTATE\tPOOL\tON\tNODES\tAGE\tIDLE\tENDPOINT")
 			for _, r := range reps {
 				var nodes []string
 				for _, s := range r.Shards {
@@ -461,8 +480,14 @@ func newReplicasCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
 				if r.Restart != "" {
 					state += " (restart " + r.Restart + ")"
 				}
-				fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n",
-					r.ID, r.Model, state, r.Pool, join(nodes),
+				// What the engine computes on, by its own account: the first
+				// shard's, which serves.
+				on := "-"
+				if len(r.Shards) > 0 {
+					on = r.Shards[0].Compute.Short()
+				}
+				fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n",
+					r.ID, r.Model, state, r.Pool, on, join(nodes),
 					(time.Duration(r.AgeSec) * time.Second).String(),
 					idleColumn(r.IdleSec), r.Endpoint)
 				// A line rather than a column, because most replicas are not
@@ -472,7 +497,7 @@ func newReplicasCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
 					if s.Fetch == nil {
 						continue
 					}
-					fmt.Fprintf(w, "  %s: fetching %s\t\t\t\t\t\t\t\n",
+					fmt.Fprintf(w, "  %s: fetching %s\t\t\t\t\t\t\t\t\n",
 						s.Node, fetchColumn(s.Fetch))
 				}
 			}
@@ -583,7 +608,42 @@ func emitJSON(v any) error {
 // more than one or MIG instances among them: a card cut into two 3g.40gb
 // instances beside a whole card is "a100-80g-mig-3g.40gb×2,a100-80g×1", where
 // the GPUS column's 3 alone would read as three of something.
+// fabricsColumn is the node's fabrics, and when they are not all up, which
+// adapters are down: what keeps it out of replicas spanning nodes.
+func fabricsColumn(n adminapi.NodeView) string {
+	s := join(n.Fabrics)
+	if n.MultiNode != "" && n.MultiNode != "ready" {
+		s += " (" + n.MultiNode + ")"
+	}
+	return s
+}
+
+// enginesColumn is each engine with its version: llamacpp b10991.
+func enginesColumn(n adminapi.NodeView) string {
+	if len(n.EngineVersions) == 0 {
+		return join(n.Engines)
+	}
+	parts := make([]string, 0, len(n.Engines))
+	for _, e := range n.Engines {
+		if v := n.EngineVersions[e]; v != "" && v != "unknown" {
+			e += " " + v
+		}
+		parts = append(parts, e)
+	}
+	return strings.Join(parts, ",")
+}
+
+// classesColumn is the node's GPU classes, with their compute capability
+// when they report one: 6000-24g (7.5).
 func classesColumn(n adminapi.NodeView) string {
+	s := classesOnly(n)
+	if len(n.ComputeCapabilities) > 0 && s != "-" {
+		s += " (" + strings.Join(n.ComputeCapabilities, ",") + ")"
+	}
+	return s
+}
+
+func classesOnly(n adminapi.NodeView) string {
 	counted := len(n.ClassGPUs) > 1
 	for _, c := range n.ClassGPUs {
 		counted = counted || c.MIG

internal/cli/ctl_3d.go

@@ -0,0 +1,130 @@
+package cli
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/url"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+)
+
+// newMeshJobsCmd is the 3D models clients asked for, as jobs: every owner's,
+// what each is doing, and a way to stop one. (ctl jobs is the control
+// plane's own work, serving and updating models.)
+func newMeshJobsCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "3d",
+		Short: "3D models clients asked for: the jobs, how far along each is, and stopping one",
+	}
+	var status string
+	var limit int
+	list := &cobra.Command{
+		Use:   "list",
+		Short: "Every owner's 3D jobs, newest first",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			q := url.Values{}
+			if status != "" {
+				q.Set("status", status)
+			}
+			if limit > 0 {
+				q.Set("limit", fmt.Sprint(limit))
+			}
+			var jobs []adminapi.JobView
+			if err := client().get(cmd.Context(), "/api/v1/client-jobs?"+q.Encode(), &jobs); err != nil {
+				return err
+			}
+			if *asJSON {
+				return emitJSON(jobs)
+			}
+			if len(jobs) == 0 {
+				fmt.Fprintln(cmd.OutOrStdout(), "no 3D jobs")
+				return nil
+			}
+			w := tabTo(cmd.OutOrStdout())
+			fmt.Fprintln(w, "JOB\tMODEL\tSTATUS\tPROGRESS\tOWNER\tASKED")
+			for _, j := range jobs {
+				fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\t%s ago\n", j.ID, j.Model, j.Status, progressText(j),
+					j.Owner, time.Since(j.CreatedAt).Round(time.Second))
+			}
+			return w.Flush()
+		},
+	}
+	list.Flags().StringVar(&status, "status", "", "only jobs in this status: queued, running, completed, failed…")
+	list.Flags().IntVar(&limit, "limit", 0, "the most jobs to show (50)")
+	get := &cobra.Command{
+		Use:   "get JOB",
+		Short: "One 3D job: its status, progress, result or error",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			var j adminapi.JobView
+			if err := client().get(cmd.Context(), "/api/v1/client-jobs/"+url.PathEscape(args[0]), &j); err != nil {
+				return err
+			}
+			if *asJSON {
+				return emitJSON(j)
+			}
+			out := cmd.OutOrStdout()
+			fmt.Fprintf(out, "job       %s\nmodel     %s\nstatus    %s\n", j.ID, j.Model, j.Status)
+			if p := progressText(j); p != "" {
+				fmt.Fprintf(out, "progress  %s\n", p)
+			}
+			fmt.Fprintf(out, "owner     %s (key %s)\nasked     %s\n", j.Owner, j.KeyID, j.CreatedAt.UTC().Format(time.RFC3339))
+			if j.FinishedAt != nil && j.StartedAt != nil {
+				fmt.Fprintf(out, "took      %s\n", j.FinishedAt.Sub(*j.StartedAt).Round(time.Second))
+			}
+			if j.OutputFileID != "" {
+				fmt.Fprintf(out, "result    %s (%s)\n", j.OutputFileID, j.ContentType)
+			}
+			if j.Error != "" {
+				fmt.Fprintf(out, "error     %s\n", j.Error)
+			}
+			return nil
+		},
+	}
+	cancel := &cobra.Command{
+		Use:   "cancel JOB",
+		Short: "Stop a 3D job, in the engine's queue too",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			var j adminapi.JobView
+			if err := client().post(cmd.Context(), "/api/v1/client-jobs/"+url.PathEscape(args[0])+"/cancel", nil, &j); err != nil {
+				return err
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "%s is %s\n", j.ID, j.Status)
+			return nil
+		},
+	}
+	cmd.AddCommand(list, get, cancel)
+	return cmd
+}
+
+// progressText is a job's progress as a person reads it.
+func progressText(j adminapi.JobView) string {
+	if len(j.Progress) == 0 {
+		return ""
+	}
+	var p struct {
+		State     string `json:"state"`
+		Ahead     int    `json:"ahead"`
+		NodeClass string `json:"node_class"`
+		Step      int    `json:"step"`
+		Steps     int    `json:"steps"`
+		Percent   int    `json:"percent"`
+	}
+	if json.Unmarshal(j.Progress, &p) != nil {
+		return ""
+	}
+	switch {
+	case p.State == "queued" && p.Ahead > 0:
+		return fmt.Sprintf("queued, %d ahead", p.Ahead)
+	case p.State == "running" && p.Steps > 0:
+		return fmt.Sprintf("running %d%%, %s step %d/%d", p.Percent, p.NodeClass, p.Step, p.Steps)
+	case p.State == "running" && p.NodeClass != "":
+		return "running " + p.NodeClass
+	}
+	return p.State
+}

internal/cli/ctl_config_test.go

@@ -0,0 +1,22 @@
+package cli
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestAPageInsteadOfTheAPIIsSaidPlainly(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		_, _ = w.Write([]byte("<!doctype html><title>llmgw</title>"))
+	}))
+	defer srv.Close()
+	c := newCtlClient(strings.TrimPrefix(srv.URL, "http://"), "")
+	var out map[string]any
+	err := c.get(t.Context(), "/api/v1/settings", &out)
+	if err == nil || !strings.Contains(err.Error(), "older release") || strings.Contains(err.Error(), "invalid character") {
+		t.Errorf("%v", err)
+	}
+}

internal/cli/ctl_mcp.go

@@ -0,0 +1,201 @@
+package cli
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+)
+
+func newMCPCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
+	c := &cobra.Command{
+		Use:   "mcp",
+		Short: "The company's own MCP servers, served through llmgw's /mcp",
+		Long: "An MCP server registered here — Jira, a file server, a database — is served\n" +
+			"through llmgw's /mcp beside llmgw's own tools, its tools named SERVER.tool.\n" +
+			"Its credentials stay on the control planes: a client gives only its llmgw\n" +
+			"key. A key sees and calls only the tools granted it, as patterns, with\n" +
+			"`llmgw keys limits --tools 'jira.*'` at any level of the tenancy tree;\n" +
+			"none granted anywhere is none. Every call is in `llmgw ctl audit`.",
+	}
+	c.AddCommand(newMCPAddCmd(client, asJSON), newMCPListCmd(client, asJSON), newMCPRemoveCmd(client),
+		newMCPTestCmd(client, asJSON))
+	return c
+}
+
+func newMCPAddCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
+	var req adminapi.MCPServerRequest
+	var headers, refs, secretFiles []string
+	var bearerFile string
+	var disabled bool
+	c := &cobra.Command{
+		Use:   "add NAME --url URL",
+		Short: "Register an MCP server, or change one",
+		Example: "  llmgw ctl mcp add jira --url https://jira.internal/mcp --bearer-file /root/jira-token\n" +
+			"  llmgw ctl mcp add llmgw --url llmgw:admin --description \"this cluster, read only\"\n" +
+			"  llmgw ctl mcp add wiki --url https://wiki.internal/mcp --header-ref Authorization=vault:secret/mcp/wiki#token\n" +
+			"  llmgw ctl mcp add jira --disabled      # off, kept",
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			var err error
+			if req.Headers, err = pairs(headers, "--header"); err != nil {
+				return err
+			}
+			if req.HeaderRefs, err = pairs(refs, "--header-ref"); err != nil {
+				return err
+			}
+			files, err := pairs(secretFiles, "--secret-file")
+			if err != nil {
+				return err
+			}
+			// A secret read here and kept in the store, sealed: the file
+			// need not be on every control plane, and is not read again.
+			for header, file := range files {
+				b, err := os.ReadFile(file) //nolint:gosec // a file the operator names
+				if err != nil {
+					return err
+				}
+				if req.Secrets == nil {
+					req.Secrets = map[string]string{}
+				}
+				req.Secrets[header] = strings.TrimSpace(string(b))
+			}
+			if bearerFile != "" {
+				b, err := os.ReadFile(bearerFile) //nolint:gosec // a file the operator names
+				if err != nil {
+					return err
+				}
+				if req.Secrets == nil {
+					req.Secrets = map[string]string{}
+				}
+				req.Secrets["Authorization"] = "Bearer " + strings.TrimSpace(string(b))
+			}
+			if cmd.Flags().Changed("disabled") {
+				on := !disabled
+				req.Enabled = &on
+			}
+			body, _ := json.Marshal(req)
+			var v adminapi.MCPServerView
+			if err := client().put(cmd.Context(), "/api/v1/mcp/servers/"+args[0], body, &v); err != nil {
+				return err
+			}
+			if *asJSON {
+				return json.NewEncoder(cmd.OutOrStdout()).Encode(v)
+			}
+			state := "on"
+			if !v.Enabled {
+				state = "off"
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "%s: %s, %s. Its tools are %s.TOOL in /mcp, to keys granted them "+
+				"(llmgw keys limits --tools '%s.*'). Check it: llmgw ctl mcp test %s\n", v.Name, v.URL, state, v.Name, v.Name, v.Name)
+			return nil
+		},
+	}
+	f := c.Flags()
+	f.StringVar(&req.URL, "url", "", "the server's streamable HTTP address, https://…/mcp; llmgw:admin for this cluster, read only")
+	f.StringVar(&req.Description, "description", "", "what it is, shown beside its tools")
+	f.StringArrayVar(&headers, "header", nil, "NAME=VALUE sent as written, for what is not secret; repeatable")
+	f.StringArrayVar(&refs, "header-ref", nil, "NAME=REF read at each call: a file on every control plane, env:, vault: or store:; repeatable")
+	f.StringArrayVar(&secretFiles, "secret-file", nil, "NAME=FILE read now and kept in the store, sealed: a token; repeatable")
+	f.StringVar(&bearerFile, "bearer-file", "", "a token FILE, read now and kept sealed, sent as Authorization: Bearer")
+	f.BoolVar(&disabled, "disabled", false, "keep it but serve none of its tools")
+	f.IntVar(&req.TimeoutSeconds, "timeout", 0, "seconds one call may take (default 60)")
+	f.IntVar(&req.RatePerMinute, "rate", 0, "calls a minute each caller may make to its tools (default: no bound; -1 takes one away)")
+	return c
+}
+
+func newMCPListCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
+	return &cobra.Command{
+		Use:   "list",
+		Short: "The MCP servers /mcp serves",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			var list []adminapi.MCPServerView
+			if err := client().get(cmd.Context(), "/api/v1/mcp/servers", &list); err != nil {
+				return err
+			}
+			if *asJSON {
+				return json.NewEncoder(cmd.OutOrStdout()).Encode(list)
+			}
+			if len(list) == 0 {
+				fmt.Fprintln(cmd.OutOrStdout(), "no MCP servers; add one: llmgw ctl mcp add NAME --url URL")
+				return nil
+			}
+			w := tabTo(cmd.OutOrStdout())
+			fmt.Fprintln(w, "NAME\tSTATE\tURL\tCREDENTIALS\tDESCRIPTION")
+			for _, s := range list {
+				state := "on"
+				if !s.Enabled {
+					state = "off"
+				}
+				var creds []string
+				for h := range s.HeaderRefs {
+					creds = append(creds, h)
+				}
+				fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\n", s.Name, state, s.URL, dash(strings.Join(creds, ",")), s.Description)
+			}
+			return w.Flush()
+		},
+	}
+}
+
+func newMCPRemoveCmd(client func() *ctlClient) *cobra.Command {
+	return &cobra.Command{
+		Use:   "remove NAME",
+		Short: "Remove an MCP server: its tools leave /mcp",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if err := client().delete(cmd.Context(), "/api/v1/mcp/servers/"+args[0], nil); err != nil {
+				return err
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "%s removed; its tools leave /mcp within half a minute\n", args[0])
+			return nil
+		},
+	}
+}
+
+func newMCPTestCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
+	return &cobra.Command{
+		Use:   "test NAME",
+		Short: "Ask an MCP server for its tools, with its credentials, as /mcp would",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			var v adminapi.MCPTestView
+			if err := client().post(cmd.Context(), "/api/v1/mcp/servers/"+args[0]+"/test", nil, &v); err != nil {
+				return err
+			}
+			if *asJSON {
+				return json.NewEncoder(cmd.OutOrStdout()).Encode(v)
+			}
+			if !v.OK {
+				return errors.New(args[0] + " did not answer: " + v.Error)
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "%s answers with %d tool(s):\n", args[0], len(v.Tools))
+			for _, t := range v.Tools {
+				fmt.Fprintln(cmd.OutOrStdout(), "  "+t)
+			}
+			return nil
+		},
+	}
+}
+
+// pairs reads NAME=VALUE flags.
+func pairs(list []string, flag string) (map[string]string, error) {
+	if len(list) == 0 {
+		return nil, nil
+	}
+	out := map[string]string{}
+	for _, p := range list {
+		k, v, ok := strings.Cut(p, "=")
+		if !ok || strings.TrimSpace(k) == "" {
+			return nil, fmt.Errorf("%s %q is not NAME=VALUE", flag, p)
+		}
+		out[strings.TrimSpace(k)] = v
+	}
+	return out, nil
+}

internal/cli/ctl_request.go

@@ -56,6 +56,12 @@ func newRequestCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
 			fmt.Fprintf(out, "status    %d\n", v.Status)
 			fmt.Fprintf(out, "time      %d ms total: %d queued, %d to the first token\n", v.LatencyMs, v.QueueMs, v.TTFTMs)
 			fmt.Fprintf(out, "tokens    %d in, %d out\n", v.PromptTokens, v.CompletionTokens)
+			if v.Images > 0 {
+				fmt.Fprintf(out, "images    %d\n", v.Images)
+			}
+			if v.Meshes > 0 {
+				fmt.Fprintf(out, "meshes    %d\n", v.Meshes)
+			}
 			if v.CacheHit {
 				fmt.Fprintf(out, "cache     answered from the project's answer cache: nothing generated, nothing charged\n")
 			}
@@ -76,8 +82,11 @@ func newRequestCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
 				fmt.Fprintf(out, "tags      %s\n", strings.Join(kv, ", "))
 			}
 			if v.GuardAction != "" {
-				fmt.Fprintf(out, "guard     %s by policy %s (%s), %d ms\n", v.GuardAction, v.GuardPolicy,
-					or(v.GuardCategory, "-"), v.GuardMs)
+				what := or(v.GuardCategory, "-")
+				if v.GuardRule != "" {
+					what += ": " + v.GuardRule
+				}
+				fmt.Fprintf(out, "guard     %s by policy %s (%s), %d ms\n", v.GuardAction, v.GuardPolicy, what, v.GuardMs)
 			} else if v.GuardMs > 0 {
 				fmt.Fprintf(out, "guard     allowed, %d ms\n", v.GuardMs)
 			}

internal/cli/ctl_restart.go

@@ -12,9 +12,10 @@ import (
 
 func newRestartCmd(client func() *ctlClient) *cobra.Command {
 	var (
-		models  []string
-		all     bool
-		inPlace bool
+		models             []string
+		all                bool
+		inPlace            bool
+		surge, unavailable int
 	)
 	c := &cobra.Command{
 		Use:   "restart [REPLICA...]",
@@ -31,6 +32,10 @@ func newRestartCmd(client func() *ctlClient) *cobra.Command {
 			"profile edited to need more than any node has — the restart is given up\n" +
 			"and the old replica keeps serving: llmgw ctl replicas says so, and why.\n\n" +
 			"--in-place stops each replica first, whatever room there is.\n\n" +
+			"A model's replicas are replaced one at a time. --max-surge N replaces N at\n" +
+			"once, each beside itself, needing room for N more; --max-unavailable N\n" +
+			"stops N at once first, needing no room and leaving N fewer serving while\n" +
+			"they load. Together, the first N are stopped first and the rest surged.\n\n" +
 			"  llmgw ctl restart qwen2.5-7b-3f2a91c0\n" +
 			"  llmgw ctl restart --model qwen2.5-7b\n" +
 			"  llmgw ctl restart --all",
@@ -38,7 +43,8 @@ func newRestartCmd(client func() *ctlClient) *cobra.Command {
 			if len(args) == 0 && len(models) == 0 && !all {
 				return errors.New("name replicas, --model, or --all")
 			}
-			body, _ := json.Marshal(adminapi.RestartRequest{Replicas: args, Models: models, All: all, InPlace: inPlace})
+			body, _ := json.Marshal(adminapi.RestartRequest{Replicas: args, Models: models, All: all, InPlace: inPlace,
+				MaxSurge: surge, MaxUnavailable: unavailable})
 			var res adminapi.RestartResult
 			if err := client().post(cmd.Context(), "/api/v1/restart", body, &res); err != nil {
 				return err
@@ -50,6 +56,9 @@ func newRestartCmd(client func() *ctlClient) *cobra.Command {
 	c.Flags().StringArrayVar(&models, "model", nil, "every replica of this model; repeatable")
 	c.Flags().BoolVar(&all, "all", false, "every ready replica in the cluster")
 	c.Flags().BoolVar(&inPlace, "in-place", false, "stop each replica before starting its replacement")
+	c.Flags().IntVar(&surge, "max-surge", 0, "replicas of a model replaced beside themselves at once (default 1)")
+	c.Flags().IntVar(&unavailable, "max-unavailable", 0,
+		"replicas of a model stopped first at once, each out while its replacement loads")
 	return c
 }
 

internal/cli/ctl_upgrade.go

@@ -268,6 +268,26 @@ func upgradeNodes(ctx context.Context, out io.Writer, client func() *ctlClient,
 	}
 	fmt.Fprintf(out, "%d node(s) upgraded to %s in %s, %d already on it\n",
 		done, v, time.Since(start).Round(time.Second), skipped)
+	// Checked at the end, against what the control plane says now: a node
+	// that is not on the version is said by name, and the command fails. A
+	// site's nodes stayed a release behind with nothing printed to say so.
+	if len(nodes) == 0 {
+		fmt.Fprintln(out, "This control plane has no nodes registered, so none were upgraded.")
+	}
+	var now []adminapi.NodeView
+	if err := client().get(ctx, "/api/v1/nodes", &now); err == nil {
+		var behind []string
+		for _, n := range now {
+			if (len(only) == 0 || slices.Contains(only, n.ID)) && n.AgentVersion != v {
+				behind = append(behind, fmt.Sprintf("%s (%s, %s)", n.ID, orUnknown(n.AgentVersion), n.State))
+			}
+		}
+		if len(behind) > 0 {
+			slices.Sort(behind)
+			return fmt.Errorf("not on %s: %s\nrun this again to try them, or `llmgw ctl logs NODE` for why",
+				v, strings.Join(behind, ", "))
+		}
+	}
 	// The one machine this does not reach. Said every time, because it is
 	// exactly the kind of thing that stays three versions behind unnoticed.
 	fmt.Fprintf(out, "The model mirror's host is not upgraded by this; on it, run:\n"+

internal/cli/ctl_upgrade_test.go

@@ -150,3 +150,54 @@ func TestABinaryInstalledByHandIsNotAServerRunningIt(t *testing.T) {
 		}
 	}
 }
+
+func TestAnUpgradeThatFindsNoNodesSaysSo(t *testing.T) {
+	// A site's nodes stayed a release behind with nothing printed to say
+	// that none had been reached.
+	f := &fakeFleet{versions: map[string]string{}}
+	srv := f.server(t)
+	var out bytes.Buffer
+	if err := upgradeNodes(t.Context(), &out, func() *ctlClient { return newCtlClient(srv.URL) }, "v1.0.1", nil, time.Second, 1); err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(out.String(), "no nodes registered") {
+		t.Errorf("output:\n%s", out.String())
+	}
+}
+
+func TestAnUpgradeFailsNamingANodeLeftBehind(t *testing.T) {
+	// A node that joins, or comes back on its old binary, while the waves
+	// run is found at the end rather than passed over.
+	f := &fakeFleet{versions: map[string]string{"a": "v1.0.0"}}
+	srv := f.server(t)
+	late := func() *ctlClient {
+		f.mu.Lock()
+		if len(f.told) == 1 {
+			f.versions["late"] = "v1.0.0"
+		}
+		f.mu.Unlock()
+		return newCtlClient(srv.URL)
+	}
+	var out bytes.Buffer
+	err := upgradeNodes(t.Context(), &out, late, "v1.0.1", nil, 5*time.Second, 1)
+	if err == nil || !strings.Contains(err.Error(), "late (v1.0.0, ready)") {
+		t.Errorf("err %v", err)
+	}
+}
+
+func TestUpgradingAControlPlaneAloneSaysItsNodesWereNot(t *testing.T) {
+	f := &fakeFleet{versions: map[string]string{"p-g1": "v1.0.0", "p-g3": "v1.0.1"}}
+	srv := f.server(t)
+	var out bytes.Buffer
+	nodesLeftBehind(t.Context(), &out, newCtlClient(srv.URL), "v1.0.1")
+	if !strings.Contains(out.String(), "1 of 2 node(s) are not on v1.0.1") ||
+		!strings.Contains(out.String(), "ctl upgrade v1.0.1 --skip-control-plane") {
+		t.Errorf("output:\n%s", out.String())
+	}
+	out.Reset()
+	f.versions["p-g1"] = "v1.0.1"
+	nodesLeftBehind(t.Context(), &out, newCtlClient(srv.URL), "v1.0.1")
+	if out.Len() != 0 {
+		t.Errorf("said something with every node on the version: %s", out.String())
+	}
+}

internal/cli/doctor.go

@@ -63,9 +63,10 @@ that file when the report is not enough to go on.`,
 				enc := json.NewEncoder(os.Stdout)
 				enc.SetIndent("", "  ")
 				return enc.Encode(struct {
-					Findings []doctor.Finding `json:"findings"`
-					Facts    doctor.Facts     `json:"facts"`
-				}{findings, facts})
+					Findings  []doctor.Finding `json:"findings"`
+					Readiness doctor.Readiness `json:"readiness"`
+					Facts     doctor.Facts     `json:"facts"`
+				}{findings, doctor.ReadinessOf(findings), facts})
 			}
 			printDoctor(os.Stdout, facts, findings, verbose)
 			for _, f := range findings {
@@ -101,12 +102,26 @@ func printDoctor(out io.Writer, f doctor.Facts, findings []doctor.Finding, verbo
 	fmt.Fprintf(out, "%s · %s %s %s · driver %s\n\n", f.Hostname, f.Host.OSID, f.Host.OSVersion,
 		f.Host.Arch, orDash(f.Host.NVIDIADriver))
 
-	for _, x := range findings {
-		fmt.Fprintf(out, "%-4s  %-6s  %s\n", x.Level, x.Area, x.Message)
-		if x.Fix != "" && (x.Level == doctor.Fail || x.Level == doctor.Warn) {
-			fmt.Fprintf(out, "              → %s\n", x.Fix)
+	// The node first; then what replicas spanning nodes would need, which
+	// keeps a node out only when a fabric was declared for it.
+	multi := false
+	for _, pass := range []bool{false, true} {
+		for _, x := range findings {
+			if x.MultiNode() != pass {
+				continue
+			}
+			if pass && !multi {
+				fmt.Fprintln(out, "\nMulti-node (fabrics, RDMA) — for replicas spanning nodes only:")
+				multi = true
+			}
+			fmt.Fprintf(out, "%-4s  %-6s  %s\n", x.Level, x.Area, x.Message)
+			if x.Fix != "" && (x.Level == doctor.Fail || x.Level == doctor.Warn) {
+				fmt.Fprintf(out, "              → %s\n", x.Fix)
+			}
 		}
 	}
+	r := doctor.ReadinessOf(findings)
+	fmt.Fprintf(out, "\nThis node:  %s\nMulti-node: %s\n", r.Node, r.MultiNode)
 
 	w := tabwriter.NewWriter(out, 0, 0, 2, ' ', 0)
 	if len(f.GPUs) > 0 {

internal/cli/enginecheck.go

@@ -4,10 +4,15 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"net"
+	"net/http"
+	"os"
 	"os/exec"
 	"path/filepath"
 	"sort"
+	"strconv"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/spf13/cobra"
@@ -22,6 +27,7 @@ func newEngineCheckCmd() *cobra.Command {
 		nodes   int
 		tp      int
 		perNode int
+		model   string
 	)
 
 	cmd := &cobra.Command{
@@ -31,6 +37,10 @@ func newEngineCheckCmd() *cobra.Command {
 			"engines rename and remove flags between versions. When that happens the\n" +
 			"failure arrives minutes into a model load, in an engine's own error\n" +
 			"message, on a node nobody was watching.\n\n" +
+			"For llama.cpp on a machine with NVIDIA GPUs it then loads a small GGUF\n" +
+			"(--model, or the smallest in the weights cache) with every layer on the GPU\n" +
+			"and asks for one token: a build whose CUDA backend does not load computes on\n" +
+			"the CPU, and that is where it is caught.\n\n" +
 			"This asks the engine itself. It runs the engine's --help and checks every\n" +
 			"flag llmgw would pass against it, which needs no GPU — a CLI prints its\n" +
 			"help on any machine. Run it after upgrading an engine.\n\n" +
@@ -49,6 +59,11 @@ func newEngineCheckCmd() *cobra.Command {
 			// rarely on PATH: a check that cannot find the engine reports
 			// nothing rather than reporting a problem.
 			cfg := engines.Config{}
+			// The build the agent installed, when none is named: the newest
+			// under /opt/llmgw/engines, which is where every node keeps it.
+			if bin == "" && name == "llamacpp" {
+				bin = installedLlama()
+			}
 			if bin != "" {
 				switch name {
 				case "llamacpp":
@@ -135,6 +150,11 @@ func newEngineCheckCmd() *cobra.Command {
 			var deviceErr error
 			if fb, ok := eng.(engines.CPUFallback); ok && help == "" {
 				deviceErr = checkDevices(cmd.Context(), name, fb, out)
+				// Seeing a GPU is not computing on it: a small model loaded
+				// on it and asked for a token is.
+				if b, ok := eng.(interface{ Binary() string }); ok && deviceErr == nil && model != "none" {
+					deviceErr = computeOnGPU(cmd.Context(), b.Binary(), model, out)
+				}
 			}
 
 			fmt.Fprintf(out, "%s: %d flags checked", name, checked)
@@ -160,7 +180,9 @@ func newEngineCheckCmd() *cobra.Command {
 
 	f := cmd.Flags()
 	f.StringVar(&help, "help-output", "", "a saved --help to check against, instead of running the engine")
-	f.StringVar(&bin, "bin", "", "where the engine lives, when it is not on PATH")
+	f.StringVar(&bin, "bin", "", "where the engine lives (default: the build the agent installed, else PATH)")
+	f.StringVar(&model, "model", "", "a GGUF file to load on the GPU and ask for a token (default: the smallest "+
+		"in this node's weights cache; none skips it)")
 	f.IntVar(&nodes, "nodes", 2, "shape the command for a replica of this many nodes")
 	f.IntVar(&tp, "tp", 8, "tensor parallel degree")
 	f.IntVar(&perNode, "gpus-per-node", 4, "GPUs each node contributes")
@@ -286,3 +308,146 @@ func checkDevices(ctx context.Context, name string, fb engines.CPUFallback, out
 	fmt.Fprintf(out, "computes on: %s\n", strings.Join(devs, "; "))
 	return nil
 }
+
+// llamaRoot is where the agent installs llama.cpp builds.
+var llamaRoot = "/opt/llmgw/engines/llamacpp"
+
+// installedLlama is the llama-server the agent installed here: under
+// llamaRoot/<version-variant>/llama-<build>/, or one level up for older
+// layouts; on a machine with NVIDIA GPUs a CUDA build first, then the newest.
+func installedLlama() string {
+	var found []string
+	for _, pat := range []string{"*/llama-server", "*/*/llama-server"} {
+		m, _ := filepath.Glob(filepath.Join(llamaRoot, pat))
+		found = append(found, m...)
+	}
+	if len(found) == 0 {
+		return ""
+	}
+	sort.Strings(found)
+	if _, err := exec.LookPath("nvidia-smi"); err == nil {
+		for i := len(found) - 1; i >= 0; i-- {
+			if strings.Contains(found[i], "cuda") {
+				return found[i]
+			}
+		}
+	}
+	return found[len(found)-1]
+}
+
+// weightDirs are where a node keeps models it has fetched.
+var weightDirs = []string{"/var/lib/llmgw-weights", "/var/lib/llmgw-models", "/srv/models"}
+
+// smallestGGUF is the smallest GGUF file under dirs, for a check that only
+// needs something to load.
+func smallestGGUF(dirs []string) string {
+	best, size := "", int64(0)
+	for _, d := range dirs {
+		_ = filepath.WalkDir(d, func(p string, e os.DirEntry, err error) error {
+			if err != nil || e.IsDir() || !strings.HasSuffix(strings.ToLower(p), ".gguf") ||
+				strings.Contains(strings.ToLower(filepath.Base(p)), "mmproj") {
+				return nil
+			}
+			if info, err := e.Info(); err == nil && (best == "" || info.Size() < size) {
+				best, size = p, info.Size()
+			}
+			return nil
+		})
+	}
+	return best
+}
+
+// computeOnGPU loads a model with every layer on the GPU, asks for one
+// token, and reads from llama.cpp's own output where the layers went.
+func computeOnGPU(ctx context.Context, bin, model string, out io.Writer) error {
+	if _, err := exec.LookPath("nvidia-smi"); err != nil {
+		return nil
+	}
+	if model == "" {
+		if model = smallestGGUF(weightDirs); model == "" {
+			fmt.Fprintln(out, "no GGUF in this node's weights cache to compute with; --model PATH runs one")
+			return nil
+		}
+	}
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		return err
+	}
+	port := ln.Addr().(*net.TCPAddr).Port
+	_ = ln.Close()
+	ctx, cancel := context.WithTimeout(ctx, 3*time.Minute)
+	defer cancel()
+	var logs syncBuffer
+	c := exec.CommandContext(ctx, bin, "-m", model, "--host", "127.0.0.1", "--port", strconv.Itoa(port), //nolint:gosec // the engine's own binary
+		"--n-gpu-layers", "999", "--ctx-size", "512", "--parallel", "1",
+		// Where the layers went is said only at this verbosity.
+		"-lv", "4")
+	c.Stdout, c.Stderr = &logs, &logs
+	if err := c.Start(); err != nil {
+		return fmt.Errorf("starting %s: %w", bin, err)
+	}
+	defer func() { _ = c.Process.Kill(); _ = c.Wait() }()
+	base := "http://127.0.0.1:" + strconv.Itoa(port)
+	start := time.Now()
+	for {
+		resp, err := http.Get(base + "/health") //nolint:gosec,noctx // loopback, bounded by the loop
+		if err == nil {
+			_ = resp.Body.Close()
+			if resp.StatusCode == http.StatusOK {
+				break
+			}
+		}
+		if ctx.Err() != nil {
+			return fmt.Errorf("%s did not come up with %s: %s", bin, filepath.Base(model), tailLines(logs.String(), 5))
+		}
+		time.Sleep(500 * time.Millisecond)
+	}
+	req, _ := http.NewRequestWithContext(ctx, http.MethodPost, base+"/completion",
+		strings.NewReader(`{"prompt":"Hello","n_predict":1}`))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("asking it for a token: %w", err)
+	}
+	_ = resp.Body.Close()
+	took := time.Since(start)
+	comp, said := engines.ReadLlamaCompute(strings.Split(logs.String(), "\n"))
+	if !said {
+		fmt.Fprintf(out, "computed a token with %s, but llama.cpp did not say where\n", filepath.Base(model))
+		return nil
+	}
+	if comp.OnTheCPU() {
+		return fmt.Errorf("%s computed on the CPU though every layer was asked for on the GPU (%d of %d offloaded): "+
+			"its CUDA backend did not load; ldd on its libggml-cuda.so names the missing library",
+			filepath.Base(model), comp.Offloaded, comp.Total)
+	}
+	fmt.Fprintf(out, "computed a token on %s: %s, %d of %d layers offloaded, in %s\n", comp.Backend,
+		strings.Join(comp.Devices, "; "), comp.Offloaded, comp.Total, took.Round(100*time.Millisecond))
+	return nil
+}
+
+func tailLines(s string, n int) string {
+	l := strings.Split(strings.TrimSpace(s), "\n")
+	if len(l) > n {
+		l = l[len(l)-n:]
+	}
+	return strings.Join(l, " | ")
+}
+
+// syncBuffer is a buffer two writers share.
+type syncBuffer struct {
+	mu sync.Mutex
+	b  strings.Builder
+}
+
+func (s *syncBuffer) Write(p []byte) (int, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.b.Write(p)
+}
+
+func (s *syncBuffer) String() string {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.b.String()
+}

internal/cli/enginecheck_gpu_test.go

@@ -0,0 +1,86 @@
+package cli
+
+import (
+	"bytes"
+	"fmt"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// TestMain lets the test binary stand in for llama-server: run with
+// LLMGW_FAKE_LLAMA set, it prints what llama.cpp prints and answers.
+func TestMain(m *testing.M) {
+	if mode := os.Getenv("LLMGW_FAKE_LLAMA"); mode != "" {
+		fakeLlama(mode)
+		return
+	}
+	os.Exit(m.Run())
+}
+
+func fakeLlama(mode string) {
+	port := ""
+	for i, a := range os.Args {
+		if a == "--port" && i+1 < len(os.Args) {
+			port = os.Args[i+1]
+		}
+	}
+	if mode == "gpu" {
+		fmt.Println("llama_model_load_from_file_impl: using device CUDA0 (Quadro RTX 6000) - 23800 MiB free")
+		fmt.Println("load_tensors: offloaded 25/25 layers to GPU")
+	} else {
+		fmt.Println("warning: no usable GPU found, --gpu-layers option will be ignored")
+		fmt.Println("load_tensors: offloaded 0/25 layers to GPU")
+	}
+	http.HandleFunc("/health", func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(http.StatusOK) })
+	http.HandleFunc("/completion", func(w http.ResponseWriter, _ *http.Request) { _, _ = w.Write([]byte(`{"content":"!"}`)) })
+	_ = http.ListenAndServe("127.0.0.1:"+port, nil) //nolint:gosec // a test's stand-in
+}
+
+func TestEngineCheckComputesATokenOnTheGPU(t *testing.T) {
+	// nvidia-smi present, so the check runs.
+	dir := t.TempDir()
+	smi := filepath.Join(dir, "nvidia-smi")
+	if err := os.WriteFile(smi, []byte("#!/bin/sh\nexit 0\n"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", dir+string(os.PathListSeparator)+os.Getenv("PATH"))
+	model := filepath.Join(dir, "tiny.gguf")
+	_ = os.WriteFile(model, []byte("GGUF"), 0o644)
+	self, _ := os.Executable()
+
+	t.Setenv("LLMGW_FAKE_LLAMA", "gpu")
+	var out bytes.Buffer
+	if err := computeOnGPU(t.Context(), self, model, &out); err != nil || !strings.Contains(out.String(), "on CUDA") ||
+		!strings.Contains(out.String(), "25 of 25") {
+		t.Fatalf("on the GPU: %v %s", err, out.String())
+	}
+
+	t.Setenv("LLMGW_FAKE_LLAMA", "cpu")
+	out.Reset()
+	if err := computeOnGPU(t.Context(), self, model, &out); err == nil || !strings.Contains(err.Error(), "computed on the CPU") {
+		t.Fatalf("a build that falls back to the CPU: %v %s", err, out.String())
+	}
+}
+
+func TestEngineCheckFindsTheBuildTheAgentInstalled(t *testing.T) {
+	old := llamaRoot
+	llamaRoot = t.TempDir()
+	t.Cleanup(func() { llamaRoot = old })
+	if got := installedLlama(); got != "" {
+		t.Fatalf("nothing installed, found %q", got)
+	}
+	for _, p := range []string{"b10991-cpu/llama-b10991/llama-server", "b10991-cuda-13.3/llama-b10991/llama-server"} {
+		full := filepath.Join(llamaRoot, p)
+		_ = os.MkdirAll(filepath.Dir(full), 0o755)
+		_ = os.WriteFile(full, []byte("x"), 0o755)
+	}
+	dir := t.TempDir()
+	_ = os.WriteFile(filepath.Join(dir, "nvidia-smi"), []byte("#!/bin/sh\n"), 0o755)
+	t.Setenv("PATH", dir)
+	if got := installedLlama(); !strings.Contains(got, "cuda-13.3/llama-b10991/llama-server") {
+		t.Errorf("with GPUs, not the CUDA build: %q", got)
+	}
+}

internal/cli/firewallcmd.go

@@ -7,12 +7,14 @@ import (
 	"fmt"
 	"net/netip"
 	"os"
+	"strings"
 	"time"
 
 	"github.com/spf13/cobra"
 
 	"gitea.mynodes.xyz/ilker/llmgw/internal/config"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/firewall"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/mirror"
 )
 
 // firewallStateFile is where a control plane writes what the cluster's
@@ -20,11 +22,9 @@ import (
 // the server itself runs as llmgw and cannot change the ruleset.
 const firewallStateFile = "/var/lib/llmgw/firewall.json"
 
-// firewallState is what is written there.
-type firewallState struct {
-	Enabled  bool     `json:"enabled"`
-	Networks []string `json:"networks,omitempty"`
-}
+// firewallState is what is written there: the same as the mirror is told
+// and keeps beside its models.
+type firewallState = mirror.FirewallState
 
 // writeFirewallState records the settings' firewall for this machine's sync
 // unit. Without the state directory — a server not run by systemd — there
@@ -46,25 +46,34 @@ func writeFirewallState(cfg config.Server) error {
 
 // The units that apply it: a path unit watching the file, and the oneshot it
 // starts.
-const (
-	firewallSyncPathUnit = "llmgw-firewall-sync.path"
-	firewallSyncUnitFile = `[Unit]
-Description=llmgw firewall: apply the cluster's settings on this control plane
+const firewallSyncPathUnit = "llmgw-firewall-sync.path"
+
+// firewallSyncUnits are the two units for a state file: on a control plane
+// the one its server writes, on a mirror the one the control plane has the
+// mirror write.
+func firewallSyncUnits(state string) (service, pathUnit string) {
+	arg := ""
+	if state != firewallStateFile {
+		arg = " --state " + state
+	}
+	service = `[Unit]
+Description=llmgw firewall: apply the cluster's settings on this machine
 
 [Service]
 Type=oneshot
-ExecStart=/usr/local/bin/llmgw firewall sync
+ExecStart=/usr/local/bin/llmgw firewall sync` + arg + `
 `
-	firewallSyncPathFile = `[Unit]
-Description=llmgw firewall: follow the cluster's settings on this control plane
+	pathUnit = `[Unit]
+Description=llmgw firewall: follow the cluster's settings on this machine
 
 [Path]
-PathChanged=` + firewallStateFile + `
+PathChanged=` + state + `
 
 [Install]
 WantedBy=multi-user.target
 `
-)
+	return service, pathUnit
+}
 
 func newFirewallCmd() *cobra.Command {
 	c := &cobra.Command{
@@ -76,6 +85,7 @@ func newFirewallCmd() *cobra.Command {
 			"which " + firewallSyncPathUnit + " applies with 'llmgw firewall sync'.",
 	}
 	var install bool
+	state := firewallStateFile
 	sync := &cobra.Command{
 		Use:   "sync",
 		Short: "Apply what the cluster's settings say of the firewall, here (root)",
@@ -85,21 +95,21 @@ func newFirewallCmd() *cobra.Command {
 				return errors.New("the firewall is changed as root: run it with sudo")
 			}
 			if install {
-				if err := installFirewallSync(cmd.Context(), firewall.Local{}); err != nil {
+				if err := installFirewallSync(cmd.Context(), firewall.Local{}, state); err != nil {
 					return err
 				}
 				fmt.Fprintln(cmd.OutOrStdout(), firewallSyncPathUnit+" follows the cluster's settings here")
-				if _, err := os.Stat(firewallStateFile); err != nil {
-					return nil // the server writes it when it starts
+				if _, err := os.Stat(state); err != nil {
+					return nil // written when the settings are first told
 				}
 			}
-			b, err := os.ReadFile(firewallStateFile)
+			b, err := os.ReadFile(state)
 			if err != nil {
 				return err
 			}
 			var st firewallState
 			if err := json.Unmarshal(b, &st); err != nil {
-				return fmt.Errorf("%s: %w", firewallStateFile, err)
+				return fmt.Errorf("%s: %w", state, err)
 			}
 			ctx, cancel := context.WithTimeout(cmd.Context(), 2*time.Minute)
 			defer cancel()
@@ -112,14 +122,17 @@ func newFirewallCmd() *cobra.Command {
 		},
 	}
 	sync.Flags().BoolVar(&install, "install", false, "first install the units that run this whenever the settings change")
+	sync.Flags().StringVar(&state, "state", firewallStateFile,
+		"the file the settings are written to: a control plane's, or "+mirror.FirewallFile+" in a mirror's directory")
 	c.AddCommand(sync)
 	return c
 }
 
 // installFirewallSync writes the sync units on a machine and has the path
 // unit follow the state file.
-func installFirewallSync(ctx context.Context, r firewall.Runner) error {
-	body := firewallSyncUnitFile + "\x00" + firewallSyncPathFile
+func installFirewallSync(ctx context.Context, r firewall.Runner, state string) error {
+	service, pathUnit := firewallSyncUnits(state)
+	body := service + "\x00" + pathUnit
 	out, err := r.Run(ctx, `set -e
 t=$(mktemp -d); trap 'rm -rf "$t"' EXIT
 cat > "$t/all"
@@ -172,5 +185,20 @@ func syncFirewall(ctx context.Context, r firewall.Runner, st firewallState) (str
 			return "", err
 		}
 	}
+	// The cluster's machines: a node on a network this one has not let in
+	// yet, which the mirror's files are for.
+	if len(st.Toward) > 0 {
+		added, err := firewall.Admit(ctx, r, st.Toward)
+		if err != nil {
+			return "", err
+		}
+		if len(added) > 0 {
+			shown := make([]string, len(added))
+			for i, p := range added {
+				shown[i] = p.String()
+			}
+			return "llmgw's firewall is on here, and now lets in " + strings.Join(shown, ", "), nil
+		}
+	}
 	return "llmgw's firewall is on here", nil
 }

internal/cli/firewallcmd_test.go

@@ -2,8 +2,11 @@ package cli
 
 import (
 	"context"
+	"net/netip"
 	"strings"
 	"testing"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/firewall"
 )
 
 type scriptLog struct {
@@ -49,3 +52,32 @@ func TestAControlPlaneFollowsTheFirewallSetting(t *testing.T) {
 		t.Errorf("on: %q %v", msg, err)
 	}
 }
+
+func TestAMachineLetsInTheClusterMachinesItIsTold(t *testing.T) {
+	// The rules hold 10.0.0.0/24; a node on 192.168.7.0/24 is let in, as
+	// the route to it says, and one already in is not asked about.
+	r := &scriptLog{reply: func(s string) string {
+		switch {
+		case strings.Contains(s, "echo loaded"):
+			return "loaded\n"
+		case strings.Contains(s, "cat /etc/llmgw/firewall.nft"):
+			return firewallRulesFor("10.0.0.0/24")
+		case strings.Contains(s, "ip -o route get 192.168.7.20"):
+			return "192.168.7.20 dev eth1 src 192.168.7.1 uid 0\n2: eth1    inet 192.168.7.1/24 brd 192.168.7.255 scope global eth1\n"
+		case strings.Contains(s, "nft -f"):
+			return "changed\n"
+		}
+		return ""
+	}}
+	msg, err := syncFirewall(context.Background(), r, firewallState{Enabled: true, Toward: []string{"10.0.0.147", "192.168.7.20"}})
+	if err != nil || !strings.Contains(msg, "192.168.7.0/24") {
+		t.Fatalf("%q %v", msg, err)
+	}
+	if strings.Contains(strings.Join(r.scripts, "\n"), "route get 10.0.0.147") {
+		t.Error("asked the route to a machine already let in")
+	}
+}
+
+func firewallRulesFor(nets string) string {
+	return firewall.Script(firewall.Spec{Ports: []firewall.Port{firewall.MirrorFiles}, Allow: []netip.Prefix{netip.MustParsePrefix(nets)}})
+}

internal/cli/firewallpub.go

@@ -0,0 +1,146 @@
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"log/slog"
+	"net"
+	"net/netip"
+	"net/url"
+	"slices"
+	"sync"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/config"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/mirror"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
+)
+
+// firewallStateKey is where, in the store, the firewall's state is kept
+// for the store's members to read.
+const firewallStateKey = "firewall"
+
+// firewallPublisher tells the machines that cannot ask a control plane
+// what the cluster's settings say of their firewall: the mirror, over its
+// API, and the store's members, through the store they hold a copy of.
+// Nodes are told over their agents' streams and control planes by their
+// own servers. On the leader only, at start, at every change to the
+// firewall's settings, and every few minutes for nodes come and gone.
+type firewallPublisher struct {
+	settings func() config.Server
+	st       *store.DB
+	nodes    func() []string
+	leader   func() bool
+	log      *slog.Logger
+
+	mu     sync.Mutex
+	mirror *mirror.Client
+	kick   chan struct{}
+}
+
+func newFirewallPublisher(settings func() config.Server, st *store.DB, nodes func() []string,
+	leader func() bool, log *slog.Logger) *firewallPublisher {
+	return &firewallPublisher{settings: settings, st: st, nodes: nodes, leader: leader, log: log,
+		kick: make(chan struct{}, 1)}
+}
+
+// setMirror has the mirror told too.
+func (p *firewallPublisher) setMirror(m *mirror.Client) {
+	p.mu.Lock()
+	p.mirror = m
+	p.mu.Unlock()
+	p.Kick()
+}
+
+// Kick has the state worked out and told again now.
+func (p *firewallPublisher) Kick() {
+	select {
+	case p.kick <- struct{}{}:
+	default:
+	}
+}
+
+func (p *firewallPublisher) run(ctx context.Context, every time.Duration) {
+	t := time.NewTicker(every)
+	defer t.Stop()
+	for {
+		p.once(ctx)
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+		case <-p.kick:
+		}
+	}
+}
+
+// state is what the settings say now, with the cluster's machines.
+func (p *firewallPublisher) state(ctx context.Context) mirror.FirewallState {
+	cfg := p.settings()
+	st := mirror.FirewallState{Enabled: cfg.Firewall.Enabled, Networks: slices.Clone(cfg.FirewallNetworks)}
+	var toward []string
+	if p.nodes != nil {
+		toward = append(toward, p.nodes()...)
+	}
+	if p.st != nil {
+		if cps, err := p.st.ControlPlanes(ctx); err == nil {
+			for _, c := range cps {
+				toward = append(toward, c.URL)
+			}
+		}
+	}
+	for _, t := range toward {
+		if a, ok := hostAddr(t); ok {
+			st.Toward = append(st.Toward, a)
+		}
+	}
+	slices.Sort(st.Toward)
+	st.Toward = slices.Compact(st.Toward)
+	return st
+}
+
+// hostAddr is the address in an address, host:port or URL; names are not
+// looked up here.
+func hostAddr(s string) (string, bool) {
+	if u, err := url.Parse(s); err == nil && u.Host != "" {
+		s = u.Hostname()
+	} else if h, _, err := net.SplitHostPort(s); err == nil {
+		s = h
+	}
+	a, err := netip.ParseAddr(s)
+	if err != nil {
+		return "", false
+	}
+	return a.Unmap().String(), true
+}
+
+func (p *firewallPublisher) once(ctx context.Context) {
+	if p.leader != nil && !p.leader() {
+		return
+	}
+	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+	defer cancel()
+	st := p.state(ctx)
+	p.mu.Lock()
+	m := p.mirror
+	p.mu.Unlock()
+	if m != nil {
+		changed, err := m.SetFirewall(ctx, st)
+		switch {
+		case err != nil:
+			p.log.Warn("could not tell the mirror what the settings say of its firewall", "err", err)
+		case changed:
+			p.log.Info("the mirror's firewall follows the cluster's settings", "enabled", st.Enabled)
+		}
+	}
+	if p.st != nil {
+		b, _ := json.Marshal(st)
+		changed, err := p.st.PutClusterState(ctx, firewallStateKey, string(b))
+		switch {
+		case err != nil:
+			p.log.Warn("could not record the firewall's state for the store's members", "err", err)
+		case changed:
+			p.log.Info("the store's members' firewall follows the cluster's settings", "enabled", st.Enabled)
+		}
+	}
+}

internal/cli/firewallpub_test.go

@@ -0,0 +1,59 @@
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"log/slog"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/config"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/mirror"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/tlsconf"
+)
+
+func TestTheLeaderTellsTheMirrorAndTheStoreWhatTheFirewallSettingsSay(t *testing.T) {
+	ctx := context.Background()
+	st, err := store.OpenSQLite(ctx, filepath.Join(t.TempDir(), "s.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer st.Close()
+	if err := st.PutControlPlane(ctx, store.ControlPlane{URL: "https://10.0.0.150:7443", Name: "ctl02"}); err != nil {
+		t.Fatal(err)
+	}
+	root := t.TempDir()
+	srv := httptest.NewServer(mirror.NewAPI(mirror.NewManager(root, slog.New(slog.DiscardHandler)), "http://m:8081").Handler())
+	defer srv.Close()
+	mc, _ := mirror.NewClient(srv.URL, tlsconf.Config{}, 0)
+
+	cfg := config.Server{Firewall: config.FirewallSettings{Enabled: false}, FirewallNetworks: []string{"192.168.5.0/24"}}
+	leader := false
+	p := newFirewallPublisher(func() config.Server { return cfg }, st,
+		func() []string { return []string{"10.0.0.147", "", "10.0.0.147", "node-by-name"} },
+		func() bool { return leader }, slog.New(slog.DiscardHandler))
+	p.setMirror(mc)
+
+	p.once(ctx)
+	if _, err := st.ClusterState(ctx, firewallStateKey); err == nil {
+		t.Error("a standby told the store")
+	}
+	leader = true
+	p.once(ctx)
+	var got mirror.FirewallState
+	v, err := st.ClusterState(ctx, firewallStateKey)
+	if err != nil || json.Unmarshal([]byte(v), &got) != nil {
+		t.Fatalf("the store holds %q %v", v, err)
+	}
+	if got.Enabled || got.Networks[0] != "192.168.5.0/24" || len(got.Toward) != 2 ||
+		got.Toward[0] != "10.0.0.147" || got.Toward[1] != "10.0.0.150" {
+		t.Errorf("state %+v", got)
+	}
+	b, err := os.ReadFile(filepath.Join(root, mirror.FirewallFile))
+	if err != nil || string(b) != v {
+		t.Errorf("the mirror holds %s, the store %s", b, v)
+	}
+}

internal/cli/guard.go

@@ -3,11 +3,13 @@ package cli
 import (
 	"encoding/json"
 	"fmt"
+	"strconv"
 	"strings"
 
 	"github.com/spf13/cobra"
 
 	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/settings"
 )
 
 func newGuardCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
@@ -24,6 +26,35 @@ func newGuardCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
 			"Targets are written org:Acme, team:Acme/ml, project:Acme/ml/training (or\n" +
 			"with IDs), key:KEY-ID or user:USER-ID. An attachment applies at once.",
 	}
+	c.AddCommand(newGuardJudgeCmd(client, asJSON))
+	for _, sw := range []struct {
+		use, short string
+		on         bool
+	}{
+		{"on", "Turn the guardrails on: every policy checks again", true},
+		{"off", "Turn the guardrails off: no request is checked, whatever the policies say", false},
+	} {
+		var note string
+		cmd := &cobra.Command{
+			Use:   sw.use,
+			Short: sw.short,
+			Long: "guard.enabled in the cluster's settings: in force on every control plane\n" +
+				"within seconds, without a restart. The policies and where they are attached\n" +
+				"stay as they are, and come back as they were when turned on again. While\n" +
+				"off, llmgw ctl status says so.",
+			Args: cobra.NoArgs,
+			RunE: func(cmd *cobra.Command, _ []string) error {
+				if note == "" {
+					note = "guardrails " + sw.use
+				}
+				return changeSettings(cmd, client, note, func(doc *settings.Doc) error {
+					return doc.SetYAML([]string{"guard", "enabled"}, strconv.FormatBool(sw.on))
+				})
+			},
+		}
+		cmd.Flags().StringVar(&note, "note", "", "why, kept with the settings' version")
+		c.AddCommand(cmd)
+	}
 	c.AddCommand(&cobra.Command{
 		Use:   "list",
 		Short: "The policies, and where each is attached",
@@ -37,6 +68,9 @@ func newGuardCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
 				return json.NewEncoder(cmd.OutOrStdout()).Encode(v)
 			}
 			out := cmd.OutOrStdout()
+			if !v.Enabled {
+				fmt.Fprintln(out, "The guardrails are OFF: no request is checked (llmgw ctl guard on).")
+			}
 			fmt.Fprintf(out, "Policies: %s\n", strings.Join(v.Policies, ", "))
 			def := strings.Join(v.Default, ", ")
 			if def == "" {

internal/cli/guard_judge.go

@@ -0,0 +1,453 @@
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"slices"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/catalog"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/modelserve"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/guard"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/settings"
+)
+
+func newGuardJudgeCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
+	c := &cobra.Command{
+		Use:   "judge",
+		Short: "The judge models the policies ask: whether each can answer, and serving one",
+		Long: "A policy with a judge has a model read what patterns cannot. The judge must\n" +
+			"be in the catalog under the name the policy gives, as a judge (role:\n" +
+			"guard), with a replica ready; otherwise what the policy judges is refused\n" +
+			"(fail: closed, guard_unavailable) or served unjudged (fail: open).\n\n" +
+			"A policy may name several, asked in turn (judge.models): a judge on a GPU\n" +
+			"first and one on CPUs after it is the GPU's speed while it is there, and\n" +
+			"the CPUs' when it is not.\n\n" +
+			"Judges llmgw knows where to fetch, which a policy may name and the leader\n" +
+			"then fetches and serves by itself: " + knownJudgeNames() + ".",
+	}
+	c.AddCommand(newGuardJudgeStatusCmd(client, asJSON), newGuardJudgeEnableCmd(client),
+		newGuardJudgeUseCmd(client), newGuardJudgeAskCmd(client, asJSON), newGuardJudgeCheckCmd(client, asJSON))
+	return c
+}
+
+func newGuardJudgeStatusCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
+	return &cobra.Command{
+		Use:   "status",
+		Short: "Each judge the policies ask, and what is wrong with it",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			var js []adminapi.JudgeView
+			if err := client().get(cmd.Context(), "/api/v1/guard/judges", &js); err != nil {
+				return err
+			}
+			if *asJSON {
+				return emitJSON(js)
+			}
+			out := cmd.OutOrStdout()
+			if len(js) == 0 {
+				fmt.Fprintln(out, "no policy asks a judge")
+				return nil
+			}
+			w := tabTo(out)
+			fmt.Fprintln(w, "JUDGE\tPOLICIES\tIN CATALOG\tAS JUDGE\tREADY\tSTATE")
+			for _, j := range js {
+				state := "answering"
+				if j.Problem != "" {
+					state = j.Problem
+				}
+				fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%d/%d\t%s\n", j.Model, strings.Join(j.Policies, ","),
+					yesNo(j.InCatalog), yesNo(j.Judge), j.Ready, j.Wanted, state)
+			}
+			for _, j := range js {
+				if len(j.Then) > 0 {
+					fmt.Fprintf(w, "\n%s gives no verdict: %s is asked instead", j.Model, strings.Join(j.Then, ", else "))
+				}
+			}
+			if err := w.Flush(); err != nil {
+				return err
+			}
+			strays, _ := strayJudges(cmd, client, js)
+			sayStrays(out, strays)
+			return nil
+		},
+	}
+}
+
+// strayJudges are models whose weights are a judge's, under a name no policy
+// asks: a judge the policies moved on from, or one served from the mirror
+// page as a model clients use, as before that page knew better.
+func strayJudges(cmd *cobra.Command, client func() *ctlClient, js []adminapi.JudgeView) ([]adminapi.ModelView, error) {
+	var models []adminapi.ModelView
+	if err := client().get(cmd.Context(), "/api/v1/models", &models); err != nil {
+		return nil, err
+	}
+	asked := map[string]bool{}
+	for _, j := range js {
+		asked[j.Model] = true
+	}
+	var out []adminapi.ModelView
+	for _, m := range models {
+		if _, judge := guard.FormatOfWeights(m.Source); !asked[m.Name] && judge {
+			out = append(out, m)
+		}
+	}
+	return out, nil
+}
+
+// sayStrays says what each stray judge is and how to be rid of it.
+func sayStrays(out io.Writer, strays []adminapi.ModelView) {
+	for _, m := range strays {
+		if m.Role == catalog.RoleGuard {
+			fmt.Fprintf(out, "\n%s is a judge no policy asks, still running: llmgw ctl model remove %s\n", m.Name, m.Name)
+			continue
+		}
+		fmt.Fprintf(out, "\n%s looks like a judge's weights but is served as a model clients use, and no "+
+			"policy asks it: llmgw ctl model remove %s\n", m.Name, m.Name)
+	}
+}
+
+func newGuardJudgeEnableCmd(client func() *ctlClient) *cobra.Command {
+	var (
+		model, repo, file, format, gpuClass string
+		replicas, cores                     int
+		gpu, replace, detach                bool
+	)
+	c := &cobra.Command{
+		Use:   "enable",
+		Short: "Serve a judge: Qwen3Guard-Gen 0.6B on CPUs, or with --gpu the 4B on a GPU",
+		Long: "Fetches a judge's weights into the mirror (once; what is there already, its\n" +
+			"checksums matching, is not fetched again), adds it to the catalog as a judge\n" +
+			"(role: guard) and waits for a replica to answer. Which judge: --model, or\n" +
+			"with --gpu " + defaultGPUJudge + ", or else the first the policies ask that is\n" +
+			"missing, or else " + defaultJudge + ".\n\n" +
+			"A judge on CPUs takes no card. One on a GPU takes one card, as a standard\n" +
+			"model: from nothing more important, so it waits while the cards are busy;\n" +
+			"put a judge on CPUs after it in the policies (llmgw ctl guard judge use) so\n" +
+			"there is always one to ask.\n\n" +
+			"Known judges: " + knownJudgeNames() + ". Another is served with --repo,\n" +
+			"--file and --format. A model of that name already in the catalog as a\n" +
+			"model clients use is refused; --replace removes it first. An offline\n" +
+			"cluster gets its judge from its bundle with server init.",
+		Example: "  llmgw ctl guard judge enable\n" +
+			"  llmgw ctl guard judge enable --gpu\n" +
+			"  llmgw ctl guard judge use " + defaultGPUJudge + " " + defaultJudge,
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			ctx := cmd.Context()
+			out := cmd.OutOrStdout()
+			var js []adminapi.JudgeView
+			if err := client().get(ctx, "/api/v1/guard/judges", &js); err != nil {
+				return err
+			}
+			name := model
+			if name == "" && gpu {
+				name = defaultGPUJudge
+			}
+			if name == "" {
+				for _, j := range js {
+					if !j.InCatalog || !j.Judge {
+						name = j.Model
+						break
+					}
+				}
+			}
+			if name == "" {
+				name = defaultJudge
+			}
+
+			k, known := knownJudgeNamed(name)
+			switch {
+			case repo != "":
+				f := format
+				if f == "" {
+					f, _ = guard.FormatOfWeights(repo + "/" + file)
+				}
+				if f == "" || !guard.KnownFormat(f) {
+					return fmt.Errorf("say how its answers are read: --format %s", strings.Join(guard.Formats, "|"))
+				}
+				k = knownJudge{Name: name, Repo: repo, File: file, Format: f, GPU: gpu}
+			case !known:
+				return fmt.Errorf("%s is not a judge llmgw knows where to fetch (%s): give --repo, --file and --format", name, knownJudgeNames())
+			}
+			if gpu {
+				k.GPU = true
+			}
+
+			var models []adminapi.ModelView
+			if err := client().get(ctx, "/api/v1/models", &models); err != nil {
+				return err
+			}
+			if i := slices.IndexFunc(models, func(m adminapi.ModelView) bool { return m.Name == name }); i >= 0 {
+				if models[i].Role == catalog.RoleGuard {
+					fmt.Fprintf(out, "%s is in the catalog as a judge already; llmgw ctl guard judge status says how it is\n", name)
+					return nil
+				}
+				if !replace {
+					return fmt.Errorf("%s is in the catalog as a model clients use, not as a judge: "+
+						"--replace removes it and serves it again as a judge", name)
+				}
+				var res map[string]string
+				if err := client().delete(ctx, "/api/v1/models/"+name, &res); err != nil {
+					return fmt.Errorf("removing %s: %w", name, err)
+				}
+				fmt.Fprintf(out, "%s removed\n", name)
+			}
+
+			opts := judgeServeOptions{Replicas: replicas, Cores: cores, GPUClass: gpuClass}
+			if k.GPU && opts.GPUClass == "" {
+				var s adminapi.Summary
+				if err := client().get(ctx, "/api/v1/summary", &s); err != nil {
+					return err
+				}
+				if opts.GPUClass = roomiestGPUClass(s.GPUs); opts.GPUClass == "" {
+					return fmt.Errorf("this cluster has no GPU for %s: serve %s on CPUs instead", name, defaultJudge)
+				}
+			}
+			fmt.Fprintf(out, "serving %s\n", k)
+			body, _ := json.Marshal(k.serveRequest(opts))
+			var job modelserve.Job
+			if err := client().patient(30*time.Second).post(ctx, "/api/v1/models/serve", body, &job); err != nil {
+				return err
+			}
+			if detach {
+				return detached(cmd, job)
+			}
+			if err := followJob(cmd, client, job, "is the judge"); err != nil {
+				return err
+			}
+			if !slices.ContainsFunc(js, func(j adminapi.JudgeView) bool { return j.Model == name }) {
+				fmt.Fprintf(out, "\nno policy asks %s yet: llmgw ctl guard judge use %s", name, name)
+				if k.GPU {
+					fmt.Fprintf(out, " %s", defaultJudge)
+				}
+				fmt.Fprintln(out)
+			}
+			if strays, _ := strayJudges(cmd, client, js); len(strays) > 0 {
+				sayStrays(out, slices.DeleteFunc(strays, func(m adminapi.ModelView) bool { return m.Name == name }))
+			}
+			return nil
+		},
+	}
+	f := c.Flags()
+	f.StringVar(&model, "model", "", "the judge to serve: "+knownJudgeNames()+", or a name for --repo's")
+	f.BoolVar(&gpu, "gpu", false, "serve it on a GPU ("+defaultGPUJudge+" when no --model)")
+	f.StringVar(&gpuClass, "gpu-class", "", "the GPUs it runs on (default: the class with the most free cards)")
+	f.StringVar(&repo, "repo", "", "the registry repository of a judge llmgw does not know")
+	f.StringVar(&file, "file", "", "the GGUF file in --repo")
+	f.StringVar(&format, "format", "", "how --repo's judge answers: "+strings.Join(guard.Formats, ", "))
+	f.IntVar(&replicas, "replicas", 0, "replicas (default: 2 on CPUs, as every judged request waits on one; 1 on a GPU)")
+	f.IntVar(&cores, "cores", 4, "CPU cores a replica on CPUs computes on")
+	f.BoolVar(&replace, "replace", false, "remove a model of that name that is not a judge first")
+	f.BoolVar(&detach, "detach", false, "start it and return; llmgw ctl jobs follows it")
+	return c
+}
+
+// roomiestGPUClass is the class with the most free cards, else the most
+// cards; empty when the cluster has none.
+func roomiestGPUClass(classes []adminapi.ClassUse) string {
+	best := -1
+	for i, c := range classes {
+		if c.Total == 0 {
+			continue
+		}
+		if best < 0 || c.Free() > classes[best].Free() || (c.Free() == classes[best].Free() && c.Total > classes[best].Total) {
+			best = i
+		}
+	}
+	if best < 0 {
+		return ""
+	}
+	return classes[best].Class
+}
+
+func newGuardJudgeUseCmd(client func() *ctlClient) *cobra.Command {
+	var policies []string
+	var note string
+	c := &cobra.Command{
+		Use:   "use JUDGE...",
+		Short: "Set the judges the policies ask, in the order they are asked",
+		Long: "Sets judge.models of every policy that has a judge, or of those given with\n" +
+			"--policy: the first judge that answers gives the verdict, and the next is\n" +
+			"asked when one has no replica serving, fails, or does not answer within\n" +
+			"the policy's latency_budget. A judge on a GPU first and one on CPUs after\n" +
+			"it is the GPU's speed while it is there, and the CPUs' when it is not.\n\n" +
+			"A judge llmgw knows (" + knownJudgeNames() + ")\n" +
+			"that is not in the catalog is fetched and served by the leader; another\n" +
+			"is served first with llmgw ctl guard judge enable --repo. In force on\n" +
+			"every control plane within seconds.",
+		Example: "  llmgw ctl guard judge use " + defaultJudge + "\n" +
+			"  llmgw ctl guard judge use " + defaultGPUJudge + " " + defaultJudge + "\n" +
+			"  llmgw ctl guard judge use " + defaultGPUJudge + " " + defaultJudge + " --policy strict",
+		Args: cobra.MinimumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			for i, a := range args {
+				if slices.Contains(args[:i], a) {
+					return fmt.Errorf("%s is named twice", a)
+				}
+			}
+			if note == "" {
+				note = "judges: " + strings.Join(args, ", else ")
+			}
+			list := "[" + strings.Join(args, ", ") + "]"
+			return changeSettings(cmd, client, note, func(doc *settings.Doc) error {
+				names := policies
+				if len(names) == 0 {
+					for _, p := range doc.MapKeys([]string{"guard", "policies"}) {
+						if doc.Node([]string{"guard", "policies", p, "judge"}) != nil {
+							names = append(names, p)
+						}
+					}
+					if len(names) == 0 {
+						return errors.New("no policy has a judge: name one with --policy, and it is given one " +
+							"that blocks what the judge finds unsafe in requests (judge.input: block)")
+					}
+				}
+				for _, p := range names {
+					base := []string{"guard", "policies", p}
+					if doc.Node(base) == nil {
+						return fmt.Errorf("there is no policy %s (llmgw ctl guard list)", p)
+					}
+					judge := append(slices.Clone(base), "judge")
+					if doc.Node(judge) == nil {
+						if err := doc.SetYAML(append(slices.Clone(judge), "input"), "block"); err != nil {
+							return err
+						}
+					}
+					doc.Unset(append(slices.Clone(judge), "model"))
+					if err := doc.SetYAML(append(slices.Clone(judge), "models"), list); err != nil {
+						return err
+					}
+					cats := append(slices.Clone(judge), "categories")
+					var have []string
+					if n := doc.Node(cats); n != nil {
+						for _, c := range n.Content {
+							have = append(have, c.Value)
+						}
+					}
+					if next := categoriesFor(args, have); next != nil {
+						if err := doc.SetYAML(cats, "["+strings.Join(next, ", ")+"]"); err != nil {
+							return err
+						}
+						fmt.Fprintf(cmd.OutOrStdout(), "%s: categories [%s] are not what %s name; it counts [%s] instead\n",
+							p, strings.Join(have, ", "), strings.Join(args, " or "), strings.Join(next, ", "))
+					}
+				}
+				return nil
+			})
+		},
+	}
+	c.Flags().StringSliceVar(&policies, "policy", nil, "the policies to change (default: every one with a judge)")
+	c.Flags().StringVar(&note, "note", "", "why, kept with the settings' version")
+	return c
+}
+
+func newGuardJudgeAskCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
+	var model, answer string
+	c := &cobra.Command{
+		Use:   "ask TEXT",
+		Short: "Have a judge read a text and say what it answered",
+		Long: "For finding out why a request was refused: the judge reads TEXT as a user's\n" +
+			"message (with --answer, ANSWER as the reply to it), past the cache, and its\n" +
+			"answer is shown as it gave it and as the gateway reads it — \"unsafe\" and\n" +
+			"the hazards it named, S6 Specialized Advice and the like. Nothing is kept:\n" +
+			"not in the audit, the usage or the logs.",
+		Example: "  llmgw ctl guard judge ask 'How do I sort a list in Python?'\n" +
+			"  llmgw ctl guard judge ask 'Write a poem' --answer 'Roses are red'",
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			body, _ := json.Marshal(adminapi.JudgeAskRequest{Model: model, Text: args[0], Answer: answer})
+			var v adminapi.JudgeAskView
+			if err := client().patient(45*time.Second).post(cmd.Context(), "/api/v1/guard/judges/ask", body, &v); err != nil {
+				return err
+			}
+			if *asJSON {
+				return emitJSON(v)
+			}
+			out := cmd.OutOrStdout()
+			fmt.Fprintf(out, "%s: %s", v.Model, v.Verdict)
+			if len(v.Categories) > 0 {
+				fmt.Fprintf(out, " (%s)", strings.Join(v.Categories, ", "))
+			}
+			fmt.Fprintf(out, ", %d ms\nit answered: %q\n", v.TookMs, v.Raw)
+			return nil
+		},
+	}
+	c.Flags().StringVar(&model, "model", "", "the judge (default: the one the policies ask)")
+	c.Flags().StringVar(&answer, "answer", "", "an assistant's reply to TEXT, judged as output is")
+	return c
+}
+
+func newGuardJudgeCheckCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
+	var model string
+	var burst int
+	c := &cobra.Command{
+		Use:   "check",
+		Short: "How a judge keeps up: a judgment alone and among others, against the time a request waits",
+		Long: "Times three judgments of a prompt of about 280 tokens, one after another, then\n" +
+			"a burst of them at once (two for each ready replica unless --burst says),\n" +
+			"and sets both against the policies' latency budget. A judgment past the\n" +
+			"budget is refused under fail: closed; past half of it alone, or past it\n" +
+			"among others, a busy moment refuses requests. Each request is judged once\n" +
+			"for its prompt and again every 600 characters of its answer.",
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			v, err := checkJudge(cmd.Context(), client(), model, burst)
+			if err != nil {
+				return err
+			}
+			if *asJSON {
+				return emitJSON(v)
+			}
+			fmt.Fprint(cmd.OutOrStdout(), judgeCheckText(v))
+			return nil
+		},
+	}
+	c.Flags().StringVar(&model, "model", "", "the judge (default: the one the policies ask)")
+	c.Flags().IntVar(&burst, "burst", 0, "judgments at once (default: two for each ready replica)")
+	return c
+}
+
+func checkJudge(ctx context.Context, c *ctlClient, model string, burst int) (adminapi.JudgeCheckView, error) {
+	body, _ := json.Marshal(adminapi.JudgeCheckRequest{Model: model, Burst: burst})
+	var v adminapi.JudgeCheckView
+	err := c.patient(3*time.Minute).post(ctx, "/api/v1/guard/judges/check", body, &v)
+	return v, err
+}
+
+// judgeCheckText says a check in a few lines, and what to do when it is not
+// fine.
+func judgeCheckText(v adminapi.JudgeCheckView) string {
+	var b strings.Builder
+	took := make([]string, len(v.TookMs))
+	for i, t := range v.TookMs {
+		took[i] = fmt.Sprintf("%.1f", float64(t)/1000)
+	}
+	fmt.Fprintf(&b, "%s, %d replica(s) ready, a request waits %.1f s for it\n", v.Model, v.Ready, float64(v.BudgetMs)/1000)
+	fmt.Fprintf(&b, "  alone:    %s s\n", strings.Join(took, ", "))
+	fmt.Fprintf(&b, "  %d at once: slowest %.1f s", v.Burst, float64(v.BurstSlowestMs)/1000)
+	if v.BurstFailed > 0 {
+		fmt.Fprintf(&b, ", %d gave no verdict", v.BurstFailed)
+	}
+	fmt.Fprintf(&b, "; about %.1f judgments a second, so about %.1f requests a second with short answers\n",
+		v.PerSecond, v.PerSecond/2)
+	switch v.Verdict {
+	case "ok":
+		b.WriteString("ok: well inside the budget\n")
+	case "tight":
+		b.WriteString("tight: a busy moment passes the budget\n")
+	default:
+		b.WriteString("slow: a judgment alone passes the budget\n")
+	}
+	for _, a := range v.Advice {
+		b.WriteString("  - " + a + "\n")
+	}
+	return b.String()
+}

internal/cli/judgekeeper.go

@@ -0,0 +1,241 @@
+package cli
+
+import (
+	"context"
+	"log/slog"
+	"slices"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/catalog"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/modelserve"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/guard"
+)
+
+// judgeKeeper fetches and serves, on the leader, each judge llmgw knows that
+// a policy names and the catalog does not have: naming qwen3guard-4b in a
+// policy is all it takes to have one, and a judge removed by mistake comes
+// back. A judge it does not know is left to llmgw ctl guard judge enable
+// --repo, said in guard judge status.
+type judgeKeeper struct {
+	library func() guard.Config
+	models  func() []catalog.Model
+	serve   interface {
+		Start(modelserve.Request) (modelserve.Job, error)
+		Jobs() []modelserve.Job
+	}
+	leader func() bool
+	gpus   func() []adminapi.ClassUse
+	log    *slog.Logger
+	now    func() time.Time
+
+	// tried is when each judge was last asked for, so one that cannot be
+	// fetched is not asked for again on every look.
+	tried map[string]time.Time
+	// grace is how long after its first look the keeper serves no judge
+	// itself: init adds its own judge just after the control plane starts,
+	// sized and placed as the install says, and one the leader added first
+	// was what init then kept. Zero waits for nothing.
+	grace time.Duration
+	first time.Time
+
+	// What refitting an earlier install's judge needs: the catalog to change
+	// its profile in, the replicas to restart, and the nodes' CPUs. Any nil
+	// leaves judges as they are.
+	profiles interface {
+		SetProfiles(ctx context.Context, name string, profiles []catalog.Profile, by string) (catalog.Model, error)
+	}
+	restart  func(ids ...string) error
+	replicas func(model string) []string
+	nodeCPUs func() []int
+	// looked is each judge already refitted or found changed by hand, so
+	// each is said once.
+	looked map[string]bool
+}
+
+// judgeRetry is how long a judge whose serving failed waits before it is
+// asked for again.
+const judgeRetry = 10 * time.Minute
+
+// judgeGrace is the keeper's grace on a control plane just started.
+const judgeGrace = 10 * time.Minute
+
+func (k *judgeKeeper) run(ctx context.Context, every time.Duration) {
+	t := time.NewTicker(every)
+	defer t.Stop()
+	for {
+		k.check()
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+		}
+	}
+}
+
+func (k *judgeKeeper) check() {
+	if k.leader != nil && !k.leader() {
+		return
+	}
+	lib := k.library()
+	if !lib.On() {
+		return
+	}
+	if k.tried == nil {
+		k.tried = map[string]time.Time{}
+	}
+	now := time.Now
+	if k.now != nil {
+		now = k.now
+	}
+	have := map[string]bool{}
+	for _, m := range k.models() {
+		have[m.Name] = true
+		k.refit(m)
+	}
+	if k.first.IsZero() {
+		k.first = now()
+	}
+	if now().Sub(k.first) < k.grace {
+		return
+	}
+	busy := map[string]bool{}
+	for _, j := range k.serve.Jobs() {
+		if j.State == modelserve.Running {
+			busy[j.Model] = true
+			busy[j.Request.Name] = true
+		}
+	}
+	var wanted []string
+	for _, p := range lib.Policies {
+		for _, j := range p.Judge.Judges() {
+			if !slices.Contains(wanted, j) {
+				wanted = append(wanted, j)
+			}
+		}
+	}
+	slices.Sort(wanted)
+	for _, name := range wanted {
+		kj, known := knownJudgeNamed(name)
+		if have[name] || !known || busy[name] {
+			continue
+		}
+		if at, ok := k.tried[name]; ok && now().Sub(at) < judgeRetry {
+			continue
+		}
+		k.tried[name] = now()
+		var opts judgeServeOptions
+		if !kj.GPU {
+			// The cores init would give the same number of judges.
+			var cpus []int
+			if k.nodeCPUs != nil {
+				cpus = k.nodeCPUs()
+			}
+			opts.Replicas = 2
+			opts.Cores = refitCores(opts.Replicas, cpus)
+		}
+		if kj.GPU {
+			if opts.GPUClass = roomiestGPUClass(k.gpus()); opts.GPUClass == "" {
+				k.log.Warn("a policy names a judge that runs on a GPU, and this cluster has none",
+					"judge", name, "instead", defaultJudge)
+				continue
+			}
+		}
+		req := kj.serveRequest(opts)
+		req.By = "llmgw (a guard policy names it)"
+		// init, or an operator, may add it while this fetches: theirs stays.
+		req.IfAbsent = true
+		job, err := k.serve.Start(req)
+		if err != nil {
+			k.log.Error("could not start serving a judge a policy names", "judge", name, "err", err)
+			continue
+		}
+		k.log.Info("serving a judge a policy names, which the catalog did not have",
+			"judge", name, "repo", kj.Repo, "file", kj.File, "job", job.ID)
+	}
+}
+
+// refit moves a judge an earlier `server init` installed to what init
+// installs now, and restarts its replicas onto it. Those judges reserved no
+// cores or one, 2 or 4 GB, and ran llama.cpp's prompt cache: on fewer than
+// eight cores every judgment missed its 5 s budget and fail: closed refused
+// every request, until fixed by hand. A judge whose profile differs in any
+// other way was set by somebody, and is left as it is, said once.
+func (k *judgeKeeper) refit(m catalog.Model) {
+	if k.profiles == nil || k.restart == nil || k.replicas == nil || m.Name != defaultJudge || !m.IsGuard() {
+		return
+	}
+	if k.looked == nil {
+		k.looked = map[string]bool{}
+	}
+	if k.looked[m.Name] {
+		return
+	}
+	k.looked[m.Name] = true
+	if !earlierInitJudge(m) {
+		if len(m.Profiles) != 1 || !slices.Contains(m.Profiles[0].Args, "--cache-ram") {
+			k.log.Info("the judge's profile is not one init wrote; left as it is",
+				"judge", m.Name, "see", "llmgw ctl model resources "+m.Name)
+		}
+		return
+	}
+	var cpus []int
+	if k.nodeCPUs != nil {
+		cpus = k.nodeCPUs()
+	}
+	p := m.Profiles[0]
+	p.MinMemoryGB = judgeMemoryGB
+	p.CPUCores = refitCores(m.Scaling.Min, cpus)
+	p.Args = []string{"--ctx-size", "8192", "--cache-ram", "0"}
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+	if _, err := k.profiles.SetProfiles(ctx, m.Name, []catalog.Profile{p}, "llmgw (the judge an earlier init installed)"); err != nil {
+		k.log.Warn("could not refit the judge an earlier init installed", "judge", m.Name, "err", err)
+		k.looked[m.Name] = false
+		return
+	}
+	ids := k.replicas(m.Name)
+	if len(ids) > 0 {
+		if err := k.restart(ids...); err != nil {
+			k.log.Warn("refitted the judge, but could not restart it", "judge", m.Name, "err", err)
+		}
+	}
+	k.log.Info("refitted the judge an earlier init installed", "judge", m.Name,
+		"memory_gb", p.MinMemoryGB, "cpu_cores", p.CPUCores, "replicas_restarted", len(ids))
+}
+
+// earlierInitJudge is whether a judge's entry is exactly what `server init`
+// before v0.14.7 wrote: one llama.cpp profile on CPUs, an 8192 context and
+// no other args, 2 or 4 GB, none to two cores.
+func earlierInitJudge(m catalog.Model) bool {
+	if len(m.Profiles) != 1 {
+		return false
+	}
+	p := m.Profiles[0]
+	return p.Name == "cpu" && p.Engine == "llamacpp" && p.GPUClass == "" && p.GPU == nil &&
+		len(p.NodeSelector) == 0 && slices.Equal(p.Args, []string{"--ctx-size", "8192"}) &&
+		(p.MinMemoryGB == 2 || p.MinMemoryGB == 4) && p.CPUCores >= 0 && p.CPUCores <= 2
+}
+
+// refitCores is a judge replica's cores by init's rule: up to four for the
+// one judge of a cluster, two each where there are more, fewer where the
+// smallest node cannot hold them all.
+func refitCores(replicas int, cpus []int) int {
+	smallest := 0
+	for _, c := range cpus {
+		if c > 0 && (smallest == 0 || c < smallest) {
+			smallest = c
+		}
+	}
+	if replicas <= 1 {
+		if smallest == 0 {
+			return judgeCores
+		}
+		return min(smallest, judgeCoresAlone)
+	}
+	cores := judgeCores
+	if len(cpus) == 1 && smallest > 0 && replicas*cores > smallest {
+		cores = max(1, smallest/replicas)
+	}
+	return cores
+}

internal/cli/judgekeeper_test.go

@@ -0,0 +1,237 @@
+package cli
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"slices"
+	"testing"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/catalog"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/modelserve"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/guard"
+)
+
+type fakeServe struct {
+	started []modelserve.Request
+	running []modelserve.Job
+	err     error
+}
+
+func (f *fakeServe) Start(r modelserve.Request) (modelserve.Job, error) {
+	if f.err != nil {
+		return modelserve.Job{}, f.err
+	}
+	f.started = append(f.started, r)
+	return modelserve.Job{ID: "j", Model: r.Name, Request: r, State: modelserve.Running}, nil
+}
+func (f *fakeServe) Jobs() []modelserve.Job { return f.running }
+
+func TestAJudgeAPolicyNamesIsFetchedWhenTheCatalogLacksIt(t *testing.T) {
+	lib := guard.Config{Policies: map[string]guard.Policy{
+		"baseline": {Judge: &guard.JudgePolicy{Models: []string{"qwen3guard-4b", "qwen3guard-0.6b"}, Input: "block"}},
+		"custom":   {Judge: &guard.JudgePolicy{Model: "our-own-judge", Input: "block"}},
+	}}
+	inCatalog := []catalog.Model{{Name: "qwen3guard-0.6b"}}
+	now := time.Date(2026, 10, 8, 12, 0, 0, 0, time.UTC)
+	fs := &fakeServe{}
+	leader := true
+	k := &judgeKeeper{
+		library: func() guard.Config { return lib },
+		models:  func() []catalog.Model { return inCatalog },
+		serve:   fs,
+		leader:  func() bool { return leader },
+		gpus:    func() []adminapi.ClassUse { return []adminapi.ClassUse{{Class: "6000-24g", Total: 1, Used: 1}} },
+		log:     slog.New(slog.DiscardHandler),
+		now:     func() time.Time { return now },
+	}
+
+	k.check()
+	// The GPU judge alone: the CPU one is there, and one llmgw does not know
+	// is not guessed at.
+	if len(fs.started) != 1 || fs.started[0].Name != "qwen3guard-4b" || fs.started[0].GPUClass != "6000-24g" ||
+		fs.started[0].Class != catalog.ClassStandard || fs.started[0].GuardFormat != "qwen3guard" || fs.started[0].CPU ||
+		!fs.started[0].IfAbsent {
+		t.Fatalf("started %+v", fs.started)
+	}
+
+	// Being fetched: not asked for again.
+	fs.running = []modelserve.Job{{Model: "qwen3guard-4b", State: modelserve.Running}}
+	k.check()
+	if len(fs.started) != 1 {
+		t.Errorf("asked for again while it is being fetched: %d", len(fs.started))
+	}
+	// Failed: asked for again only after a while.
+	fs.running = nil
+	now = now.Add(time.Minute)
+	k.check()
+	if len(fs.started) != 1 {
+		t.Error("asked for again at once after it failed")
+	}
+	now = now.Add(judgeRetry)
+	k.check()
+	if len(fs.started) != 2 {
+		t.Error("never asked for again")
+	}
+
+	// Only the leader fetches, and nothing while the guardrails are off.
+	leader = false
+	now = now.Add(judgeRetry)
+	k.check()
+	leader = true
+	off := false
+	lib.Enabled = &off
+	k.check()
+	if len(fs.started) != 2 {
+		t.Errorf("a standby or the guardrails off fetched: %d", len(fs.started))
+	}
+
+	// A CPU judge on a cluster without GPUs is served on CPUs, two of it.
+	lib = guard.Config{Policies: map[string]guard.Policy{"b": {Judge: &guard.JudgePolicy{Model: "qwen3guard-0.6b", Input: "block"}}}}
+	inCatalog = nil
+	k.gpus = func() []adminapi.ClassUse { return nil }
+	k.nodeCPUs = func() []int { return []int{8, 4} }
+	k.check()
+	// Sized as init sizes its two judges: 2 GB, and two cores each on a
+	// cluster whose smallest node has four.
+	if last := fs.started[len(fs.started)-1]; last.Name != "qwen3guard-0.6b" || !last.CPU || last.Replicas != 2 ||
+		last.MemoryGB != judgeMemoryGB || last.CPUCores != refitCores(2, []int{8, 4}) || last.CPUCores == 0 {
+		t.Errorf("CPU judge: %+v", last)
+	}
+	fs.err = errors.New("the mirror is down")
+	lib = guard.Config{Policies: map[string]guard.Policy{"b": {Judge: &guard.JudgePolicy{Model: "qwen3guard-8b", Input: "block"}}}}
+	k.check() // no GPU, so not started, and no panic on the error path either
+}
+
+// A policy moved from Llama Guard's codes to Qwen3Guard would count nothing:
+// its categories become the judge's own.
+func TestCategoriesFollowTheJudges(t *testing.T) {
+	lg := []string{"S1", "S2", "S10"}
+	if got := categoriesFor([]string{"qwen3guard-0.6b"}, lg); !slices.Equal(got, baselineCategories["qwen3guard"]) {
+		t.Errorf("Llama Guard's codes for Qwen3Guard: %v", got)
+	}
+	if got := categoriesFor([]string{"qwen3guard-4b", "qwen3guard-0.6b"}, []string{"Violent", "Jailbreak"}); got != nil {
+		t.Errorf("its own names were replaced: %v", got)
+	}
+	if got := categoriesFor([]string{"llama-guard-3-1b"}, lg); got != nil {
+		t.Errorf("Llama Guard's own codes were replaced: %v", got)
+	}
+	// Both kinds asked in turn: each must have something to count.
+	got := categoriesFor([]string{"qwen3guard-4b", "llama-guard-3-1b"}, []string{"Violent"})
+	if !slices.Contains(got, "Violent") || !slices.Contains(got, "S1") {
+		t.Errorf("mixed: %v", got)
+	}
+	if got := categoriesFor([]string{"our-own-judge"}, lg); got != nil {
+		t.Errorf("a judge llmgw does not know: %v", got)
+	}
+	if got := categoriesFor([]string{"qwen3guard-0.6b"}, nil); got != nil {
+		t.Errorf("no categories (every one counts) became %v", got)
+	}
+}
+
+type fakeProfiles struct {
+	set map[string][]catalog.Profile
+}
+
+func (f *fakeProfiles) SetProfiles(_ context.Context, name string, ps []catalog.Profile, _ string) (catalog.Model, error) {
+	if f.set == nil {
+		f.set = map[string][]catalog.Profile{}
+	}
+	f.set[name] = ps
+	return catalog.Model{Name: name, Profiles: ps}, nil
+}
+
+// A judge that v0.14.6 or earlier's init installed is moved to today's
+// figures, once, and its replicas restarted onto them; one somebody changed
+// is left alone.
+func TestAnEarlierInstallsJudgeIsRefittedOnce(t *testing.T) {
+	lib := guard.Config{Policies: map[string]guard.Policy{
+		"baseline": {Judge: &guard.JudgePolicy{Model: "qwen3guard-0.6b", Input: "block"}},
+	}}
+	earlier := guardModel("http://10.0.0.5:8081/qwen3guard-0.6b/guard/g.gguf", 2, 1, nil)
+	earlier.Profiles[0].MinMemoryGB, earlier.Profiles[0].Args = 4, []string{"--ctx-size", "8192"}
+	inCatalog := []catalog.Model{earlier}
+	fp := &fakeProfiles{}
+	var restarted []string
+	k := &judgeKeeper{
+		library:  func() guard.Config { return lib },
+		models:   func() []catalog.Model { return inCatalog },
+		serve:    &fakeServe{},
+		log:      slog.New(slog.DiscardHandler),
+		profiles: fp,
+		restart:  func(ids ...string) error { restarted = append(restarted, ids...); return nil },
+		replicas: func(string) []string { return []string{"j-1", "j-2"} },
+		nodeCPUs: func() []int { return []int{4} },
+	}
+	k.check()
+	got := fp.set["qwen3guard-0.6b"]
+	if len(got) != 1 || got[0].MinMemoryGB != 2 || got[0].CPUCores != 2 || !slices.Contains(got[0].Args, "--cache-ram") {
+		t.Fatalf("refitted to %+v", got)
+	}
+	if !slices.Equal(restarted, []string{"j-1", "j-2"}) {
+		t.Errorf("restarted %v", restarted)
+	}
+	k.check()
+	if len(restarted) != 2 {
+		t.Error("refitted twice")
+	}
+
+	// Changed by somebody: an extra arg. Left as it is.
+	mine := guardModel("http://x/g.gguf", 2, 3, nil)
+	mine.Profiles[0].Args = []string{"--ctx-size", "16384"}
+	inCatalog = []catalog.Model{mine}
+	fp.set, k.looked = nil, nil
+	k.check()
+	if fp.set != nil {
+		t.Errorf("a judge set by hand was changed: %+v", fp.set)
+	}
+}
+
+func TestAJudgeIsRefittedToTheCoresInitWouldGive(t *testing.T) {
+	for _, c := range []struct {
+		replicas int
+		cpus     []int
+		want     int
+	}{
+		{1, []int{4}, 4},
+		{1, []int{2}, 2},
+		{1, []int{16}, 4},
+		{2, []int{4}, 2},
+		{2, []int{2}, 1},
+		{2, []int{4, 32}, 2},
+		{2, nil, 2},
+	} {
+		if got := refitCores(c.replicas, c.cpus); got != c.want {
+			t.Errorf("%d judges on %v: %d cores, want %d", c.replicas, c.cpus, got, c.want)
+		}
+	}
+}
+
+// Just after the control plane starts, the judge init is adding is left to
+// init: the keeper serves one itself only after its grace.
+func TestTheKeeperLeavesAJustStartedInstallsJudgeToInit(t *testing.T) {
+	lib := guard.Config{Policies: map[string]guard.Policy{"b": {Judge: &guard.JudgePolicy{Model: "qwen3guard-0.6b", Input: "block"}}}}
+	now := time.Date(2026, 10, 19, 12, 0, 0, 0, time.UTC)
+	fs := &fakeServe{}
+	k := &judgeKeeper{
+		library: func() guard.Config { return lib },
+		models:  func() []catalog.Model { return nil },
+		serve:   fs, grace: judgeGrace,
+		gpus: func() []adminapi.ClassUse { return nil },
+		log:  slog.New(slog.DiscardHandler),
+		now:  func() time.Time { return now },
+	}
+	k.check()
+	now = now.Add(judgeGrace / 2)
+	k.check()
+	if len(fs.started) != 0 {
+		t.Fatalf("served within its grace: %+v", fs.started)
+	}
+	now = now.Add(judgeGrace)
+	k.check()
+	if len(fs.started) != 1 {
+		t.Errorf("never served after its grace: %d", len(fs.started))
+	}
+}

internal/cli/judges_known.go

@@ -0,0 +1,160 @@
+package cli
+
+import (
+	"fmt"
+	"slices"
+	"strings"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/catalog"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/modelserve"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/guard"
+)
+
+// knownJudge is a judge model llmgw knows where to fetch and how to serve:
+// what a policy may name without anyone saying where its weights are.
+type knownJudge struct {
+	Name, Repo, File, Format string
+	// GPU is a judge too slow on CPUs to wait for: served on one card.
+	GPU   bool
+	About string
+}
+
+// knownJudges, the default first. Measured on the reference cluster against
+// ordinary coding requests ("continue", "kill the process on port 8080") and
+// harmful ones: Llama Guard 3 1B scored both alike, about one in two
+// ordinary ones refused; Qwen3Guard-Gen 0.6B kept them apart, 0.15 against
+// 1.00 at the worst, at about two seconds a check on two CPU threads.
+var knownJudges = []knownJudge{
+	{Name: "qwen3guard-0.6b", Repo: "mradermacher/Qwen3Guard-Gen-0.6B-GGUF", File: "Qwen3Guard-Gen-0.6B.Q8_0.gguf",
+		Format: "qwen3guard", About: "Qwen3Guard-Gen 0.6B on CPUs, 0.8 GB: the default"},
+	{Name: "qwen3guard-4b", Repo: "mradermacher/Qwen3Guard-Gen-4B-GGUF", File: "Qwen3Guard-Gen-4B.Q4_K_M.gguf",
+		Format: "qwen3guard", GPU: true, About: "Qwen3Guard-Gen 4B on a GPU, 2.5 GB"},
+	{Name: "qwen3guard-8b", Repo: "mradermacher/Qwen3Guard-Gen-8B-GGUF", File: "Qwen3Guard-Gen-8B.Q4_K_M.gguf",
+		Format: "qwen3guard", GPU: true, About: "Qwen3Guard-Gen 8B on a GPU, 4.7 GB"},
+	{Name: "llama-guard-3-1b", Repo: "QuantFactory/Llama-Guard-3-1B-GGUF", File: "Llama-Guard-3-1B.Q4_K_M.gguf",
+		Format: "llamaguard3", About: "Llama Guard 3 1B on CPUs, 0.9 GB: refuses ordinary coding requests"},
+	{Name: "llama-guard-3-8b", Repo: "QuantFactory/Llama-Guard-3-8B-GGUF", File: "Llama-Guard-3-8B.Q4_K_M.gguf",
+		Format: "llamaguard3", GPU: true, About: "Llama Guard 3 8B on a GPU, 4.6 GB"},
+}
+
+const (
+	defaultJudge    = "qwen3guard-0.6b"
+	defaultGPUJudge = "qwen3guard-4b"
+)
+
+// baselineCategories are what the baseline policy counts of each format's
+// verdicts: not PII, which is the patterns', nor what refuses ordinary work
+// — copyright, unethical acts, politically sensitive topics; Llama Guard's
+// defamation, specialized advice, intellectual property and elections.
+var baselineCategories = map[string][]string{
+	"qwen3guard":  {"Violent", "Non-violent Illegal Acts", "Sexual Content or Sexual Acts", "Suicide & Self-Harm", "Jailbreak"},
+	"llamaguard3": {"S1", "S2", "S3", "S4", "S7", "S9", "S10", "S11", "S12"},
+}
+
+// reported is whether a judge of that format ever names category c: its own
+// names, or for Llama Guard its codes.
+func reported(format, c string) bool {
+	if slices.ContainsFunc(guard.DefaultCategories(format), func(n string) bool { return strings.EqualFold(n, c) }) {
+		return true
+	}
+	var n int
+	_, err := fmt.Sscanf(c, "S%d", &n)
+	return format == "llamaguard3" && err == nil && n >= 1 && n <= 14
+}
+
+// categoriesFor is what a policy asking these judges should count, when the
+// categories it has are ones none of them names: a policy moved from Llama
+// Guard's S1 to Qwen3Guard, which says Violent, would otherwise count
+// nothing. Nil keeps what it has; so does a judge llmgw does not know.
+func categoriesFor(judges, have []string) []string {
+	var formats []string
+	for _, j := range judges {
+		k, ok := knownJudgeNamed(j)
+		if !ok {
+			return nil
+		}
+		if !slices.Contains(formats, k.Format) {
+			formats = append(formats, k.Format)
+		}
+	}
+	if len(have) == 0 {
+		return nil
+	}
+	stray := false
+	for _, f := range formats {
+		for _, c := range have {
+			if !reported(f, c) && !slices.ContainsFunc(formats, func(o string) bool { return reported(o, c) }) {
+				stray = true
+			}
+		}
+		// Every judge must have something it counts.
+		if !slices.ContainsFunc(have, func(c string) bool { return reported(f, c) }) {
+			stray = true
+		}
+	}
+	if !stray {
+		return nil
+	}
+	var out []string
+	for _, f := range formats {
+		out = append(out, baselineCategories[f]...)
+	}
+	return out
+}
+
+func knownJudgeNamed(name string) (knownJudge, bool) {
+	i := slices.IndexFunc(knownJudges, func(k knownJudge) bool { return k.Name == name })
+	if i < 0 {
+		return knownJudge{}, false
+	}
+	return knownJudges[i], true
+}
+
+func knownJudgeNames() string {
+	var n []string
+	for _, k := range knownJudges {
+		n = append(n, k.Name)
+	}
+	return strings.Join(n, ", ")
+}
+
+// judgeServeOptions are how a judge is served beyond which weights.
+type judgeServeOptions struct {
+	Replicas, Cores int
+	// GPUClass is the cards a GPU judge runs on; empty lets the plan choose.
+	GPUClass string
+}
+
+// serveRequest is the serve job for a judge. A judge on CPUs is critical,
+// as every judged request waits on it; one on a GPU is standard, so it takes
+// a card only from what may give one up, and the judge on CPUs after it in
+// the policies stands in while it has none.
+func (k knownJudge) serveRequest(o judgeServeOptions) modelserve.Request {
+	req := modelserve.Request{
+		Repo: k.Repo, File: k.File, Name: k.Name, GuardFormat: k.Format,
+		Description: "The guardrails' judge: reads prompts and answers for unsafe content. Not offered to clients.",
+		Replicas:    o.Replicas, CtxPool: 8192, ContextLength: 4096,
+	}
+	if k.GPU {
+		req.GPUClass, req.GPUsPerNode, req.Class = o.GPUClass, 1, catalog.ClassStandard
+		if req.Replicas == 0 {
+			req.Replicas = 1
+		}
+		return req
+	}
+	// Sized as init sizes its judge: the memory it measured to need with
+	// no prompt cache, and the cores its rule gives.
+	req.CPU, req.CPUCores, req.MemoryGB = true, o.Cores, judgeMemoryGB
+	if req.Replicas == 0 {
+		req.Replicas = 2
+	}
+	return req
+}
+
+func (k knownJudge) String() string {
+	where := "CPUs"
+	if k.GPU {
+		where = "a GPU"
+	}
+	return fmt.Sprintf("%s (%s, %s/%s, on %s)", k.Name, k.Format, k.Repo, k.File, where)
+}