v0.14.8: changelog and README

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

.gitea/workflows/ci.yml

@@ -34,7 +34,11 @@ 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 ./...

BACKLOG.md

@@ -15,6 +15,41 @@ Conventions this codebase keeps, which every item here must keep too:
 - `go test ./...`, `go vet ./...` and `govulncheck ./...` pass. No release is
   cut and nothing is deployed to the PoC cluster without being told to.
 
+## Open, in order (2026-10-16, after v0.14.7)
+
+What is left, most needed first. The detail is in the item each names.
+
+1. ~~**J1**~~ — done 2026-10-16: a restart no longer refused for room
+   another restart was giving back.
+2. ~~**J5**~~ — done 2026-10-16: an upgrade refits an earlier install's
+   judge by itself.
+3. ~~**I3**~~ — done 2026-10-16: `ctl bench overhead`, figures in the
+   README.
+4. ~~**I4**~~ — done 2026-10-17: several keys for one outside provider.
+5. ~~**Active Directory and Entra ID**~~ — done 2026-10-18: `auth.ldap`
+   sign-in and sync, Entra's 200-group overflow kept from taking roles.
+   Still to do: try it against a real domain controller (a Samba AD DC
+   on Proxmox): LDAPS, nested groups, a disabled user suspended by the
+   sync.
+6. **J2** — a judge the leader adds by itself is sized as init's is. (S)
+7. **J3** — HA setup puts the judges on nodes of their own. (S)
+8. **J8** — a judge budget that fits the machine, measured at install. (S)
+9. **F5** — large imports limited by the embedding engine's slots. (M)
+10. **I1** — answers to similar questions from the cache. (M)
+11. **J4** — the model mirror on more than one machine. (M)
+12. **I2** — the customer's MCP servers behind llmgw. (L)
+13. Smaller leftovers: audit before/after values, a tenant-admin role and
+    forms hidden from viewers (C1); Parquet and a scheduled push for usage
+    export (C4); English errors on Turkish pages (C24); H1 tried on the PoC;
+    licences in video and audio (H5); nginx in front of several control
+    planes (J7).
+
+Not code, the operator's to decide or do: the PoC on v0.14.7 (it runs a
+v0.14.5 dev build; no hurry); where Alertmanager sends (its receiver is
+"none"). Settled 2026-10-16: Apertus 8B is on demand (min 0); the HA test
+VMs 157–159, 165, 166 and the e2e VMs 151, 153–156 (a v0.11 HA test from
+2026-10-03, idle since, holding 10.0.0.160 with VRRP id 51) were removed.
+
 ---
 
 ## A. Security — do first
@@ -386,10 +421,9 @@ portal is not done — the page shows; the console and ctl change.
    tenant-admin / billing; `ctl audit`. Depends on A5 for a real actor.
 2. **Done (branch `features-c`):** OIDC sign-in (`auth.oidc`, PKCE,
    verified email, roles and memberships from groups, `no_passwords`) and
-   SCIM 2.0 (`/scim/v2` Users and Groups). Left: the sign-in cookie is
-   signed with a per-process key, so with two control planes behind a
-   balancer the callback must reach the one that started it (sticky
-   sessions) until the key comes from the store. **OIDC/SSO login (M), then SCIM (M).** `internal/account/service.go`,
+   SCIM 2.0 (`/scim/v2` Users and Groups). The sign-in cookie's key comes
+   from the store (2026-10-10), so a callback may reach either control
+   plane behind a balancer. **OIDC/SSO login (M), then SCIM (M).** `internal/account/service.go`,
    `internal/web/account.go`; map IdP groups to org/team/admin.
 3. **Done (branch `features-c`):** key lifetime limits (gateway, org, team,
    project), `keys rotate --overlap`, kinds and expiry in `keys list`.
@@ -405,8 +439,9 @@ portal is not done — the page shows; the console and ctl change.
    lost, budget spent, update available; signed JSON or Slack; retries,
    hourly de-duplication), `ctl notify test`, Alertmanager receiver
    templates. Left: `server init` and the console do not yet ask for a
-   receiver — the templates are filled in by hand; each control plane sends
-   budget events on its own, so two behind a balancer may both send one.
+   receiver — the templates are filled in by hand. Events are claimed in
+   the store before they are sent (2026-10-10), so two control planes send
+   each once.
    **Alerting out of the box (S).** `deploy/monitoring/alertmanager.yml`
    ships `receiver: none`; add Slack/email/webhook/PagerDuty receiver
    templates driven by `server init` or the console; llmgw-native webhooks
@@ -569,9 +604,12 @@ portal is not done — the page shows; the console and ctl change.
     client tests against a fake admin API and the OpenAPI document;
     acceptance tests with Terraform and OpenTofu against the fake; one
     apply, empty plan, in-place change and destroy against a real `llmgw
-    server` run by hand. Left: organizations, teams, projects, people and
-    keys are not in the admin API (they are `llmgw org`/`users`/`keys`
-    against the store), so not in the provider; a model's definition beyond
+    server` run by hand. Organizations, teams, projects, keys and
+    memberships are in the admin API since 2026-10-08 (`/api/v1/orgs`,
+    `teams`, `projects`, `keys`, `users/{id}/memberships`) and in the
+    provider (`llmgw_org`, `llmgw_team`, `llmgw_project`, `llmgw_key`,
+    `llmgw_membership`); accounts are still made by sign-up, invitation or
+    OIDC/SCIM. Left: a model's definition beyond
     scaling, class, owner and adapters is changed by replacing it (the API
     has no edit, and `resources` is not used yet); `canary`, `slo`,
     `scaling.schedule` and `prewarm`, `guard` role and `origin` are not in
@@ -793,10 +831,19 @@ leader 30s later with /health answering throughout; rollback did the same.
   facility state from the store (it kept what it read at start).
 - Retires `appendGuardIfMissing` (server init): the import does it.
 
-### E2. Generated files from settings (L) — firewall on/off done 2026-10-06
+### E2. Generated files from settings (L) — firewall on/off done 2026-10-06, every machine 2026-10-09
 `firewall.enabled` in the cluster's settings reaches nodes over the agent
-stream and control planes through llmgw-firewall-sync.path. Left: the mirror
-machine and store members, the allowed set from membership, the other files.
+stream and control planes through llmgw-firewall-sync.path. Since
+2026-10-09 the mirror machine too (the leader PUTs /v1/firewall, the mirror
+writes `.firewall.json`, the same path unit applies it) and store members
+that run no llmgw (the leader keeps it in `cluster_state`, a root timer
+reads the member's own copy with psql); `firewall_networks` reach all of
+them, and the mirror lets in the network of every node and control plane
+the leader knows. Tried on the PoC: off and on, and a network added, on
+control planes, mirror, store member and nodes. Left: the allowed set
+replaced by membership rather than added to (a network taken out of the
+settings stays let in), the other files (the mirror's unit flags,
+keepalived, etcd and Patroni configuration).
 
 Every machine runs the agent (root) with roles — node, control plane, mirror,
 store member — and the agent renders and applies what was written once by
@@ -807,14 +854,34 @@ Patroni configuration. The firewall's allowed set is the cluster's membership
 removed changes every machine's rules. Retires `firewall.Admit` and
 `firewall_networks` in server.yaml (imported into the store).
 
-### E3. agent.yaml down to bootstrap (M)
+### E3. agent.yaml down to bootstrap (M) — done 2026-10-08 (branch `settings-e`)
 agent.yaml keeps the control planes' addresses, its certificate and its id.
 Labels, fabrics, engines, heartbeat and supervisor settings move to the
 store per node and reach the agent over its stream; a change to the file is
 noticed and the agent restarts itself.
+Built as a section of the cluster's settings rather than a store of its own,
+so history, audit, `ctl config`, the console and the portal page cover it:
+`agents.default` and `agents.nodes.<id>` (config.AgentSettings; bootstrap
+keys node_id/server(s)/hostname/mgmt_addr/tls refused; each node's merge
+loaded as an agent would, so a bad fabric is refused on save). A live key:
+the control plane sends ControlMessage.AgentSettings on register and, a
+second apart per node, on change; the agent compares with what it started on,
+checks it loads beside its agent.yaml (else logs and keeps running), keeps it
+in /var/lib/llmgw-agent/agent-settings.yaml and restarts (engines adopted).
+At start: agent.yaml < kept settings < LLMGW_ env; kept settings that no
+longer load are set aside, never a reason not to start. agent.yaml is
+watched every 10 s and restarted on when it changes and loads. Left: file
+keys are not imported into the settings (they keep working under them);
+`node add` still writes a full agent.yaml; labels have two homes now
+(`ctl label`, which wins, and agents.*.labels).
 
-### E4. Web settings page (S)
+### E4. Web settings page (S) — done 2026-10-08 (branch `settings-e`)
 The same document, edited on /admin/settings, for whoever has no terminal.
+Built: administrators only (staff roles get 404: webhook secrets), checked by
+the same function as PUT /api/v1/settings, made from a base version or
+refused on a newer one (the edit kept in the editor), history with view and
+roll back as a new version, audit with the size not the body, English and
+Turkish, a Settings link in the menu.
 
 ---
 
@@ -843,6 +910,12 @@ Built (`internal/store/knowledge.go`, migration 0035 PostgreSQL only):
   partial HNSW index per collection on its organization's partition
   (`embedding::vector(dims)`, `WHERE collection = '<id>'`). EXPLAIN on
   20k rows: partition pruned, that index used, policy applied.
+  Later (scale, 2026-10-08): a partial GIN per collection too
+  (`kb_tsv_<id>`, backfilled at open); `vec_type` per collection, `halfvec`
+  on pgvector ≥ 0.7 (up to 4000 dims); `SET LOCAL hnsw.ef_search` to
+  candidates(k) clamped 40..1000 (EXPLAIN: 40 rows without it, all with
+  it); the text arm takes candidates by `ts_rank` in a subquery and scores
+  only those.
 - RLS FORCEd on `kb_chunks` against `llmgw.kb_org`/`llmgw.kb_collections`
   (set with set_config per transaction), one role — the table owner — not
   a separate one. Chunks are deleted by the foreign-key cascade from their
@@ -985,7 +1058,7 @@ a request without the header, `none` turns it off, an explicit header with
 k=2 gives two sources and no more, llmgw-kb lists owners by path. Left: returned passages
 are not audited per request (the header and the kept request record them).
 
-### F4. Adapter training (L, after F1–F3)
+### F4. Adapter training (L, after F1–F3) — done 2026-10-08 (branch `adapters-f4`)
 A run-to-completion job placed by the control plane like a replica and
 supervised by the agent like an engine, in a Python environment the agent
 installs (TRL + PEFT, QLoRA). Data: Q/A pairs generated from a collection by
@@ -993,12 +1066,606 @@ a cluster model through `/v1/batches`, reviewed by people. Output to the
 mirror, into the model's `adapters`, through canary and a quality suite.
 Runs when the scaling schedule frees a GPU; 8–14B dense bases on one card.
 Never train on a collection some users of the adapter may not read.
+Tried 2026-10-08 on the PoC, by hand: Qwen2.5-0.5B-Instruct (fp16) with a
+LoRA (r=16, every linear layer, 8.8M trainable), trained beside the 35B in
+cuda01's last 2.3 GB (peak 2158 MiB on the card, 64 s for 138 steps, PEFT in a
+venv over the vLLM engine's torch). Data: 90 Turkish Q/A pairs a cluster
+model wrote from the nine Demo/politikalar documents, through the gateway.
+On nine questions it had not seen, phrased otherwise: base 0/9, 6 epochs
+4/9, 4 epochs at a lower rate 2/9. Wrong answers mixed facts across
+documents (the meal card's amount, the office day). The same nine through
+retrieval: 9/9 with sources. So F4 is for format, vocabulary and tone, and
+facts come from F1–F3; a bigger base on a free card would do better but not
+change that. The training itself fits a small slot on a shared card, which
+the job design can rely on for small bases.
+
+Built: `ctl kb dataset` (POST /api/v1/kb/collections/{id}/dataset, NDJSON
+with each pair's collection); train_jobs/train_artifacts (migrations 0037,
+0038 owner); internal/control/train (queue, one job per node, artifacts in
+1 MiB pieces, a node that goes fails its job); internal/agent/train (the
+newest vLLM's python3 + `uv pip install --no-deps --target` peft 0.21.2 and
+accelerate 1.15.0; llama.cpp's conversion code for the installed release,
+untarred from its source; the card with the most free memory, if enough;
+runs as llmgw-engine); `ctl train start|list|show --follow|cancel|rm|
+download|publish`; the mirror's PUT /v1/models/{model}/{version}/{file};
+publish uploads the GGUF (llama.cpp) or PEFT files (vLLM) and sets the
+adapter after checkAdapters. Owners: catalog.Adapter.Owner, enforced in the
+router (404, hidden from /v1/models); a job's owner defaults to its single
+collection's owner, must be able to read every collection the pairs came
+from, and pairs from a knowledge base are never public. Tried on the PoC:
+dataset of 90 pairs in 89 s; a job trained beside the 35B (peak 2214 MiB,
+138 steps in about a minute) and sent back PEFT and GGUF.
+Left: a job dies with its agent's stream (no resume); no console screen for
+training yet; quality gating of a published adapter is by hand (ctl eval).
 
 ---
 
+### F5. Large imports (M) — measured 2026-10-09, open
+The metallurgy corpus (2,314 files, 108,779 chunks, bge-m3 on the one
+GPU) went in at about 25 chunks/s, the same over a phone hotspot and the
+LAN. The engine's slots were the limit: llama.cpp `--parallel 4` embeds
+four texts per pass, while llmgw-kb sends 32 a request from 6 workers. The
+usage rows show 4.6 s a request on average, 1.8 s of it in the gateway's
+queue and 0.04 s in the guard. The GPU sat at 18–50% and the store machine
+at a third of its CPUs.
+- An embedding model's profile with many slots by default (`--parallel`
+  32–64, `--ctx-size` to match, `--batch-size`/`--ubatch-size` at least the
+  longest chunk), or `ctl model serve` choosing that for a model with
+  `capabilities.embeddings`. With the default 512, one 516-token chunk failed.
+- Embedding on the gateway's side of a document PUT, so the client sends
+  text only: today an embeddings answer is ~21 KB of JSON a chunk, and
+  the text and vector go up again (~11 KB).
+- The store next: HNSW inserts took half of one of pg01's two cores; at a
+  million chunks the vectors alone outgrow its 4 GB. halfvec (pgvector ≥
+  0.7) and a larger store machine.
+- Done: a batch of embeddings checked text by text against the context
+  (branch `embeddings-batch`); it was refused as one over-long prompt.
+- Done: `query_prefix` on an embedding model, before questions only.
+- Qwen3-Embedding-4B on the RTX 6000 (2026-10-09): llama.cpp Q8 1,575
+  tok/s as first set up (32k cache, 16 slots), 2,700 with a 16k cache,
+  FlashAttention and ubatch 1–2k; f16 no better. vLLM fp16 (`--runner
+  pooling`) 6,200 direct, 4,700–4,900 through the gateway in the import,
+  and its vectors match llama.cpp's (cosine 0.9995). The 103,579 chunks
+  took 3 h. Done (2026-10-10, branch `admission-bulk`): a source per
+  profile, so an embedding model's GPU profile runs vLLM and its CPU
+  profile llama.cpp; a band's own `queue_ttl` for bulk imports, and
+  `Retry-After` on a busy refusal, which is what had turned passages away
+  (llmgw-kb retries only what says when to).
+- Retrieval on 40 questions written from the corpus, document in the top
+  5: bge-m3 31/40 (Turkish questions 13/21), Qwen3-Embedding-4B 37/40
+  (18/21), with its query prefix 36/40 and first place 31/40 instead of
+  28 (MRR 0.738 → 0.789 → 0.838). Next: translating the question with the
+  chat model, and a reranker.
+
+## G. Jobs: 3D generation through ComfyUI (2026-10-10)
+
+A request for a 3D model takes minutes on the one 24 GB card, and the card has to be
+emptied of the chat model first. That is not a request to hold a socket for
+— `internal/router/activate.go:46` already says so — it is a job: queued,
+answered with an id, asked after, its result downloaded. The job machinery
+is built first and tested without a GPU; the ComfyUI generalisation and the
+custom-node install come after. Decided 2026-10-10: a `jobs` table of its
+own rather than a one-line batch (the JSONL shape would be artificial and
+has nowhere for progress), and progress is shown, not just a status.
+
+Which models (decided 2026-10-10): the assets go into a game sold on
+Steam, worldwide, the EU included, so the licence of the output decides
+before the quality does. Hunyuan3D (every version) is out: Tencent's
+licence excludes the EU, UK and South Korea, and whether a game shipped
+there with its outputs is "use in the Territory" is not a question to
+leave to a court. In, in this order: **TRELLIS.2** shape (MIT; the best
+geometry; its own texture baking goes through nvdiffrec and nvdiffrast,
+both under NVIDIA's non-commercial source licence, so that stage is not
+run), **Step1X-3D** (Apache 2.0, StepFun; shape and texture in one, the
+EU-safe textured path — its ComfyUI node and VRAM need are to be
+checked), **Direct3D-S2** (MIT, DreamTech; high-detail shape, has a
+ComfyUI node) if TRELLIS.2's detail falls short. Not in: TripoSR and
+InstantMesh (permissive but superseded), Stable Fast 3D (Stability's
+community licence, revenue-capped; served all the same since 2026-10-10
+at the user's request, see G3), SAM 3D Objects (Meta's own licence,
+to be read before it is considered). Steam's disclosure form (changed
+2026-01-16) lists pre-generated 3D models as content that must be
+declared on the store page: the licence notice G3 writes into the GLB is
+what the studio answers that form from.
+
+### G1. Jobs: store, worker, endpoints (M) — done 2026-10-10 (branch `jobs-g1`)
+Built as written, with two choices: a job found running after its gateway
+died is run again from the start (the prompt id column is there for G2 to
+follow the same work instead), and the request is validated at the door
+only as far as costs nothing — key, model, allowlist, the request's shape
+— with limits, guardrails and admission applied when the worker replays it,
+said as the job's error. The result file's `content_type` is the job's; the
+files endpoint still serves every file as an octet stream.
+- Store: `jobs` (id, owner key/principal, kind, model, status, input
+  (JSON), progress (JSON: queue position, percent, step), result file id,
+  error, created/started/finished, lease owner/until), migrations for
+  sqlite and postgres beside `internal/store/batches.go`, whose
+  claim/renew/release lease pattern is copied, not shared: a job is one
+  unit of work, a batch is many lines.
+- Worker: `internal/router/jobworker.go` after `batchworker.go`. Any
+  gateway on the store claims a queued job, asks for the model with
+  `activator.Want` and waits as long as it takes (no `ActivationWait`
+  bound: nobody is holding a connection), runs it, stores the output
+  through the files store, writes usage and price, marks it done. A
+  gateway that dies mid-job loses its lease and another one picks it up;
+  the ComfyUI prompt id is in the job row so the second gateway asks
+  after the same work rather than queueing it again.
+- Endpoints: `POST /v1/3d/generations` validates like any inference
+  request (key, allowlist, limits, admission, guardrails on the prompt),
+  writes the job, answers 202 with `{id, status: "queued"}`;
+  `GET /v1/3d/generations/{id}` returns status, progress and, when done,
+  `output_file_id` and the usage; `POST .../{id}/cancel`; the file comes
+  from `GET /v1/files/{id}/content`. Owner-scoped like batches. Results
+  are kept for the batch files' retention and deleted with them: a
+  departure from `images.go`'s "kept nowhere", because a mesh is a
+  download, not a JSON field; the retention is the bound.
+- Done when: a job survives the gateway that took it being killed, a
+  cancelled job leaves ComfyUI's queue (`comfy.Client.cancel`), two
+  gateways never both run one job (test with the lease), and the usage
+  row carries the job's price.
+
+### G2. Progress from ComfyUI (S, after G1) — done 2026-10-10 (branch `jobs-3d`)
+Built as written: the gate's websocket under its own client id, the
+client_id of every /prompt rewritten, /progress/{prompt_id} on the gate,
+the router reading it and /queue into the job (only into a job of the same
+key). Left: a node that reports no steps (TripoSR's) shows its name and no
+percent; a vanished replica is said by the job failing, not by progress.
+The gate (`internal/comfy/gate.go`) passes seven paths and no websocket.
+Rather than open `/ws`, the gate subscribes to ComfyUI's own `/ws` once,
+with `golang.org/x/net/websocket` (already a dependency), under a client
+id of its own, and rewrites the `client_id` of every `/prompt` it
+forwards to that one. It keeps the last `executing`, `progress`
+(value/max/node) and `execution_error` message per prompt id and serves
+them at `GET /progress/{prompt_id}` on the gate; the router polls that
+beside `/history` and `/queue` and writes queue position, percent and the
+current node's class into the job's progress. The gate's buffer is
+bounded (the last N prompts) and the websocket reconnects. Done when a
+3D job shows "queued, 2 ahead" then "running 40%, step 12/30" in
+`ctl jobs` and on the account page, and a job whose replica vanished
+says so within one poll.
+
+### G3. ComfyUI beyond pictures: 3D models and custom nodes (M, after G1) — done 2026-10-10 (branch `jobs-3d`), with TripoSR
+Built: output kinds, image upload through the gate, every output list
+fetched, OBJ to GLB, licence in /v1/models, the job and the GLB, per_mesh
+and usage.meshes (migration 0045), custom nodes cloned at their commit by
+the gate with packages beside the replica (a node's named packages at its
+range, the rest at ComfyUI's versions). Not as written: the model. On the
+PoC's Turing card TRELLIS.2 cannot run — it needs Meta's gated DINOv3,
+its published background remover (RMBG-2.0) is non-commercial, and its
+sparse attention and Direct3D-S2's need flash-attention (Ampere and
+newer). TripoSR (MIT) proves the chain on cuda01: a .glb from a picture
+in about 30 s. Left: background removal before TripoSR (BiRefNet, MIT,
+as a node), TRELLIS.2 or Direct3D-S2 on an Ampere card with an ungated
+encoder, a missing node refusing the replica by name.
+Added 2026-10-10 at the user's request, beside the order above: **Stable
+Fast 3D** as `sf3d` (Stability AI Community License: free under US$1 M
+annual revenue, an enterprise licence above, "Powered by Stability AI"),
+the textured mesh that runs on Turing: about 1 s a mesh warm in fp16,
+UV-mapped GLB with its texture, 18 GB of the card at peak. Its weights are
+gated, so they were fetched once with the user's token into
+/srv/llmgw-comfy/stable-fast-3d and linked into the engine user's
+Hugging Face cache, which its loader node reads by repository name; no
+token is on the machine at runtime. Its own save node returns the GLB as
+base64, which the gate cannot fetch, so `LLMGWSaveMesh` writes the file;
+`LLMGWPrepareForMesh` now also gives the object's mask. Left: its two
+CUDA extensions (texture_baker, uv_unwrapper) are not on PyPI, so they
+were built on cuda01 and installed into the engine's venv by hand; a
+custom node's requirements need a way to name a local build, or the
+engine install must carry them, before a customer site gets this. And
+rembg's default session now fetches BRIA RMBG-2.0 (non-commercial):
+every workflow must name its rembg model (ours say u2net).
+- Catalog: a model makes `pictures` or `meshes` (`MakesImages` becomes an
+  output kind; `ServesComfyUI` stays). 3D weight folders in the gate's
+  `modelFolders`; the workflow's placeholders gain `image` (the input
+  picture, base64 in the request, written to the replica's `input/` by
+  the gate through a new `POST /upload/image` the gate allows — or a
+  base64-loading node, whichever TRELLIS.2's wrapper wants).
+- `comfy.Client.fetch` reads every output key, not `images` only, and
+  fetches each file named by `/view`; `Image` becomes `Artifact` with its
+  content type (model/gltf-binary, application/octet-stream for .obj).
+- Custom nodes: a model (or the engine config) names git repositories
+  and a pip requirements list; the agent's provision step clones them
+  into the replica's `custom_nodes/` (the gate's `--base-directory` is
+  where ComfyUI looks, not the install directory) and installs the
+  requirements into the engine's venv with the same PyTorch index and
+  lock discipline as A8. A replica with a missing node refuses to start
+  with the node's name in the error rather than ComfyUI's traceback.
+- Licence of the output (decided 2026-10-10: it matters). A catalog model
+  carries `license: {name, url, notice}`; a job's answer, `/v1/models`
+  and the portal page show it beside the result, and the mesh's GLB
+  `asset.extras` carries the notice too, since the file travels without
+  the API. What was checked on 2026-10-10: TRELLIS.2 weights are MIT and
+  its outputs free, but its texture baking depends on nvdiffrast, whose
+  NVIDIA Source Code License is non-commercial — a commercial service
+  must render textures another way or skip that stage. Hunyuan3D 2.0 and
+  2.1 claim no rights in outputs, but the licence excludes the EU, UK and
+  South Korea, needs Tencent's permission above 1 M monthly active users,
+  forbids using outputs to train other models, and asks for "Powered by
+  Tencent Hunyuan"; the notice ships with any distribution. TripoSR is
+  MIT, InstantMesh Apache 2.0. Every one of them trained on Objaverse,
+  some of whose objects are CC-BY-NC: a provenance question no licence
+  text settles, to be said in the notice rather than hidden.
+- Pricing: `per_image` stays; `per_mesh` beside it in `accounting.Price`,
+  `Outcome.Meshes`, the usage sums and exports (as eaea671 did for
+  pictures).
+- Done when: TRELLIS.2 on cuda01 with `scaling: {min: 0,
+  idle_timeout: 10m}` makes a .glb from a picture through G1's endpoint
+  with nvdiffrast and nvdiffrec not installed in its venv (the licence
+  is kept by the install, not by a note), the GLB carries the MIT
+  notice,
+  the card is free again after the idle timeout, and the same request
+  against flux-schnell is refused as "makes pictures, not meshes".
+
+### G4. Portal and console (S, after G2) — done 2026-10-10 (branch `jobs-3d`)
+Built: /3d with model-viewer served from the gateway, progress, download
+and licence; `ctl 3d list|get|cancel` over /api/v1/client-jobs (ctl jobs
+was taken by the control plane's own work). Left: the console's Jobs view.
+A 3D page beside `/images` (upload a picture, watch progress, download
+the .glb, a viewer with `<model-viewer>` from the allowed CDNs), `ctl
+jobs list|get|cancel`, the console's Jobs view. The page sends down the
+same path as the API, like `imagesSend` does.
+
+## H. ComfyUI as a platform (written 2026-10-11)
+
+G made one model at a time work: flux for pictures, TripoSR and SF3D for
+meshes, each with its own endpoint, its own request shape and its own
+replica. The user's direction (2026-10-11): llmgw is a generic platform,
+and should serve whatever ComfyUI can run — pictures, edits, video,
+audio, meshes, upscaling, segmentation — as data in the catalog rather
+than code per model. Two decisions shape everything below:
+
+- **The licence is metadata, not a filter.** llmgw does not leave a
+  model out because of its licence. The licence travels with the model
+  and with every file it makes; what a site will not serve is that
+  site's policy (H6). The game studio's EU constraint is one such policy,
+  not a decision the code makes for everyone.
+- **The install fits the hardware.** The PoC has one Turing card; other
+  sites will have Ampere, Ada and Hopper. A catalog entry must be
+  writable once and placed sensibly anywhere: fp16 on Turing, bf16 or
+  fp8 where the card has them, flash-attention models only where it
+  runs, CUDA extensions built for the card that runs them (H2, H4).
+
+The first set of models proves the structure at its corners rather than
+by licence: Qwen-Image-Edit (several weight files, two pictures in),
+Wan 2.2 small (video out, a long job), ACE-Step (audio out), SF3D (a
+package not on PyPI, gated weights), Hunyuan3D (a licence that excludes
+the EU, which H6 must be able to say no to).
+
+### H1. A workflow says what it takes and makes (M) — built 2026-10-11, not yet tried on the PoC
+Built as written, with three choices: a run answers with one file, the
+first of its output kind (several outputs as one zip is left); the
+workflow's placeholders are checked against the inputs when a run is
+served, since the catalog never reads the workflow file; and video,
+audio and files count as nothing in usage until a per-run price exists
+(per_image and per_mesh still count pictures and meshes).
+- Catalog: `comfyui.inputs` — a list of `{name, type, required, default,
+  min, max, choices, max_mb, doc}`, type one of text, int, float, bool,
+  choice, image, mask, audio, video, file. Each is a placeholder of the
+  same name in the workflow. The template's own placeholders are checked
+  against the list when the catalog is built: one the workflow uses that
+  no input or built-in names is refused there, not at the first request.
+- `comfyui.output` gains `video`, `audio` and `files` beside `pictures`
+  and `meshes`; `files` takes whatever the workflow saves. `comfy.Image`
+  becomes `comfy.File` and `typeByName` knows mp4, webm, gif, wav, flac,
+  mp3, ogg.
+- Endpoint: `POST /v1/workflows/runs` with `{model, inputs: {...}}`, a
+  job like G1's (`GET /v1/workflows/runs[/{id}]`, `.../cancel`). A file
+  input is base64, a data URL, or a `file-…` id from `/v1/files` for
+  what is too big to send inline (video, long audio). Files go into the
+  replica's input directory through the gate's `/upload/image`, which
+  ComfyUI uses for any file. `/v1/images/generations` and
+  `/v1/3d/generations` stay as they are, as fixed shapes over the same
+  machinery.
+- The models list (`/v1/models`) gives each ComfyUI model its inputs and
+  output kind, so a client can build a form without reading the catalog.
+- Done when: the existing flux, triposr and sf3d entries work unchanged,
+  and one model with a picture and a text input (Qwen-Image-Edit) runs
+  through `/v1/workflows/runs` with a 400 for a missing required input
+  before any job is written.
+
+### H2. Profiles that fit the hardware (M) — built 2026-10-11
+Built as written. A profile by need is left out of placement until the
+cluster's cards are known: with no class, placement would have read it as
+a CPU profile. A profile's own `source` is loaded under its own file name
+by the workflow's `{{checkpoint}}`.
+- A profile may say `gpu: {min_compute_capability, min_memory_gb}` in
+  place of `gpu_class`. When the reconciler places a model, such a
+  profile stands for every GPU class in the cluster that meets it, at
+  the profile's priority: the catalog function that turns profiles into
+  placement's view takes the cluster's classes (class, compute
+  capability, memory) and returns one concrete profile per class that
+  fits, named `<profile>@<class>`. Placement itself is unchanged: it
+  still sees exact classes, and a tensor-parallel group still never
+  mixes them.
+- A ComfyUI profile may carry its own `comfyui` block (workflow, nodes,
+  checkpoint) over the model's: the fp8 workflow on compute 8.9 and up,
+  the fp16 one on 7.5. A Turing card is not an error, it is the profile
+  that fits it.
+- Done when: one catalog entry with an "ampere+" profile (min 8.0) and a
+  "turing" fallback places the fallback on cuda01, and the same entry,
+  in a test with an A100 in the inventory, places the other.
+
+### H3. Environments: which models can share a replica (S, the catalog side)
+- `comfyui.environment: <name>` puts a model in a named environment.
+  Models in one environment must agree on every custom node they both
+  name (same repository, same commit) and their requirements must
+  resolve together; the catalog refuses an environment that cannot, with
+  both models' names. Models with no environment are each their own, as
+  today.
+- `Catalog.Environments()` returns each environment with its models and
+  the union of their nodes: what one replica of it must install.
+- Placement and eviction of a replica that serves every model of its
+  environment (so flux, SF3D and Qwen-Image-Edit stop handing the card to
+  each other with a 30 s cold start each time) is the other session's
+  work (llmgw-b7), built on this.
+
+### H4. Custom nodes with packages that are built, not downloaded (S) — built 2026-10-11
+Built as written, with `uv build --no-build-isolation` against ComfyUI's
+Python, the card's capability asked of torch in the replica (so
+CUDA_VISIBLE_DEVICES is the card it will run on), and wheels kept under
+the engines' cache by commit, `sm<arch>` and directory. Also
+`comfyui.huggingface_repo`: a node that loads its weights by repository
+name (SF3D's) finds them in the engines' Hugging Face cache, linked by the
+gate, so no token is on the node.
+- `nodes[].build: [subdir, ...]`: directories of the node's repository
+  that are Python packages with C++/CUDA extensions (SF3D's texture_baker
+  and uv_unwrapper). The gate builds each as a wheel with the engine's
+  Python, `TORCH_CUDA_ARCH_LIST` set from the compute capability of the
+  card it runs on, and installs it into the replica's own `site` like
+  any other requirement. Built wheels are kept under the engine's home by
+  node commit, subdirectory and architecture, so the second replica on
+  the same kind of card does not build again.
+- A node needing nvcc on a node without it refuses the replica with that
+  said, not with a compiler's traceback.
+- Done when: SF3D runs on cuda01 with nothing installed into the engine's
+  venv by hand (the hand install of 2026-10-10 removed first).
+
+### H5. Licence on every output (S) — done 2026-10-14: the whole licence in GLB asset.extras and PNG iTXt; video and audio not yet
+- `License` gains `id` (SPDX where there is one, else a lowercase name:
+  stability-community, tencent-hunyuan-community), `commercial` (unset is
+  not said), `excluded_regions` (ISO 3166 codes, `EU` for the union),
+  `revenue_cap_usd` and `attribution` ("Powered by Stability AI"). All
+  optional but the name. Done 2026-10-11 in the catalog, so H6 can match
+  on `id`.
+- Written into the file where the format has a place for it: glTF
+  `asset.extras.license` (as now), PNG an `iTXt` chunk named `license`
+  (the workflow's own text chunks are still stripped), MP4/WebM and the
+  audio formats in their metadata where ffmpeg is at hand on the router,
+  otherwise beside it in the job's answer only — said in the docs.
+
+### H6. Licence choices (S) — done 2026-10-11 (4bbac08), live on the PoC
+The user asked (2026-10-11) for the choice to be a person's: on their
+profile they pick the licences they will not use, and their keys and
+portal session neither see those models in `/v1/models` nor may call
+them (403, saying which licence). Matched on `license.id`, and on
+`commercial` / `excluded_regions` where a choice is put that way. Its
+store table is migration 0046. A site-wide or team-wide default can sit
+on top of it later.
+
+### H7. A job worker per model, not one for all (S) — done 2026-10-14: one job per model at a time, eight in all
+The worker runs one job at a time: a job waiting for the card holds up a
+job for another model that could run now (seen on the PoC, 2026-10-10).
+Jobs are claimed and run concurrently up to a limit per model (or per
+environment, after H3) and a cluster-wide cap, with the lease and
+leader-only rules of G1 kept.
+
+### H8. Presets that add themselves (S) — done 2026-10-13 (v0.14.5)
+flux-schnell and triposr come with llmgw (`ctl model add <preset>`), and
+the leader adds them on demand where a node fits one, the cluster installs
+ComfyUI and the catalog makes nothing of that kind (`presets.auto`); a
+preset removed is declined and not added back. The cluster page and the
+console show and add them.
+
+### H9. Small things learned on the PoC (2026-10-14)
+- Done: `albedo_match` on sf3d (its delighting made dark objects light);
+  `on_demand.evict_after_idle` / `min_lifetime` as live settings; an
+  upgrade that leaves nodes behind says which; `ctl model serve` serves an
+  embedding model for embedding; refreshes wait while a form is filled in.
+- Done 2026-10-15: llmgw's `/mcp` with picture, 3D, VLM and workflow tools,
+  so a client needs no server of its own (asked by the game team); the
+  shared ComfyUI replica (H3's placement side).
+- Done 2026-10-16 (v0.14.6, v0.14.7): setup lists every part with what it
+  is and its settings; three machines each run the control plane, with a
+  floating address (VRRP id from the address); a lost store primary costs no
+  request (3 s connect per member, keepalive and TCP_USER_TIMEOUT, Patroni
+  ttl 20, a standby leaves the lease alone a round after the store returns);
+  a new leader waits for its judge within the budget; a judge is asked again
+  on another machine at half its budget; init sizes the judge (2 GB, no
+  prompt cache, two cores, one judge on up to four cores on one machine).
+
+## I. What other gateways do that llmgw does not (written 2026-10-16)
+
+From a comparison with Bifrost (maximhq/bifrost, Apache 2.0, Go), with
+LiteLLM and Portkey in mind. Bifrost routes to 23+ cloud providers and runs
+no model; llmgw runs the models, so most of Bifrost is either in llmgw
+already (keys, budgets, fallbacks, guardrails, tracing, SSO, HA — the last
+three paid in Bifrost) or does not apply. These four are worth taking for
+a site that runs its own models. Left until a customer asks: native
+Azure/Anthropic/Bedrock/Vertex adapters, request hooks a customer plugs in,
+routing by what a request holds. Not taken: a realtime (WebSocket audio)
+API, prompt management, an `npx` install.
+
+### I1. Answers to similar questions, not only the same one (M)
+The answer cache (`internal/router/cache.go`, C17) answers a request whose
+body is the same byte for byte. A help desk asked "how do I reset my
+password" in forty wordings asks the model forty times.
+- Per project, off by default, beside the exact cache: `llmgw keys cache
+  --project P --similar 0.95` (the cosine similarity a question must reach;
+  higher is stricter). The exact cache is asked first.
+- The question embedded by a model the operator names
+  (`router.cache.embedding_model`, an embedding model in the catalog), into a
+  pgvector table per project with the answer, the model and the TTL; the
+  store's halfvec and text index work from F applies. SQLite stores keep the
+  exact cache only.
+- What counts as the question: the last user turn, with the system prompt
+  and the earlier turns hashed and required to match exactly — a similar
+  question in another conversation is not the same question. Tools,
+  `response_format` and the sampling settings also exact.
+- Said: `x-llmgw-cache: similar` with the similarity, and the usage row
+  says so; guardrails judge the request before a hit, as for the exact
+  cache. A project with `no_store` gets neither.
+- Done when: forty rewordings of one question on the PoC cost one model call
+  and 39 lookups, and an eval suite run with the cache on scores within a
+  point of the run with it off.
+
+### I2. MCP gateway: the customer's tool servers behind llmgw (L)
+`/mcp` serves llmgw's own tools. An agent inside a company also wants Jira,
+the file server, a database — each an MCP server, each today configured
+in every client with its own credentials and nobody seeing what was called.
+- Servers registered once, by an administrator: `llmgw ctl mcp add jira
+  --url https://… --header-file /etc/llmgw/secrets/jira` (HTTP transport;
+  stdio servers run on the control plane under their own user, like an
+  engine). Their credentials stay on the control plane, never in a client.
+- `/mcp` lists every server's tools, prefixed by its name (`jira.search`),
+  filtered by what the key may use: an allowlist per org, team, project or
+  key, by server or by tool, in the tenancy tree as model allowlists are.
+- Each call goes to the audit log — who, which tool, the arguments' size,
+  the outcome and how long — and through the guardrails both ways (a tool's
+  answer is prompt input). A per-tool rate limit.
+- Later, if it earns it: Bifrost's "code mode" (the tools as one typed API
+  the model writes code against), which cuts the tokens of a long tool list.
+- Done when: Claude Code given only llmgw's `/mcp` reaches a test MCP server
+  through it, a key without the grant does not see the server's tools, and
+  every call is in `ctl audit`.
+
+### I3. What llmgw adds to a request, measured (S) — done 2026-10-16
+`llmgw ctl bench overhead` (`internal/cli/bench_overhead.go`): an instant
+engine and the gateway in one process, four modes (direct, bare, auth, auth
+and guard patterns) at rising rates. On an Apple M5 the gateway added
+0.05–0.42 ms at p50 and at most 0.49 ms at p99, in the README.
+`TestTheGatewaysOverheadIsMeasured` runs a second of it in CI with no bound
+asserted. Left: the CPU figure is rough with everything in one process; a
+gateway in a process of its own would measure it properly. The original
+item follows.
+
+Bifrost's headline is "11 µs at 5k RPS" (its own figure, and its own pages
+disagree with it). llmgw has none, so any question about its overhead is
+answered with a guess.
+- `llmgw ctl bench --overhead`: the same load through the gateway and straight
+  at a `sim-engine` (`internal/cli/simengine.go`) that answers at once, at
+  rising request rates, with auth, accounting and the guardrails' pattern
+  checks on and off. Reports the added latency at p50/p99 and the gateway's
+  CPU per thousand requests.
+- On the PoC the CPU is oversubscribed (pve1, 28 threads for ~125 vCPUs):
+  report it as a ratio and record the host's load beside it, and repeat on
+  an idle machine before a figure goes into the README.
+- Done when: the README states the overhead, with how it was measured, and
+  CI runs the short version so a change that doubles it is seen.
+
+### I4. Several keys for one outside provider (S) — done 2026-10-17
+`external.api_key_files` (`catalog.ExternalKey`: file, weight), one endpoint
+each in `control.externalEndpoints`, 401 retried on another key and
+`external_key_refused` notified (`router.keyRefused`). With one key a 401 is
+still the client's. `TestAKeyAtItsLimitOrRefusedIsPassedOverForAnother`. The
+original item follows.
+
+An external model has one `api_key_file` (`internal/control/control.go`,
+where external endpoints are made). A provider's limit is per key; one key
+answering 429 makes the whole fallback answer 429.
+- `api_key_files: [a, b, c]`, each with an optional `weight`: one endpoint
+  per key (`external:<model>#<n>`), so the router's scoring, retries and
+  breakers work per key as they already do per replica. A key answering 429
+  or 401 is passed over while its breaker is open; a 401 also notifies
+  (`external_key_refused`).
+- The usage row says which key answered (by its index, never the key).
+- Done when: with two keys and one returning 429, every request is answered
+  by the other, and the console shows the one breaker open.
+
+## J. Found testing HA and single-machine installs (written 2026-10-16)
+
+Three VMs installed as HA from the setup screens, a fourth as a judge node,
+a fifth as a single 4-core, 8 GB machine; machines powered off under load.
+
+### J1. A restart refused for room another restart was giving back (S) — done 2026-10-16
+Not a wait for ever, as first written: on the 4-core VM the judge's restart
+was *refused* ("fits on no node even with this replica stopped") because the
+starter, restarted at the same time to reserve fewer cores, still held its
+old ones. Once refused, nothing tried again, so the judges kept their old
+figures. Two fixes in `internal/control/reconciler`:
+- a restart whose replacement fits once other restarts under way have gone
+  (queued, retiring or draining) waits for them, up to DrainGrace, instead
+  of being refused (`fitsAfterRestarts`, restart.go);
+- a drained replica counts a retiring one that still answers as serving, so
+  one restart after another no longer leaves the first's drained replica,
+  and the room it holds, waiting out its grace (reconciler.go).
+`TestARestartWaitsForRoomAnotherRestartWillGiveBack` is the 4-core case.
+
+### J2. A judge the leader adds is sized as init's is (S)
+When a policy names a judge the catalog lacks, the leader serves it itself
+(`internal/cli/judgekeeper.go` via `knownJudge.serveRequest` in
+`judges_known.go`, through modelserve). That judge reserves 3 GB (the
+weights, an 8192-token KV cache and a fixed gigabyte), no cores, and runs
+with llama.cpp's prompt cache, which grew one to 3.2 GB. init's judge
+(`guardModel` in `internal/cli/serverinit_cluster.go`) reserves 2 GB and
+its cores and runs with `--cache-ram 0`.
+- `modelserve` gives a guard model `--cache-ram 0`, and the keeper's
+  request the same memory and cores rule as `cpuPlan`.
+- Done when: a judge removed from the catalog comes back with the same
+  figures init would have given it.
+
+### J3. HA setup puts the judges on nodes of their own (S)
+Under load on a 4-core control plane that was also a node, 38 of 60
+requests were refused for want of a judgment. With the judges on a node of
+their own (4 cores, 32 GB, two cores each) the same test refused 2.
+- The HA setup offers a judge node or two: machines given like the store's,
+  added as nodes with a label (`llmgw.role: judge`), and the judge's
+  profile selects that label.
+- Done when: the setup installs the judges on the machines given for them,
+  and the load test above refuses no more than it did by hand.
+
+### J4. The model mirror on more than one machine (M)
+In an HA install the mirror stays on the first machine. While it is down,
+models the nodes already have keep serving and new ones wait for it.
+- A second mirror kept in step (each machine of the store, or one more), the
+  control planes and nodes given both, the first that answers used.
+- Done when: with the first machine powered off, a model added then is
+  fetched and served.
+
+### J5. An upgrade corrects an earlier install's judge (S) — done 2026-10-16
+Built in the judge keeper (`internal/cli/judgekeeper.go`, `refit`), on the
+leader: a judge whose entry is exactly what init before v0.14.7 wrote is
+given 2 GB, `--cache-ram 0` and cores by init's rule (`refitCores`: up to
+four for one judge, two each for more), through `modelsvc.SetProfiles`,
+and its ready replicas are restarted (after J1). Its replica count is left
+as it is. One that differs is left alone and said once in the log. The
+original item follows.
+
+v0.14.6 and earlier installed two judges reserving no cores or one, with
+2 or 4 GB and the prompt cache on. On fewer than eight cores every judgment
+missed its 5 s budget and every request was refused. v0.14.7's notes say
+how to fix it by hand (`ctl model resources`, then `ctl restart`).
+- On upgrade, or on `server init` run again, a judge whose profile is still
+  exactly what an earlier init wrote is moved to today's figures and
+  restarted (after J1). One changed by hand is left alone and named.
+- Done when: a v0.14.6 single-machine install upgraded to it judges within
+  budget without anything typed.
+
+### J6. Rate limits per process (note)
+Rate limits are counted in each control plane's memory. A failover starts
+every key's minute afresh. Documented in install.md; worth a shared count in
+the store only if a customer's limits must hold across a failover.
+
+### J7. nginx in front of several control planes (S)
+`deploy/proxy/Caddyfile` sends to whichever control plane answers `/leader`.
+nginx's open-source build has no active health checks, so its `upstream`
+block would send to standbys and to a lost leader alike.
+- nginx.conf: the floating address as its one upstream, and why; or the
+  `max_fails` passive approach with what it costs.
+
+### J8. A judge budget that fits the machine (S)
+A judgment takes 2.3 s on four cores and 4.2 on two, against the 5 s
+default: two cores are close to it, and a busy machine passes it.
+- At install, after the judge is up, time three judgments. If the slowest is
+  more than half the budget, say so in the plan's closing text with the
+  choices (more cores, a GPU judge, a longer `latency_budget`, `fail:
+  open`). The budget itself is not changed without being asked.
+- Done when: an install on a machine too slow for its judge says so before
+  its first refused request.
+
 ## D. Facts worth knowing before starting
 
-- Admin API: `127.0.0.1:9090`, no auth, `ctlClient` in `internal/cli/ctl.go`.
+- Admin API: `127.0.0.1:9090`, behind the token in
+  `/var/lib/llmgw/admin-token` (A5), `ctlClient` in `internal/cli/ctl.go`.
   Metrics on `:9091` with `/prometheus/targets` beside them.
 - Store: `internal/store`, migrations under `internal/store/migrations/{sqlite,postgres}`;
   the PoC runs PostgreSQL under Patroni.

CHANGELOG.md

@@ -18,12 +18,669 @@ is only released once its **exit criterion** is met, not when its code lands.
 | v0.11.0 | — | High availability from setup, the setup and console screens, usage sums and per-tenant alerts | released |
 | 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 |
-| v1.0.0 | 5 | Tenancy, prefix affinity, benchmarking | planned |
+| 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) |
+| 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 |
 
 Until v1.0.0 the minor version is the breaking one: configuration formats and Go
 APIs change between minors without a deprecation period.
 
+## v0.14.8 — 2026-10-18
+
+Sign-in with an on-premises Active Directory, and Entra ID made safe for
+people in many groups. Also several keys for one outside provider, and a
+measure of what the gateway adds to a request.
+
+**Upgrading.**
+- Migration 0048 adds the `user_directory` table, applied when the control
+  plane starts.
+- Nothing changes until `auth.ldap` is set; docs/install.md, "Active
+  Directory", has an example. It has been tested against a fake directory,
+  not yet against a real domain controller.
+- A judge installed by an earlier `server init` is refitted by the leader
+  by itself (below); the steps given for v0.14.7 are no longer needed.
+
+### Added
+
+- **Sign-in with Active Directory** (`auth.ldap`). People sign in on the gateway's form with their AD username or mail
+  and password, checked against the domain controllers over LDAPS or StartTLS. Groups, nested ones included, give
+  staff roles and places in the tree, as with OIDC. Accounts are tied to the `objectGUID` and made at first sign-in
+  when `create_accounts` is on. Every 15 minutes the leader reads the directory. People disabled or deleted there are
+  suspended and reinstated when they come back; roles and memberships follow their groups. A sync that would suspend
+  more than half the accounts is refused. See docs/install.md, "Active Directory".
+
+- **Several keys for one outside provider.** An external model takes `api_key_files`, each with an optional weight, in
+  place of `api_key_file`. Each key is an endpoint of its own (`external:MODEL#1`, `#2`), so a key answering 429 is
+  passed over while its breaker is open and the request goes to another. A key answering 401 is passed over too, and
+  `external_key_refused` is sent, naming the endpoint, never the key. Usage records which key answered by that name.
+
+- **`llmgw ctl bench overhead`**: what the gateway adds to a request, measured against an engine that answers at
+  once. Gateway and engine run in one process on loopback, so no cluster is needed. The load is sent straight to the
+  engine and through the gateway: bare, with authentication and accounting, and with the guardrails' pattern checks.
+  It reports p50 and p99 latency, what the gateway added, and a rough CPU per thousand requests. On an Apple M5 the
+  gateway added 0.05–0.42 ms at p50 and at most 0.49 ms at p99 (README).
+
+### Fixed
+
+- **Entra ID's groups past 200 no longer take a role away.** For someone in more than 200 groups Entra sends none in
+  the token, only a pointer to Graph. That was read as no groups, so an administrator lost their role at the next
+  sign-in. Their role and memberships are now left as they were, and an error is logged saying what to change in the app
+  registration. docs/install.md has an Entra ID section.
+- **An account made by SCIM or OIDC could not be reinstated.** Setting it active was refused as "never approved".
+- **An upgrade refits the judge an earlier `server init` installed.** Upgrading to v0.14.7 left such a judge as it was:
+  no cores or one, 2 or 4 GB, the prompt cache on. On fewer than eight cores every request was refused until it was
+  fixed by hand. Now the leader finds a judge whose entry is exactly what an earlier init wrote and gives it 2 GB, no
+  prompt cache and cores by today's rule (up to four for one judge, two each for more). It then restarts the judge's
+  replicas onto that. The number of replicas is left as it is. A judge whose entry was changed by hand is left alone,
+  and the log says so once.
+- **A restart is no longer refused for room another restart is giving back.** With every core of a node reserved, two
+  models restarted together, one to need more and one less (as after `ctl model resources` on a judge and a starter),
+  had the first refused: "fits on no node even with this replica stopped", though the second was about to give back
+  its cores. A restart now waits for other restarts under way, up to the drain grace, before it is refused. A drained
+  replica also counts a replica being restarted that still answers as serving, so replicas restarted one after
+  another no longer wait out the five-minute grace each.
+
+## v0.14.7 — 2026-10-16
+
+The judge installed by `server init` sized for what it does. On a machine
+of fewer than eight cores v0.14.6 left every judgment past its budget, so
+`fail: closed` refused every request. A single-machine install of v0.14.7
+on a 4-core VM passed 20 of 20, and on 8 cores 20 of 20 under load.
+
+**Upgrading.**
+- No migration.
+- **Upgrading does not change a judge already in the catalog.** v0.14.6
+  and earlier installed two judges, reserving no cores or one, and 2 or
+  4 GB. To give them what they need:
+  `llmgw ctl model resources qwen3guard-0.6b --memory 2 --cores 2`, then
+  `llmgw ctl restart --model qwen3guard-0.6b`. The two then need four cores
+  on a single machine; below that, a longer `latency_budget` or
+  `fail: open`.
+- On a node whose cores are all reserved, `ctl restart --model` cannot
+  start the new replica beside the old one and waits. Stop the old engine
+  process, and the replica comes back with the new figures.
+
+### Fixed
+
+- **Both judges fit an 8 GB machine again.** v0.14.6 had `server init` reserve 4 GB a judge replica. That figure came
+  from one replica at 3.2 GB after a day of traffic. The growth was llama.cpp's prompt cache, up to 8 GB by default,
+  which a judge never reuses: each text it reads is different. On a 4-core, 8 GB machine the second judge then fitted
+  nowhere ("has 7 GB of memory with 1 free, needs 4"). The judge now runs with `--cache-ram 0`, uses about 1.6 GB and
+  stays there, and reserves 2.
+- **One machine runs one judge, on up to four cores.** A second replica on the same machine shares its cores and is
+  lost with it, so it bought nothing but half the speed of each. `server init` on a single machine now serves one judge
+  on up to four cores (2.3 s a judgment where two on two cores took 4.2). Where there will be other nodes, it serves two
+  on two cores each, as in HA setups. `--judge-replicas` and the setup's Copies still choose.
+- **A judge gets the two cores it needs.** v0.14.6 gave each judge replica one core on machines under eight. A judgment
+  of about 280 tokens takes 8.0 s on one core, 4.2 s on two and 2.3 s on four, against the 5 s budget, so on a 4-core
+  machine every judgment timed out and every request was refused. Where there are two judges, each now reserves two
+  cores (one only below four CPUs), and the one judge of a single machine up to four; the starter has what is left, or
+  shares when nothing is. A judge on two cores stays close to its budget: give it more cores or a GPU, or raise
+  `latency_budget`, where requests must not wait.
+
+## v0.14.6 — 2026-10-16
+
+Setup that says what each part of an install is and lets every one be
+chosen and set; three machines that each run the gateway, so any one can
+be lost; a cluster that loses its store's primary without losing a
+request; one ComfyUI for an environment's models; pictures, 3D and
+workflows as MCP tools; alerts asked for at setup; extended thinking.
+
+**Upgrading.**
+- No migration.
+- **Control planes**: with `control.lease_ttl` unset the lease is now 10 s
+  (was 15). Upgrade the standbys first and the leader last; a mix of
+  versions meanwhile is fine.
+- **The store** (PostgreSQL): each member is dialled for 3 s before the
+  next is tried. A store so far away that connecting takes longer needs
+  `connect_timeout=10` in its address.
+- **Nodes** notice a control plane that died without closing its
+  connection in 8 s (was 15) once they run this release.
+- **Judges installed by an earlier `server init`** keep reserving no cores
+  and 2 GB. To give them their own:
+  `llmgw ctl model resources qwen3guard-0.6b --memory 4 --cores 2`, then
+  `llmgw ctl restart --model qwen3guard-0.6b`.
+- **Patroni** replaces a lost primary within 20 s on a new cluster. On an
+  existing one, run `server init --patroni ...` again from the machine with
+  the authority; it changes only that.
+- **A floating address** keeps VRRP router id 51 until `server add --vip`
+  runs again, which moves it to one of its own; run it for every standby.
+- A request whose judge is not there yet waits up to the policy's
+  `latency_budget` for one before `fail: closed` refuses it.
+
+### Added
+
+- **Setup lets every part be chosen, each with its settings, and says what each is.** `sudo llmgw` on a new machine lists
+  the parts of an install: the control plane, the store, the model mirror, this machine as a node, the starter model,
+  pictures and 3D, the guardrails' judge, the firewall, notifications, limits and keys, on-demand turns, an offline
+  bundle. Beside each is what it will be or what is missing without it. Space turns a part on or off, and Enter opens
+  its settings in a dialog that explains it at more length. The settings are: which starter model (six Qwen sizes, or
+  any GGUF on Hugging Face) and its context; the mirror's directory or another machine's mirror; the judge's
+  categories, copies, wait and what happens when it does not answer; the portal's language; the sign-up form; the
+  default limits; the longest a key lives; the on-demand waits. A plan page then lists what is installed and what is
+  left out, with the same install as a command. Every setting is a `server init` flag too (`--starter`,
+  `--judge-fail`, `--media`, `--max-key-ttl`, ...).
+- **Three machines are high availability for the gateway, not only the store.** With three machines, setup makes the two
+  database machines control planes too, standing by while the first leads, with an optional floating address
+  (keepalived) that follows whichever leads. Any one machine can now be lost. By command: `server init --patroni ...
+  --standbys --vip 10.0.0.160/24`. The mirror's management API answers the three control planes, so a standby that
+  comes to lead can still fetch models.
+
+- **Pictures uploaded to work from**: `/v1/files` takes `purpose=vision` or
+  `user_data` besides `batch`, kept as long as job results, so a picture is
+  sent once and named by its `file-…` id in the MCP tools and a workflow's
+  inputs.
+- **One ComfyUI for an environment's models**: ComfyUI models in one
+  `comfyui.environment` (two or more) share one replica — the catalog
+  makes it a hidden entry, `comfyui-env-<name>`, on the first member's
+  profiles with the most memory any member needs, carrying every member's
+  weights and custom nodes. Asking for any member starts it; it answers for
+  each with that member's workflow and checkpoint, and the members get no
+  replicas of their own. A picture model and a 3D model on one card stop
+  handing it to each other with a cold start each way.
+- **Pictures, 3D models, vision and workflows as MCP tools** at `/mcp`,
+  beside the memory notes, each offered only where the gateway has a model
+  for it: `generate_image` (with `concept`, `side` and `texture` styles),
+  `generate_mesh` (from a picture or a prompt), `review_images` (a vision
+  model, to a JSON schema), `run_workflow`, `job_status` and
+  `gateway_status`. Each makes its request under the caller's key, so
+  allowlists, limits, licences and budgets apply and it is charged like
+  any request; what it makes is kept as the caller's file and answered by
+  id and download URL. A client that takes a stream gets
+  `notifications/progress` while a mesh is made and waits up to ten
+  minutes; one that does not, 50 seconds, then the job id.
+- **Setup asks where alerts go**: `llmgw server init --webhook URL`
+  (repeatable) and a **Notification webhooks** field on both setup screens.
+  Slack's, Mattermost's and Rocket.Chat's addresses are sent Slack's text,
+  any other the event as JSON (`slack:` or `json:` in front says which).
+  They are added to the cluster's `notify.webhooks` beside those already
+  there, and each is sent a test once the control plane runs on them.
+
+- **Extended thinking on `/v1/messages`**: `thinking: {type: "enabled"}`
+  tells a model that thinks by its chat template to (`enable_thinking`),
+  and its reasoning comes back as `thinking` blocks before the text,
+  streamed as `thinking_delta` events; `disabled` tells it not to. Not
+  asked for, the reasoning is left out as before.
+- **How long on-demand models hold a card** is a setting, in force on the
+  leader within seconds: `on_demand.evict_after_idle` (2m unless set) and
+  `on_demand.min_lifetime` (5m). On one card shared by a picture model and
+  a 3D model, 1m each brings the wait between a picture and its mesh to
+  about a minute.
+
+### Fixed
+
+- **The judges and the starter model divide a machine's CPUs instead of each taking all of them.** `server init` gave the
+  judge and the starter no cores of their own, so every llama.cpp engine ran on every core: two judges and the starter
+  on a 4-core control plane competed, and under load 38 of 60 requests were refused for want of a judgment. Moved to a
+  node of their own with 2 cores each, the same test refused 2. When this machine is the node, init now gives each judge
+  replica 1 core (2 from 8 cores) and the starter what is left (at most 8); judges bound for other nodes get 2 each. A
+  judge also reserves 4 GB, not 2: it uses about 3.2.
+
+- **A lost store machine stops costing requests most of a minute.** The store's connections try each member for 3 seconds,
+  not until the kernel gives up, and a connection to a machine that is gone is closed within about 10 seconds (TCP
+  keepalive, and `TCP_USER_TIMEOUT` on Linux). Patroni replaces a lost primary within 20 seconds (`ttl` 20, `loop_wait`
+  5, `retry_timeout` 5). Running `server init --patroni` again applies this to an existing cluster. Measured on three
+  VMs with the primary's power cut: about 45 seconds of hanging requests before.
+- **Leadership stays put while the store's primary is replaced.** Replacing a lost primary takes longer than the
+  leadership lease lives, so the lease had lapsed for everyone by the time the store answered again. Whoever asked first
+  took it, as often a standby as the leader. A standby that saw the store out of reach now leaves the lease alone for one
+  round after it returns, so the leader renews it, and a leader that is truly gone is replaced a round later. With that,
+  the default lease is 10 seconds (was 15). A node notices a control plane that died without closing its connection in
+  8 seconds (was 15), so it is on its way to the new leader as that one takes over.
+- **A judge replica that hangs no longer costs the request.** All the tries of a judge request shared the policy's
+  budget, so a replica that hung used it all and the try on another replica had none left: under `fail: closed` the
+  request was refused while a judge stood idle. When the first replica has not answered by half the budget, the same
+  question now goes to a replica on another machine too, and the first answer is taken. The first replica is not cut
+  short, which on a slow machine would refuse answers it was about to give. Replicas on one machine whose CPUs are taken
+  are slow together, so asking both only doubles the work there: measured that way, as many requests failed as before.
+  On such a machine the remedy is room, not a second question: judges on more than one node, more cores, or the judge
+  on a GPU.
+- **A new leader waits for the judge instead of refusing at once.** The moment a control plane takes the lead it knows no
+  judge yet. When every judge fails at once, they are asked again every 250 ms while the policy's `latency_budget` lasts,
+  so `fail: closed` no longer answers every request in those seconds with 503 (about 17 seconds of them in the test). A
+  judge that is slow is not asked again, and an alarm is raised once per request, not once per try.
+
+- Node discovery for Prometheus listed only the control plane asked and the
+  store, so a machine that is both was a control plane to one and a store
+  member to the other — scraped twice — and a standby asked alone lost every
+  node. Every control plane lists all of them alike; deploy/monitoring's
+  prometheus.yml says to scrape and ask each.
+- A model whose weights and context pool did not fit its card was added
+  and then failed to make its context on every start, taking the card from
+  others each time (Apertus 70B with a 65536-token pool, 8B with 131072, on
+  24 GB). `ctl model serve` shrinks the pool to what the card holds, saying
+  so, and refuses weights that do not fit at all; the portal's serve form
+  refuses such a pool and says the largest that fits.
+- Removing weights from the mirror that a catalog model still loads is
+  refused, naming the model: removed from the mirror alone, the model stayed
+  in the catalog and its replicas went on loading the node's copy.
+- Jobs ran one at a time, so a 3D job waiting for the card held up another
+  model's job that could have run. They run side by side, one per model at
+  a time and eight in all, on the leader as before.
+- `llmgw ctl model serve` served an embedding model as a chat model: no
+  `--embedding`, four slots, a 512-token batch, `embeddings` unset and a
+  "say hello" smoke test it could not pass. A model whose GGUF says it
+  pools (or `--embeddings`) is served for embedding: 32 slots of 1024
+  tokens unless sized otherwise, a batch that holds a whole passage, and
+  one vector asked for as its smoke test.
+- `llmgw ctl upgrade` checks every node's version once the waves are done
+  and fails naming any not on the release, and says when the control plane
+  has no nodes registered; `llmgw upgrade` on a control plane says how many
+  nodes it left behind and the command that upgrades them. A site's nodes
+  stayed a release behind with nothing to say so.
+- The cluster and node pages swapped their live part every few seconds,
+  forms and all, so filling one in raced the clock: what was typed, an
+  open choice and the focus were lost. The refresh now waits while a field
+  in it has the focus or a form in it has been typed into and not sent;
+  the mirror page's reload during a download waits the same way.
+
+## v0.14.5 — 2026-10-14
+
+Picture and 3D models that add themselves where a card fits them, with a
+card on the portal and a screen in the console to see and add them; a
+mesh's colour brought to the picture it was made from; and the whole
+licence written into every mesh.
+
+**Upgrading.**
+- The store gains a table (migration 0047: preset_state); nothing to do.
+- **`presets.auto` is on**: once upgraded, the leading control plane adds
+  flux-schnell and triposr, on demand, where a node's card fits one, the
+  cluster installs ComfyUI (`engines.comfyui`) and the catalog makes
+  nothing of that kind. Nothing is fetched until somebody asks for one.
+  Turn it off with `llmgw ctl model presets auto off`.
+- **Nodes** need this release for `albedo_match` (it is in the save node
+  the gate puts in each replica); a ComfyUI replica takes it when it
+  starts again.
+
+### Added
+
+- **A mesh's base colour brought to its picture's**: `LLMGWSaveMesh` takes
+  `albedo_match` with the picture and its mask, and scales the texture in
+  linear light to the object's brightness in the picture. Stable Fast 3D
+  takes the light out of what it sees and read a dark basalt (0.17) as a
+  light stone dimly lit (0.67); matched, it is 0.17. On sf3d it is the
+  `albedo_match` input (off unless asked).
+- **Picture and 3D models by themselves**: once a node has a card that fits
+  flux-schnell or triposr and the catalog makes nothing of that kind, the
+  leading control plane adds the preset on demand — so a new cluster's
+  portal has its Images and 3D pages without a definition written — where
+  the cluster installs ComfyUI. `presets.auto` turns it off; a preset
+  somebody removes is not added back. `GET /api/v1/presets` says how each
+  stands and why one is not added; `POST /api/v1/presets/{name}` adds one
+  (and sets `engines.comfyui` if the cluster has none); `PUT
+  /api/v1/presets/auto`. Each automatic addition is in the audit log.
+- **Presets on the portal and in the console**: the cluster page's
+  **Pictures and 3D models** card lists each preset — what it makes, the
+  classes it fits here, whether and by whom it was added, why the leader
+  has not — with an **Add** button that says first when it would install
+  ComfyUI and restart the control planes, and the switch for `presets.auto`.
+  The console's models screen shows the same; **A** adds one, **P** flips
+  the switch. `ctl model add PRESET` and `ctl model presets` go through the
+  API (and `ctl model presets auto on|off`), falling back to the entry as
+  v0.14.4 sent it on an older control plane.
+
+### Fixed
+
+- A mesh carried only its licence's name, URL and notice; it carries the
+  whole licence as `/v1/models` gives it — id, commercial use, excluded
+  regions, revenue cap, attribution — for a pipeline that sorts assets by
+  licence.
+- A workflow's `{{name|false}}` default filled a BOOLEAN input with the
+  word rather than a boolean.
+
+
+## v0.14.4 — 2026-10-13
+
+Any ComfyUI workflow as a job, with typed inputs; picture and 3D models
+added by name; profiles that fit whatever card a site has, and ComfyUI on
+a V100; licences a machine can match and a person can leave out; a job
+waiting for the one card says what holds it. Many fixes to on-demand
+models taking turns on one card.
+
+**Upgrading.**
+- The store gains a table (migration 0046: user_excluded_licences);
+  nothing to do.
+- **Nodes** need this release for ComfyUI on Volta or Pascal cards (the
+  cu126 build), for a driver from NVIDIA's open kernel module to be read,
+  and for a node that loads its weights by repository name (sf3d); a
+  ComfyUI already installed is kept.
+- **Control planes before nodes**: an entry using the built-in `triposr`
+  workflow, or a `gpu:` need instead of a class, is refused by an older
+  control plane.
+- Models added with `llmgw ctl model add <preset>` take the preset's name;
+  remove an entry of that name first.
+
+### Added
+
+- **The client API described**: OpenAPI 3.1 at `/v1/openapi.json`, no key
+  needed, generated from a route table a test holds to the router's own;
+  and `/docs/api`, Swagger UI (served from the gateway) over it and, for
+  staff, over the admin API's document.
+- **A job waiting for the card says so**: `progress` is
+  `{"state":"waiting_gpu","held_by":…,"eta_seconds":…}` while another
+  on-demand model holds it; a direct request's 503 carries
+  `X-Llmgw-Waiting-For` and `X-Llmgw-Eta-Seconds`.
+- **Any ComfyUI workflow, as a job**: `POST /v1/workflows/runs` with
+  `{model, inputs}`. A model's catalog entry declares its inputs
+  (`comfyui.inputs`: text, int, float, bool, choice, image, mask, audio,
+  video, file, with bounds and defaults) and its output (`comfyui.output`:
+  pictures, meshes, video, audio or files); a request is checked against
+  them before a job is written, file inputs are base64, a data URL or a
+  `/v1/files` id, and `/v1/models` lists each model's `workflow` so a
+  client can build its form. A PNG result carries the licence in an
+  `iTXt` chunk, a GLB in `asset.extras` as before.
+- **Environments**: `comfyui.environment` names ComfyUI models that agree
+  on their custom nodes and may share one replica; the catalog refuses
+  one that cannot.
+- **Profiles that fit the hardware**: a profile may say `gpu:
+  {min_compute_capability, min_memory_gb}` instead of `gpu_class`, and
+  stands for every class in the cluster that meets it, as
+  `<profile>@<class>`; a ComfyUI profile may carry its own `comfyui`
+  workflow, checkpoint and nodes, and any profile its own `source`. One
+  catalog entry then runs fp8 where the card has it and fp16 on Turing.
+- **Custom nodes that compile**: `nodes[].build` names directories of a
+  node that are C++/CUDA packages; the gate builds each as a wheel for the
+  card the replica runs on, keeps it on the node, and installs it beside
+  the replica. `comfyui.huggingface_repo` shows a model's weights to a node
+  that loads them by repository name.
+- **A licence a machine can match**: `license.id`, `commercial`,
+  `excluded_regions`, `revenue_cap_usd`, `attribution`.
+- **On-demand models in `/v1/models`**, with `loaded` saying whether one is
+  up now; a picture is cut out and put on grey before TripoSR sees it
+  (`LLMGWPrepareForMesh`, rembg when it has no alpha).
+- **Licences a person leaves out**: on the profile page, by licence, or by
+  rule — every licence forbidding commercial use, every licence granting
+  nothing in a region — so a model under one is neither listed to nor
+  served for that person's keys and sessions (403 `licence_excluded`).
+- **Presets: a picture or 3D model added by name.** `llmgw ctl model add
+  flux-schnell` or `triposr` adds an entry that comes with llmgw — its
+  workflow (TripoSR's now built in), custom nodes, packages and licence,
+  and a profile by card need rather than class — and has the nodes install
+  ComfyUI when the cluster's settings name none. `llmgw ctl model presets`
+  lists them; the console's **A** on the models screen offers them beside
+  a definition file.
+
+### Fixed
+
+- A model waiting for another on-demand model to give up the card failed at
+  once as "cannot be placed"; it now waits, and a job with it.
+- A model evicted for being idle was placed again on the next pass, ahead of
+  the one it made room for.
+- A job or batch leased by a standby control plane, whose router has no
+  endpoints, waited on "loading" for good; they are served only by the
+  leader. A job told its model fits nowhere asks again for five minutes
+  before failing, which an agent re-registering makes true for seconds.
+- An on-demand replica adopted after a restart was never idle enough to
+  evict, so a model waiting for its card waited out its whole idle timeout;
+  it counts as used at adoption.
+- A picture in a prompt was counted as its base64 by the context check, so
+  one 1280x720 PNG was "138 thousand tokens" and a vision model refused it;
+  a picture or a sound now counts as about a thousand.
+- An on-demand model of a higher class was evicted, idle, for a lower-class
+  one two minutes into a lull; it keeps the card through its idle timeout,
+  and a model waiting on it is told so.
+- A model removed from the catalog stayed wanted, so added again it loaded
+  unasked.
+- A node that loads its weights by repository name (sf3d) went to Hugging
+  Face for a gated repository and got a 401: the agent did not hand the
+  gate `comfyui.huggingface_repo`, so the weights on the node were never
+  linked into its cache.
+- **ComfyUI on a V100.** torch's CUDA 12.8 and newer builds have no Volta
+  kernels, but its cu129 build was taken to run from compute capability
+  7.0, so on a V100 both ComfyUI builds were installed, about 10 GB each,
+  and failed with "no kernel image". Cards older than Turing now get
+  ComfyUI on PyTorch's CUDA 12.6 torch (build `cu126`); a Turing or newer
+  node keeps the build it has.
+- **The open NVIDIA driver read by its version.** With the open kernel
+  module, the default since 560, the agent read the driver as "for" and so
+  as unknown, and tried every engine build whatever driver it needs.
+
+## v0.14.3 — 2026-10-10
+
+3D models from a picture, as jobs: made by ComfyUI on the cluster's cards,
+with their progress, their licence written into the mesh, a price per mesh
+and a page to make them. Also: a profile's own weights, a band for bulk
+work, and fixes for control planes behind a balancer and agents that
+restart.
+
+**Upgrading.**
+- The store gains tables and columns (migrations 0043–0045: notify_sent,
+  jobs, usage meshes); nothing to do.
+- **Nodes** need this release for their engines' output to survive an
+  agent restart and for ComfyUI's custom nodes and progress; engines
+  started by an older agent keep its pipe until they are restarted.
+- A 3D model needs a model that makes them (see install.md, "A model that
+  makes them"); none is added.
+
+### Added
+
+- **Jobs: 3D models asked after, not waited for.** `POST
+  /v1/3d/generations` answers 202 with a job id; `GET
+  /v1/3d/generations/{id}` says its status, progress and, when done, the
+  file its result is in (`/v1/files/{id}/content`); `POST .../cancel` stops
+  it, in the engine's queue too. The request is replayed by whichever
+  gateway holds the job's lease through the same path a client's request
+  takes — key, allowlist, limits, admission, guardrails, accounting — so
+  it is charged like any request, tagged `job=<id>`, and a model still
+  loading is waited out for as long as the job has (24 h) rather than
+  refused. A job survives the gateway that took it; results are kept for
+  `router.batch.retain_days`. Migration 0044.
+- **ComfyUI models that make meshes** (`comfyui.output: meshes`). The
+  picture is uploaded to the replica's ComfyUI and the workflow's
+  `{{image}}`; the mesh the workflow saves is the job's file, an OBJ turned
+  into a GLB. TripoSR (MIT) is the tested model; on Ampere and newer cards
+  stronger ones can be added the same way.
+- **Custom nodes** (`comfyui.nodes`): a repository at a full commit, put in
+  each replica's own `custom_nodes` by the gate, with its packages
+  installed beside the replica, never into ComfyUI's environment.
+- **A job's progress**: the gate listens to ComfyUI's websocket and the job
+  says queued and how many ahead, then the node running, its step and
+  percent.
+- **A model's `license`** (name, url, notice), in `/v1/models`, in the job,
+  on the portal and in the GLB's `asset.extras`.
+- **`per_mesh`** in `auth.pricing`; usage rows, sums and exports count
+  `meshes`.
+- **`/3d` on the portal**, beside `/images`: a picture chosen, the job
+  followed, the mesh in a viewer with a download and its licence; and
+  **`llmgw ctl 3d list|get|cancel`** for every owner's jobs.
+- **A profile's own `source`**: the weights it loads instead of the
+  model's, so an embedding model can run on vLLM from its repository on a
+  card and on llama.cpp from a GGUF on CPUs as one model. Placement prefers
+  nodes holding each profile's weights, `ctl model add` checks every
+  source, and `ctl weights` collects none a profile loads.
+- **A band's own `queue_ttl`** (`router.admission.bands[].queue_ttl`): how
+  long its requests may wait for room, instead of the admission's 30 s. A
+  band for bulk work — a knowledge-base import — waits behind people rather
+  than being turned away.
+
+### Fixed
+
+- **An engine's output no longer breaks when its agent restarts.** Engines
+  wrote to a pipe of the agent's, which an agent that restarted and adopted
+  them left with no reader; an engine's next large write failed, and in a
+  Python engine took the request it was reporting on with it. Each process
+  now writes to its own file in the agent's work directory, and an adopted
+  engine's log keeps what it wrote before the restart.
+- **Single sign-on behind a balancer.** The cookie that carries a sign-in
+  across the identity provider was signed with a key of each process's own,
+  so with two control planes a callback that reached the other one was
+  refused. The key is now a secret in the store, the same on every control
+  plane.
+- **Notifications sent once by two control planes.** Each kept its own
+  hour of quiet per event, so a budget spent on a team both served was
+  announced twice. The control plane that claims an event in the store
+  (migration 0043) sends it; with the store unreachable it is sent anyway.
+- **A request turned away for a busy cluster says when to come back.** A
+  request that waited as long as it may (504) or found the queue full (503)
+  had no `Retry-After`, so `llmgw-kb` counted the passage as failed instead
+  of sending it again; both now say 10 seconds.
+- The usage sums and exports count pictures (`images`), as the request
+  records did; pictures made before are added to the sums.
+
+## v0.14.2 — 2026-10-10
+
+Pictures: OpenAI's `/v1/images/generations`, made by ComfyUI on the
+cluster's own cards. The agents install ComfyUI themselves, the gateway
+prices pictures by the picture, and the portal has a page to make them.
+Also: on-demand models that survive a failover, and knowledge-base
+embeddings fixes.
+
+**Upgrading.**
+- The store gains a column (`usage.images`); nothing to do.
+- **ComfyUI is installed only where asked**: `llmgw ctl config set
+  engines.comfyui 0.39.2` has every node with an NVIDIA GPU build it (about
+  10 GB under `/opt/llmgw/engines`). Nodes need this release to install it
+  or run engine `comfyui`.
+
+### Added
+
+- **Pictures at `/v1/images/generations`**, OpenAI's shape, through the same
+  key, allowlist, limit, admission and guardrail checks as any request. A
+  model with profiles on engine `comfyui` is placed on a GPU node like any
+  other. A ComfyUI server outside the cluster can be an external model with
+  `api: comfyui` instead. The workflow is a built-in (`flux-schnell`, the
+  default, or `flux-dev`) or a JSON file in ComfyUI's API format, with
+  `{{prompt}}`, `{{width}}`, `{{seed}}` and the like where the request's
+  values go. Requests may also send `seed`, `steps`, `negative_prompt` and
+  `guidance`. The seed used comes back in `x-llmgw-seed`. Pictures come back
+  as `b64_json`; ComfyUI's workflow is stripped from each PNG, and a client
+  that leaves takes its workflow off the queue. `/v1/models` says `images`
+  for such a model.
+- **Engine `comfyui`.** ComfyUI asks for no key, so the agent starts it
+  behind `llmgw comfyui-gate`. ComfyUI listens on the loopback only. The
+  gate listens on the replica's port, demands the replica's key, and lets
+  through only what the router asks. The model's `comfyui:` block names
+  the workflow and, for a source that is a set of files, the checkpoint.
+- **The agents install ComfyUI** (`engines.comfyui`). The release's source is
+  checked against a digest llmgw holds, since GitHub publishes none, and a
+  version without one is refused. Its requirements are resolved as PyPI
+  stood the day after the release, with PyPI's CUDA 13 torch or PyTorch's
+  CUDA 12.9 one for an older driver, and the result is checked on the card.
+  A ComfyUI installed by hand is named by `engines.comfyui.dir` in
+  agent.yaml.
+- **A price per picture**: `per_image` in `auth.pricing`, on top of the
+  prompt's tokens. A model priced only per picture is not free, so a spent
+  budget still stops it. Each usage row keeps how many pictures were made,
+  shown by `llmgw ctl request`.
+- **`/images` on the portal**, beside the chat, for the models that make
+  pictures. The chat no longer offers them. The page offers size, how many,
+  seed, steps and a negative prompt, and shows each picture with its seed
+  and a download link. Nothing is kept but the usage.
+- **An embedding model's `query_prefix`**, put before the question a
+  knowledge-base search embeds and never before documents, for Qwen3-Embedding
+  and models trained like it.
+
+### Fixed
+
+- **An awake on-demand model survived no restart or change of leader of the
+  control plane.** A control plane that had heard no requests read every
+  on-demand replica its nodes reported as wanted by nobody, and drained them
+  all. An adopted replica now gets a whole idle timeout.
+- `ctl models` said `not placed` for an on-demand model that had been woken
+  and was serving; it now says `ready (on demand)`.
+- A batch of embeddings was refused as one over-long prompt when the
+  passages together exceeded the context, though each one fit. The longest
+  input is what has to fit.
+- The chat's kept conversation sat in the browser under one key for
+  everybody, so the next person to sign in on the same browser opened the
+  last one's conversation. It is kept per account, and signing out clears
+  what the pages stored.
+
+## v0.14.1 — 2026-10-09
+
+Adapters trained on the nodes from a knowledge base and kept private to
+their owners; the cluster's and the agents' settings edited in one place;
+the tenancy tree and keys over the admin API and in Terraform; knowledge
+bases that hold up with many documents; the firewall setting on every
+machine.
+
+**Upgrading.**
+- **Nodes** need this release to follow `agents.*` in the cluster's
+  settings; until a node is upgraded its agent.yaml is what it runs on.
+- **A separate mirror machine and store members that run nothing else**
+  follow the firewall setting once what reads it is installed: run `sudo
+  llmgw mirror init` on the mirror again with the flags it was set up with,
+  and `llmgw server init --patroni` again for the store's members. A control
+  plane set up before v0.12.0 needs `sudo llmgw firewall sync --install`.
+- **The store's PostgreSQL memory** applies after each member is restarted,
+  one at a time, the leader last; until then it runs as before.
+- The store gains tables and columns; nothing to do. Existing knowledge-base
+  collections get their full-text index when a control plane starts, and
+  keep `vector` storage; only new collections use `halfvec`, and only on
+  pgvector 0.7 or later.
+- Cached knowledge-base passages in vLLM are made again once, under the new
+  `cache_salt`.
+
+### Added
+
+- **The cluster's settings on the portal** (BACKLOG E4): `/admin/settings`
+  for administrators. It edits the document `llmgw ctl config edit` opens:
+  checked as a control plane would load it, refused when made from a
+  version since replaced, with the history to view and roll back. Changes
+  are audited by size, never by contents.
+- **The nodes' agent settings in the cluster's settings** (BACKLOG E3):
+  `agents.default` and `agents.nodes.<id>` hold everything agent.yaml can
+  say but the agent's id, control planes, address and certificate. They are
+  sent to the agents as they change; an agent starts again on new settings,
+  or on an edited agent.yaml, with its engines serving throughout. Settings
+  that would not load are refused on save, and set aside on a node rather
+  than keep its agent from starting. Nodes need this release to follow
+  them.
+- **LoRA adapters trained on the nodes** (BACKLOG F4): `llmgw ctl kb dataset`
+  writes question/answer pairs from a collection with a model of the
+  cluster. `llmgw ctl train start` trains an adapter on a node with its
+  installed vLLM's torch and a small overlay, on a card with enough memory
+  free (beside an engine, if it leaves that much), converting to GGUF for
+  llama.cpp. `llmgw ctl train publish` keeps it on the mirror (which now
+  accepts uploads) and makes it the model's adapter.
+- **Adapters with owners.** An adapter's `owner` (org, team, project, user
+  or key) is the only part of the tree that sees it; to anyone else it is a
+  model that does not exist. An adapter trained on a knowledge base belongs
+  to a part of the tree that may read it, and is never made public.
+- The knowledge bases' vLLM `cache_salt` follows the collections searched,
+  not the organization, so two teams of one organization no longer share
+  cached passages.
+- **Organizations, teams, projects, API keys and memberships in the admin
+  API**: `/api/v1/orgs` (the tree), `POST /api/v1/teams` and `projects`,
+  `PATCH` to rename or move, `DELETE` for what is empty; `/api/v1/keys` to
+  issue (the key is in the answer, once), list and revoke; `/api/v1/users`
+  and `/api/v1/users/{id}/memberships`. They were only `llmgw org`, `keys`
+  and `users` on a control plane before. The Terraform provider manages them
+  as `llmgw_org`, `llmgw_team`, `llmgw_project`, `llmgw_key` (the key in a
+  sensitive `secret`) and `llmgw_membership`.
+- **The firewall setting reaches every machine.** A separate mirror and the
+  store's members follow `firewall.enabled` and `firewall_networks` as nodes
+  and control planes did: the leading control plane tells the mirror over
+  its API, and keeps the state in the store for members that run no llmgw,
+  which a timer on each reads. The mirror also lets in the network of every
+  node the leader knows. `mirror init` and `server init --patroni` install
+  what follows it; run them again on a cluster set up before.
+
+### Changed
+
+- **The store's PostgreSQL is sized to its machine's memory.** Before, it ran
+  on PostgreSQL's defaults (128MB cache) under Patroni, or on 96MB on one
+  machine. Now each member gets a share of its own RAM, a smaller one where
+  a control plane or agent shares the machine, and the share is read again
+  every time `server init --patroni` runs. The new cache is applied by
+  restarting one member at a time, the leader last.
+- **Knowledge-base searches hold up with many documents.** New collections
+  store their index as `halfvec` where pgvector is 0.7 or later (half the
+  memory, and embeddings up to 4000 dimensions instead of 2000); older
+  collections, and clusters on pgvector 0.6, keep `vector`. Each collection
+  has its own full-text index, as it has its own vector index, made for
+  existing collections when the control plane starts. The text arm ranks by
+  the cheap measure first and scores only those candidates.
+
+### Fixed
+
+- A knowledge-base search asking for more than 10 passages
+  (`X-Llmgw-Knowledge-K`) got at most 40 candidates per collection from the
+  vector index, whatever it asked for: pgvector's `hnsw.ef_search` is now
+  raised to the number wanted, up to 1000.
+- `llmgw server backup` and `restore` against a replicated store over TLS
+  failed looking for `~/.postgresql/root.crt`: pg_dump was given
+  `sslmode=verify-full` without the cluster's authority.
+
 ## v0.14.0 — 2026-10-08
 
 Knowledge bases: a company's documents, put in by people from their own

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,117 @@ 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) |
+| 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).
@@ -124,6 +197,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 +228,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 +245,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 +257,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

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;
   }
 }
 
@@ -73,6 +75,9 @@ message ControlMessage {
     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
@@ -103,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
@@ -872,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;
+}

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

@@ -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,64 @@ 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"
+```
+
+### 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 +611,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/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,15 +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 Qwen3Guard-Gen 0.6B, the guardrails' judge, and runs two
-    replicas on the CPUs of nodes with room — this one, or the first that
-    join ([guardrails.md](guardrails.md#a-judge-model) has one on a GPU too)
+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.
 
@@ -155,15 +187,19 @@ 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`. 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.
 
@@ -201,6 +237,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.
@@ -258,8 +304,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.
@@ -269,6 +321,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
@@ -995,6 +1074,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
@@ -1223,10 +1323,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
@@ -1507,6 +1782,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
@@ -1607,6 +1883,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
@@ -1703,9 +1996,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
 
@@ -1863,6 +2158,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
@@ -1944,6 +2375,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
@@ -1960,8 +2418,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
@@ -2079,6 +2541,82 @@ 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
+
+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:
+
+```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.
+- **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`,
@@ -2151,13 +2689,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

docs/knowledge.md

@@ -45,6 +45,20 @@ is available to everyone who may use them.
   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
@@ -132,6 +146,24 @@ Rules that apply:
 - 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
@@ -317,9 +349,11 @@ Behaviour to know about:
   (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 its organization. One organization's
-  passages then never share cached blocks with another's, so how fast an
-  answer starts says nothing about what another tenant asked.
+  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.
@@ -340,6 +374,49 @@ 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

docs/reference.md

@@ -18,6 +18,7 @@ rather than repeated.
 | `name` | `string` | [Adapter](#adapter) |
 | `source` | `string` | [Adapter](#adapter) |
 | `scale` | `float64` | [Adapter](#adapter) |
+| `owner` | `string` | [Adapter](#adapter) |
 | `enabled` | `bool` | [Admission](#admission) |
 | `bands` | `[]Band` | [Admission](#admission) |
 | `default_band` | `string` | [Admission](#admission) |
@@ -26,6 +27,8 @@ rather than repeated.
 | `queue_capacity_per_band` | `int` | [Admission](#admission) |
 | `queue_capacity_total` | `int` | [Admission](#admission) |
 | `interval` | `time.Duration` | [Admission](#admission) |
+| `default` | `map[string]any` | [AgentSettings](#agentsettings) |
+| `nodes` | `map[string]map[string]any` | [AgentSettings](#agentsettings) |
 | `enabled` | `bool` | [Auth](#auth) |
 | `store` | `string` | [Auth](#auth) |
 | `cache_ttl` | `time.Duration` | [Auth](#auth) |
@@ -34,6 +37,7 @@ rather than repeated.
 | `default_tpm` | `int` | [Auth](#auth) |
 | `signup_open` | `bool` | [Auth](#auth) |
 | `oidc` | `OIDC` | [Auth](#auth) |
+| `ldap` | `LDAP` | [Auth](#auth) |
 | `scim` | `SCIM` | [Auth](#auth) |
 | `max_key_ttl` | `time.Duration` | [Auth](#auth) |
 | `personal` | `Personal` | [Auth](#auth) |
@@ -57,6 +61,17 @@ rather than repeated.
 | `tools` | `bool` | [Capabilities](#capabilities) |
 | `vision` | `bool` | [Capabilities](#capabilities) |
 | `embeddings` | `bool` | [Capabilities](#capabilities) |
+| `images` | `bool` | [Capabilities](#capabilities) |
+| `meshes` | `bool` | [Capabilities](#capabilities) |
+| `workflow` | `string` | [ComfyUI](#comfyui) |
+| `checkpoint` | `string` | [ComfyUI](#comfyui) |
+| `output` | `string` | [ComfyUI](#comfyui) |
+| `inputs` | `[]Input` | [ComfyUI](#comfyui) |
+| `nodes` | `[]CustomNode` | [ComfyUI](#comfyui) |
+| `huggingface_repo` | `string` | [ComfyUI](#comfyui) |
+| `environment` | `string` | [ComfyUI](#comfyui) |
+| `dir` | `string` | [ComfyUIConfig](#comfyuiconfig) |
+| `python` | `string` | [ComfyUIConfig](#comfyuiconfig) |
 | `interval` | `time.Duration` | [Control](#control) |
 | `base_backoff` | `time.Duration` | [Control](#control) |
 | `max_backoff` | `time.Duration` | [Control](#control) |
@@ -68,11 +83,16 @@ rather than repeated.
 | `eval_dir` | `string` | [Control](#control) |
 | `enabled` | `bool` | [Control](#control) |
 | `lease_ttl` | `time.Duration` | [Control](#control) |
+| `repo` | `string` | [CustomNode](#customnode) |
+| `commit` | `string` | [CustomNode](#customnode) |
+| `requirements` | `[]string` | [CustomNode](#customnode) |
+| `build` | `[]string` | [CustomNode](#customnode) |
 | `id` | `string` | [Endpoint](#endpoint) |
 | `url` | `string` | [Endpoint](#endpoint) |
 | `api_key` | `string` | [Endpoint](#endpoint) |
 | `models` | `[]string` | [Endpoint](#endpoint) |
 | `engine` | `string` | [Endpoint](#endpoint) |
+| `workflow` | `string` | [Endpoint](#endpoint) |
 | `pool` | `string` | [Endpoint](#endpoint) |
 | `weight` | `float64` | [Endpoint](#endpoint) |
 | `priority` | `int` | [Endpoint](#endpoint) |
@@ -86,7 +106,13 @@ rather than repeated.
 | `url` | `string` | [External](#external) |
 | `model` | `string` | [External](#external) |
 | `api_key_file` | `string` | [External](#external) |
+| `api_key_files` | `[]ExternalKey` | [External](#external) |
 | `peer` | `string` | [External](#external) |
+| `api` | `string` | [External](#external) |
+| `workflow` | `string` | [External](#external) |
+| `output` | `string` | [External](#external) |
+| `file` | `string` | [ExternalKey](#externalkey) |
+| `weight` | `float64` | [ExternalKey](#externalkey) |
 | `budgets` | `[]FacilityBudget` | [Facility](#facility) |
 | `margin` | `float64` | [Facility](#facility) |
 | `gpu_watts` | `float64` | [Facility](#facility) |
@@ -99,8 +125,19 @@ rather than repeated.
 | `name` | `string` | [Federation](#federation) |
 | `interval` | `time.Duration` | [Federation](#federation) |
 | `enabled` | `bool` | [FirewallSettings](#firewallsettings) |
+| `min_compute_capability` | `float64` | [GPUNeed](#gpuneed) |
+| `min_memory_gb` | `int` | [GPUNeed](#gpuneed) |
 | `format` | `string` | [GuardModel](#guardmodel) |
 | `categories` | `[]string` | [GuardModel](#guardmodel) |
+| `name` | `string` | [Input](#input) |
+| `type` | `string` | [Input](#input) |
+| `required` | `bool` | [Input](#input) |
+| `default` | `any` | [Input](#input) |
+| `min` | `*float64` | [Input](#input) |
+| `max` | `*float64` | [Input](#input) |
+| `choices` | `[]string` | [Input](#input) |
+| `max_mb` | `int` | [Input](#input) |
+| `doc` | `string` | [Input](#input) |
 | `model` | `string` | [JudgePolicy](#judgepolicy) |
 | `models` | `[]string` | [JudgePolicy](#judgepolicy) |
 | `input` | `string` | [JudgePolicy](#judgepolicy) |
@@ -111,10 +148,32 @@ rather than repeated.
 | `tokenize_timeout` | `time.Duration` | [KVIndex](#kvindex) |
 | `min_blocks` | `int` | [KVIndex](#kvindex) |
 | `max_blocks` | `int` | [KVIndex](#kvindex) |
+| `urls` | `[]string` | [LDAP](#ldap) |
+| `start_tls` | `bool` | [LDAP](#ldap) |
+| `ca_file` | `string` | [LDAP](#ldap) |
+| `bind_dn` | `string` | [LDAP](#ldap) |
+| `bind_password_file` | `string` | [LDAP](#ldap) |
+| `base_dn` | `string` | [LDAP](#ldap) |
+| `group_base_dn` | `string` | [LDAP](#ldap) |
+| `user_filter` | `string` | [LDAP](#ldap) |
+| `label` | `string` | [LDAP](#ldap) |
+| `create_accounts` | `bool` | [LDAP](#ldap) |
+| `roles` | `map[string][]string` | [LDAP](#ldap) |
+| `memberships` | `map[string]string` | [LDAP](#ldap) |
+| `sync_interval` | `time.Duration` | [LDAP](#ldap) |
+| `timeout` | `time.Duration` | [LDAP](#ldap) |
 | `contact` | `string` | [Landing](#landing) |
 | `notice` | `string` | [Landing](#landing) |
 | `language` | `string` | [Landing](#landing) |
 | `docs_sign_in` | `bool` | [Landing](#landing) |
+| `id` | `string` | [License](#license) |
+| `name` | `string` | [License](#license) |
+| `url` | `string` | [License](#license) |
+| `notice` | `string` | [License](#license) |
+| `commercial` | `*bool` | [License](#license) |
+| `excluded_regions` | `[]string` | [License](#license) |
+| `revenue_cap_usd` | `int64` | [License](#license) |
+| `attribution` | `string` | [License](#license) |
 | `bin` | `string` | [LlamaCppConfig](#llamacppconfig) |
 | `parallel` | `int` | [LlamaCppConfig](#llamacppconfig) |
 | `threads` | `int` | [LlamaCppConfig](#llamacppconfig) |
@@ -132,6 +191,8 @@ rather than repeated.
 | `class` | `string` | [Model](#model) |
 | `owner` | `string` | [Model](#model) |
 | `external` | `*External` | [Model](#model) |
+| `comfyui` | `*ComfyUI` | [Model](#model) |
+| `license` | `*License` | [Model](#model) |
 | `adapters` | `[]Adapter` | [Model](#model) |
 | `max_loaded_adapters` | `int` | [Model](#model) |
 | `fallbacks` | `[]string` | [Model](#model) |
@@ -142,6 +203,7 @@ rather than repeated.
 | `context_length` | `int` | [Model](#model) |
 | `max_output` | `int` | [Model](#model) |
 | `capabilities` | `Capabilities` | [Model](#model) |
+| `query_prefix` | `string` | [Model](#model) |
 | `role` | `string` | [Model](#model) |
 | `guard` | `*GuardModel` | [Model](#model) |
 | `origin` | `*Origin` | [Model](#model) |
@@ -161,6 +223,8 @@ rather than repeated.
 | `no_passwords` | `bool` | [OIDC](#oidc) |
 | `mirror` | `string` | [Offline](#offline) |
 | `checksums` | `string` | [Offline](#offline) |
+| `evict_after_idle` | `time.Duration` | [OnDemandSettings](#ondemandsettings) |
+| `min_lifetime` | `time.Duration` | [OnDemandSettings](#ondemandsettings) |
 | `nvidia_smi` | `string` | [Options](#options) |
 | `ib_root` | `string` | [Options](#options) |
 | `prefer_nvml` | `bool` | [Options](#options) |
@@ -200,6 +264,7 @@ rather than repeated.
 | `match_ratio` | `float64` | [Prefix](#prefix) |
 | `balance_abs` | `float64` | [Prefix](#prefix) |
 | `balance_rel` | `float64` | [Prefix](#prefix) |
+| `auto` | `bool` | [PresetSettings](#presetsettings) |
 | `source` | `string` | [PreviousOrigin](#previousorigin) |
 | `revision` | `string` | [PreviousOrigin](#previousorigin) |
 | `files` | `[]OriginFile` | [PreviousOrigin](#previousorigin) |
@@ -207,6 +272,7 @@ rather than repeated.
 | `engine` | `string` | [Profile](#profile) |
 | `engine_version` | `string` | [Profile](#profile) |
 | `gpu_class` | `string` | [Profile](#profile) |
+| `source` | `string` | [Profile](#profile) |
 | `tp` | `int` | [Profile](#profile) |
 | `pp` | `int` | [Profile](#profile) |
 | `gpus_per_node` | `int` | [Profile](#profile) |
@@ -223,6 +289,11 @@ rather than repeated.
 | `priority` | `int` | [Profile](#profile) |
 | `startup_timeout` | `time.Duration` | [Profile](#profile) |
 | `kv_events` | `bool` | [Profile](#profile) |
+| `gpu` | `*GPUNeed` | [Profile](#profile) |
+| `comfyui` | `*ProfileComfyUI` | [Profile](#profile) |
+| `workflow` | `string` | [ProfileComfyUI](#profilecomfyui) |
+| `checkpoint` | `string` | [ProfileComfyUI](#profilecomfyui) |
+| `nodes` | `[]CustomNode` | [ProfileComfyUI](#profilecomfyui) |
 | `activation_wait` | `time.Duration` | [Router](#router) |
 | `scrape_interval` | `time.Duration` | [Router](#router) |
 | `scrape_timeout` | `time.Duration` | [Router](#router) |
@@ -294,6 +365,9 @@ rather than repeated.
 | `mail` | `mail.Config` | [Server](#server) |
 | `serving` | `ServingSettings` | [Server](#server) |
 | `firewall` | `FirewallSettings` | [Server](#server) |
+| `presets` | `PresetSettings` | [Server](#server) |
+| `on_demand` | `OnDemandSettings` | [Server](#server) |
+| `agents` | `AgentSettings` | [Server](#server) |
 | `firewall_networks` | `[]string` | [Server](#server) |
 | `backup_recipients` | `[]string` | [Server](#server) |
 | `backup_copy_to` | `[]string` | [Server](#server) |
@@ -338,9 +412,12 @@ rather than repeated.
 | `secret_file` | `string` | [Webhook](#webhook) |
 | `prompt_per_1k` | `int64` | [accounting.Price](#accountingprice) |
 | `completion_per_1k` | `int64` | [accounting.Price](#accountingprice) |
+| `per_image` | `int64` | [accounting.Price](#accountingprice) |
+| `per_mesh` | `int64` | [accounting.Price](#accountingprice) |
 | `name` | `string` | [admission.Band](#admissionband) |
 | `priority` | `int` | [admission.Band](#admissionband) |
 | `saturation_ceiling` | `float64` | [admission.Band](#admissionband) |
+| `queue_ttl` | `time.Duration` | [admission.Band](#admissionband) |
 | `bands` | `[]Band` | [admission.Config](#admissionconfig) |
 | `default_band` | `string` | [admission.Config](#admissionconfig) |
 | `queue_ttl` | `time.Duration` | [admission.Config](#admissionconfig) |
@@ -370,14 +447,18 @@ rather than repeated.
 | `name` | `string` | [config.Band](#configband) |
 | `priority` | `int` | [config.Band](#configband) |
 | `saturation_ceiling` | `float64` | [config.Band](#configband) |
+| `queue_ttl` | `time.Duration` | [config.Band](#configband) |
 | `prompt_per_1k` | `int64` | [config.Price](#configprice) |
 | `completion_per_1k` | `int64` | [config.Price](#configprice) |
+| `per_image` | `int64` | [config.Price](#configprice) |
+| `per_mesh` | `int64` | [config.Price](#configprice) |
 | `disabled` | `[]string` | [engines.Config](#enginesconfig) |
 | `vllm` | `VLLMConfig` | [engines.Config](#enginesconfig) |
 | `sglang` | `SGLangConfig` | [engines.Config](#enginesconfig) |
 | `llamacpp` | `LlamaCppConfig` | [engines.Config](#enginesconfig) |
 | `trtllm` | `TRTLLMConfig` | [engines.Config](#enginesconfig) |
 | `sim` | `SimConfig` | [engines.Config](#enginesconfig) |
+| `comfyui` | `ComfyUIConfig` | [engines.Config](#enginesconfig) |
 | `enabled` | `*bool` | [guard.Config](#guardconfig) |
 | `default` | `[]string` | [guard.Config](#guardconfig) |
 | `policies` | `map[string]Policy` | [guard.Config](#guardconfig) |
@@ -423,6 +504,16 @@ weights are.
 
 Scale is how strongly it is applied; zero takes 1.
 
+### `owner`
+
+`string`
+
+Owner is the part of the tenancy tree the adapter belongs to —
+org:ID, team:ID, project:ID, user:ID or key:ID — and only callers in
+it see it: to anyone else it is a model that does not exist. An
+adapter trained on an organisation's documents carries some of what
+they say in its weights. Empty is every caller the model allows.
+
 ## Admission
 
 ### `enabled`
@@ -469,6 +560,21 @@ Zero takes half of all the bands' capacities together.
 
 `time.Duration`
 
+## AgentSettings
+
+### `default`
+
+`map[string]any`
+
+Default is agent.yaml's keys for every node.
+
+### `nodes`
+
+`map[string]map[string]any`
+
+Nodes are agent.yaml's keys for one node each, by node id, over
+Default.
+
 ## Auth
 
 ### `enabled`
@@ -528,6 +634,15 @@ OIDC is sign-in through an identity provider.
 
 Takes a [OIDC](#oidc) block.
 
+### `ldap`
+
+`LDAP`
+
+LDAP is sign-in against a directory, Active Directory above all, and
+the accounts kept in step with it.
+
+Takes a [LDAP](#ldap) block.
+
 ### `scim`
 
 `SCIM`
@@ -686,6 +801,97 @@ token is MaxTTFTRatio times this model's. Zero is 50, 0.05 and 1.5.
 
 `bool`
 
+### `images`
+
+`bool`
+
+Images is a model that makes pictures, asked for at
+/v1/images/generations. Implied by an external model whose API is
+ComfyUI's.
+
+### `meshes`
+
+`bool`
+
+Meshes is a model that makes 3D models from a picture, asked for as a
+job at /v1/3d/generations. Implied by a ComfyUI model whose output is
+meshes.
+
+## ComfyUI
+
+### `workflow`
+
+`string`
+
+Workflow is a built-in's name (flux-schnell, the default, or
+flux-dev) or a JSON file on the control plane, in ComfyUI's API
+format.
+
+### `checkpoint`
+
+`string`
+
+Checkpoint is the file the workflow's {{checkpoint}} names: the
+source's own name unless set, which a source that is a set of files
+must.
+
+### `output`
+
+`string`
+
+Output is what the workflow makes: pictures (the default), asked for
+at /v1/images/generations; meshes, asked for as a job at
+/v1/3d/generations from a picture; or video, audio or files. Every
+kind is asked for as a job at /v1/workflows/runs too.
+
+### `inputs`
+
+`[]Input`
+
+Inputs are what the workflow takes from a request at
+/v1/workflows/runs, each the placeholder of its name.
+
+### `nodes`
+
+`[]CustomNode`
+
+Nodes are custom nodes the workflow needs, put in each replica's own
+custom_nodes at the commit named.
+
+### `huggingface_repo`
+
+`string`
+
+HuggingFaceRepo is the repository a custom node loads the weights by
+name from (Stable Fast 3D's loader asks for stabilityai/stable-fast-3d):
+the replica's weights are shown to the node there, in the Hugging Face
+cache of the engines' user, so nothing is fetched and no token is
+needed when it runs.
+
+### `environment`
+
+`string`
+
+Environment names the models that may share one ComfyUI replica: every
+model of an environment agrees on the custom nodes they both name, so
+one replica can carry all of them and ComfyUI moves between their
+weights itself. Empty is an environment of the model alone.
+
+## ComfyUIConfig
+
+### `dir`
+
+`string`
+
+Dir is ComfyUI's directory, where main.py is. Readable by the user
+engines run as.
+
+### `python`
+
+`string`
+
+Python is the interpreter of its environment; Dir's .venv when unset.
+
 ## Control
 
 ### `interval`
@@ -769,7 +975,43 @@ work stands without being renewed.
 Only meaningful with a shared store, where a second control plane can
 see the claim. Long enough to survive a slow query or a brief network
 stall, short enough that a standby takes over before anyone has finished
-reading the alert. Zero takes the default.
+reading the alert. Zero takes the default, 10s.
+
+## CustomNode
+
+### `repo`
+
+`string`
+
+Repo is the repository, https only.
+
+### `commit`
+
+`string`
+
+Commit is the full commit the node is used at: a branch moves, and a
+node that changed under a model is a model that changed unasked.
+
+### `requirements`
+
+`[]string`
+
+Requirements are the PyPI packages the node needs, by name and version
+range only. They are installed beside the replica, never into
+ComfyUI's environment: a package named here at the range named, and
+every other one at the version ComfyUI already runs. One named here
+is first on ComfyUI's path, so its range must suit ComfyUI too.
+
+### `build`
+
+`[]string`
+
+Build are directories of the repository that are Python packages to
+be compiled rather than downloaded: C++ and CUDA extensions no index
+has (Stable Fast 3D's texture_baker and uv_unwrapper). Each is built
+as a wheel with ComfyUI's Python for the card the replica runs on,
+kept on the node for the next replica on the same kind of card, and
+installed beside the replica like its requirements.
 
 ## Endpoint
 
@@ -799,6 +1041,13 @@ with one.
 Engine names the inference engine, which decides what its metrics are
 called. Empty means vLLM's names.
 
+### `workflow`
+
+`string`
+
+Workflow is the ComfyUI workflow for engine: comfyui, a built-in's
+name or its JSON; flux-schnell unless set.
+
 ### `pool`
 
 `string`
@@ -881,6 +1130,15 @@ APIKeyFile holds the provider's key, on the control plane. A file
 rather than the key itself, so the key is in neither the catalog, the
 store nor the audit log; empty for a provider that asks for none.
 
+### `api_key_files`
+
+`[]ExternalKey`
+
+APIKeyFiles are several keys for the provider, in place of
+APIKeyFile: one endpoint each (external:MODEL#1, #2…), so a key that
+answers 429 or 401 is passed over while its breaker is open and the
+request goes to another. A provider's limits are per key.
+
 ### `peer`
 
 `string`
@@ -890,6 +1148,43 @@ a model that federation added (`llmgw ctl federation add`) rather
 than one written by hand. Such a model is named PEER/MODEL, comes and
 goes with the peer's own list, and is sent only while the peer is up.
 
+### `api`
+
+`string`
+
+API is what the provider speaks: OpenAI's, unless this says comfyui —
+a ComfyUI server, asked for pictures at /v1/images/generations and
+sent the workflow below with the request's prompt in it. Model is then
+the checkpoint file the workflow loads, as ComfyUI lists it.
+
+### `workflow`
+
+`string`
+
+Workflow is the ComfyUI workflow, in its API format: a built-in's name
+(flux-schnell, the default, or flux-dev) or a JSON file on the control
+plane.
+
+### `output`
+
+`string`
+
+Output is what it makes: pictures, or meshes (see ComfyUI.Output).
+
+## ExternalKey
+
+### `file`
+
+`string`
+
+File holds the key, on the control plane, as APIKeyFile does.
+
+### `weight`
+
+`float64`
+
+Weight is its share of the requests against the others'; zero is 1.
+
 ## Facility
 
 ### `budgets`
@@ -990,6 +1285,21 @@ site whose own firewall does that job; the rules are kept, and true
 puts them back. Changed in the cluster's settings, it is in force on
 every node and control plane within seconds.
 
+## GPUNeed
+
+### `min_compute_capability`
+
+`float64`
+
+MinComputeCapability is the oldest architecture that runs it: 7.5 is
+Turing, 8.0 Ampere (bf16, flash-attention 2), 8.9 Ada (fp8), 9.0 Hopper.
+
+### `min_memory_gb`
+
+`int`
+
+MinMemoryGB is the card's own memory it needs.
+
 ## GuardModel
 
 ### `format`
@@ -1009,6 +1319,62 @@ ShieldGemma: Yes or No), or json ({"safe": false, "categories":
 Categories the model is asked about, for shieldgemma — each a policy
 sentence — and the names reported for llamaguard3's S1, S2, ….
 
+## Input
+
+### `name`
+
+`string`
+
+Name is the placeholder's, and the request's key.
+
+### `type`
+
+`string`
+
+Type is one of text, int, float, bool, choice, image, mask, audio,
+video, file. The last five are files, sent as base64, a data URL, or
+the id of a file uploaded to /v1/files, and put in ComfyUI's input
+directory; the placeholder gets the name they were given there.
+
+### `required`
+
+`bool`
+
+Required inputs must be in every request; the others take Default,
+or the workflow's own {{name|default}}.
+
+### `default`
+
+`any`
+
+### `min`
+
+`*float64`
+
+Min and Max bound a number; for text, Max bounds its length.
+
+### `max`
+
+`*float64`
+
+### `choices`
+
+`[]string`
+
+Choices are what a choice may be.
+
+### `max_mb`
+
+`int`
+
+MaxMB bounds a file input; zero is the type's own bound.
+
+### `doc`
+
+`string`
+
+Doc says what the input is for, to whoever fills it in.
+
 ## JudgePolicy
 
 ### `model`
@@ -1085,6 +1451,106 @@ MaxBlocks bounds how many of a prompt's blocks are hashed and looked
 up. Beyond it a longer match still helps, but the difference no longer
 decides anything. Zero takes 4096.
 
+## LDAP
+
+### `urls`
+
+`[]string`
+
+URLs are the directory's servers, tried in turn: ldaps:// (636), or
+ldap:// (389) with StartTLS.
+
+### `start_tls`
+
+`bool`
+
+StartTLS upgrades an ldap:// connection before anything is sent. A
+password never crosses a connection without TLS: ldap:// without it
+is refused.
+
+### `ca_file`
+
+`string`
+
+CAFile is the authority the servers' certificates are checked against,
+when it is not the system's: an AD Certificate Services root.
+
+### `bind_dn`
+
+`string`
+
+BindDN and the file holding its password: a service account that may
+read users and groups. Nothing is written to the directory.
+
+### `bind_password_file`
+
+`string`
+
+### `base_dn`
+
+`string`
+
+BaseDN is where people are searched for, subtree included.
+
+### `group_base_dn`
+
+`string`
+
+GroupBaseDN is where their groups are; empty is BaseDN's domain root.
+
+### `user_filter`
+
+`string`
+
+UserFilter narrows who may sign in, ANDed with the login match: a
+group (memberOf=...) or an OU's people only. Empty is every enabled
+user object.
+
+### `label`
+
+`string`
+
+Label is what the form says to sign in with: "Sign in with your
+<label> account". Empty is "Active Directory".
+
+### `create_accounts`
+
+`bool`
+
+CreateAccounts makes an account, active, for a person the directory
+vouches for and the gateway does not know. Off, only existing accounts
+sign in this way.
+
+### `roles`
+
+`map[string][]string`
+
+Roles maps a staff role (viewer, operator, billing, admin) to the
+groups that give it, by name (CN) or whole DN. Set at every sign-in
+and sync: someone taken out of the group loses the role.
+
+### `memberships`
+
+`map[string]string`
+
+Memberships maps a group, by CN or DN, to a place in the tree —
+org:NAME, team:ORG/TEAM, project:ORG/TEAM/PROJECT — joined at sign-in
+and kept by the sync, which also takes away a place whose group the
+person has left.
+
+### `sync_interval`
+
+`time.Duration`
+
+SyncInterval is how often the leader reads the directory. Zero is
+15m; negative turns the sync off, leaving only sign-in.
+
+### `timeout`
+
+`time.Duration`
+
+Timeout bounds each round trip to a server. Zero is 10s.
+
 ## Landing
 
 ### `contact`
@@ -1120,6 +1586,63 @@ llmgw in general — no address, model or key of this installation —
 which the project's repository publishes anyway. On, a visitor is sent
 to sign in, and without accounts the portal needs an API key.
 
+## License
+
+### `id`
+
+`string`
+
+ID names the licence for a machine: an SPDX identifier where there is
+one (MIT, Apache-2.0, CC-BY-NC-4.0), else a lowercase name of the
+licence's own (stability-community, tencent-hunyuan-community). What a
+person's or a site's choice of licences matches on. Name is for people.
+
+### `name`
+
+`string`
+
+Name is the licence's own: MIT, Apache-2.0.
+
+### `url`
+
+`string`
+
+### `notice`
+
+`string`
+
+Notice is what must accompany what was made: attribution, terms on
+the output, what the weights were trained on.
+
+### `commercial`
+
+`*bool`
+
+Commercial says whether what is made may be used commercially: nil
+is not said, which is not the same as yes.
+
+### `excluded_regions`
+
+`[]string`
+
+ExcludedRegions are where the licence grants nothing: ISO 3166 codes,
+and EU for the union (Hunyuan's: EU, UK, KR).
+
+### `revenue_cap_usd`
+
+`int64`
+
+RevenueCapUSD is the yearly revenue above which the licence asks for
+another agreement (Stability's community licence: 1000000). Zero is
+none.
+
+### `attribution`
+
+`string`
+
+Attribution is what a product using the output must show: "Powered by
+Stability AI".
+
 ## LlamaCppConfig
 
 ### `bin`
@@ -1276,6 +1799,25 @@ allowlist.
 
 Takes a [External](#external) block.
 
+### `comfyui`
+
+`*ComfyUI`
+
+ComfyUI is how a model whose profiles run engine comfyui makes its
+pictures: the workflow, and the file it loads.
+
+Takes a [ComfyUI](#comfyui) block.
+
+### `license`
+
+`*License`
+
+License is the terms of what the model makes, for a model whose
+output somebody ships: shown with every result and written into a
+mesh.
+
+Takes a [License](#license) block.
+
 ### `adapters`
 
 `[]Adapter`
@@ -1360,6 +1902,16 @@ Capabilities is what this model can do beyond plain completion.
 
 Takes a [Capabilities](#capabilities) block.
 
+### `query_prefix`
+
+`string`
+
+QueryPrefix is put before a question an embedding model embeds for a
+knowledge-base search; documents are embedded without it. Models
+trained with an instruction on the query side want it, Qwen3-Embedding
+"Instruct: Given a web search query, retrieve relevant passages that
+answer the query\nQuery: " for one.
+
 ### `role`
 
 `string`
@@ -1513,6 +2065,25 @@ kept by llmgw bundle import and llmgw bundle trust; every engine file
 a node fetches from the mirror is checked against it. Read again
 whenever it changes. Empty is /etc/llmgw/offline.sha256.
 
+## OnDemandSettings
+
+### `evict_after_idle`
+
+`time.Duration`
+
+EvictAfterIdle is how long an on-demand replica must go unasked-for
+before a model that wants its card may have it. Zero keeps 2m.
+
+### `min_lifetime`
+
+`time.Duration`
+
+MinLifetime is how long a replica that has just come up is safe from
+that, so two models do not take turns paying for loads. Zero keeps
+5m. On one card shared by a picture model and a 3D model, 1m each
+brings the wait between a picture and its mesh to about a minute.
+Both are in force on the leader within seconds.
+
 ## Options
 
 ### `nvidia_smi`
@@ -1761,6 +2332,20 @@ before affinity is abandoned.
 
 `float64`
 
+## PresetSettings
+
+### `auto`
+
+`bool`
+
+Auto has the leading control plane add a picture model (flux-schnell)
+and a 3D model (triposr) by itself, on demand, once a node has a card
+that fits one and the catalog has no model that makes the same kind of
+thing — so a new cluster's portal has its pictures and 3D pages
+without anybody writing a definition. Only where the cluster already
+installs ComfyUI (engines.comfyui). A preset somebody removed is not
+added again by itself. In force on the leader within a minute.
+
 ## PreviousOrigin
 
 ### `source`
@@ -1797,6 +2382,16 @@ version starts with it: "0.11" takes vLLM 0.11.0 and 0.11.1, not
 
 `string`
 
+### `source`
+
+`string`
+
+Source is the weights this profile loads, when not the model's: an
+embedding model served by vLLM from its repository on a card and by
+llama.cpp from a GGUF on CPUs is one model with two sources. Empty
+loads the model's. Updates and canaries move the model's source; a
+profile with its own keeps it.
+
 ### `tp`
 
 `int`
@@ -1944,6 +2539,39 @@ is started with sha256_cbor block hashing and a fixed PYTHONHASHSEED,
 which the router's hashing assumes; arguments overriding either leave
 the index empty, and the agent says so in its log.
 
+### `gpu`
+
+`*GPUNeed`
+
+GPU says what card the profile needs, in place of naming its class:
+it stands for every class in the cluster that meets it. A catalog
+entry written once then places sensibly on any site's cards.
+
+Takes a [GPUNeed](#gpuneed) block.
+
+### `comfyui`
+
+`*ProfileComfyUI`
+
+ComfyUI is this profile's own workflow, checkpoint and nodes, over the
+model's: an fp8 workflow where the card has fp8, fp16 where it has not.
+
+Takes a [ProfileComfyUI](#profilecomfyui) block.
+
+## ProfileComfyUI
+
+### `workflow`
+
+`string`
+
+### `checkpoint`
+
+`string`
+
+### `nodes`
+
+`[]CustomNode`
+
 ## Router
 
 ### `activation_wait`
@@ -2520,6 +3148,35 @@ Firewall turns llmgw's firewall on every machine on or off.
 
 Takes a [FirewallSettings](#firewallsettings) block.
 
+### `presets`
+
+`PresetSettings`
+
+Presets is how the models that come with llmgw reach the catalog.
+
+Takes a [PresetSettings](#presetsettings) block.
+
+### `on_demand`
+
+`OnDemandSettings`
+
+OnDemand is how models that load when asked for take turns on the
+cards.
+
+Takes a [OnDemandSettings](#ondemandsettings) block.
+
+### `agents`
+
+`AgentSettings`
+
+Agents are the nodes' agent settings: agent.yaml's keys but those an
+agent needs to start, for every node (default) and for one
+(nodes.<id>). Sent to the agents as they change; an agent whose
+settings changed starts again on them, its engines serving
+throughout.
+
+Takes a [AgentSettings](#agentsettings) block.
+
 ### `firewall_networks`
 
 `[]string`
@@ -2848,6 +3505,21 @@ is sha256=<hex HMAC of the body>.
 
 `int64`
 
+### `per_image`
+
+`int64`
+
+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.
+
+### `per_mesh`
+
+`int64`
+
+PerMesh is what one 3D model costs: minutes of a card, which no
+token count measures.
+
 ## admission.Band
 
 ### `name`
@@ -2867,6 +3539,15 @@ Priority orders bands; higher is served first.
 SaturationCeiling is the pool saturation above which this band waits.
 1.0 means "never hold this band back".
 
+### `queue_ttl`
+
+`time.Duration`
+
+QueueTTL, set, is how long this band's requests may wait instead of
+the controller's: a band for bulk work — a knowledge-base import, a
+backfill — whose requests had rather wait ten minutes behind people
+than be turned away after thirty seconds.
+
 ## admission.Config
 
 ### `bands`
@@ -3080,6 +3761,14 @@ Takes a [Tracing](#tracing) block.
 
 `float64`
 
+### `queue_ttl`
+
+`time.Duration`
+
+QueueTTL is how long this band's requests may wait for room; the
+admission's queue_ttl unless set. Long for a band of bulk work, which
+had rather wait behind people than be turned away.
+
 ## config.Price
 
 ### `prompt_per_1k`
@@ -3090,6 +3779,19 @@ Takes a [Tracing](#tracing) block.
 
 `int64`
 
+### `per_image`
+
+`int64`
+
+PerImage is the cost of one picture, for a model that makes them
+(/v1/images/generations), on top of its prompt's tokens.
+
+### `per_mesh`
+
+`int64`
+
+PerMesh is the cost of one 3D model (/v1/3d/generations).
+
 ## engines.Config
 
 ### `disabled`
@@ -3133,6 +3835,14 @@ Takes a [TRTLLMConfig](#trtllmconfig) block.
 
 Takes a [SimConfig](#simconfig) block.
 
+### `comfyui`
+
+`ComfyUIConfig`
+
+ComfyUI makes pictures; offered by a node whose ComfyUI is named here.
+
+Takes a [ComfyUIConfig](#comfyuiconfig) block.
+
 ## guard.Config
 
 ### `enabled`

go.mod

@@ -12,6 +12,7 @@ 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
@@ -35,6 +36,7 @@ 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
@@ -44,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
@@ -56,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
@@ -88,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=

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
 	}
@@ -402,7 +434,10 @@ func (s *Service) RequestReset(ctx context.Context, rs ResetStore, email string)
 		return "", store.User{}, ErrTooManyTries
 	}
 	u, err := rs.UserByEmail(ctx, email)
-	if err != nil || u.PasswordHash == "" || u.State != store.UserActive {
+	// 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)

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.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,27 @@ 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); got != 1 {
 		t.Errorf("one prompt token cost %d", got)
 	}
-	if got := p.Cost(1000, 1000); got != 4000 {
+	if got := p.Cost(1000, 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); got != 0 {
 		t.Errorf("an empty request cost %d", got)
 	}
 }
 
+func TestAPictureCostsItsPriceOnTopOfItsPrompt(t *testing.T) {
+	p := Price{PromptPer1k: 1000, PerImage: 50000}
+	if got := p.Cost(20, 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,13 @@ import (
 type Price struct {
 	PromptPer1k     int64 `koanf:"prompt_per_1k"`
 	CompletionPer1k int64 `koanf:"completion_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 +32,17 @@ 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.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)
+func (p Price) Cost(promptTokens, completionTokens, images, meshes int64) int64 {
+	return divUp(promptTokens*p.PromptPer1k, 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
 }
 
@@ -880,6 +901,12 @@ 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",
@@ -1105,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.
@@ -1365,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.

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/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/engine.go

@@ -214,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
 }
 
@@ -262,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/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/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
@@ -248,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()
@@ -315,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)
 	}
@@ -339,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
 }
@@ -353,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
@@ -395,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)
@@ -440,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,
@@ -760,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.
@@ -838,15 +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
@@ -874,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
@@ -900,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"
@@ -905,3 +906,78 @@ func TestAnAdoptedShardsComputeIsKeptWithoutCrashing(t *testing.T) {
 		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/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/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

@@ -241,6 +241,12 @@ var liveSettings = []string{
 	"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,11 @@ 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") {
@@ -173,6 +178,7 @@ func newCtlCmd() *cobra.Command {
 		newRetryCmd(client),
 		newUpgradeCmd(client),
 		newJobsCmd(client, &asJSON),
+		newMeshJobsCmd(client, &asJSON),
 		newEngineCheckCmd(),
 		newEngineBuildCmd(client),
 		newToolCheckCmd(client),
@@ -181,6 +187,7 @@ func newCtlCmd() *cobra.Command {
 		newQuotaCmd(client, &asJSON),
 		newGuardCmd(client, &asJSON),
 		newKBCmd(client, &asJSON),
+		newTrainCmd(client, &asJSON),
 		newConfigCmd(client, &asJSON),
 		newAuditCmd(client, &asJSON),
 		newNotifyCmd(client, &asJSON),
@@ -325,6 +332,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:

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_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")
 			}

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/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/judgekeeper.go

@@ -32,6 +32,19 @@ type judgeKeeper struct {
 	// 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
+
+	// 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
@@ -69,6 +82,7 @@ func (k *judgeKeeper) check() {
 	have := map[string]bool{}
 	for _, m := range k.models() {
 		have[m.Name] = true
+		k.refit(m)
 	}
 	busy := map[string]bool{}
 	for _, j := range k.serve.Jobs() {
@@ -114,3 +128,88 @@ func (k *judgeKeeper) check() {
 			"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

@@ -1,6 +1,7 @@
 package cli
 
 import (
+	"context"
 	"errors"
 	"log/slog"
 	"slices"
@@ -124,3 +125,81 @@ func TestCategoriesFollowTheJudges(t *testing.T) {
 		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)
+	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)
+	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)
+		}
+	}
+}

internal/cli/kb.go

@@ -1,10 +1,14 @@
 package cli
 
 import (
+	"bytes"
 	"encoding/json"
 	"fmt"
+	"io"
 	"net/url"
+	"os"
 	"strings"
+	"time"
 
 	"github.com/spf13/cobra"
 
@@ -212,6 +216,45 @@ func newKBCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
 	def.Flags().BoolVar(&clear, "clear", false, "no default any more")
 	c.AddCommand(def)
 
+	var dsModel, dsOut string
+	var dsPer, dsMax int
+	dataset := &cobra.Command{
+		Use:   "dataset COLLECTION --model MODEL",
+		Short: "Write training data from a collection: questions and answers, for an adapter",
+		Long: "A chat model of the cluster reads each chunk of the collection and writes\n" +
+			"questions a person might ask of it, with the answers it holds, one JSON object\n" +
+			"a line ({\"q\", \"a\", \"doc\", \"ord\"}). Read it through and correct it before\n" +
+			"training on it (llmgw ctl train): what the model got wrong, an adapter learns.\n\n" +
+			"An adapter learns how answers sound — the organisation's words, format and\n" +
+			"tone — far better than what they say; the facts stay the knowledge base's.",
+		Example: "  llmgw ctl kb dataset Acme/policies --model qwen2.5-coder-14b-instruct --out policies.jsonl",
+		Args:    cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			w := cmd.OutOrStdout()
+			if dsOut != "" {
+				f, err := os.Create(dsOut)
+				if err != nil {
+					return err
+				}
+				defer f.Close()
+				w = f
+			}
+			lw := &datasetWriter{pairs: w, problems: cmd.ErrOrStderr()}
+			body, _ := json.Marshal(adminapi.KBDatasetRequest{Model: dsModel, PerChunk: dsPer, MaxChunks: dsMax})
+			err := client().patient(6*time.Hour).do(cmd.Context(), "POST",
+				"/api/v1/kb/collections/"+url.PathEscape(args[0])+"/dataset", json.RawMessage(body), lw)
+			lw.flush()
+			fmt.Fprintf(cmd.ErrOrStderr(), "%d pairs from %d chunks; %d chunks gave none\n", lw.n, len(lw.chunks), lw.failed)
+			return err
+		},
+	}
+	dataset.Flags().StringVar(&dsModel, "model", "", "the chat model that writes the questions and answers")
+	dataset.Flags().StringVar(&dsOut, "out", "", "the file to write (default: standard output)")
+	dataset.Flags().IntVar(&dsPer, "per-chunk", 8, "pairs from each chunk")
+	dataset.Flags().IntVar(&dsMax, "max-chunks", 500, "the most chunks read")
+	_ = dataset.MarkFlagRequired("model")
+	c.AddCommand(dataset)
+
 	var k int
 	search := &cobra.Command{
 		Use:   "search COLLECTION QUERY...",
@@ -240,3 +283,50 @@ func newKBCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
 	c.AddCommand(search)
 	return c
 }
+
+// datasetWriter splits the dataset stream: pairs to the file, problems to
+// the terminal, counted as they pass.
+type datasetWriter struct {
+	pairs, problems io.Writer
+	buf             []byte
+	n, failed       int
+	chunks          map[string]bool
+}
+
+func (d *datasetWriter) Write(p []byte) (int, error) {
+	d.buf = append(d.buf, p...)
+	for {
+		i := bytes.IndexByte(d.buf, '\n')
+		if i < 0 {
+			return len(p), nil
+		}
+		d.line(d.buf[:i])
+		d.buf = d.buf[i+1:]
+	}
+}
+
+func (d *datasetWriter) flush() {
+	if len(bytes.TrimSpace(d.buf)) > 0 {
+		d.line(d.buf)
+	}
+	d.buf = nil
+}
+
+func (d *datasetWriter) line(b []byte) {
+	var l adminapi.KBDatasetLine
+	if json.Unmarshal(b, &l) != nil {
+		return
+	}
+	if d.chunks == nil {
+		d.chunks = map[string]bool{}
+	}
+	d.chunks[fmt.Sprintf("%s#%d", l.Doc, l.Ord)] = true
+	if l.Error != "" {
+		d.failed++
+		fmt.Fprintf(d.problems, "  %s #%d: %s\n", l.Doc, l.Ord, l.Error)
+		return
+	}
+	d.n++
+	out, _ := json.Marshal(l)
+	fmt.Fprintln(d.pairs, string(out))
+}

internal/cli/mirrorinit.go

@@ -8,6 +8,7 @@ import (
 	"net"
 	"net/netip"
 	"os"
+	"path/filepath"
 	"runtime"
 	"strings"
 	"time"
@@ -65,6 +66,14 @@ Safe to run again: it changes only what differs.`,
 			}
 			if !noFirewall {
 				mirrorFirewall(cmd.Context(), cmd.OutOrStdout(), controlPlanes)
+				// And after, as the cluster's settings say: the control plane
+				// tells the mirror, which writes it beside its models.
+				state := filepath.Join(*dir, mirror.FirewallFile)
+				if err := installFirewallSync(cmd.Context(), firewall.Local{}, state); err != nil {
+					fmt.Fprintf(cmd.OutOrStdout(), "  !!    firewall: %v; the cluster's settings will not change it here\n", err)
+				} else {
+					fmt.Fprintln(cmd.OutOrStdout(), "  ok    firewall: follows the cluster's settings ("+firewallSyncPathUnit+")")
+				}
 			}
 			return nil
 		},

internal/cli/model.go

@@ -3,6 +3,7 @@ package cli
 import (
 	"encoding/json"
 	"fmt"
+	"net/url"
 	"os"
 	"os/user"
 	"slices"
@@ -32,7 +33,7 @@ func newModelCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
 		Use:   "model",
 		Short: "Add or remove models while the cluster is running",
 	}
-	c.AddCommand(newModelAddCmd(client), newModelRemoveCmd(client), newModelPlanCmd(client),
+	c.AddCommand(newModelAddCmd(client), newModelPresetsCmd(client, asJSON), newModelRemoveCmd(client), newModelPlanCmd(client),
 		newResourcesCmd(client), newClassCmd(client), newOwnerCmd(client),
 		newTargetCmd(client, asJSON), newAdaptersCmd(client),
 		newModelServeCmd(client), newModelUpdatesCmd(client, asJSON), newModelUpdateCmd(client),
@@ -46,49 +47,74 @@ func newModelAddCmd(client func() *ctlClient) *cobra.Command {
 	var path string
 	var skipCheck bool
 	c := &cobra.Command{
-		Use:   "add -f <file.yaml>",
-		Short: "Add a model from a definition file",
-		Long: "The definition is the same YAML a model takes in server.yaml, so an\n" +
+		Use:   "add PRESET | -f <file.yaml>",
+		Short: "Add a model that comes with llmgw, or one from a definition file",
+		Long: "A preset is a model that comes with llmgw, its workflow, nodes and licence\n" +
+			"already found and tried: " + strings.Join(catalog.PresetNames(), ", ") + " (llmgw ctl model presets).\n" +
+			"Adding a ComfyUI one also has the nodes install ComfyUI, when the cluster\n" +
+			"has not been told otherwise.\n\n" +
+			"A definition is the same YAML a model takes in server.yaml, so an\n" +
 			"entry can be moved between the two by copying it.\n\n" +
 			"The catalog is rebuilt and validated before anything is written, so a\n" +
 			"definition that collides with an existing name, or names a fallback that\n" +
 			"does not exist, is refused rather than stored and then ignored on every\n" +
 			"start. Once accepted it takes effect on the reconciler's next pass — no\n" +
 			"restart — and survives one.",
-		Args: cobra.NoArgs,
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			if path == "" {
-				return fmt.Errorf("--file is required: the model definition, as YAML")
-			}
-			// Read by koanf, the same parser and the same tags that read
-			// server.yaml — so an entry can be moved between the two by copying
-			// it, and a field that works in one cannot silently mean nothing in
-			// the other.
-			k := koanf.New(".")
-			if err := k.Load(file.Provider(path), yaml.Parser()); err != nil {
-				return fmt.Errorf("%s: %w", path, err)
-			}
+		Example: "  llmgw ctl model add triposr\n" +
+			"  llmgw ctl model add -f qwen.yaml",
+		Args: cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
 			var m catalog.Model
-			if err := k.UnmarshalWithConf("", &m, koanf.UnmarshalConf{Tag: "koanf"}); err != nil {
-				return fmt.Errorf("%s: %w", path, err)
-			}
-			if m.Name == "" {
-				return fmt.Errorf("%s: the definition has no name", path)
+			switch {
+			case len(args) == 1 && path != "":
+				return fmt.Errorf("a preset or a file, not both")
+			case len(args) == 1:
+				p, ok := catalog.PresetNamed(args[0])
+				if !ok {
+					return fmt.Errorf("no preset %q: there are %s; any other model is added from a file (-f)",
+						args[0], strings.Join(catalog.PresetNames(), ", "))
+				}
+				// The control plane adds it, and keeps that it was added as
+				// a preset, by whom; one from before it could is sent the
+				// entry, as it was then.
+				var res adminapi.ModelAdded
+				err := client().post(cmd.Context(), "/api/v1/presets/"+url.PathEscape(p.Model.Name), []byte("{}"), &res)
+				if err == nil {
+					fmt.Fprintf(cmd.OutOrStdout(),
+						"%s added, and ComfyUI with it where the cluster had none. It is placed on the next\n"+
+							"reconcile pass and loads when first asked for; watch it with:\n  llmgw ctl models\n", p.Model.Name)
+					return nil
+				}
+				if !olderControlPlane(err) {
+					return err
+				}
+				m = p.Model
+			case path == "":
+				return fmt.Errorf("a preset (%s) or --file, the model definition as YAML",
+					strings.Join(catalog.PresetNames(), ", "))
+			default:
+				var err error
+				if m, err = readModelFile(path); err != nil {
+					return err
+				}
 			}
 
 			// Before the catalog is touched, because a source that does not
 			// resolve is otherwise discovered by a replica failing to start
 			// minutes later on a node — with an error naming the node rather
 			// than the typo.
+			// Every source the model's profiles load, not the model's alone.
 			if !skipCheck {
-				size, err := sourcecheck.Check(cmd.Context(), m.Source)
-				if err != nil {
-					return fmt.Errorf("%w\n  Pass --no-source-check to add it anyway, "+
-						"which is right when the mirror is not up yet or the nodes "+
-						"reach it by an address this machine does not.", err)
-				}
-				if _, isURL := sourcecheck.HTTPSource(m.Source); isURL {
-					fmt.Fprintln(cmd.OutOrStdout(), sourceNote(m.Source, size))
+				for _, src := range m.WeightSources() {
+					size, err := sourcecheck.Check(cmd.Context(), src)
+					if err != nil {
+						return fmt.Errorf("%w\n  Pass --no-source-check to add it anyway, "+
+							"which is right when the mirror is not up yet or the nodes "+
+							"reach it by an address this machine does not.", err)
+					}
+					if _, isURL := sourcecheck.HTTPSource(src); isURL {
+						fmt.Fprintln(cmd.OutOrStdout(), sourceNote(src, size))
+					}
 				}
 			}
 
@@ -104,6 +130,9 @@ func newModelAddCmd(client func() *ctlClient) *cobra.Command {
 			fmt.Fprintf(cmd.OutOrStdout(),
 				"%s added. It will be placed on the next reconcile pass; watch it with:\n"+
 					"  llmgw ctl models\n", m.Name)
+			if m.ServesComfyUI() && !m.IsExternal() {
+				return ensureComfyUI(cmd, client, m.Name)
+			}
 			return nil
 		},
 	}
@@ -113,6 +142,25 @@ func newModelAddCmd(client func() *ctlClient) *cobra.Command {
 	return c
 }
 
+// readModelFile reads a model's definition. By koanf, the same parser and
+// the same tags that read server.yaml — so an entry can be moved between the
+// two by copying it, and a field that works in one cannot silently mean
+// nothing in the other.
+func readModelFile(path string) (catalog.Model, error) {
+	var m catalog.Model
+	k := koanf.New(".")
+	if err := k.Load(file.Provider(path), yaml.Parser()); err != nil {
+		return m, fmt.Errorf("%s: %w", path, err)
+	}
+	if err := k.UnmarshalWithConf("", &m, koanf.UnmarshalConf{Tag: "koanf"}); err != nil {
+		return m, fmt.Errorf("%s: %w", path, err)
+	}
+	if m.Name == "" {
+		return m, fmt.Errorf("%s: the definition has no name", path)
+	}
+	return m, nil
+}
+
 func newModelRemoveCmd(client func() *ctlClient) *cobra.Command {
 	return &cobra.Command{
 		Use:   "remove <name>",

internal/cli/model_presets.go

@@ -0,0 +1,166 @@
+package cli
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/provision"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/catalog"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/settings"
+)
+
+func newModelPresetsCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
+	c := &cobra.Command{
+		Use:   "presets",
+		Short: "The models that come with llmgw: whether each fits and is here",
+		Long: "Each is a catalog entry whose workflow, custom nodes, packages and licence\n" +
+			"were found and tried, and whose profile says the card it needs rather than\n" +
+			"a class, so it places on any site's cards. Add one with\n" +
+			"`llmgw ctl model add NAME`.\n\n" +
+			"While presets.auto is on, the leader adds one by itself when a card fits it\n" +
+			"and the catalog has nothing that makes what it makes; one somebody removed\n" +
+			"is not added again by itself.",
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			var v adminapi.PresetsView
+			err := client().get(cmd.Context(), "/api/v1/presets", &v)
+			if err != nil && !olderControlPlane(err) {
+				return err
+			}
+			if *asJSON && err == nil {
+				return emitJSON(v)
+			}
+			w := tabTo(cmd.OutOrStdout())
+			if err != nil {
+				// A control plane from before it kept them: what this
+				// release has, with nothing about the cluster.
+				fmt.Fprintln(w, "NAME\tMAKES\tCARD\tLICENCE\tWHAT IT IS FOR")
+				for _, p := range catalog.Presets() {
+					fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\n", p.Model.Name, p.Makes, presetCard(p.Model),
+						presetLicence(p.Model), p.Model.Description)
+				}
+				return w.Flush()
+			}
+			fmt.Fprintln(w, "NAME\tMAKES\tCARD\tLICENCE\tFITS\tHERE\tWHAT IT IS FOR")
+			for _, p := range v.Presets {
+				fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\t%s\t%s\n", p.Name, p.Makes, p.Card, licenceText(p.Licence),
+					orDash(strings.Join(p.FitsClasses, ",")), presetState(p), p.Description)
+			}
+			if err := w.Flush(); err != nil {
+				return err
+			}
+			if v.Auto {
+				fmt.Fprintln(cmd.OutOrStdout(), "\nAdded by themselves where a card fits (presets.auto); "+
+					"llmgw ctl model presets auto off stops it.")
+			} else {
+				fmt.Fprintln(cmd.OutOrStdout(), "\nNot added by themselves; llmgw ctl model presets auto on starts it.")
+			}
+			return nil
+		},
+	}
+	c.AddCommand(&cobra.Command{
+		Use:       "auto on|off",
+		Short:     "Whether the leader adds a preset by itself where a card fits it",
+		Args:      cobra.ExactArgs(1),
+		ValidArgs: []string{"on", "off"},
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if args[0] != "on" && args[0] != "off" {
+				return fmt.Errorf("on or off, not %q", args[0])
+			}
+			body, _ := json.Marshal(adminapi.PresetsAutoRequest{On: args[0] == "on"})
+			var v adminapi.PresetsView
+			if err := client().put(cmd.Context(), "/api/v1/presets/auto", body, &v); err != nil {
+				return err
+			}
+			if v.Auto {
+				fmt.Fprintln(cmd.OutOrStdout(), "Presets are added by themselves where a card fits.")
+			} else {
+				fmt.Fprintln(cmd.OutOrStdout(), "Presets are no longer added by themselves.")
+			}
+			return nil
+		},
+	})
+	return c
+}
+
+// olderControlPlane is an error from a control plane that has no such path:
+// one from before it was added.
+func olderControlPlane(err error) bool {
+	s := err.Error()
+	return strings.Contains(s, "answered with a page") || strings.HasPrefix(s, "404 Not Found: 404 page not found")
+}
+
+func presetState(p adminapi.PresetView) string {
+	switch {
+	case p.InCatalog && p.AddedBy == "auto":
+		return "added by itself"
+	case p.InCatalog && p.AddedBy != "":
+		return "added by " + p.AddedBy
+	case p.InCatalog:
+		return "here"
+	case p.Declined:
+		return "removed; stays out"
+	}
+	return "—"
+}
+
+func licenceText(l catalog.License) string {
+	if l.Commercial != nil && !*l.Commercial {
+		return l.Name + ", not commercial"
+	}
+	return l.Name
+}
+
+func presetCard(m catalog.Model) string {
+	if len(m.Profiles) == 0 || m.Profiles[0].GPU == nil {
+		return "—"
+	}
+	return m.Profiles[0].GPU.String()
+}
+
+func presetLicence(m catalog.Model) string {
+	if m.License == nil {
+		return "—"
+	}
+	l := m.License.Name
+	if c := m.License.Commercial; c != nil && !*c {
+		l += ", not commercial"
+	}
+	return l
+}
+
+// ensureComfyUI has the nodes install ComfyUI for a model that needs it,
+// unless the cluster names a version already, or none on purpose.
+func ensureComfyUI(cmd *cobra.Command, client func() *ctlClient, model string) error {
+	out := cmd.OutOrStdout()
+	path := []string{"engines", catalog.EngineComfyUI}
+	var cur adminapi.SettingsView
+	if err := client().get(cmd.Context(), "/api/v1/settings", &cur); err != nil {
+		return err
+	}
+	doc, err := settings.FromBytes("settings", []byte(cur.Body))
+	if err != nil {
+		return err
+	}
+	version := provision.ComfyUIVersion()
+	if n := doc.Node(path); n != nil {
+		if n.Value == "" {
+			fmt.Fprintf(out, "engines.comfyui is set to none, so the nodes install no ComfyUI for it: set a version "+
+				"(llmgw ctl config set engines.comfyui %s) or name one installed by hand in agent.yaml\n", version)
+		}
+		return nil
+	}
+	fmt.Fprintf(out, "Nodes with an NVIDIA GPU install ComfyUI %s for it, about 10 GB each:\n", version)
+	if err := doc.SetYAML(path, version); err != nil {
+		return err
+	}
+	b, err := doc.Bytes()
+	if err != nil {
+		return err
+	}
+	return putSettings(cmd, client, cur, b, "ComfyUI for "+model)
+}

internal/cli/model_presets_test.go

@@ -0,0 +1,128 @@
+package cli
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/catalog"
+)
+
+// presetAdmin is an admin API holding settings, which records the models
+// added and the settings put.
+type presetAdmin struct {
+	// api is a control plane that adds presets itself; without it, one
+	// from before, which answers their paths with a 404.
+	api      bool
+	byAPI    []string
+	mu       sync.Mutex
+	settings string
+	added    []catalog.Model
+	put      []string
+}
+
+func (a *presetAdmin) client(t *testing.T) func() *ctlClient {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		a.mu.Lock()
+		defer a.mu.Unlock()
+		body, _ := io.ReadAll(r.Body)
+		w.Header().Set("Content-Type", "application/json")
+		switch {
+		case a.api && r.Method == http.MethodPost && strings.HasPrefix(r.URL.Path, "/api/v1/presets/"):
+			name := strings.TrimPrefix(r.URL.Path, "/api/v1/presets/")
+			a.byAPI = append(a.byAPI, name)
+			_ = json.NewEncoder(w).Encode(adminapi.ModelAdded{Added: name})
+		case r.Method == http.MethodPost && r.URL.Path == "/api/v1/models":
+			var m catalog.Model
+			_ = json.Unmarshal(body, &m)
+			a.added = append(a.added, m)
+			_ = json.NewEncoder(w).Encode(map[string]string{"name": m.Name})
+		case r.Method == http.MethodGet && r.URL.Path == "/api/v1/settings":
+			_ = json.NewEncoder(w).Encode(adminapi.SettingsView{Version: 1, Body: a.settings})
+		case r.Method == http.MethodPut && r.URL.Path == "/api/v1/settings":
+			var req adminapi.SettingsRequest
+			_ = json.Unmarshal(body, &req)
+			a.put = append(a.put, req.Body)
+			a.settings = req.Body
+			_ = json.NewEncoder(w).Encode(adminapi.SettingsView{Version: 2, Body: req.Body})
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	t.Cleanup(srv.Close)
+	return func() *ctlClient { return newCtlClient(strings.TrimPrefix(srv.URL, "http://"), "") }
+}
+
+func runModelAdd(t *testing.T, client func() *ctlClient, args ...string) (string, error) {
+	t.Helper()
+	cmd := newModelAddCmd(client)
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&out)
+	cmd.SetArgs(append(args, "--no-source-check"))
+	err := cmd.ExecuteContext(t.Context())
+	return out.String(), err
+}
+
+func TestAPresetIsAddedByTheControlPlane(t *testing.T) {
+	a := &presetAdmin{api: true}
+	out, err := runModelAdd(t, a.client(t), "triposr")
+	if err != nil {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	if len(a.byAPI) != 1 || a.byAPI[0] != "triposr" || len(a.added) != 0 || len(a.put) != 0 {
+		t.Errorf("by the API %v; sent the entry %v; settings %v", a.byAPI, a.added, a.put)
+	}
+}
+
+// A control plane from before presets were its own is sent the entry, and
+// ComfyUI set beside it, as the release that brought presets did.
+func TestAPresetIsAddedByNameAndHasTheNodesInstallComfyUI(t *testing.T) {
+	a := &presetAdmin{settings: "router:\n  retries: 2\n"}
+	out, err := runModelAdd(t, a.client(t), "triposr")
+	if err != nil {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	if len(a.added) != 1 || a.added[0].Name != "triposr" || a.added[0].ComfyUI.Workflow != "triposr" {
+		t.Fatalf("added %+v", a.added)
+	}
+	if len(a.put) != 1 || !strings.Contains(a.put[0], "comfyui: 0.39.2") || !strings.Contains(a.put[0], "retries: 2") {
+		t.Fatalf("settings put %q", a.put)
+	}
+	if !strings.Contains(out, "install ComfyUI 0.39.2") {
+		t.Errorf("not said:\n%s", out)
+	}
+}
+
+func TestAClusterThatNamesItsComfyUIKeepsIt(t *testing.T) {
+	for _, settings := range []string{"engines:\n  comfyui: 0.38.0\n", "engines:\n  comfyui: \"\"\n"} {
+		a := &presetAdmin{settings: settings}
+		out, err := runModelAdd(t, a.client(t), "flux-schnell")
+		if err != nil {
+			t.Fatalf("%v\n%s", err, out)
+		}
+		if len(a.put) != 0 {
+			t.Errorf("%q: settings changed to %q", settings, a.put)
+		}
+		if none := strings.Contains(settings, `""`); none != strings.Contains(out, "set to none") {
+			t.Errorf("%q: %s", settings, out)
+		}
+	}
+}
+
+func TestAnUnknownPresetNamesTheOnesThereAre(t *testing.T) {
+	a := &presetAdmin{}
+	_, err := runModelAdd(t, a.client(t), "sdxl")
+	if err == nil || !strings.Contains(err.Error(), "flux-schnell, triposr") || len(a.added) != 0 {
+		t.Errorf("%v, added %v", err, a.added)
+	}
+	if _, err := runModelAdd(t, a.client(t), "triposr", "-f", "x.yaml"); err == nil {
+		t.Error("a preset and a file were both taken")
+	}
+}

internal/cli/model_serve.go

@@ -60,6 +60,8 @@ func newModelServeCmd(client func() *ctlClient) *cobra.Command {
 	f.StringVar(&req.Quant, "quant", "", "the quantisation to serve (default: the one that suits the cluster best)")
 	f.StringVar(&req.File, "file", "", "the file to serve, instead of choosing by --quant")
 	f.StringVar(&req.Projector, "projector", "", "a vision model's mmproj file, fetched and loaded beside it")
+	f.BoolVar(&req.Embeddings, "embeddings", false, "serve it as an embedding model (its GGUF header says so for most): "+
+		"--embedding, 32 slots of 1024 tokens unless --ctx-pool or --context-length says otherwise")
 	f.StringVar(&req.Format, "format", "gguf", "gguf, run by llama.cpp, or safetensors: the original weights, run by vLLM on GPUs")
 	f.BoolVar(&req.CPU, "cpu", false, "run it on the CPU, whatever the plan says")
 	f.StringVar(&req.GPUClass, "gpu-class", "", "run it on GPUs of this class, whatever the plan says")

internal/cli/root.go

@@ -54,6 +54,7 @@ func Root() *cobra.Command {
 		newMirrorCmd(),
 		newBundleCmd(),
 		newSimEngineCmd(),
+		newComfyUIGateCmd(),
 		newDoctorCmd(),
 		newNodeCmd(),
 		newSelfUpgradeCmd(),

internal/cli/selfupgrade.go

@@ -1,8 +1,11 @@
 package cli
 
 import (
+	"context"
 	"errors"
 	"fmt"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+	"io"
 	"os"
 	"os/exec"
 	"runtime"
@@ -70,6 +73,9 @@ func newSelfUpgradeCmd() *cobra.Command {
 				if strings.TrimSpace(string(b)) == "active" {
 					if steady++; steady >= 3 {
 						fmt.Fprintf(out, "%s restarted and running\n", service)
+						if service == "llmgw-server" {
+							nodesLeftBehind(cmd.Context(), out, newCtlClient("127.0.0.1:9090"), v)
+						}
 						return nil
 					}
 				} else {
@@ -85,3 +91,25 @@ func newSelfUpgradeCmd() *cobra.Command {
 	c.Flags().StringVar(&service, "service", "", "the systemd unit to restart afterwards, e.g. llmgw-mirror")
 	return c
 }
+
+// nodesLeftBehind says, after a control plane alone was upgraded, that its
+// nodes were not, and how they are: this command looks like the cluster's
+// upgrade and is not, and a site's nodes stayed a release behind after it.
+func nodesLeftBehind(ctx context.Context, out io.Writer, c *ctlClient, v string) {
+	var nodes []adminapi.NodeView
+	_ = c.patient(20*time.Second).get(ctx, "/api/v1/nodes", &nodes)
+	behind := 0
+	for _, n := range nodes {
+		if n.AgentVersion != v {
+			behind++
+		}
+	}
+	switch {
+	case len(nodes) == 0:
+		fmt.Fprintf(out, "This upgraded this machine only. The nodes are upgraded from the leading "+
+			"control plane with:\n  sudo llmgw ctl upgrade %s --skip-control-plane\n", v)
+	case behind > 0:
+		fmt.Fprintf(out, "This upgraded this machine only: %d of %d node(s) are not on %s. On the leading "+
+			"control plane, run:\n  sudo llmgw ctl upgrade %s --skip-control-plane\n", behind, len(nodes), v, v)
+	}
+}

internal/cli/server.go

@@ -49,6 +49,7 @@ import (
 	"gitea.mynodes.xyz/ilker/llmgw/internal/control/fleetmetrics"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/control/modelsvc"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/control/reconciler"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/train"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/guard"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/hf"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/kvevents"
@@ -209,6 +210,10 @@ func newServerCmd() *cobra.Command {
 			if err != nil {
 				return err
 			}
+			if st := rt.Store(); st != nil {
+				// Each control plane raises the same events; one sends each.
+				notifier.SetClaimer(st)
+			}
 			rt.SetNotifier(notifier)
 			if gate != nil && notifier != nil {
 				gate.SetJudgeAlarm(func(model string, err error) {
@@ -232,6 +237,9 @@ func newServerCmd() *cobra.Command {
 			var agentHandler http.Handler
 			var agentPath string
 			var admin *control.Controller
+			// What the settings say of the firewall, for the mirror and the
+			// store's members; nil without a control plane.
+			var fwPub *firewallPublisher
 			updateMetrics := &modelserve.UpdateCollector{}
 			// The store's cluster, when it is one; read by the metrics and
 			// by `ctl status`.
@@ -256,6 +264,7 @@ func newServerCmd() *cobra.Command {
 				agentSvc = svc
 				// Stopped by the operators (llmgw stop): nothing placed.
 				ctl.Reconciler().SetStopped(cfg.Serving.Stopped)
+				ctl.Reconciler().SetEvictionTimes(cfg.OnDemand.EvictAfterIdle, cfg.OnDemand.MinLifetime)
 				// Whether nodes keep llmgw's firewall, as the settings say now.
 				svc.SetFirewall(func() *llmgwv1.Firewall {
 					c := current.Load()
@@ -263,9 +272,31 @@ func newServerCmd() *cobra.Command {
 					return &llmgwv1.Firewall{Enabled: c.Firewall.Enabled, Networks: c.FirewallNetworks,
 						EnginePortsFrom: int32(from), EnginePortsTo: int32(to)} //nolint:gosec // ports
 				})
+				// What each node's agent runs on, as the settings say now.
+				svc.SetAgentSettings(func(node string) string {
+					b, err := config.Marshal(current.Load().Agents.For(node))
+					if err != nil {
+						log.Warn("could not write a node's agent settings", "node", node, "err", err)
+						return ""
+					}
+					return string(b)
+				})
 				ctl.Reconciler().SetNotifier(notifier)
 				admin = ctl
 				agentPath, agentHandler = svc.Handler()
+				fwPub = newFirewallPublisher(func() config.Server { return *current.Load() }, rt.Store(),
+					func() []string {
+						var out []string
+						for _, n := range ctl.Inventory().Nodes() {
+							out = append(out, n.MgmtAddr)
+						}
+						return out
+					},
+					func() bool { return ctl.Leadership() == nil || ctl.Leadership().IsLeader() }, log)
+				go fwPub.run(ctx, 5*time.Minute)
+				if l := ctl.Leadership(); l != nil {
+					l.OnLead(fwPub.Kick)
+				}
 
 				// Before AdminHandler, which is where the registry is built —
 				// registering after it silently publishes nothing, which is
@@ -378,10 +409,19 @@ func newServerCmd() *cobra.Command {
 					// Knowledge bases, with the cluster's own models to embed a
 					// probe (a collection's dimension) and an operator's search.
 					api.SetKB(&adminapi.KBAdmin{Store: st, Embed: embedder(rt.Replay)})
+					// LoRA adapters trained on the nodes.
+					if agentSvc != nil {
+						trainer := train.New(st, agentSvc, log)
+						agentSvc.SetTrain(trainer)
+						go trainer.Run(ctx)
+						api.SetTrain(&adminapi.TrainAdmin{Store: st, Service: trainer})
+					}
 					// The cluster's settings, each change checked against this
 					// machine's own keys before it is kept.
 					api.SetSettings(&adminapi.Settings{Store: st, LocalKeys: config.LocalKeys(),
 						Check: func(body []byte) error { return checkClusterSettings(configPath, body) }})
+					// And the same document on the portal, for administrators.
+					rt.SetSettingsCheck(func(body []byte) error { return checkClusterSettings(configPath, body) }, config.LocalKeys())
 				}
 				// Catalog changes need somewhere to persist, so this is wired
 				// only when there is a store. Without one, the endpoints say so
@@ -426,6 +466,14 @@ func newServerCmd() *cobra.Command {
 					}
 					api.SetModels(svc)
 					catalogSvc = svc
+					// The models that come with llmgw: added by the leader
+					// when a node fits one and the catalog makes nothing of
+					// its kind, unless somebody removed it or turned it off.
+					api.SetPresets(st, func() adminapi.PresetConfig {
+						c := current.Load()
+						return adminapi.PresetConfig{Auto: c.Presets.Auto, ComfyUI: c.Engines[catalog.EngineComfyUI]}
+					})
+					go runPresetsPass(ctx, api, admin.Leadership(), log)
 					// And the mirror page, so a model that has just been
 					// fetched can be served without writing YAML by hand.
 					rt.SetCatalogAdmin(svc)
@@ -438,6 +486,7 @@ func newServerCmd() *cobra.Command {
 					api.SetUsage(st)
 					// Capacity quotas, set and read over this API.
 					api.SetQuotas(st)
+					api.SetTenancy(st)
 				}
 				api.Register(adminMux)
 
@@ -499,6 +548,16 @@ func newServerCmd() *cobra.Command {
 					return fmt.Errorf("the model mirror: %w", err)
 				}
 				rt.SetMirror(mc)
+				if fwPub != nil {
+					fwPub.setMirror(mc)
+				}
+				// Adapters trained on the nodes are kept there too; sending one
+				// takes longer than the mirror's usual answers.
+				if adminAPI != nil {
+					if up, err := mirror.NewClient(cfg.Mirror.API, cfg.Mirror.TLS, 10*time.Minute); err == nil {
+						adminAPI.SetTrainMirror(up)
+					}
+				}
 				// Browsing the registry is what turns "paste a resolve URL"
 				// into "find the model". It needs a way out to the internet
 				// from this machine, which the mirror's own fetching does not.
@@ -534,6 +593,25 @@ func newServerCmd() *cobra.Command {
 							},
 							gpus: func() []adminapi.ClassUse { return adminAPI.Summary().GPUs },
 							log:  log,
+							// An earlier install's judge, moved to today's figures.
+							profiles: catalogSvc,
+							restart:  admin.Reconciler().Restart,
+							replicas: func(model string) []string {
+								var ids []string
+								for _, r := range admin.Reconciler().ReadyReplicas() {
+									if r.Model == model {
+										ids = append(ids, r.ID)
+									}
+								}
+								return ids
+							},
+							nodeCPUs: func() []int {
+								var out []int
+								for _, n := range admin.Nodes() {
+									out = append(out, n.CPUCount)
+								}
+								return out
+							},
 						}
 						go keeper.run(ctx, 30*time.Second)
 					}
@@ -716,6 +794,16 @@ func newServerCmd() *cobra.Command {
 						if agentSvc != nil {
 							agentSvc.BroadcastFirewall()
 						}
+						if fwPub != nil {
+							fwPub.Kick()
+						}
+					}
+					if slices.ContainsFunc(changed, func(c string) bool { return strings.HasPrefix(c, "on_demand") }) && admin != nil {
+						admin.Reconciler().SetEvictionTimes(next.OnDemand.EvictAfterIdle, next.OnDemand.MinLifetime)
+					}
+					if slices.ContainsFunc(changed, func(c string) bool { return strings.HasPrefix(c, "agents") }) && agentSvc != nil {
+						// A moment apart per node, so off this goroutine.
+						go agentSvc.BroadcastAgentSettings()
 					}
 					if slices.ContainsFunc(changed, func(c string) bool { return strings.HasPrefix(c, "guard") }) {
 						if gate == nil {
@@ -1116,18 +1204,18 @@ func servableCheck(llamaVersion string) func(context.Context, catalog.Model) err
 		if llamaVersion == "" {
 			return nil
 		}
-		usesLlama := false
+		// Each source a llama.cpp profile loads: its own, or the model's.
 		for _, p := range m.Profiles {
-			if p.Engine == "llamacpp" {
-				usesLlama = true
+			if p.Engine != "llamacpp" {
+				continue
+			}
+			url, ok := sourcecheck.HTTPSource(m.SourceOf(p))
+			if !ok || !gguf.IsGGUF(url) {
+				continue
+			}
+			if v := gguf.Check(ctx, url, llamaVersion); !v.Servable {
+				return fmt.Errorf("%s cannot be served: %s", m.Name, v.Reason)
 			}
-		}
-		url, ok := sourcecheck.HTTPSource(m.Source)
-		if !usesLlama || !ok || !gguf.IsGGUF(url) {
-			return nil
-		}
-		if v := gguf.Check(ctx, url, llamaVersion); !v.Servable {
-			return fmt.Errorf("%s cannot be served: %s", m.Name, v.Reason)
 		}
 		return nil
 	}
@@ -1224,3 +1312,32 @@ func embedder(replay func(ctx context.Context, path, model string, body []byte)
 		return res.Data[0].Embedding, nil
 	}
 }
+
+// presetsEvery is how often the leader looks for presets to add; the first
+// look waits as long, for the nodes to have registered their cards.
+const presetsEvery = time.Minute
+
+// runPresetsPass has the leader add the presets a node fits and the catalog
+// lacks, now and then.
+func runPresetsPass(ctx context.Context, api *adminapi.API, lead *control.Leadership, log *slog.Logger) {
+	t := time.NewTicker(presetsEvery)
+	defer t.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+		}
+		if lead != nil && !lead.IsLeader() {
+			continue
+		}
+		added, err := api.PresetsPass(ctx)
+		for _, name := range added {
+			log.Info("added a preset by itself: a node fits it and the catalog made nothing of its kind",
+				"model", name, "off_switch", "presets.auto")
+		}
+		if err != nil {
+			log.Warn("could not add a preset", "err", err)
+		}
+	}
+}

internal/cli/serveradd.go

@@ -9,6 +9,7 @@ import (
 	"encoding/pem"
 	"errors"
 	"fmt"
+	"hash/fnv"
 	"io"
 	"net"
 	"os"
@@ -44,6 +45,11 @@ type serverAdd struct {
 	// addr is the machine's address as given; ip what the others reach it at.
 	addr, ip, name string
 	out            io.Writer
+	// priority is its keepalived priority, under this machine's 110; 0 is
+	// 100. Two standbys get two, so which takes the address is not a tie.
+	priority int
+	// quiet leaves out the closing sentence, for init, which says its own.
+	quiet bool
 }
 
 func newServerAddCmd() *cobra.Command {
@@ -148,7 +154,9 @@ func (sa *serverAdd) run(ctx context.Context) error {
 			return fmt.Errorf("%s: %w", s.name, err)
 		}
 	}
-	fmt.Fprintf(sa.out, "\n%s is a control plane of this cluster, standing by while this one leads.\n", sa.name)
+	if !sa.quiet {
+		fmt.Fprintf(sa.out, "\n%s is a control plane of this cluster, standing by while this one leads.\n", sa.name)
+	}
 	return nil
 }
 
@@ -160,7 +168,7 @@ func (sa *serverAdd) firewall(ctx context.Context) error {
 		return err
 	}
 	// What applies the cluster's firewall setting there when it changes.
-	if err := installFirewallSync(ctx, sa.remote); err != nil {
+	if err := installFirewallSync(ctx, sa.remote, firewallStateFile); err != nil {
 		fmt.Fprintf(sa.out, "  !!    firewall: %v\n", err)
 	}
 	if !cfg.Firewall.Enabled {
@@ -511,18 +519,31 @@ func (sa *serverAdd) floating(ctx context.Context) error {
 		return err
 	}
 	here := pgha.Local{}
+	priority := sa.priority
+	if priority <= 0 {
+		priority = 100
+	}
 	for _, m := range []struct {
 		r        onboard.Remote
 		name     string
 		priority int
-	}{{here, "this machine", 110}, {sa.remote, sa.name, 100}} {
+	}{{here, "this machine", 110}, {sa.remote, sa.name, priority}} {
+		// The interface on the address's network, by its route: not the
+		// route to the address, which is lo on the machine holding it
+		// already, as a run after the first finds it.
 		out, err := m.r.Run(ctx, fmt.Sprintf(`set -e
 command -v keepalived >/dev/null 2>&1 || { sudo DEBIAN_FRONTEND=noninteractive apt-get -qq update >/dev/null; sudo DEBIAN_FRONTEND=noninteractive apt-get -qq install -y keepalived >/dev/null; }
-ip -o route get %s | awk '{for(i=1;i<=NF;i++) if($i=="dev") {print $(i+1); exit}}'`, vip), nil)
+dev() { awk '{for(i=1;i<=NF;i++) if($i=="dev") {print $(i+1); exit}}'; }
+d=$(ip -o -4 route show %s | dev)
+[ -n "$d" ] && [ "$d" != lo ] || d=$(ip -o route get %s | dev)
+echo "$d"`, nw.String(), vip), nil)
 		if err != nil {
 			return fmt.Errorf("on %s: %v: %s", m.name, err, strings.TrimSpace(string(out)))
 		}
 		iface := strings.TrimSpace(string(out))
+		if iface == "" || iface == "lo" {
+			return fmt.Errorf("on %s: no interface on %s's network", m.name, sa.vip)
+		}
 		conf := keepalivedConf(iface, vip.String(), prefix, m.priority, pass)
 		if out, err := m.r.Run(ctx, `set -e
 sudo install -d -m 0755 /etc/keepalived
@@ -560,6 +581,17 @@ func vrrpPassword(etcDir string) (string, error) {
 	return pass, nil
 }
 
+// vrrpRouterID is the VRRP router id for a floating address: from the
+// address, so two clusters on one network, each with its own address, do
+// not answer each other's adverts — with one id for all, each logged the
+// other's as an invalid password, and dropped its own address's
+// announcements with them.
+func vrrpRouterID(vip string) int {
+	h := fnv.New32a()
+	_, _ = h.Write([]byte(vip))
+	return int(h.Sum32()%255) + 1
+}
+
 func keepalivedConf(iface, vip string, prefix, priority int, pass string) string {
 	return fmt.Sprintf(`# llmgw: the gateway's floating address, on whichever control plane leads.
 vrrp_script llmgw_leader {
@@ -572,7 +604,7 @@ vrrp_script llmgw_leader {
 vrrp_instance llmgw {
   state BACKUP
   interface %s
-  virtual_router_id 51
+  virtual_router_id %d
   priority %d
   advert_int 1
   authentication {
@@ -586,7 +618,7 @@ vrrp_instance llmgw {
     llmgw_leader
   }
 }
-`, iface, priority, pass, vip, prefix)
+`, iface, vrrpRouterID(vip), priority, pass, vip, prefix)
 }
 
 // clientCapable says a control plane's certificate can also present itself

internal/cli/serverinit.go

@@ -73,6 +73,9 @@ type serverInit struct {
 	// patroni are user@host of the machines to keep the store on under
 	// Patroni, replicated; this machine is the third etcd vote for two.
 	patroni []string
+	// webhooks are where the cluster's alerts go: put into its settings
+	// once it runs, and each sent a test.
+	webhooks []string
 	// patroniNodes are the same machines already connected to, which the
 	// setup screen does with the password it was given; when set, patroni
 	// only names them.
@@ -92,9 +95,34 @@ type serverInit struct {
 	// bundle is an offline bundle to install from, and bundleSHA its
 	// manifest's sha256: the cluster is then set up offline.
 	bundle, bundleSHA string
-	// mirrorPath is the mirror's directory here; "" is /srv/models. A seam
-	// for tests.
+	// mirrorPath is the mirror's directory here; "" is /srv/models.
 	mirrorPath string
+
+	// What setup lets a person choose besides the parts: zero is the
+	// default (serverinit_choices.go).
+	starter    starterSpec
+	starterCtx int
+	judge      judgeSpec
+	// language is the portal's for a browser that asks for neither of its
+	// own; "" leaves it English.
+	language               string
+	signupOpen             bool
+	defaultRPM, defaultTPM int
+	maxKeyTTL              time.Duration
+	// media has the nodes install ComfyUI and the leader add a picture model
+	// and a 3D model once a card fits one.
+	media bool
+	// evictAfterIdle and minLifetime are on_demand's; zero leaves its own.
+	evictAfterIdle, minLifetime time.Duration
+	// standbys makes each machine of the replicated store a control plane
+	// too, standing by while this one leads: three machines, each able to
+	// take over. vip is a floating address, as 10.0.0.160/24, kept on
+	// whichever leads.
+	standbys bool
+	vip      string
+	// cpus is this machine's CPU count for dividing it between init's
+	// models; zero asks the machine. A seam for tests.
+	cpus int
 	// pgSetup prepares PostgreSQL and returns the store address; a seam for
 	// tests. Nil does it for real.
 	pgSetup func(context.Context) (string, error)
@@ -119,7 +147,10 @@ func newDefaultServerInit() serverInit {
 
 func newServerInitCmd() *cobra.Command {
 	in := newDefaultServerInit()
-	var plain bool
+	var (
+		plain              bool
+		starter, judgeCats string
+	)
 	cmd := &cobra.Command{
 		Use:   "init",
 		Short: "Set this machine up as a control plane and start it",
@@ -155,6 +186,9 @@ func newServerInitCmd() *cobra.Command {
 			if os.Geteuid() != 0 {
 				return errors.New("init creates a user, writes /etc and starts a service: run it as root")
 			}
+			if err := in.readChoices(starter, judgeCats); err != nil {
+				return err
+			}
 			in.out = cmd.OutOrStdout()
 			if !plain && isTerminal(in.out) {
 				return in.runInitTUI(cmd.Context(), in.out)
@@ -182,9 +216,40 @@ func newServerInitCmd() *cobra.Command {
 		"leave the firewall alone, instead of keeping llmgw's internal ports to the cluster's networks")
 	f.BoolVar(&in.postgres, "postgres", false,
 		"keep the store in PostgreSQL on this machine, installing it and moving an existing SQLite store into it")
+	f.StringArrayVar(&in.webhooks, "webhook", nil,
+		"where alerts go — a model parked, a node lost, a budget spent: an http(s) address, Slack's, Mattermost's "+
+			"and Rocket.Chat's sent Slack's text, any other the event as JSON (slack: or json: in front says which); repeatable")
 	f.StringArrayVar(&in.patroni, "patroni", nil,
 		"user@host of a machine to keep the store on, replicated under Patroni; give two or more. "+
 			"Installs PostgreSQL, Patroni and etcd there over ssh, and moves the existing store in")
+
+	// What server.yaml is written with; each is in it only when init writes
+	// it, never into one already there.
+	f.StringVar(&in.mirrorPath, "mirror-dir", mirrorDir, "the directory the mirror on this machine keeps model files in")
+	f.StringVar(&starter, "starter", starterName,
+		"the starter model: "+strings.Join(starterNames(), ", ")+", or hf:<owner>/<repo>/<file>.gguf")
+	f.IntVar(&in.starterCtx, "starter-context", defaultContext, "the context, in tokens, a client may use of the starter model")
+	f.StringVar(&in.judge.Fail, "judge-fail", "closed",
+		"a request no judge read in time: closed refuses it, open serves it flagged")
+	f.StringVar(&judgeCats, "judge-categories", strings.Join(defaultJudgeCategories, ","),
+		"what the judge refuses, comma-separated, of: "+strings.Join(judgeCategories, ", "))
+	f.IntVar(&in.judge.Replicas, "judge-replicas", 2, "how many copies of the judge run, each on CPUs")
+	f.DurationVar(&in.judge.Budget, "judge-budget", 5*time.Second, "how long a request waits for the judge")
+	f.StringVar(&in.language, "language", "", "the portal's language for a browser that asks for neither: en or tr")
+	f.BoolVar(&in.signupOpen, "signup-open", false, "let anyone ask for an account on the portal, to be approved by an administrator")
+	f.IntVar(&in.defaultRPM, "default-rpm", defaultRPM, "requests a minute a key may make when nothing gives it a limit")
+	f.IntVar(&in.defaultTPM, "default-tpm", defaultTPM, "tokens a minute a key may use when nothing gives it a limit")
+	f.DurationVar(&in.maxKeyTTL, "max-key-ttl", defaultMaxKeyTTL, "the longest an API key lives")
+	f.BoolVar(&in.media, "media", false,
+		"pictures and 3D: the nodes install ComfyUI, and a picture model and a 3D model are added once a card fits one")
+	f.DurationVar(&in.evictAfterIdle, "evict-after-idle", 0,
+		"how long a model loaded on demand goes unasked-for before another may have its card (0: 2m)")
+	f.DurationVar(&in.minLifetime, "min-lifetime", 0,
+		"how long a model just loaded on demand is safe from that (0: 5m)")
+	f.BoolVar(&in.standbys, "standbys", false,
+		"with --patroni, make each of those machines a control plane too, standing by while this one leads")
+	f.StringVar(&in.vip, "vip", "",
+		"with --standbys, a floating address for whichever control plane leads, as 10.0.0.160/24 (keepalived on each)")
 	return cmd
 }
 
@@ -249,6 +314,9 @@ func (in *serverInit) run(ctx context.Context) error {
 			fmt.Fprintf(in.out, "  !!    firewall: %v; llmgw's ports answer every network this machine is on\n", err)
 		}
 	}
+	if err := in.ensureWebhooks(ctx); err != nil {
+		fmt.Fprintf(in.out, "  !!    webhooks: %v\n", err)
+	}
 	if in.judgeWanted() && in.configJudgesWith(guardModelName) {
 		// Not fatal: without its judge the baseline policy still checks for
 		// secrets and injection, and a judged request is served flagged.
@@ -265,6 +333,11 @@ func (in *serverInit) run(ctx context.Context) error {
 			return fmt.Errorf("starter model: %w", err)
 		}
 	}
+	if in.standbys {
+		if err := in.ensureStandbys(ctx); err != nil {
+			return fmt.Errorf("standby control planes: %w", err)
+		}
+	}
 	in.nextSteps()
 	return nil
 }
@@ -301,29 +374,45 @@ func (in *serverInit) configJudgesWith(model string) bool {
 }
 
 // guardSection is server.yaml's guard: the baseline every request passes,
-// with the judge model when there is one.
+// with the judge model, as init sets it up unless told otherwise, when there
+// is one.
 func guardSection(judge bool) string {
-	j := `      # A judge model reads what patterns cannot: violence, weapons, abuse,
+	if !judge {
+		return guardSectionFor(nil)
+	}
+	j := (&serverInit{}).judgeFor()
+	return guardSectionFor(&j)
+}
+
+// guardSectionFor is server.yaml's guard with this judge, or none.
+func guardSectionFor(j *judgeSpec) string {
+	fail := "closed"
+	jb := `      # A judge model reads what patterns cannot: violence, weapons, abuse,
       # self-harm. Installed by init; --no-guard-model leaves it out.
       # judge: {model: ` + guardModelName + `, input: block, output: block, ...}
 `
-	if judge {
-		j = `      # A judge model reads what patterns cannot: violence, crime, sexual
-      # content, self-harm, jailbreaks. Two replicas run on CPUs, about two
+	if j != nil {
+		fail = j.Fail
+		copies := map[int]string{1: "One replica runs", 2: "Two replicas run", 3: "Three replicas run"}[j.Replicas]
+		if copies == "" {
+			copies = fmt.Sprintf("%d replicas run", j.Replicas)
+		}
+		jb = `      # A judge model reads what patterns cannot: violence, crime, sexual
+      # content, self-harm, jailbreaks. ` + copies + ` on CPUs, about two
       # seconds for a short text; an answer is read every 600 characters as
       # it streams. With fail: closed, a request no judge can read within
       # latency_budget is refused (503); open serves it, flagged, unjudged.
       # PII is the patterns' (above), and copyright, unethical acts and
-      # politically sensitive topics are left out: they refuse too much
-      # ordinary work. Controversial counts as safe; controversial: unsafe
-      # makes it count. With a GPU: llmgw ctl guard judge enable --gpu, then
-      # llmgw ctl guard judge use ` + defaultGPUJudge + ` ` + guardModelName + `.
+      # politically sensitive topics are left out unless chosen: they refuse
+      # too much ordinary work. Controversial counts as safe; controversial:
+      # unsafe makes it count. With a GPU: llmgw ctl guard judge enable --gpu,
+      # then llmgw ctl guard judge use ` + defaultGPUJudge + ` ` + guardModelName + `.
       judge:
         models: [` + guardModelName + `]
         input: block
         output: block
-        categories: [Violent, Non-violent Illegal Acts, Sexual Content or Sexual Acts, Suicide & Self-Harm, Jailbreak]
-        latency_budget: 5s
+        categories: [` + strings.Join(j.Categories, ", ") + `]
+        latency_budget: ` + durationYAML(j.Budget) + `
 `
 	}
 	return `# Guardrails (docs/guardrails.md). The baseline applies to every request;
@@ -333,13 +422,13 @@ guard:
   default: [baseline]
   policies:
     baseline:
-      fail: closed
+      fail: ` + fail + `
       input:
         pii: {secret: block, card: redact}
         injection: flag
       output:
         pii: {secret: block, card: redact}
-` + j
+` + jb
 }
 
 func (in *serverInit) done(format string, a ...any) {
@@ -518,6 +607,10 @@ func (in *serverInit) certHosts() []string {
 	for _, h := range in.hosts {
 		add(h)
 	}
+	// The floating address is this machine's whenever it leads.
+	if ip, _, err := net.ParseCIDR(in.vip); err == nil {
+		add(ip.String())
+	}
 	if name, err := os.Hostname(); err == nil {
 		add(name)
 	}
@@ -556,8 +649,13 @@ func (in *serverInit) ensureConfig(context.Context) error {
 		if contact == "" {
 			contact = "platform@example.com"
 		}
-		body := fmt.Sprintf(serverConfigTemplate, in.etcDir, in.etcDir, in.etcDir,
-			in.storeAddress(), contact, guardSection(in.judgeWanted()))
+		var judge *judgeSpec
+		if in.judgeWanted() {
+			j := in.judgeFor()
+			judge = &j
+		}
+		body := in.tuneConfig(fmt.Sprintf(serverConfigTemplate, in.etcDir, in.etcDir, in.etcDir,
+			in.storeAddress(), contact, guardSectionFor(judge)))
 		if err := os.WriteFile(path, []byte(body), 0o640); err != nil {
 			return err
 		}

internal/cli/serverinit_choices.go

@@ -0,0 +1,411 @@
+package cli
+
+import (
+	"fmt"
+	"math"
+	"net"
+	"path"
+	"slices"
+	"strconv"
+	"strings"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/provision"
+)
+
+// What a first install lets a person choose beyond which parts it has: which
+// starter model, how the judge decides, what the portal speaks, the limits a
+// key starts with, and whether pictures and 3D come by themselves. Each zero
+// value is what init did before it could be chosen, so `llmgw server init`
+// with no flags installs what it always did.
+//
+// All of it is written into server.yaml when init writes it, and the cluster's
+// keys among it become the cluster's first settings when the control plane
+// first starts. A server.yaml already there is never overwritten, so a second
+// run changes none of it: the settings page and `llmgw ctl config` do.
+
+// starterSpec is a model init can fetch and serve so there is something to ask.
+type starterSpec struct {
+	Name, Alias, Source string
+	// SizeGB is the weights' size, for the memory a node needs; 0 is not known.
+	SizeGB float64
+	About  string
+}
+
+// starterChoices are the starters offered, smallest first: the first is the
+// default. Each is a single GGUF file, Q4_K_M.
+var starterChoices = []starterSpec{
+	{starterName, starterAlias, starterSource, 0.5, "answers at once on any CPU; fast, not clever"},
+	{"qwen2.5-1.5b-instruct", "qwen-1.5b", "hf:Qwen/Qwen2.5-1.5B-Instruct-GGUF/qwen2.5-1.5b-instruct-q4_k_m.gguf", 1.1,
+		"still quick on a CPU, and noticeably better"},
+	{"qwen2.5-3b-instruct", "qwen-3b", "hf:Qwen/Qwen2.5-3B-Instruct-GGUF/qwen2.5-3b-instruct-q4_k_m.gguf", 2.1,
+		"slow on a CPU, quick on any GPU"},
+	{"qwen3-4b", "", "hf:Qwen/Qwen3-4B-GGUF/Qwen3-4B-Q4_K_M.gguf", 2.5,
+		"thinks before it answers; a GPU is worth having"},
+	{"qwen3-8b", "", "hf:Qwen/Qwen3-8B-GGUF/Qwen3-8B-Q4_K_M.gguf", 5.0,
+		"a real assistant; a GPU with 8 GB or more"},
+	{"qwen3-14b", "", "hf:Qwen/Qwen3-14B-GGUF/Qwen3-14B-Q4_K_M.gguf", 9.0,
+		"better still; a GPU with 16 GB or more"},
+}
+
+// starterFrom reads --starter: a name from starterChoices, or the hf: source
+// of any GGUF file, named after the file.
+func starterFrom(s string) (starterSpec, error) {
+	s = strings.TrimSpace(s)
+	for _, c := range starterChoices {
+		if s == c.Name || (c.Alias != "" && s == c.Alias) {
+			return c, nil
+		}
+	}
+	if rest, ok := strings.CutPrefix(s, "hf:"); ok && strings.Count(rest, "/") >= 2 && strings.HasSuffix(strings.ToLower(rest), ".gguf") {
+		name := strings.ToLower(strings.TrimSuffix(path.Base(rest), path.Ext(rest)))
+		return starterSpec{Name: name, Source: s, About: "chosen at install"}, nil
+	}
+	var names []string
+	for _, c := range starterChoices {
+		names = append(names, c.Name)
+	}
+	return starterSpec{}, fmt.Errorf("starter %q: one of %s, or hf:<owner>/<repo>/<file>.gguf", s, strings.Join(names, ", "))
+}
+
+func starterNames() []string {
+	var out []string
+	for _, c := range starterChoices {
+		out = append(out, c.Name)
+	}
+	return out
+}
+
+// readChoices takes the flags that are not read straight into init: the
+// starter by its name, the judge's categories by commas. Then it checks them
+// all.
+func (in *serverInit) readChoices(starter, categories string) error {
+	if strings.TrimSpace(starter) != "" {
+		s, err := starterFrom(starter)
+		if err != nil {
+			return err
+		}
+		in.starter = s
+	}
+	in.judge.Categories = nil
+	for _, c := range strings.Split(categories, ",") {
+		if c = strings.TrimSpace(c); c != "" {
+			in.judge.Categories = append(in.judge.Categories, c)
+		}
+	}
+	return in.checkChoices()
+}
+
+// checkChoices says what among the choices cannot be installed.
+func (in *serverInit) checkChoices() error {
+	switch in.language {
+	case "", "en", "tr":
+	default:
+		return fmt.Errorf("language %q: en or tr", in.language)
+	}
+	switch in.judge.Fail {
+	case "", "closed", "open":
+	default:
+		return fmt.Errorf("judge fail %q: closed or open", in.judge.Fail)
+	}
+	for _, c := range in.judge.Categories {
+		if !slices.Contains(judgeCategories, c) {
+			return fmt.Errorf("judge category %q: one of %s", c, strings.Join(judgeCategories, ", "))
+		}
+	}
+	switch {
+	case in.judge.Replicas < 0 || in.judge.Replicas > 8:
+		return fmt.Errorf("judge replicas %d: from 1 to 8", in.judge.Replicas)
+	case in.judge.Budget < 0 || in.judge.Budget > time.Minute:
+		return fmt.Errorf("judge budget %s: at most a minute", in.judge.Budget)
+	case in.starterCtx < 0 || in.starterCtx > 262144:
+		return fmt.Errorf("starter context %d: at most 262144 tokens", in.starterCtx)
+	case in.starterCtx > 0 && in.starterCtx < 512:
+		return fmt.Errorf("starter context %d: at least 512 tokens", in.starterCtx)
+	case in.defaultRPM < 0 || in.defaultTPM < 0:
+		return fmt.Errorf("default limits cannot be negative")
+	case in.maxKeyTTL < 0 || (in.maxKeyTTL > 0 && in.maxKeyTTL < time.Hour):
+		return fmt.Errorf("max key ttl %s: an hour at least", in.maxKeyTTL)
+	case in.evictAfterIdle < 0 || in.minLifetime < 0:
+		return fmt.Errorf("on-demand times cannot be negative")
+	case in.vip != "" && !in.standbys:
+		return fmt.Errorf("a floating address moves between control planes: it needs the standbys")
+	}
+	if in.vip != "" {
+		ip, _, err := net.ParseCIDR(in.vip)
+		if err != nil || ip.To4() == nil {
+			return fmt.Errorf("floating address %q: an IPv4 address with its prefix, as 10.0.0.160/24", in.vip)
+		}
+	}
+	return nil
+}
+
+// starterModelSpec is the starter this install serves.
+func (in *serverInit) starterModelSpec() starterSpec {
+	if in.starter.Source == "" {
+		return starterChoices[0]
+	}
+	return in.starter
+}
+
+// minMemoryGB is what a node needs free for the starter: its weights and
+// room for its context, never less than the 2 GB it always asked.
+func (s starterSpec) minMemoryGB() int {
+	return max(2, int(math.Ceil(s.SizeGB+1.5)))
+}
+
+// defaultContext is the context a client may use of the starter.
+const defaultContext = 4096
+
+// starterContext is the context a client may use of the starter.
+func (in *serverInit) starterContext() int {
+	if in.starterCtx > 0 {
+		return in.starterCtx
+	}
+	return defaultContext
+}
+
+// judgeSpec is how the guardrails' judge decides.
+type judgeSpec struct {
+	// Fail is what is done with a request no judge read in time: closed
+	// refuses it, open serves it flagged.
+	Fail       string
+	Categories []string
+	Replicas   int
+	Budget     time.Duration
+}
+
+// judgeCategories are the ones a judge can be asked about, as Qwen3Guard
+// names them; defaultJudgeCategories those it is asked about unless told.
+var (
+	judgeCategories = []string{"Violent", "Non-violent Illegal Acts", "Sexual Content or Sexual Acts",
+		"Suicide & Self-Harm", "Jailbreak", "PII", "Unethical Acts", "Politically Sensitive Topics", "Copyright Violation"}
+	defaultJudgeCategories = judgeCategories[:5]
+)
+
+// judgeFor is the judge as this install sets it up, the defaults filled in.
+func (in *serverInit) judgeFor() judgeSpec {
+	j := in.judge
+	if j.Fail == "" {
+		j.Fail = "closed"
+	}
+	if len(j.Categories) == 0 {
+		j.Categories = defaultJudgeCategories
+	}
+	if j.Replicas <= 0 {
+		j.Replicas = 2
+		if in.singleMachine() {
+			j.Replicas = 1
+		}
+	}
+	if j.Budget <= 0 {
+		j.Budget = 5 * time.Second
+	}
+	return j
+}
+
+// singleMachine is an install where this machine is the only node there
+// will be, as far as init knows: a second judge replica there shares the
+// same cores and is lost with the same machine, so it buys nothing but
+// half the speed of each.
+func (in *serverInit) singleMachine() bool {
+	return !in.noNode && !in.standbys && len(in.patroni) == 0 && len(in.patroniNodes) == 0
+}
+
+// The configuration's limits, as init writes them unless told otherwise.
+const (
+	defaultRPM       = 60
+	defaultTPM       = 200000
+	defaultMaxKeyTTL = 2160 * time.Hour
+)
+
+// tuneConfig writes this install's choices into the server.yaml template:
+// the lines the template has, changed, and the blocks it has not, added.
+// Unchosen, the template comes back as it was.
+func (in *serverInit) tuneConfig(body string) string {
+	set := func(old, now string) {
+		if old != now {
+			body = strings.Replace(body, old, now, 1)
+		}
+	}
+	if in.signupOpen {
+		set("  signup_open: false", "  signup_open: true")
+	}
+	if in.defaultRPM > 0 {
+		set("  default_rpm: 60", "  default_rpm: "+strconv.Itoa(in.defaultRPM))
+	}
+	if in.defaultTPM > 0 {
+		set("  default_tpm: 200000", "  default_tpm: "+strconv.Itoa(in.defaultTPM))
+	}
+	if in.maxKeyTTL > 0 && in.maxKeyTTL != defaultMaxKeyTTL {
+		set("  max_key_ttl: 2160h   # 90 days", fmt.Sprintf("  max_key_ttl: %s   # %s", durationYAML(in.maxKeyTTL), days(in.maxKeyTTL)))
+	}
+	if in.language != "" {
+		set("  # language: tr", "  language: "+in.language)
+	}
+	var extra []string
+	if in.media {
+		extra = append(extra, "# Pictures and 3D, chosen at install: the nodes install ComfyUI, and the\n"+
+			"# leader adds a picture model and a 3D model by itself once a card fits\n"+
+			"# one ('llmgw ctl model presets auto off' stops it).\n"+
+			"engines:\n  comfyui: "+provision.ComfyUIVersion()+"\npresets:\n  auto: true\n")
+	}
+	if in.evictAfterIdle > 0 || in.minLifetime > 0 {
+		b := "# How models that load when asked for take turns on a card, chosen at\n# install.\non_demand:\n"
+		if in.evictAfterIdle > 0 {
+			b += "  evict_after_idle: " + durationYAML(in.evictAfterIdle) + "\n"
+		}
+		if in.minLifetime > 0 {
+			b += "  min_lifetime: " + durationYAML(in.minLifetime) + "\n"
+		}
+		extra = append(extra, b)
+	}
+	if len(extra) > 0 {
+		body += "\n" + strings.Join(extra, "\n")
+	}
+	return body
+}
+
+// durationYAML is a duration as a person writes it: 2h, 90m, 1m30s.
+func durationYAML(d time.Duration) string {
+	switch {
+	case d == 0:
+		return "0s"
+	case d%time.Hour == 0:
+		return fmt.Sprintf("%dh", d/time.Hour)
+	case d%time.Minute == 0:
+		return fmt.Sprintf("%dm", d/time.Minute)
+	}
+	return d.String()
+}
+
+func days(d time.Duration) string {
+	n := int(d.Hours() / 24)
+	if n == 1 {
+		return "1 day"
+	}
+	return fmt.Sprintf("%d days", n)
+}
+
+// initFlags is this install as `llmgw server init`'s flags, for doing it
+// again from a script; what is left at its default is left out.
+func (in *serverInit) initFlags() []string {
+	var out []string
+	add := func(flag string, v ...string) {
+		if len(v) == 0 {
+			out = append(out, flag)
+			return
+		}
+		out = append(out, flag+" "+shellWord(v[0]))
+	}
+	if in.admin != "" {
+		add("--admin", in.admin)
+	}
+	for _, h := range in.hosts {
+		add("--host", h)
+	}
+	if in.language != "" {
+		add("--language", in.language)
+	}
+	if in.signupOpen {
+		add("--signup-open")
+	}
+	if in.defaultRPM > 0 && in.defaultRPM != defaultRPM {
+		add("--default-rpm", strconv.Itoa(in.defaultRPM))
+	}
+	if in.defaultTPM > 0 && in.defaultTPM != defaultTPM {
+		add("--default-tpm", strconv.Itoa(in.defaultTPM))
+	}
+	if in.maxKeyTTL > 0 && in.maxKeyTTL != defaultMaxKeyTTL {
+		add("--max-key-ttl", durationYAML(in.maxKeyTTL))
+	}
+	if in.postgres {
+		add("--postgres")
+	}
+	for _, t := range in.patroni {
+		add("--patroni", t)
+	}
+	switch {
+	case in.mirrorURL != "":
+		add("--mirror", in.mirrorURL)
+	case in.noMirror:
+		add("--no-mirror")
+	case in.mirrorPath != "" && in.mirrorPath != mirrorDir:
+		add("--mirror-dir", in.mirrorPath)
+	}
+	if in.bundle != "" {
+		add("--bundle", in.bundle)
+		add("--bundle-sha256", in.bundleSHA)
+	}
+	if in.noNode {
+		add("--no-node")
+	}
+	if in.noModel {
+		add("--no-model")
+	} else {
+		if s := in.starterModelSpec(); s.Name != starterName {
+			v := s.Name
+			if !slices.ContainsFunc(starterChoices, func(c starterSpec) bool { return c.Name == s.Name }) {
+				v = s.Source
+			}
+			add("--starter", v)
+		}
+		if in.starterCtx > 0 && in.starterCtx != defaultContext {
+			add("--starter-context", strconv.Itoa(in.starterCtx))
+		}
+	}
+	if in.noGuardModel {
+		add("--no-guard-model")
+	} else {
+		// Against the defaults for an install of the same shape: one judge
+		// on one machine, two otherwise.
+		shape := serverInit{noNode: in.noNode, standbys: in.standbys, patroni: in.patroni, patroniNodes: in.patroniNodes}
+		j, d := in.judgeFor(), shape.judgeFor()
+		if j.Fail != d.Fail {
+			add("--judge-fail", j.Fail)
+		}
+		if !slices.Equal(j.Categories, d.Categories) {
+			add("--judge-categories", strings.Join(j.Categories, ","))
+		}
+		if j.Replicas != d.Replicas {
+			add("--judge-replicas", strconv.Itoa(j.Replicas))
+		}
+		if j.Budget != d.Budget {
+			add("--judge-budget", durationYAML(j.Budget))
+		}
+	}
+	if in.noFirewall {
+		add("--no-firewall")
+	}
+	if in.standbys {
+		add("--standbys")
+	}
+	if in.vip != "" {
+		add("--vip", in.vip)
+	}
+	for _, w := range in.webhooks {
+		for _, s := range strings.Split(w, ",") {
+			if s = strings.TrimSpace(s); s != "" {
+				add("--webhook", s)
+			}
+		}
+	}
+	if in.media {
+		add("--media")
+	}
+	if in.evictAfterIdle > 0 {
+		add("--evict-after-idle", durationYAML(in.evictAfterIdle))
+	}
+	if in.minLifetime > 0 {
+		add("--min-lifetime", durationYAML(in.minLifetime))
+	}
+	return out
+}
+
+// shellWord quotes a word for a shell when it needs it.
+func shellWord(s string) string {
+	if s != "" && !strings.ContainsAny(s, " \t\n'\"\\$`&;|<>(){}*?[]#~!") {
+		return s
+	}
+	return "'" + strings.ReplaceAll(s, "'", `'\''`) + "'"
+}

internal/cli/serverinit_choices_test.go

@@ -0,0 +1,241 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/config"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/pgha"
+)
+
+func TestEveryChoiceIsInTheConfigurationWrittenAndItLoads(t *testing.T) {
+	in := &serverInit{
+		language: "tr", signupOpen: true, defaultRPM: 120, defaultTPM: 50000, maxKeyTTL: 30 * 24 * time.Hour,
+		media: true, evictAfterIdle: time.Minute, minLifetime: 90 * time.Second,
+		judge: judgeSpec{Fail: "open", Categories: []string{"Violent", "PII"}, Replicas: 3, Budget: 3 * time.Second},
+	}
+	j := in.judgeFor()
+	body := in.tuneConfig(fmt.Sprintf(serverConfigTemplate, "/etc/llmgw", "/etc/llmgw", "/etc/llmgw",
+		"/var/lib/llmgw/llmgw.db", "ops@example.com", guardSectionFor(&j)))
+	path := filepath.Join(t.TempDir(), "server.yaml")
+	if err := os.WriteFile(path, []byte(body), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := config.Load(path)
+	if err != nil {
+		t.Fatalf("%v\n%s", err, body)
+	}
+	if err := cfg.Validate(); err != nil {
+		t.Fatal(err)
+	}
+	switch {
+	case cfg.Landing.Language != "tr" || !cfg.Auth.SignupOpen:
+		t.Errorf("language %q signup %v", cfg.Landing.Language, cfg.Auth.SignupOpen)
+	case cfg.Auth.DefaultRPM != 120 || cfg.Auth.DefaultTPM != 50000 || cfg.Auth.MaxKeyTTL != 30*24*time.Hour:
+		t.Errorf("limits %d %d %s", cfg.Auth.DefaultRPM, cfg.Auth.DefaultTPM, cfg.Auth.MaxKeyTTL)
+	case !cfg.Presets.Auto || cfg.Engines["comfyui"] == "":
+		t.Errorf("pictures and 3D: presets %v comfyui %q", cfg.Presets.Auto, cfg.Engines["comfyui"])
+	case cfg.OnDemand.EvictAfterIdle != time.Minute || cfg.OnDemand.MinLifetime != 90*time.Second:
+		t.Errorf("on demand %+v", cfg.OnDemand)
+	}
+	base := cfg.Guard.Policies["baseline"]
+	if base.Fail != "open" || base.Judge == nil || !slices.Equal(base.Judge.Categories, []string{"Violent", "PII"}) ||
+		base.Judge.LatencyBudget != 3*time.Second {
+		t.Errorf("the judge as written: fail %q %+v", base.Fail, base.Judge)
+	}
+	if !strings.Contains(body, "Three replicas run on CPUs") {
+		t.Error("the comment says another number of judges than run")
+	}
+}
+
+func TestNothingChosenIsTheTemplateAsItWas(t *testing.T) {
+	body := fmt.Sprintf(serverConfigTemplate, "/e", "/e", "/e", "/s.db", "a@b", guardSection(true))
+	if got := (&serverInit{}).tuneConfig(body); got != body {
+		t.Error("an install with nothing chosen writes another configuration than before")
+	}
+	// Each line tuneConfig changes is in the template, or a choice would be
+	// lost without a word.
+	for _, line := range []string{"  signup_open: false", "  default_rpm: 60", "  default_tpm: 200000",
+		"  max_key_ttl: 2160h   # 90 days", "  # language: tr"} {
+		if !strings.Contains(serverConfigTemplate, line) {
+			t.Errorf("the template has no %q", line)
+		}
+	}
+}
+
+func TestAStarterIsChosenByNameOrByItsFile(t *testing.T) {
+	s, err := starterFrom("qwen3-8b")
+	if err != nil || s.SizeGB != 5.0 || !strings.HasPrefix(s.Source, "hf:Qwen/Qwen3-8B-GGUF/") {
+		t.Errorf("by name: %+v %v", s, err)
+	}
+	s, err = starterFrom("hf:bartowski/Phi-4-GGUF/Phi-4-Q4_K_M.gguf")
+	if err != nil || s.Name != "phi-4-q4_k_m" {
+		t.Errorf("by file: %+v %v", s, err)
+	}
+	if _, err := starterFrom("gpt-5"); err == nil {
+		t.Error("a model nobody offers was taken")
+	}
+	m := starterModel(s, 8192, 0, "http://x/p.gguf", []string{"6000-24g"}, true)
+	if m.Name != "phi-4-q4_k_m" || m.ContextLength != 8192 || len(m.Aliases) != 0 ||
+		!slices.Equal(m.Profiles[0].Args, []string{"--ctx-size", "32768"}) {
+		t.Errorf("entry %+v", m)
+	}
+	big, _ := starterFrom("qwen3-14b")
+	if m := starterModel(big, 16384, 0, "http://x/q.gguf", nil, true); m.Profiles[0].MinMemoryGB != 11 ||
+		!slices.Equal(m.Profiles[0].Args, []string{"--ctx-size", "65536"}) {
+		t.Errorf("a 9 GB starter asks for %d GB, %v", m.Profiles[0].MinMemoryGB, m.Profiles[0].Args)
+	}
+}
+
+func TestTheChoicesAreTheirFlagsAgain(t *testing.T) {
+	in := &serverInit{admin: "ops@example.com", hosts: []string{"llm.example.com"}, postgres: true,
+		mirrorPath: "/data/models", noNode: true, language: "tr", media: true,
+		webhooks: []string{"https://hooks.slack.com/services/T/B/x, json:https://a.example.com/in"},
+		judge:    judgeSpec{Categories: []string{"Violent", "Jailbreak"}}, maxKeyTTL: 7 * 24 * time.Hour}
+	in.starter, _ = starterFrom("qwen3-4b")
+	got := strings.Join(in.initFlags(), " ")
+	want := "--admin ops@example.com --host llm.example.com --language tr --max-key-ttl 168h --postgres " +
+		"--mirror-dir /data/models --no-node --starter qwen3-4b --judge-categories Violent,Jailbreak " +
+		"--webhook https://hooks.slack.com/services/T/B/x --webhook json:https://a.example.com/in --media"
+	if got != want {
+		t.Errorf("flags\n got %s\nwant %s", got, want)
+	}
+	if got := strings.Join((&serverInit{}).initFlags(), " "); got != "" {
+		t.Errorf("nothing chosen is %q", got)
+	}
+	if w := shellWord("Non-violent Illegal Acts,PII"); w != "'Non-violent Illegal Acts,PII'" {
+		t.Errorf("quoted %s", w)
+	}
+}
+
+func TestChoicesThatCannotBeInstalledAreRefused(t *testing.T) {
+	for _, in := range []serverInit{
+		{language: "de"},
+		{judge: judgeSpec{Fail: "maybe"}},
+		{judge: judgeSpec{Categories: []string{"Rudeness"}}},
+		{judge: judgeSpec{Replicas: 9}},
+		{starterCtx: 100},
+		{maxKeyTTL: time.Minute},
+		{vip: "10.0.0.160/24"},
+		{standbys: true, vip: "10.0.0.160"},
+	} {
+		if err := in.checkChoices(); err == nil {
+			t.Errorf("taken: %+v", in)
+		}
+	}
+	if err := (&serverInit{standbys: true, vip: "10.0.0.160/24"}).checkChoices(); err != nil {
+		t.Error(err)
+	}
+}
+
+func TestWithStandbysTheMirrorAnswersEveryControlPlane(t *testing.T) {
+	in := &serverInit{hosts: []string{"10.0.0.5"}, patroniNodes: []pgha.Node{
+		{Member: pgha.Member{Name: "db1", IP: "10.0.0.6"}}, {Member: pgha.Member{Name: "db2", IP: "10.0.0.7"}},
+	}}
+	if u := in.mirrorUnit(); !strings.Contains(u, "--api-listen 127.0.0.1:8082") || strings.Contains(u, "--api-allow") {
+		t.Errorf("one control plane: the API is for this machine only:\n%s", u)
+	}
+	in.standbys = true
+	u := in.mirrorUnit()
+	for _, want := range []string{"--api-listen :8082", "--api-allow 10.0.0.5", "--api-allow 10.0.0.6", "--api-allow 10.0.0.7"} {
+		if !strings.Contains(u, want) {
+			t.Errorf("the unit lacks %q:\n%s", want, u)
+		}
+	}
+	if got := in.mirrorAPIURL(); got != "http://10.0.0.5:8082" {
+		t.Errorf("the control planes reach the mirror at %s", got)
+	}
+}
+
+func TestTheFloatingAddressIsInTheCertificate(t *testing.T) {
+	in := &serverInit{vip: "10.0.0.160/24"}
+	if !slices.Contains(in.certHosts(), "10.0.0.160") {
+		t.Errorf("hosts %v", in.certHosts())
+	}
+}
+
+func TestStandbysWantTheStoresMachines(t *testing.T) {
+	in := &serverInit{standbys: true, out: &strings.Builder{}}
+	if err := in.ensureStandbys(context.Background()); err == nil || !strings.Contains(err.Error(), "--patroni") {
+		t.Errorf("standbys with nowhere to go: %v", err)
+	}
+}
+
+func TestTwoClustersOnOneNetworkKeepApartFloatingAddresses(t *testing.T) {
+	a, b := vrrpRouterID("10.0.0.161"), vrrpRouterID("10.0.0.164")
+	if a == b || a < 1 || a > 255 || b < 1 || b > 255 {
+		t.Errorf("router ids %d and %d", a, b)
+	}
+	conf := keepalivedConf("ens18", "10.0.0.164", 24, 100, "secret12")
+	if !strings.Contains(conf, fmt.Sprintf("virtual_router_id %d\n", b)) || !strings.Contains(conf, "interface ens18") {
+		t.Errorf("conf:\n%s", conf)
+	}
+}
+
+func TestTheJudgesAndTheStarterShareTheCPUsRatherThanEachTakingAll(t *testing.T) {
+	for _, c := range []struct {
+		in             serverInit
+		judge, starter int
+	}{
+		// One machine: one judge, on up to four cores; the starter has the rest.
+		{serverInit{cpus: 4}, 4, 0},
+		{serverInit{cpus: 8}, 4, 4},
+		{serverInit{cpus: 32}, 4, 8},
+		{serverInit{cpus: 2}, 2, 0},
+		{serverInit{cpus: 1}, 0, 0},
+		{serverInit{cpus: 4, noGuardModel: true}, judgeCores, 4}, // no judge: all for the starter
+		// Two asked for on one machine: two cores each, one each where two
+		// would not fit both.
+		{serverInit{cpus: 8, judge: judgeSpec{Replicas: 2}}, 2, 4},
+		{serverInit{cpus: 2, judge: judgeSpec{Replicas: 2}}, 1, 0},
+		{serverInit{cpus: 8, judge: judgeSpec{Replicas: 3}}, 2, 2},
+		{serverInit{cpus: 4, noNode: true}, 2, 0}, // on nodes not known yet
+	} {
+		got := c.in.cpuPlan()
+		if got.judge != c.judge || got.starter != c.starter {
+			t.Errorf("%+v: judge %d starter %d, want %d %d", c.in, got.judge, got.starter, c.judge, c.starter)
+		}
+	}
+	m := guardModel("http://x/g.gguf", 2, 1)
+	if p := m.Profiles[0]; p.CPUCores != 1 || p.MinMemoryGB != 2 || !slices.Contains(p.Args, "--cache-ram") {
+		t.Errorf("judge profile: %d cores, %d GB, args %v", p.CPUCores, p.MinMemoryGB, p.Args)
+	}
+	s := starterModel(starterChoices[0], defaultContext, 2, "http://x/q.gguf", []string{"6000-24g"}, true)
+	if cpu := s.Profiles[len(s.Profiles)-1]; cpu.Name != "cpu" || cpu.CPUCores != 2 || s.Profiles[0].CPUCores != 0 {
+		t.Errorf("starter: GPU profile %d cores, CPU %+v", s.Profiles[0].CPUCores, cpu)
+	}
+}
+
+// A second judge on the same machine shares its cores and is lost with it:
+// one machine has one, more machines two.
+func TestOneMachineHasOneJudgeAndMoreHaveTwo(t *testing.T) {
+	for _, c := range []struct {
+		in   serverInit
+		want int
+	}{
+		{serverInit{}, 1},
+		{serverInit{noNode: true}, 2},
+		{serverInit{patroni: []string{"a@db1", "b@db2"}}, 2},
+		{serverInit{standbys: true}, 2},
+		{serverInit{judge: judgeSpec{Replicas: 3}}, 3},
+	} {
+		if got := c.in.judgeFor().Replicas; got != c.want {
+			t.Errorf("%+v: %d judges, want %d", c.in, got, c.want)
+		}
+	}
+	// The defaults are left out of the command; a choice against them is in.
+	ha := serverInit{noNode: true, patroni: []string{"a@db1", "b@db2"}, judge: judgeSpec{Replicas: 2}}
+	if f := strings.Join(ha.initFlags(), " "); strings.Contains(f, "--judge-replicas") {
+		t.Errorf("two judges on three machines named: %s", f)
+	}
+	one := serverInit{judge: judgeSpec{Replicas: 2}}
+	if f := strings.Join(one.initFlags(), " "); !strings.Contains(f, "--judge-replicas 2") {
+		t.Errorf("two judges on one machine not named: %s", f)
+	}
+}

internal/cli/serverinit_cluster.go

@@ -9,7 +9,9 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"runtime"
 	"slices"
+	"strconv"
 	"strings"
 	"time"
 
@@ -120,10 +122,36 @@ func (in *serverInit) writeUnit(path, body string) (bool, error) {
 
 func (in *serverInit) mirrorUnit() string {
 	base := "http://" + net.JoinHostPort(in.reachableAddr(), "8081")
-	return mirrorUnitFor(mirrorDir, mirrorAPI, base, nil,
+	if in.standbys {
+		return mirrorUnitFor(in.mirrorRoot(), ":8082", base, in.mirrorAllow(),
+			"'llmgw server init'. Bytes on :8081 for every node; the\n# management API for the control planes only, whichever leads.")
+	}
+	return mirrorUnitFor(in.mirrorRoot(), mirrorAPI, base, nil,
 		"'llmgw server init'. Bytes on :8081 for every node; the\n# management API on loopback only, for the control plane beside it.")
 }
 
+// localMirrorAPI is the management API of the mirror beside this control
+// plane: on loopback, or, with standbys that may lead instead, on an address
+// they reach.
+func (in *serverInit) localMirrorAPI() string {
+	if in.standbys {
+		return "http://" + net.JoinHostPort(in.reachableAddr(), "8082")
+	}
+	return "http://" + mirrorAPI
+}
+
+// mirrorAllow are the control planes the mirror's management API answers
+// besides loopback: this one by its own address, and each standby.
+func (in *serverInit) mirrorAllow() []string {
+	out := []string{in.reachableAddr()}
+	for _, n := range in.patroniNodes {
+		if !slices.Contains(out, n.IP) {
+			out = append(out, n.IP)
+		}
+	}
+	return out
+}
+
 // mirrorUnitFor is a mirror's systemd unit. allow is who, besides the
 // machine itself, may use the management API.
 func mirrorUnitFor(dir, apiListen, base string, allow []string, about string) string {
@@ -160,7 +188,7 @@ func (in *serverInit) mirrorAPIURL() string {
 	if in.mirrorURL != "" {
 		return in.mirrorURL
 	}
-	return "http://" + mirrorAPI
+	return in.localMirrorAPI()
 }
 
 // useMirror points the control plane at a mirror on another machine, set up
@@ -202,15 +230,16 @@ func (in *serverInit) ensureMirror(ctx context.Context) error {
 	if err != nil {
 		return err
 	}
-	if cfg.Mirror.API != "" && cfg.Mirror.API != "http://"+mirrorAPI {
+	if cfg.Mirror.API != "" && cfg.Mirror.API != "http://"+mirrorAPI && cfg.Mirror.API != in.localMirrorAPI() {
 		in.kept("mirror at %s, as server.yaml says", cfg.Mirror.API)
 		return nil
 	}
 
-	if err := os.MkdirAll(mirrorDir, 0o755); err != nil {
+	dir := in.mirrorRoot()
+	if err := os.MkdirAll(dir, 0o755); err != nil {
 		return err
 	}
-	if err := in.chown(mirrorDir, true); err != nil {
+	if err := in.chown(dir, true); err != nil {
 		return err
 	}
 	changed, err := in.writeUnit(mirrorUnitPath, in.mirrorUnit())
@@ -227,21 +256,25 @@ func (in *serverInit) ensureMirror(ctx context.Context) error {
 		if err := in.systemctl(ctx, "restart", "llmgw-mirror"); err != nil {
 			return err
 		}
-		in.done("model mirror in %s, serving on :8081", mirrorDir)
+		in.done("model mirror in %s, serving on :8081", dir)
 	} else {
-		in.kept("model mirror in %s", mirrorDir)
+		in.kept("model mirror in %s", dir)
 	}
 
 	if cfg.Mirror.API == "" {
-		if err := appendMirrorBlockFor(in.configPath(), "http://"+mirrorAPI,
-			"# The model mirror on this machine, added by 'llmgw server init'. Its\n"+
-				"# management API is on loopback, so it needs no certificate."); err != nil {
+		comment := "# The model mirror on this machine, added by 'llmgw server init'. Its\n" +
+			"# management API is on loopback, so it needs no certificate."
+		if in.standbys {
+			comment = "# The model mirror on this machine, added by 'llmgw server init'. Its\n" +
+				"# management API answers the control planes' addresses only."
+		}
+		if err := appendMirrorBlockFor(in.configPath(), in.localMirrorAPI(), comment); err != nil {
 			return err
 		}
 		in.done("server.yaml points at the mirror")
 	}
 
-	m, err := mirror.NewClient("http://"+mirrorAPI, tlsconf.Config{}, 5*time.Second)
+	m, err := mirror.NewClient(in.localMirrorAPI(), tlsconf.Config{}, 5*time.Second)
 	if err != nil {
 		return err
 	}
@@ -414,8 +447,9 @@ func hasNVIDIADevice() bool {
 // --- the starter model ---
 
 // starterModel is the catalog entry: a GPU profile first when there is a card,
-// and a CPU profile always, both pinned to this machine.
-func starterModel(source string, gpuClasses []string, pinned bool) catalog.Model {
+// and a CPU profile always, both pinned to this machine. ctx is the context a
+// client may use; each engine holds four times that, for four at once.
+func starterModel(spec starterSpec, ctx, cores int, source string, gpuClasses []string, pinned bool) catalog.Model {
 	var pin map[string]string
 	if pinned {
 		pin = map[string]string{localLabelKey: localLabelValue}
@@ -424,21 +458,25 @@ func starterModel(source string, gpuClasses []string, pinned bool) catalog.Model
 	for _, class := range gpuClasses {
 		profiles = append(profiles, catalog.Profile{
 			Name: "gpu-" + class, Engine: "llamacpp", GPUClass: class,
-			Priority: 200, MinMemoryGB: 2, NodeSelector: pin,
-			Args: []string{"--ctx-size", "32768"},
+			Priority: 200, MinMemoryGB: spec.minMemoryGB(), NodeSelector: pin,
+			Args: []string{"--ctx-size", strconv.Itoa(max(32768, 4*ctx))},
 		})
 	}
 	profiles = append(profiles, catalog.Profile{
-		Name: "cpu", Engine: "llamacpp", Priority: 100, MinMemoryGB: 2, NodeSelector: pin,
-		Args: []string{"--ctx-size", "16384"},
+		Name: "cpu", Engine: "llamacpp", Priority: 100, MinMemoryGB: spec.minMemoryGB(), CPUCores: cores, NodeSelector: pin,
+		Args: []string{"--ctx-size", strconv.Itoa(max(16384, 4*ctx))},
 	})
+	var aliases []string
+	if spec.Alias != "" {
+		aliases = []string{spec.Alias}
+	}
 	return catalog.Model{
-		Name:           starterName,
-		Aliases:        []string{starterAlias},
-		Description:    "A small model init put here so there is something to try; fast, not clever.",
+		Name:           spec.Name,
+		Aliases:        aliases,
+		Description:    "The model init put here so there is something to try: " + spec.About + ".",
 		Source:         source,
 		RoutingProfile: "chat",
-		ContextLength:  4096,
+		ContextLength:  ctx,
 		MaxOutput:      1024,
 		Scaling:        catalog.Scaling{Min: 1, Max: 1},
 		Profiles:       profiles,
@@ -446,8 +484,8 @@ func starterModel(source string, gpuClasses []string, pinned bool) catalog.Model
 }
 
 // guardModel is the judge's catalog entry: CPU only, so it takes no card from
-// the models people use, on whichever node has room.
-func guardModel(source string) catalog.Model {
+// the models people use, on whichever node has room; replicas copies of it.
+func guardModel(source string, replicas, cores int) catalog.Model {
 	return catalog.Model{
 		Name:        guardModelName,
 		Description: "The guardrails' judge: reads prompts and answers for unsafe content. Not offered to clients.",
@@ -456,10 +494,15 @@ func guardModel(source string) catalog.Model {
 		Guard:       &catalog.GuardModel{Format: "qwen3guard"},
 		// Two: every judged request waits on it, and with fail: closed a
 		// judge that is not there refuses everything.
-		Scaling: catalog.Scaling{Min: 2, Max: 2},
+		Scaling: catalog.Scaling{Min: replicas, Max: replicas},
 		Profiles: []catalog.Profile{{
-			Name: "cpu", Engine: "llamacpp", Priority: 100, MinMemoryGB: 2,
-			Args: []string{"--ctx-size", "8192"},
+			// About 1.6 GB with its context, which stays so with no prompt
+			// cache: llama.cpp keeps up to 8 GB of prompts by default, and a
+			// judge's, each a different text, are not asked again. With the
+			// cache one grew to 3.2 GB over a day of traffic; reserving 4 for
+			// that left a 7 GB machine room for only one of the two.
+			Name: "cpu", Engine: "llamacpp", Priority: 100, MinMemoryGB: judgeMemoryGB, CPUCores: cores,
+			Args: []string{"--ctx-size", "8192", "--cache-ram", "0"},
 		}},
 	}
 }
@@ -469,15 +512,20 @@ func (in *serverInit) ensureStarter(ctx context.Context) error {
 	// Served here when this machine is a node, pinned so it does not wander
 	// to the first GPU node that joins; otherwise on whichever node joins.
 	pinned := !in.noNode
-	return in.ensureServed(ctx, starterName, starterSource, starterVersion, pinned,
-		func(url string, classes []string) catalog.Model { return starterModel(url, classes, pinned) })
+	spec, n := in.starterModelSpec(), in.starterContext()
+	return in.ensureServed(ctx, spec.Name, spec.Source, starterVersion, pinned,
+		func(url string, classes []string) catalog.Model {
+			return starterModel(spec, n, in.cpuPlan().starter, url, classes, pinned)
+		})
 }
 
 // ensureGuardModel fetches the guardrails' judge model into the mirror and
 // adds it to the catalog, to run on any node with room.
 func (in *serverInit) ensureGuardModel(ctx context.Context) error {
 	return in.ensureServed(ctx, guardModelName, guardModelSource, guardModelVersion, false,
-		func(url string, _ []string) catalog.Model { return guardModel(url) })
+		func(url string, _ []string) catalog.Model {
+			return guardModel(url, in.judgeFor().Replicas, in.cpuPlan().judge)
+		})
 }
 
 // ensureServed fetches a model into the mirror, adds it to the catalog, and
@@ -661,3 +709,55 @@ func waitFor(ctx context.Context, limit time.Duration, what string, done func()
 		}
 	}
 }
+
+// cpuSplit is the cores init's models reserve: each judge replica's, and
+// the starter's on CPU.
+type cpuSplit struct{ judge, starter int }
+
+// cpuPlan divides the CPUs between the judges and the starter, so that the
+// engines do not each take every core. Without it, two judge replicas and
+// the starter on one 4-core control plane all ran on all four: under load
+// most judgments missed their budget and the requests were refused.
+//
+// A judge needs cores: a judgment of about 280 tokens took 8.0 s on one,
+// 4.2 s on two and 2.3 s on four, against a 5 s budget. On one machine its
+// one replica gets up to four; where there are two, two each (one each only
+// where two would not fit both). The starter has what is left, up to 8, or
+// no reservation at all when nothing is, rather than a starter that fits
+// nowhere. A machine that is not the node reserves two a judge on whichever
+// node takes it, and the starter, on a node not known yet, none.
+func (in *serverInit) cpuPlan() cpuSplit {
+	if in.noNode {
+		return cpuSplit{judge: judgeCores}
+	}
+	n := in.cpus
+	if n <= 0 {
+		n = runtime.NumCPU()
+	}
+	if n < 2 {
+		return cpuSplit{}
+	}
+	judges := 0
+	if !in.noGuardModel {
+		judges = in.judgeFor().Replicas
+	}
+	judge := judgeCores
+	switch {
+	case judges == 1:
+		judge = min(n, judgeCoresAlone)
+	case judges > 0 && judges*judge > n:
+		judge = max(1, n/judges)
+	}
+	left := max(n-judges*judge, 0)
+	return cpuSplit{judge: judge, starter: min(left, 8)}
+}
+
+// judgeCores and judgeMemoryGB are what a judge replica needs: two cores
+// for a judgment within its budget, and 2 GB for its 1.6 with no prompt
+// cache. judgeCoresAlone is what the one judge of a single machine takes,
+// past which a model this small hardly gets faster.
+const (
+	judgeCores      = 2
+	judgeCoresAlone = 4
+	judgeMemoryGB   = 2
+)

internal/cli/serverinit_cluster_test.go

@@ -28,7 +28,7 @@ func TestTheInitAgentUnitIsTheShippedUnit(t *testing.T) {
 }
 
 func TestTheStarterUsesTheGPUAndFallsBackToCPUOnThisMachine(t *testing.T) {
-	m := starterModel("http://10.0.0.5:8081/qwen2.5-0.5b-instruct/starter/q.gguf", []string{"4090-24g"}, true)
+	m := starterModel(starterChoices[0], defaultContext, 0, "http://10.0.0.5:8081/qwen2.5-0.5b-instruct/starter/q.gguf", []string{"4090-24g"}, true)
 	c, err := catalog.New([]catalog.Model{m})
 	if err != nil {
 		t.Fatalf("the starter is not a valid catalog entry: %v", err)
@@ -53,7 +53,7 @@ func TestTheStarterUsesTheGPUAndFallsBackToCPUOnThisMachine(t *testing.T) {
 		t.Error("the starter should be running, not waiting to be asked for")
 	}
 
-	if m := starterModel("http://x/q.gguf", nil, true); len(m.Profiles) != 1 || m.Profiles[0].Name != "cpu" {
+	if m := starterModel(starterChoices[0], defaultContext, 0, "http://x/q.gguf", nil, true); len(m.Profiles) != 1 || m.Profiles[0].Name != "cpu" {
 		t.Errorf("without a GPU only the CPU profile: %+v", m.Profiles)
 	}
 }
@@ -96,7 +96,7 @@ func TestTheMirrorUnitAdvertisesAnAddressNodesCanReach(t *testing.T) {
 }
 
 func TestWithNoNodeHereTheStarterGoesToTheFirstNodeThatJoins(t *testing.T) {
-	m := starterModel("http://x/q.gguf", nil, false)
+	m := starterModel(starterChoices[0], defaultContext, 0, "http://x/q.gguf", nil, false)
 	for _, p := range m.Profiles {
 		if len(p.NodeSelector) > 0 {
 			t.Errorf("profile %s is pinned to a machine that is not a node: %v", p.Name, p.NodeSelector)
@@ -171,7 +171,7 @@ func TestTheInstalledConfigurationIsHardenedAndLoads(t *testing.T) {
 }
 
 func TestTheGuardModelIsAValidJudge(t *testing.T) {
-	m := guardModel("http://10.0.0.5:8081/qwen3guard-0.6b/guard/g.gguf")
+	m := guardModel("http://10.0.0.5:8081/qwen3guard-0.6b/guard/g.gguf", 2, 2)
 	c, err := catalog.New([]catalog.Model{m})
 	if err != nil {
 		t.Fatalf("not a valid catalog entry: %v", err)

internal/cli/serverinit_firewall.go

@@ -93,6 +93,11 @@ func (in *serverInit) storeFirewall(ctx context.Context, members []pgha.Node, se
 				} else {
 					in.kept("firewall on %s", m.Name)
 				}
+				// And after, as the cluster's settings say, read from the
+				// member's own copy of the store.
+				if err := firewall.InstallFollower(ctx, m.Remote); err != nil {
+					fmt.Fprintf(in.out, "  !!    firewall on %s: %v; the cluster's settings will not change it\n", m.Name, err)
+				}
 				continue
 			}
 		}
@@ -135,5 +140,5 @@ func loopbackListen(listen string) bool {
 // ensureFirewallSync installs the units that apply the cluster's firewall
 // setting on this control plane.
 func (in *serverInit) ensureFirewallSync(ctx context.Context) error {
-	return installFirewallSync(ctx, firewall.Local{})
+	return installFirewallSync(ctx, firewall.Local{}, firewallStateFile)
 }

internal/cli/serverinit_notify.go

@@ -0,0 +1,185 @@
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/url"
+	"slices"
+	"strings"
+	"time"
+
+	"go.yaml.in/yaml/v3"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/notify"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/settings"
+)
+
+// Where the cluster says what went wrong: a model parked, a node lost, a
+// budget spent. notify.webhooks existed, and setup never asked for one, so a
+// site learnt of a lost node from its users.
+
+// parseWebhook reads a webhook as setup takes it: an address, with "slack:"
+// or "json:" in front to say what it is sent, else what its address says.
+func parseWebhook(s string) (notify.Webhook, error) {
+	s = strings.TrimSpace(s)
+	format := ""
+	for _, f := range []string{"slack", "json"} {
+		if rest, ok := strings.CutPrefix(s, f+":"); ok && !strings.HasPrefix(rest, "//") {
+			format, s = f, rest
+		}
+	}
+	u, err := url.Parse(s)
+	if err != nil || (u.Scheme != "https" && u.Scheme != "http") || u.Host == "" {
+		return notify.Webhook{}, fmt.Errorf("webhook %q: an http(s) address, with slack: or json: in front to say its format", s)
+	}
+	if format == "" {
+		format = webhookFormat(u)
+	}
+	return notify.Webhook{URL: s, Format: format}, nil
+}
+
+// webhookFormat is what an address takes: Slack's own, and the incoming
+// webhooks that read Slack's {"text": …} — Mattermost's and Rocket.Chat's
+// /hooks/, Discord's …/slack — are sent that; anything else the event as
+// JSON.
+func webhookFormat(u *url.URL) string {
+	switch {
+	case u.Host == "hooks.slack.com",
+		strings.Contains(u.Path, "/hooks/"),
+		strings.HasSuffix(u.Path, "/slack"):
+		return "slack"
+	}
+	return "json"
+}
+
+// parseWebhooks reads a list of them, by commas or as given.
+func parseWebhooks(list []string) ([]notify.Webhook, error) {
+	var out []notify.Webhook
+	for _, item := range list {
+		for _, s := range strings.Split(item, ",") {
+			if strings.TrimSpace(s) == "" {
+				continue
+			}
+			w, err := parseWebhook(s)
+			if err != nil {
+				return nil, err
+			}
+			out = append(out, w)
+		}
+	}
+	return out, nil
+}
+
+// webhookEntry is one of notify.webhooks as the settings document has it.
+type webhookEntry struct {
+	URL        string   `yaml:"url"`
+	Format     string   `yaml:"format,omitempty"`
+	Events     []string `yaml:"events,omitempty,flow"`
+	SecretFile string   `yaml:"secret_file,omitempty"`
+}
+
+// withWebhooks adds these webhooks to a settings document's notify.webhooks,
+// and says whether that changed it: one already there, by address, is left
+// as it is, with whatever events and secret it was given.
+func withWebhooks(doc *settings.Doc, add []notify.Webhook) (bool, error) {
+	path := []string{"notify", "webhooks"}
+	var list []webhookEntry
+	if n := doc.Node(path); n != nil {
+		if err := n.Decode(&list); err != nil {
+			return false, fmt.Errorf("notify.webhooks in the cluster's settings: %w", err)
+		}
+	}
+	changed := false
+	for _, w := range add {
+		if !slices.ContainsFunc(list, func(e webhookEntry) bool { return e.URL == w.URL }) {
+			list = append(list, webhookEntry{URL: w.URL, Format: w.Format})
+			changed = true
+		}
+	}
+	if !changed {
+		return false, nil
+	}
+	b, err := yaml.Marshal(list)
+	if err != nil {
+		return false, err
+	}
+	return true, doc.SetYAML(path, string(b))
+}
+
+// ensureWebhooks puts the webhooks given into the cluster's settings and
+// sends each a test, once the control plane runs on them. Said, not fatal: a
+// cluster without its alerts still serves.
+func (in *serverInit) ensureWebhooks(ctx context.Context) error {
+	if len(in.webhooks) == 0 {
+		return nil
+	}
+	hooks, err := parseWebhooks(in.webhooks)
+	if err != nil {
+		return err
+	}
+	c := in.adminAPI()
+	var cur adminapi.SettingsView
+	if err := c.get(ctx, "/api/v1/settings", &cur); err != nil {
+		return err
+	}
+	doc, err := settings.FromBytes("settings", []byte(cur.Body))
+	if err != nil {
+		return err
+	}
+	changed, err := withWebhooks(doc, hooks)
+	if err != nil {
+		return err
+	}
+	if changed {
+		b, err := doc.Bytes()
+		if err != nil {
+			return err
+		}
+		req, _ := json.Marshal(adminapi.SettingsRequest{Base: cur.Version, Body: string(b), Note: "notification webhooks, from setup"})
+		if err := c.put(ctx, "/api/v1/settings", req, &cur); err != nil {
+			return err
+		}
+		in.done("notification webhooks in the cluster's settings (version %d)", cur.Version)
+	} else {
+		in.kept("notification webhooks (already in the cluster's settings)")
+	}
+
+	// The control planes start again on the change; the test is sent by
+	// one that knows every webhook asked for.
+	var res []notify.Result
+	err = waitFor(ctx, 2*time.Minute, "the control plane to run on its webhooks", func() (bool, error) {
+		res = nil
+		if c.post(ctx, "/api/v1/notify/test", nil, &res) != nil {
+			return false, nil
+		}
+		for _, w := range hooks {
+			// Answered by host: the path of a webhook is its secret.
+			if !slices.ContainsFunc(res, func(r notify.Result) bool { return r.URL == notify.Redact(w.URL) }) {
+				return false, nil
+			}
+		}
+		return true, nil
+	})
+	if err != nil {
+		return err
+	}
+	var failed []string
+	for _, r := range res {
+		if !slices.ContainsFunc(hooks, func(w notify.Webhook) bool { return notify.Redact(w.URL) == r.URL }) {
+			continue
+		}
+		if r.Err != "" {
+			failed = append(failed, r.URL+": "+r.Err)
+			continue
+		}
+		in.done("a test notification reached %s", r.URL)
+	}
+	if len(failed) > 0 {
+		return errors.New("a test notification did not arrive: " + strings.Join(failed, "; ") +
+			" (kept in the settings: 'llmgw ctl notify test' tries again)")
+	}
+	return nil
+}

internal/cli/serverinit_notify_test.go

@@ -0,0 +1,122 @@
+package cli
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/notify"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/settings"
+)
+
+func TestAWebhooksFormatIsWhatItsAddressTakes(t *testing.T) {
+	for in, want := range map[string]string{
+		"https://hooks.slack.com/services/T1/B2/abc":            "slack",
+		"https://chat.example.com/hooks/xyz":                    "slack", // Mattermost, Rocket.Chat
+		"https://discord.com/api/webhooks/1/abc/slack":          "slack",
+		"https://alerts.example.com/llmgw":                      "json",
+		"json:https://hooks.slack.com/services/T1/B2/abc":       "json",
+		"slack:https://alerts.example.com/llmgw":                "slack",
+		"  https://events.pagerduty.com/integration/x/enqueue ": "json",
+	} {
+		w, err := parseWebhook(in)
+		if err != nil || w.Format != want || strings.HasPrefix(w.URL, "slack:") || strings.HasPrefix(w.URL, "json:") {
+			t.Errorf("%q: %+v %v, want %s", in, w, err, want)
+		}
+	}
+	for _, bad := range []string{"hooks.slack.com/x", "ftp://example.com/x", "slack:", "https://"} {
+		if _, err := parseWebhook(bad); err == nil {
+			t.Errorf("%q was taken", bad)
+		}
+	}
+}
+
+func TestWebhooksAreAddedToTheSettingsBesideTheOnesThere(t *testing.T) {
+	doc, err := settings.FromBytes("settings", []byte("router:\n  retries: 2\nnotify:\n  webhooks:\n"+
+		"    - url: https://alerts.example.com/a\n      events: [node_lost]\n      secret_file: /etc/llmgw/secrets/hook\n"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	hooks, _ := parseWebhooks([]string{"https://alerts.example.com/a, https://hooks.slack.com/services/T/B/c"})
+	changed, err := withWebhooks(doc, hooks)
+	if err != nil || !changed {
+		t.Fatalf("changed %v: %v", changed, err)
+	}
+	b, _ := doc.Bytes()
+	got := string(b)
+	for _, want := range []string{"retries: 2", "url: https://alerts.example.com/a", "events: [node_lost]",
+		"secret_file: /etc/llmgw/secrets/hook", "url: https://hooks.slack.com/services/T/B/c", "format: slack"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("%q not in:\n%s", want, got)
+		}
+	}
+	if strings.Count(got, "alerts.example.com/a") != 1 {
+		t.Errorf("a webhook already there was added again:\n%s", got)
+	}
+	if changed, _ := withWebhooks(doc, hooks); changed {
+		t.Error("adding the same webhooks again changed the settings")
+	}
+}
+
+func TestSetupPutsItsWebhooksInTheSettingsAndTestsThemOnceInForce(t *testing.T) {
+	var mu sync.Mutex
+	body, tests := "router:\n  retries: 2\n", 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		mu.Lock()
+		defer mu.Unlock()
+		w.Header().Set("Content-Type", "application/json")
+		switch {
+		case r.Method == http.MethodGet && r.URL.Path == "/api/v1/settings":
+			_ = json.NewEncoder(w).Encode(adminapi.SettingsView{Version: 1, Body: body})
+		case r.Method == http.MethodPut && r.URL.Path == "/api/v1/settings":
+			var req adminapi.SettingsRequest
+			_ = json.NewDecoder(r.Body).Decode(&req)
+			body = req.Body
+			_ = json.NewEncoder(w).Encode(adminapi.SettingsView{Version: 2, Body: body})
+		case r.Method == http.MethodPost && r.URL.Path == "/api/v1/notify/test":
+			tests++
+			// The first answer comes from the control plane before it
+			// started again on the change: it knows no webhooks.
+			res := []notify.Result{}
+			if tests > 1 {
+				res = []notify.Result{{URL: notify.Redact("https://hooks.slack.com/services/T/B/c")},
+					{URL: notify.Redact("https://ops.example.com/in"), Err: "502 Bad Gateway"}}
+			}
+			_ = json.NewEncoder(w).Encode(res)
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer srv.Close()
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "server.yaml"),
+		[]byte("admin_listen: "+strings.TrimPrefix(srv.URL, "http://")+"\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	var out bytes.Buffer
+	in := &serverInit{etcDir: dir, out: &out,
+		webhooks: []string{"https://hooks.slack.com/services/T/B/c", "https://ops.example.com/in"}}
+	err := in.ensureWebhooks(t.Context())
+	if err == nil || !strings.Contains(err.Error(), "502") || !strings.Contains(err.Error(), "ctl notify test") {
+		t.Errorf("a webhook that did not answer: %v", err)
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	if !strings.Contains(body, "format: slack") || !strings.Contains(body, "url: https://ops.example.com/in") ||
+		!strings.Contains(body, "retries: 2") || tests < 2 {
+		t.Errorf("settings %q after %d tests", body, tests)
+	}
+	if strings.Contains(out.String(), "/services/T/B/c") {
+		t.Errorf("a webhook's secret path was printed:\n%s", out.String())
+	}
+	if !strings.Contains(out.String(), "reached https://hooks.slack.com/…") {
+		t.Errorf("the one that answered is not said:\n%s", out.String())
+	}
+}

internal/cli/serverinit_patroni.go

@@ -51,6 +51,8 @@ func (in *serverInit) ensurePatroni(ctx context.Context) (err error) {
 			Remote: remote,
 		})
 	}
+	// Kept: the standbys are made control planes on the same machines.
+	in.patroniNodes = setup.DB
 	self, err := sourceIPToward(setup.DB[0].IP)
 	if err != nil {
 		return err

internal/cli/serverinit_postgres.go

@@ -16,6 +16,7 @@ import (
 	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/discovery"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/agent/provision"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/config"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/pgha"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
 )
 
@@ -348,15 +349,23 @@ func (in *serverInit) setupPostgres(ctx context.Context) (string, error) {
 	}
 
 	if installed {
-		// Its defaults assume it owns the machine. A gateway swapped out to
-		// give the database cache is worse than a smaller cache, and a store
-		// whose working set is megabytes needs little. Only a PostgreSQL init
-		// installed itself: one that was already here may serve something
-		// else that needs its connections.
-		for _, q := range []string{
-			"ALTER SYSTEM SET shared_buffers = '96MB'",
-			"ALTER SYSTEM SET max_connections = 40",
-		} {
+		// Sized to the machine's memory, as one it shares with the gateway:
+		// a gateway swapped out to give the database cache is worse than a
+		// smaller cache, but a knowledge base's vector index is searched
+		// well only from memory. Only a PostgreSQL init installed itself:
+		// one that was already here may serve something else that needs its
+		// connections.
+		meminfo, _ := os.ReadFile("/proc/meminfo")
+		total, ok := pgha.MemTotal(string(meminfo))
+		if !ok {
+			total = 1 << 30
+		}
+		mem := pgha.MemorySettings(total, true)
+		qs := []string{"ALTER SYSTEM SET max_connections = 40"}
+		for _, k := range []string{"shared_buffers", "effective_cache_size", "maintenance_work_mem", "work_mem"} {
+			qs = append(qs, "ALTER SYSTEM SET "+k+" = '"+mem[k]+"'")
+		}
+		for _, q := range qs {
 			if _, err := in.psql(ctx, q); err != nil {
 				return "", err
 			}
@@ -367,7 +376,8 @@ func (in *serverInit) setupPostgres(ctx context.Context) (string, error) {
 		if err := in.waitForPostgres(ctx); err != nil {
 			return "", err
 		}
-		in.done("PostgreSQL sized for a machine it shares (shared_buffers 96MB, 40 connections)")
+		in.done("PostgreSQL sized for a machine it shares, with %d MB of memory (shared_buffers %s, work_mem %s, 40 connections)",
+			total>>20, mem["shared_buffers"], mem["work_mem"])
 	}
 
 	in.setupPgvector(ctx, discovery.DiscoverHost())

internal/cli/serverinit_standby.go

@@ -0,0 +1,39 @@
+package cli
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net"
+)
+
+// Three machines, each able to take over: the store's two machines are made
+// control planes too, standing by while this one leads, as 'llmgw server add'
+// makes any machine one. With the store replicated across them and etcd's
+// three votes on the three, losing any one machine loses neither the store
+// nor the gateway. With a floating address, clients keep the one address.
+
+// ensureStandbys makes each machine of the replicated store a control plane,
+// one after the other.
+func (in *serverInit) ensureStandbys(ctx context.Context) error {
+	if len(in.patroniNodes) == 0 {
+		return errors.New("the standbys go on the store's machines: give them with --patroni")
+	}
+	var hosts []string
+	if ip, _, err := net.ParseCIDR(in.vip); err == nil {
+		hosts = []string{ip.String()}
+	}
+	for i, n := range in.patroniNodes {
+		fmt.Fprintf(in.out, "  ..    making %s a control plane too\n", n.Name)
+		sa := serverAdd{
+			etcDir: in.etcDir, pkiDir: in.pkiDir, hosts: hosts, vip: in.vip,
+			remote: n.Remote, noFirewall: in.noFirewall, addr: n.IP, ip: n.IP,
+			out: in.out, priority: 100 - 10*i, quiet: true,
+		}
+		if err := sa.run(ctx); err != nil {
+			return fmt.Errorf("%s: %w", n.Name, err)
+		}
+		in.done("%s (%s) is a control plane too, standing by while this one leads", n.Name, n.IP)
+	}
+	return nil
+}

internal/cli/status_test.go

@@ -52,6 +52,8 @@ func TestModelStatusSeparatesWaitingFromBroken(t *testing.T) {
 		{"nothing could be placed", adminapi.ModelView{Min: 1, Ready: 0, Total: 0}, "not placed"},
 		{"deliberately not running", adminapi.ModelView{Min: 0, Ready: 0, Total: 0}, "stopped"},
 		{"short but rebuilding", adminapi.ModelView{Min: 2, Ready: 1, Total: 2}, "starting"},
+		{"woken by a request", adminapi.ModelView{Min: 0, Ready: 1, Total: 1}, "ready (on demand)"},
+		{"waking", adminapi.ModelView{Min: 0, Ready: 0, Total: 1}, "starting"},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
 			if got := modelStatus(tc.view); got != tc.want {

internal/cli/train.go

@@ -0,0 +1,293 @@
+package cli
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/store"
+)
+
+func newTrainCmd(client func() *ctlClient, asJSON *bool) *cobra.Command {
+	c := &cobra.Command{
+		Use:   "train",
+		Short: "Train LoRA adapters on the nodes, on question/answer pairs",
+		Long: "A node trains an adapter for a catalog model on pairs (llmgw ctl kb dataset\n" +
+			"writes them from a knowledge base; read them through first). It trains with\n" +
+			"its installed vLLM's torch and a small overlay, as the engines' user, on a card\n" +
+			"with --gpu-memory free — beside an engine, if it leaves that much. What it\n" +
+			"makes is kept by the control plane: llmgw ctl train download, or publish it\n" +
+			"as the model's adapter.\n\n" +
+			"An adapter learns how answers sound — words, format, tone — far better than\n" +
+			"what they say. Facts belong to the knowledge base.",
+	}
+
+	var model, base, rev, node, data, owner string
+	var public bool
+	var gpuMem int
+	var epochs, rank int
+	var lr float64
+	var noGGUF bool
+	start := &cobra.Command{
+		Use:   "start NAME --model MODEL --base-repo OWNER/NAME --node NODE --data FILE",
+		Short: "Queue an adapter's training on a node",
+		Example: "  llmgw ctl train start policies-tone --model qwen2.5-0.5b-instruct \\\n" +
+			"    --base-repo Qwen/Qwen2.5-0.5B-Instruct --node cuda01 --gpu-memory 2300 --data policies.jsonl",
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			b, err := os.ReadFile(data)
+			if err != nil {
+				return err
+			}
+			req := adminapi.TrainRequest{Name: args[0], Model: model, BaseRepo: base, BaseRevision: rev, Node: node,
+				GPUMemoryMiB: gpuMem, Data: string(b), Params: map[string]any{}, Owner: owner, Public: public}
+			if cmd.Flags().Changed("epochs") {
+				req.Params["epochs"] = epochs
+			}
+			if cmd.Flags().Changed("rank") {
+				req.Params["rank"] = rank
+			}
+			if cmd.Flags().Changed("lr") {
+				req.Params["lr"] = lr
+			}
+			if noGGUF {
+				f := false
+				req.GGUF = &f
+			}
+			body, _ := json.Marshal(req)
+			var v adminapi.TrainJobView
+			if err := client().patient(2*time.Minute).do(cmd.Context(), "POST", "/api/v1/train/jobs", json.RawMessage(body), &v); err != nil {
+				return err
+			}
+			who := "every caller of " + v.Model
+			if v.Owner != "" {
+				who = v.Owner + " only"
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "queued %s: %s for %s on %s, %d pairs; it will be seen by %s\n",
+				v.ID, v.Name, v.Model, v.Node, v.Pairs, who)
+			fmt.Fprintf(cmd.OutOrStdout(), "follow it with: llmgw ctl train show %s --follow\n", v.ID)
+			return nil
+		},
+	}
+	f := start.Flags()
+	f.StringVar(&model, "model", "", "the catalog model the adapter is for")
+	f.StringVar(&base, "base-repo", "", "the weights to train on, as safetensors on Hugging Face (owner/name)")
+	f.StringVar(&rev, "base-revision", "", "a revision of them (default: the newest)")
+	f.StringVar(&node, "node", "", "the node that trains")
+	f.IntVar(&gpuMem, "gpu-memory", 4096, "MiB of a card the job needs free")
+	f.StringVar(&data, "data", "", "the pairs, NDJSON of {\"q\", \"a\"}")
+	f.IntVar(&epochs, "epochs", 6, "passes over the pairs")
+	f.IntVar(&rank, "rank", 16, "the adapter's rank")
+	f.Float64Var(&lr, "lr", 2e-4, "the learning rate")
+	f.BoolVar(&noGGUF, "no-gguf", false, "skip the llama.cpp GGUF, even for a model llama.cpp serves")
+	f.StringVar(&owner, "owner", "", "who the adapter belongs to — org:, team:, project: (path or ID), user: or key: — and only they see it "+
+		"(default: the knowledge base's owner, when the pairs come from one)")
+	f.BoolVar(&public, "public", false, "every caller of the model sees it; refused for pairs from a knowledge base")
+	for _, req := range []string{"model", "base-repo", "node", "data"} {
+		_ = start.MarkFlagRequired(req)
+	}
+	c.AddCommand(start)
+
+	c.AddCommand(&cobra.Command{
+		Use:   "list",
+		Short: "Training jobs, newest first",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			var jobs []adminapi.TrainJobView
+			if err := client().get(cmd.Context(), "/api/v1/train/jobs", &jobs); err != nil {
+				return err
+			}
+			if *asJSON {
+				return json.NewEncoder(cmd.OutOrStdout()).Encode(jobs)
+			}
+			if len(jobs) == 0 {
+				fmt.Fprintln(cmd.OutOrStdout(), "No training jobs (llmgw ctl train start).")
+				return nil
+			}
+			w := tab()
+			fmt.Fprintln(w, "JOB\tADAPTER\tMODEL\tOWNER\tNODE\tSTATE\tPROGRESS\tLOSS\tPEAK\tCREATED")
+			for _, j := range jobs {
+				fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n", j.ID, j.Name, j.Model, or(j.Owner, "everyone"), j.Node, j.State,
+					trainProgress(j), trainLoss(j), trainPeak(j), j.CreatedAt.Local().Format("01-02 15:04"))
+			}
+			return w.Flush()
+		},
+	})
+
+	var follow bool
+	show := &cobra.Command{
+		Use:   "show JOB",
+		Short: "How a training job goes, and what it made",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			out := cmd.OutOrStdout()
+			last := ""
+			for {
+				var j adminapi.TrainJobView
+				if err := client().get(cmd.Context(), "/api/v1/train/jobs/"+args[0], &j); err != nil {
+					return err
+				}
+				if *asJSON {
+					return json.NewEncoder(out).Encode(j)
+				}
+				line := fmt.Sprintf("%s  %s  %s  loss %s  peak %s  %s", j.State, trainProgress(j), j.Node, trainLoss(j), trainPeak(j), j.Message)
+				if !follow {
+					fmt.Fprintf(out, "%s: adapter %s for %s, owned by %s, on %s (base %s), %d pairs\n", j.ID, j.Name, j.Model,
+						or(j.Owner, "everyone"), j.Node, j.BaseRepo, j.Pairs)
+					fmt.Fprintln(out, line)
+					if len(j.Artifacts) > 0 {
+						fmt.Fprintf(out, "made: %s (llmgw ctl train download %s --kind KIND)\n", strings.Join(j.Artifacts, ", "), j.ID)
+					}
+					return nil
+				}
+				if line != last {
+					fmt.Fprintf(out, "%s  %s\n", time.Now().Format("15:04:05"), line)
+					last = line
+				}
+				if store.TrainOver(j.State) {
+					if j.State != store.TrainDone {
+						return fmt.Errorf("%s %s", j.ID, j.State)
+					}
+					return nil
+				}
+				select {
+				case <-cmd.Context().Done():
+					return nil
+				case <-time.After(3 * time.Second):
+				}
+			}
+		},
+	}
+	show.Flags().BoolVarP(&follow, "follow", "f", false, "follow it until it ends")
+	c.AddCommand(show)
+
+	c.AddCommand(&cobra.Command{
+		Use:   "cancel JOB",
+		Short: "Stop a training job",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if err := client().do(cmd.Context(), "POST", "/api/v1/train/jobs/"+args[0]+"/cancel", nil, nil); err != nil {
+				return err
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "%s cancelled\n", args[0])
+			return nil
+		},
+	})
+	c.AddCommand(&cobra.Command{
+		Use:   "rm JOB",
+		Short: "Remove an ended training job and what it made",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if err := client().do(cmd.Context(), "DELETE", "/api/v1/train/jobs/"+args[0], nil, nil); err != nil {
+				return err
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "%s removed\n", args[0])
+			return nil
+		},
+	})
+
+	var restart bool
+	publish := &cobra.Command{
+		Use:   "publish JOB",
+		Short: "Make what a finished job made its model's adapter, kept on the mirror",
+		Long: "The GGUF for a model llama.cpp serves, the PEFT files for one vLLM serves, are kept\n" +
+			"on the mirror and added to the model's adapters; a request then asks for the\n" +
+			"adapter by its name, as a model. llama.cpp loads adapters when a replica starts:\n" +
+			"--restart replaces the model's replicas, one at a time, to load it.",
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			var v adminapi.TrainPublishView
+			if err := client().patient(15*time.Minute).do(cmd.Context(), "POST", "/api/v1/train/jobs/"+args[0]+"/publish", nil, &v); err != nil {
+				return err
+			}
+			out := cmd.OutOrStdout()
+			fmt.Fprintf(out, "%s is %s's adapter, from %s\n", v.Adapter, v.Model, v.Source)
+			if v.Owner != "" {
+				fmt.Fprintf(out, "only %s sees it; to anyone else it is a model that does not exist\n", v.Owner)
+			}
+			if restart && strings.Contains(v.Note, "restart") {
+				body, _ := json.Marshal(adminapi.RestartRequest{Models: []string{v.Model}})
+				var res adminapi.RestartResult
+				if err := client().post(cmd.Context(), "/api/v1/restart", body, &res); err != nil {
+					return err
+				}
+				fmt.Fprintf(out, "%d replica(s) of %s restarting to load it; then ask for model %s\n", len(res.Queued), v.Model, v.Adapter)
+				return nil
+			}
+			fmt.Fprintln(out, v.Note)
+			return nil
+		},
+	}
+	publish.Flags().BoolVar(&restart, "restart", false, "restart the model's replicas to load it (llama.cpp)")
+	c.AddCommand(publish)
+
+	var kind, outFile string
+	download := &cobra.Command{
+		Use:   "download JOB",
+		Short: "Save what a training job made: the PEFT adapter (peft) or the GGUF (gguf)",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if outFile == "" {
+				outFile = args[0] + ".tar.gz"
+				if kind == "gguf" {
+					outFile = args[0] + ".gguf"
+				}
+			}
+			f, err := os.Create(outFile)
+			if err != nil {
+				return err
+			}
+			defer f.Close()
+			cw := &countWriter{w: f}
+			if err := client().patient(10*time.Minute).do(cmd.Context(), "GET",
+				"/api/v1/train/jobs/"+args[0]+"/artifacts/"+kind, nil, io.Writer(cw)); err != nil {
+				_ = os.Remove(outFile)
+				return err
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "%s: %s\n", outFile, humanBytes(cw.n))
+			return nil
+		},
+	}
+	download.Flags().StringVar(&kind, "kind", "peft", "peft (a gzipped tar of the PEFT adapter) or gguf")
+	download.Flags().StringVarP(&outFile, "out", "o", "", "the file to write")
+	c.AddCommand(download)
+	return c
+}
+
+type countWriter struct {
+	w io.Writer
+	n int64
+}
+
+func (c *countWriter) Write(p []byte) (int, error) {
+	n, err := c.w.Write(p)
+	c.n += int64(n)
+	return n, err
+}
+
+func trainProgress(j adminapi.TrainJobView) string {
+	if j.Steps == 0 {
+		return "-"
+	}
+	return fmt.Sprintf("%d/%d", j.Step, j.Steps)
+}
+
+func trainLoss(j adminapi.TrainJobView) string {
+	if j.Loss == 0 {
+		return "-"
+	}
+	return fmt.Sprintf("%.3f", j.Loss)
+}
+
+func trainPeak(j adminapi.TrainJobView) string {
+	if j.PeakMiB == 0 {
+		return "-"
+	}
+	return fmt.Sprintf("%d MiB", j.PeakMiB)
+}

internal/cli/tui_choices.go

@@ -0,0 +1,751 @@
+package cli
+
+import (
+	"fmt"
+	"net/mail"
+	"net/url"
+	"slices"
+	"strconv"
+	"strings"
+	"time"
+
+	tea "github.com/charmbracelet/bubbletea"
+	"github.com/charmbracelet/lipgloss"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/notify"
+)
+
+// The parts of an install, each chosen and each with its settings: what the
+// setup screens show before anything is installed, for one machine and for
+// three alike. Beside each part is what it is for and what is missing
+// without it; Enter opens its settings, which say the same at more length.
+
+type installPart struct {
+	title string
+	// about is what the part is, at the length its dialog has room for.
+	about string
+	// fixed parts are always installed: they have settings, not a box.
+	fixed bool
+	on    bool
+	// fields are its settings; none is a part only to tick.
+	fields []*setupField
+	// summary is a line of what it will be; off what is missing without it.
+	summary func() string
+	off     string
+	// needs, when set, says why the part cannot be had with the rest as
+	// chosen: a starter model with no mirror to fetch it into.
+	needs func() string
+}
+
+type installForm struct {
+	ha    bool
+	host  string
+	found []string
+	parts []*installPart
+	// focus is a part, or len(parts) for the button that goes on.
+	focus int
+	// open is the part whose settings are open in a dialog.
+	open   *installPart
+	dialog *setupDialog
+	// err is said in a dialog of its own; when errField is set, closing it
+	// opens that field's part with the focus on it.
+	err      string
+	errPart  *installPart
+	errField *setupField
+	height   int
+
+	standby *installPart
+	vipF    *setupField
+
+	control, store, mirror, node, starter, media, judge, firewall, alerts, limits, turns, bundle *installPart
+
+	admin, hosts, language, signup         *setupField
+	storeKind                              *setupField
+	mirrorWhere, mirrorDirF, mirrorURL     *setupField
+	starterPick, starterSource, starterCtx *setupField
+	judgeFail, judgeCopies, judgeBudget    *setupField
+	judgeCats                              []*setupField
+	webhooks                               *setupField
+	rpm, tpm, keyDays                      *setupField
+	idle, safe                             *setupField
+	bundlePath, bundleSHA                  *setupField
+}
+
+// newInstallForm is the parts as in has them: its flags, or the defaults.
+func newInstallForm(in *serverInit, host string, found []string, ha bool) *installForm {
+	f := &installForm{ha: ha, host: host, found: found, height: 24}
+
+	// --- the control plane ---
+	f.admin = textSetupField("Administrator's email", in.admin, "you@example.com",
+		"A password is made for this account and shown once, at the end.")
+	if !ha {
+		f.admin.Hint += " Leave it empty to make accounts later with 'llmgw users create'."
+	}
+	known := "none found"
+	if len(found) > 0 {
+		known = strings.Join(found, ", ")
+	}
+	f.hosts = textSetupField("Other names nodes reach this machine by", strings.Join(in.hosts, ", "),
+		"llm.example.com, 203.0.113.10",
+		"Already in its certificate: "+known+". Add a DNS name, a NAT address or a floating address, comma-separated.")
+	lang := 0
+	if in.language == "tr" {
+		lang = 1
+	}
+	f.language = choiceField("The portal speaks", []string{"English", "Türkçe"}, lang,
+		"To a browser that asks for neither. Each person can switch at the foot of any page.")
+	f.signup = choiceField("Sign-up form", []string{"closed", "open"}, map[bool]int{false: 0, true: 1}[in.signupOpen], "")
+	f.signup.Notes = []string{
+		"Accounts are made by an administrator, or come from single sign-on.",
+		"Anyone who reaches the portal can ask for an account; it waits for an administrator's approval.",
+	}
+	f.control = &installPart{
+		title: "Control plane", fixed: true, on: true,
+		about: "The gateway every request comes through, the admin API, the web portal on port 8080, and the " +
+			"certificate authority that signs every node's identity. Always installed: it is what llmgw is.\n\n" +
+			"Its authority's key stays in " + orText(in.pkiDir, defaultPKIDir) + " on this machine. Back it up: nothing recovers it.",
+		fields: []*setupField{f.admin, f.hosts, f.language, f.signup},
+		summary: func() string {
+			s := []string{}
+			if a := f.admin.Value(); a != "" {
+				s = append(s, "administrator "+a)
+			} else {
+				s = append(s, "no administrator")
+			}
+			s = append(s, f.language.Options[f.language.Choice], "sign-up "+f.signup.Options[f.signup.Choice])
+			return strings.Join(s, " · ")
+		},
+	}
+
+	// --- the store ---
+	f.storeKind = choiceField("Kept in", []string{"SQLite", "PostgreSQL"}, map[bool]int{false: 0, true: 1}[in.postgres], "")
+	f.storeKind.Notes = []string{
+		"A file on this machine. Nothing to look after; enough for one control plane and a team's traffic.",
+		"Installed here, with its own role and a generated password. For a larger store, or before adding a second control plane.",
+	}
+	f.store = &installPart{
+		title: "Store", fixed: true, on: true,
+		about: "Accounts, API keys, the catalog of models, usage and the cluster's settings live here.",
+		summary: func() string {
+			if ha {
+				return "PostgreSQL under Patroni, on the other two"
+			}
+			return f.storeKind.Options[f.storeKind.Choice] + " on this machine"
+		},
+	}
+	if ha {
+		f.store.about += "\n\nWith three machines it is PostgreSQL on the other two, replicated under Patroni: " +
+			"if the primary is lost the standby takes over in about thirty seconds, and the control plane follows. " +
+			"The machines are asked for on the next page."
+	} else {
+		f.store.fields = []*setupField{f.storeKind}
+	}
+
+	// --- control planes on all three ---
+	if ha {
+		f.vipF = textSetupField("Floating address", in.vip, "10.0.0.160/24",
+			"Optional. An unused address on these machines' network, with its prefix: keepalived keeps it on "+
+				"whichever control plane leads, and clients use it. Without one, put a load balancer in front, "+
+				"or give clients the three addresses.")
+		f.standby = &installPart{
+			title: "Control plane on all three", on: in.standbys,
+			about: "The two database machines become control planes too, standing by while this one leads. " +
+				"If the leader is lost, one of them takes over within seconds: it places models, and every node " +
+				"is told of it and fails over without being touched. With the store on two machines and etcd's " +
+				"three votes on the three, losing any one machine loses neither the store nor the gateway.\n\n" +
+				"The model mirror stays on this machine: while it is down, models the nodes already have keep " +
+				"serving, and new ones wait for it.",
+			fields: []*setupField{f.vipF},
+			off:    "the gateway runs on this machine only: if it is lost, the store survives but nothing is served until it is back",
+			summary: func() string {
+				if v := f.vipF.Value(); v != "" {
+					return "two standbys; " + v + " follows whichever leads"
+				}
+				return "two standbys; no floating address"
+			},
+		}
+	}
+
+	// --- the mirror ---
+	where := 0
+	if in.mirrorURL != "" {
+		where = 1
+	}
+	f.mirrorWhere = choiceField("Where", []string{"on this machine", "on another machine"}, where, "")
+	f.mirrorWhere.Notes = []string{
+		"Serves model files on port 8081 to every node; its management API is on loopback only.",
+		"Set up there first with 'llmgw mirror init --control-plane <this machine>'.",
+	}
+	f.mirrorDirF = textSetupField("Directory", orText(in.mirrorPath, mirrorDir), mirrorDir,
+		"Models are large: a 7B model is about 5 GB, a 70B about 40 GB. Put it on the biggest disk.")
+	f.mirrorDirF.Show = func() bool { return f.mirrorWhere.Choice == 0 }
+	f.mirrorURL = textSetupField("Its management API", in.mirrorURL, "http://10.0.0.20:8082", "")
+	f.mirrorURL.Show = func() bool { return f.mirrorWhere.Choice == 1 }
+	f.mirror = &installPart{
+		title: "Model mirror", on: !in.noMirror || in.mirrorURL != "",
+		about: "Downloads each model once, from Hugging Face or wherever it comes from, and serves the files to " +
+			"every node on the network, so ten nodes do not download the same 40 GB ten times. " +
+			"The starter model, the judge and an offline bundle go into it.",
+		fields: []*setupField{f.mirrorWhere, f.mirrorDirF, f.mirrorURL},
+		off:    "each model's files must already be on a mirror somewhere; no starter model, no judge",
+		summary: func() string {
+			if f.mirrorWhere.Choice == 1 {
+				return "at " + orText(f.mirrorURL.Value(), "(an address)")
+			}
+			return "on this machine, in " + orText(f.mirrorDirF.Value(), mirrorDir)
+		},
+	}
+
+	// --- this machine as a node ---
+	f.node = &installPart{
+		title: "This machine as a node", on: !in.noNode,
+		about: "Runs models here as well, on this machine's NVIDIA GPUs when it has them and on its CPU otherwise. " +
+			"The node installs its own engines (llama.cpp first, vLLM after where the card can run it).\n\n" +
+			"Leave it off when this machine has neither the memory nor the cards to spare: models then run on " +
+			"the nodes added later with 'llmgw node add'.",
+		off:     "models run only on nodes added later",
+		summary: func() string { return "serves models here, on its GPUs or its CPU" },
+	}
+	if ha {
+		f.node.about += " With three machines the control plane usually serves none."
+	}
+
+	// --- the starter model ---
+	var opts, notes []string
+	pick := 0
+	cur := in.starterModelSpec()
+	for i, c := range starterChoices {
+		opts = append(opts, strings.TrimSuffix(c.Name, "-instruct"))
+		notes = append(notes, fmt.Sprintf("%s, about %.1f GB: %s.", c.Name, c.SizeGB, c.About))
+		if c.Name == cur.Name {
+			pick = i
+		}
+	}
+	opts = append(opts, "other")
+	notes = append(notes, "Any single GGUF file on Hugging Face.")
+	custom := ""
+	if in.starter.Source != "" && !slices.ContainsFunc(starterChoices, func(c starterSpec) bool { return c.Name == in.starter.Name }) {
+		pick, custom = len(starterChoices), in.starter.Source
+	}
+	f.starterPick = choiceField("Model", opts, pick, "")
+	f.starterPick.Notes = notes
+	f.starterSource = textSetupField("Its file", custom, "hf:owner/repo/file.gguf", "")
+	f.starterSource.Show = func() bool { return f.starterPick.Choice == len(starterChoices) }
+	f.starterCtx = textSetupField("Context a client may use, in tokens", strconv.Itoa(in.starterContext()), "4096",
+		"The engine holds four times this, for four requests at once; more context takes more memory.")
+	f.starter = &installPart{
+		title: "Starter model", on: !in.noModel,
+		about: "A model fetched into the mirror and served on this machine, so there is something to ask the " +
+			"moment the install finishes. Small ones answer on any CPU; the larger want a GPU. More models are " +
+			"added later from /admin/mirror or with 'llmgw ctl model add'.",
+		fields: []*setupField{f.starterPick, f.starterSource, f.starterCtx},
+		off:    "nothing to ask until a model is added",
+		summary: func() string {
+			name := opts[f.starterPick.Choice]
+			if f.starterPick.Choice == len(starterChoices) {
+				name = orText(f.starterSource.Value(), "(a file)")
+			} else {
+				name = fmt.Sprintf("%s (%.1f GB)", starterChoices[f.starterPick.Choice].Name, starterChoices[f.starterPick.Choice].SizeGB)
+			}
+			return name + ", " + f.starterCtx.Value() + " tokens"
+		},
+		needs: func() string {
+			if !f.mirror.on {
+				return "the starter model is fetched into the mirror: turn the mirror on, or the starter model off"
+			}
+			return ""
+		},
+	}
+	if ha {
+		f.starter.about += " Unless this machine is a node, it runs on the first node that joins with room for it."
+	}
+
+	// --- pictures and 3D ---
+	f.media = &installPart{
+		title: "Pictures and 3D", on: in.media,
+		about: "The nodes install ComfyUI, and once a node has a card that fits one the control plane adds a " +
+			"picture model (FLUX.1 schnell) and a 3D model (TripoSR) by itself, so the portal's pictures and 3D " +
+			"pages and their APIs work without anybody writing a definition. They load when asked for and give " +
+			"their card back when idle.\n\n" +
+			"Each comes under its own licence, kept with every file it makes. A preset someone removes is not " +
+			"added again. Later: 'llmgw ctl model presets auto off|on'.",
+		off:     "no pictures or 3D until a preset is added from the console or /admin",
+		summary: func() string { return "ComfyUI; a picture model and a 3D model once a card fits" },
+	}
+
+	// --- the guardrails' judge ---
+	j := in.judgeFor()
+	f.judgeFail = choiceField("When no judge answers in time", []string{"refuse", "serve flagged"},
+		map[string]int{"closed": 0, "open": 1}[j.Fail], "")
+	f.judgeFail.Notes = []string{
+		"The request is refused (503). Safe, and why the judge runs twice.",
+		"The request is served unjudged and marked so in the logs. Nothing is refused for the judge's sake.",
+	}
+	f.judgeCopies = textSetupField("Copies", strconv.Itoa(j.Replicas), "2",
+		"On one machine one copy, on up to four cores; with more machines two, two cores each, on different nodes. Each reserves 2 GB.")
+	f.judgeBudget = textSetupField("Waits at most", durationYAML(j.Budget), "5s",
+		"A short text is judged in about two seconds on CPUs.")
+	judgeFields := []*setupField{f.judgeFail, f.judgeCopies, f.judgeBudget, headingField("Refuses")}
+	catNotes := map[string]string{
+		"PII":                          "the patterns already catch secrets and card numbers",
+		"Unethical Acts":               "refuses much ordinary work",
+		"Politically Sensitive Topics": "refuses much ordinary work",
+		"Copyright Violation":          "refuses much ordinary work",
+	}
+	for _, c := range judgeCategories {
+		t := toggleField(c, slices.Contains(j.Categories, c), catNotes[c])
+		f.judgeCats = append(f.judgeCats, t)
+		judgeFields = append(judgeFields, t)
+	}
+	f.judge = &installPart{
+		title: "Guardrails' judge", on: !in.noGuardModel,
+		about: "Qwen3Guard 0.6B reads every prompt and every answer for what patterns cannot see: violence, " +
+			"crime, sexual content, self-harm, jailbreaks. It runs on CPUs and takes no card. Without it the " +
+			"baseline still blocks secrets and card numbers and flags prompt injection.",
+		fields: judgeFields,
+		off:    "requests are checked by patterns only: secrets, card numbers, injection",
+		summary: func() string {
+			n := 0
+			for _, c := range f.judgeCats {
+				if c.On {
+					n++
+				}
+			}
+			return fmt.Sprintf("Qwen3Guard ×%s on CPUs, %d categories, unanswered: %s",
+				f.judgeCopies.Value(), n, f.judgeFail.Options[f.judgeFail.Choice])
+		},
+		needs: func() string {
+			if !f.mirror.on {
+				return "the judge's model is fetched into the mirror: turn the mirror on, or the judge off"
+			}
+			return ""
+		},
+	}
+
+	// --- the firewall ---
+	f.firewall = &installPart{
+		title: "Firewall", on: !in.noFirewall,
+		about: "An nftables table of llmgw's own keeps its internal ports — the agents' 7443, the mirror's 8081, " +
+			"the store's — to the networks the cluster is on. The portal and API on 8080 stay open. " +
+			"Other rules on the machine are left as they are.",
+		off:     "llmgw's internal ports answer every network this machine is on",
+		summary: func() string { return "internal ports to the cluster's networks only" },
+	}
+
+	// --- notifications ---
+	f.webhooks = textSetupField("Webhooks", strings.Join(in.webhooks, ", "), "https://hooks.slack.com/services/…",
+		"Slack, Mattermost, Rocket.Chat, or any address taking JSON; comma-separated. slack: or json: in front says which. A test is sent to each.")
+	f.alerts = &installPart{
+		title: "Notifications", on: len(in.webhooks) > 0,
+		about: "Where the cluster says what went wrong: a model parked because it fits nowhere, a node lost, " +
+			"a judge not answering, a budget spent.",
+		fields: []*setupField{f.webhooks},
+		off:    "nothing is said outside the dashboards",
+		summary: func() string {
+			hooks, err := parseWebhooks([]string{f.webhooks.Value()})
+			if err != nil || len(hooks) == 0 {
+				return "(no webhook yet)"
+			}
+			var where []string
+			for _, h := range hooks {
+				where = append(where, notify.Redact(h.URL))
+			}
+			return strings.Join(where, ", ")
+		},
+	}
+
+	// --- limits ---
+	f.rpm = textSetupField("Requests a minute", strconv.Itoa(orInt(in.defaultRPM, defaultRPM)), "60", "")
+	f.tpm = textSetupField("Tokens a minute", strconv.Itoa(orInt(in.defaultTPM, defaultTPM)), "200000", "")
+	ttl := in.maxKeyTTL
+	if ttl <= 0 {
+		ttl = defaultMaxKeyTTL
+	}
+	f.keyDays = textSetupField("The longest a key lives, in days", strconv.Itoa(int(ttl.Hours()/24)), "90",
+		"A key made without an expiry gets this. Shorter per organization, team or project later.")
+	f.limits = &installPart{
+		title: "Limits and keys", fixed: true, on: true,
+		about: "What a key may use when nothing more particular gives it a limit: a project made without limits " +
+			"would otherwise be metered by nothing. Organizations, teams and projects get their own later.",
+		fields: []*setupField{f.rpm, f.tpm, f.keyDays},
+		summary: func() string {
+			return fmt.Sprintf("%s requests and %s tokens a minute; keys live %s days", f.rpm.Value(), f.tpm.Value(), f.keyDays.Value())
+		},
+	}
+
+	// --- on-demand turns ---
+	f.idle = textSetupField("Unused for", durationYAML(orDur(in.evictAfterIdle, 2*time.Minute)), "2m",
+		"before a model loaded on demand gives its card to another that wants it.")
+	f.safe = textSetupField("Safe after loading for", durationYAML(orDur(in.minLifetime, 5*time.Minute)), "5m",
+		"so two models do not take turns paying for loads. 1m each suits one card shared by a picture model and a 3D model.")
+	f.turns = &installPart{
+		title: "Taking turns on a card", fixed: true, on: true,
+		about: "Models that load when asked for share the cards: on a site with fewer cards than such models, " +
+			"one waits for another to go idle. These are the waits.",
+		fields: []*setupField{f.idle, f.safe},
+		summary: func() string {
+			return "after " + f.idle.Value() + " unused; safe for " + f.safe.Value() + " after loading"
+		},
+	}
+
+	// --- offline bundle ---
+	f.bundlePath = textSetupField("Bundle", in.bundle, "/media/usb/llmgw-bundle.tar",
+		"Made on a machine with internet by 'llmgw bundle create'.")
+	f.bundleSHA = textSetupField("Its sha256", in.bundleSHA, "the sha256 'llmgw bundle create' printed", "")
+	f.bundleSHA.Text.Width = 64
+	f.bundle = &installPart{
+		title: "Offline bundle", on: in.bundle != "",
+		about: "For a site with no internet: engines, releases and models carried in on a disk. They go into the " +
+			"mirror, and the cluster is set to reach nothing outside.",
+		fields:  []*setupField{f.bundlePath, f.bundleSHA},
+		off:     "engines and models are downloaded from the internet",
+		summary: func() string { return orText(f.bundlePath.Value(), "(a file)") },
+		needs: func() string {
+			if !f.mirror.on {
+				return "an offline bundle goes into the model mirror: turn the mirror on"
+			}
+			return ""
+		},
+	}
+
+	f.parts = []*installPart{f.control, f.store}
+	if ha {
+		f.parts = append(f.parts, f.standby)
+	}
+	f.parts = append(f.parts, f.mirror, f.node, f.starter, f.media, f.judge, f.firewall,
+		f.alerts, f.limits, f.turns, f.bundle)
+	return f
+}
+
+func orText(s, d string) string {
+	if strings.TrimSpace(s) == "" {
+		return d
+	}
+	return s
+}
+
+func orInt(n, d int) int {
+	if n <= 0 {
+		return d
+	}
+	return n
+}
+
+func orDur(v, d time.Duration) time.Duration {
+	if v <= 0 {
+		return d
+	}
+	return v
+}
+
+// openPart opens a part's settings.
+func (f *installForm) openPart(p *installPart) {
+	f.open = p
+	f.dialog = &setupDialog{Title: p.title, About: p.about, Fields: p.fields}
+	f.dialog.first()
+}
+
+// fail says what is wrong, and with what, so that closing the message opens it.
+func (f *installForm) fail(p *installPart, field *setupField, msg string) error {
+	f.err, f.errPart, f.errField = msg, p, field
+	return fmt.Errorf("%s", msg)
+}
+
+// key takes a key; next is whether the person asked to go on, the choices
+// already put into in.
+func (f *installForm) key(k tea.KeyMsg, in *serverInit) (next bool) {
+	if f.err != "" {
+		p, field := f.errPart, f.errField
+		f.err, f.errPart, f.errField = "", nil, nil
+		if p != nil {
+			f.openPart(p)
+			if field != nil {
+				f.dialog.focusOn(field)
+			}
+		}
+		return false
+	}
+	if f.dialog != nil {
+		if f.dialog.key(k) {
+			f.dialog, f.open = nil, nil
+		}
+		return false
+	}
+	n := len(f.parts) + 1
+	switch k.String() {
+	case "down", "tab", "j":
+		f.focus = (f.focus + 1) % n
+	case "up", "shift+tab", "k":
+		f.focus = (f.focus + n - 1) % n
+	case " ", "x":
+		if f.focus < len(f.parts) {
+			p := f.parts[f.focus]
+			if p.fixed {
+				break
+			}
+			p.on = !p.on
+			// A part that is nothing until it is told something is told
+			// at once.
+			if p.on && (p == f.alerts && f.webhooks.Value() == "" || p == f.bundle && f.bundlePath.Value() == "") {
+				f.openPart(p)
+			}
+		}
+	case "enter":
+		if f.focus < len(f.parts) {
+			f.openPart(f.parts[f.focus])
+			return false
+		}
+		return f.apply(in) == nil
+	}
+	return false
+}
+
+// apply checks the choices and puts them into in; what is wrong is kept to
+// be said.
+func (f *installForm) apply(in *serverInit) error {
+	for _, p := range f.parts {
+		if p.on && p.needs != nil {
+			if why := p.needs(); why != "" {
+				return f.fail(nil, nil, why)
+			}
+		}
+	}
+	admin := f.admin.Value()
+	if admin != "" || f.ha {
+		if _, err := mail.ParseAddress(admin); err != nil {
+			msg := "the administrator's email is not an address"
+			if admin == "" {
+				msg = "the administrator's email is needed"
+			}
+			return f.fail(f.control, f.admin, msg)
+		}
+	}
+	var hosts []string
+	for _, h := range strings.Split(f.hosts.Value(), ",") {
+		if h = strings.TrimSpace(h); h != "" {
+			hosts = append(hosts, h)
+		}
+	}
+
+	mirrorURL := ""
+	if f.mirror.on && f.mirrorWhere.Choice == 1 {
+		u, err := url.Parse(f.mirrorURL.Value())
+		if err != nil || (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" {
+			return f.fail(f.mirror, f.mirrorURL, "the other machine's mirror: its management API, as http://host:8082")
+		}
+		mirrorURL = f.mirrorURL.Value()
+	}
+	mirrorPath := ""
+	if f.mirror.on && f.mirrorWhere.Choice == 0 {
+		mirrorPath = f.mirrorDirF.Value()
+		if !strings.HasPrefix(mirrorPath, "/") {
+			return f.fail(f.mirror, f.mirrorDirF, "the mirror's directory: a path from /")
+		}
+	}
+
+	var starter starterSpec
+	ctx := 0
+	if f.starter.on {
+		if f.starterPick.Choice < len(starterChoices) {
+			starter = starterChoices[f.starterPick.Choice]
+		} else {
+			s, err := starterFrom(f.starterSource.Value())
+			if err != nil || !strings.HasPrefix(s.Source, "hf:") {
+				return f.fail(f.starter, f.starterSource, "the starter model's file: hf:<owner>/<repo>/<file>.gguf")
+			}
+			starter = s
+		}
+		n, err := strconv.Atoi(f.starterCtx.Value())
+		if err != nil || n < 512 || n > 262144 {
+			return f.fail(f.starter, f.starterCtx, "the starter's context: a number of tokens from 512 to 262144")
+		}
+		ctx = n
+	}
+
+	var judge judgeSpec
+	if f.judge.on {
+		judge.Fail = []string{"closed", "open"}[f.judgeFail.Choice]
+		n, err := strconv.Atoi(f.judgeCopies.Value())
+		if err != nil || n < 1 || n > 8 {
+			return f.fail(f.judge, f.judgeCopies, "the judge's copies: from 1 to 8")
+		}
+		judge.Replicas = n
+		d, err := time.ParseDuration(f.judgeBudget.Value())
+		if err != nil || d < 500*time.Millisecond || d > time.Minute {
+			return f.fail(f.judge, f.judgeBudget, "how long the judge is waited for: a duration such as 5s, at most 1m")
+		}
+		judge.Budget = d
+		for i, c := range f.judgeCats {
+			if c.On {
+				judge.Categories = append(judge.Categories, judgeCategories[i])
+			}
+		}
+		if len(judge.Categories) == 0 {
+			return f.fail(f.judge, f.judgeCats[0], "the judge refuses nothing: tick a category, or turn the judge off")
+		}
+	}
+
+	var hooks []string
+	if f.alerts.on {
+		h := f.webhooks.Value()
+		parsed, err := parseWebhooks([]string{h})
+		if err != nil {
+			return f.fail(f.alerts, f.webhooks, err.Error())
+		}
+		if len(parsed) == 0 {
+			return f.fail(f.alerts, f.webhooks, "give a webhook, or turn notifications off")
+		}
+		hooks = []string{h}
+	}
+
+	rpm, err := strconv.Atoi(f.rpm.Value())
+	if err != nil || rpm < 1 {
+		return f.fail(f.limits, f.rpm, "requests a minute: a whole number, 1 or more")
+	}
+	tpm, err := strconv.Atoi(f.tpm.Value())
+	if err != nil || tpm < 1 {
+		return f.fail(f.limits, f.tpm, "tokens a minute: a whole number, 1 or more")
+	}
+	keyDays, err := strconv.Atoi(f.keyDays.Value())
+	if err != nil || keyDays < 1 || keyDays > 3650 {
+		return f.fail(f.limits, f.keyDays, "the longest a key lives: days, from 1 to 3650")
+	}
+	idle, err := time.ParseDuration(f.idle.Value())
+	if err != nil || idle < 0 {
+		return f.fail(f.turns, f.idle, "a duration such as 2m or 90s")
+	}
+	safe, err := time.ParseDuration(f.safe.Value())
+	if err != nil || safe < 0 {
+		return f.fail(f.turns, f.safe, "a duration such as 5m or 90s")
+	}
+
+	bundle, sum := "", ""
+	if f.bundle.on {
+		bundle, sum = f.bundlePath.Value(), strings.ToLower(f.bundleSHA.Value())
+		switch {
+		case bundle == "":
+			return f.fail(f.bundle, f.bundlePath, "give the bundle's path, or turn the offline bundle off")
+		case sum == "":
+			return f.fail(f.bundle, f.bundleSHA, "give the bundle's sha256, as 'llmgw bundle create' printed it")
+		}
+	}
+
+	in.admin, in.hosts = admin, hosts
+	in.language = map[int]string{0: "", 1: "tr"}[f.language.Choice]
+	in.signupOpen = f.signup.Choice == 1
+	in.postgres = !f.ha && f.storeKind.Choice == 1
+	in.noMirror = !f.mirror.on || mirrorURL != ""
+	in.mirrorURL, in.mirrorPath = mirrorURL, mirrorPath
+	in.noNode = !f.node.on
+	in.noModel = !f.starter.on
+	in.starter, in.starterCtx = starter, ctx
+	in.media = f.media.on
+	in.noGuardModel = !f.judge.on
+	in.judge = judge
+	in.noFirewall = !f.firewall.on
+	in.webhooks = hooks
+	in.defaultRPM, in.defaultTPM = rpm, tpm
+	in.maxKeyTTL = time.Duration(keyDays) * 24 * time.Hour
+	in.evictAfterIdle, in.minLifetime = 0, 0
+	if idle != 2*time.Minute {
+		in.evictAfterIdle = idle
+	}
+	if safe != 5*time.Minute {
+		in.minLifetime = safe
+	}
+	in.bundle, in.bundleSHA = bundle, sum
+	in.standbys, in.vip = false, ""
+	if f.standby != nil && f.standby.on {
+		in.standbys, in.vip = true, f.vipF.Value()
+	}
+	if err := in.checkChoices(); err != nil {
+		if strings.HasPrefix(err.Error(), "floating address") {
+			return f.fail(f.standby, f.vipF, err.Error())
+		}
+		return f.fail(nil, nil, err.Error())
+	}
+	return nil
+}
+
+// view is the list of parts, and what the focused one is, under it.
+func (f *installForm) view(width int) string {
+	var b strings.Builder
+	b.WriteString("\n  " + sDim.Render("Space turns a part on or off · Enter opens its settings and says more") + "\n\n")
+	titleW := 0
+	for _, p := range f.parts {
+		titleW = max(titleW, len(p.title))
+	}
+	for i, p := range f.parts {
+		box := "[ ]"
+		switch {
+		case p.fixed:
+			box = " • "
+		case p.on:
+			box = "[" + sOK.Render("x") + "]"
+		}
+		title := fmt.Sprintf("%-*s", titleW, p.title)
+		line := ""
+		if p.on {
+			line = p.summary()
+		} else {
+			line = sDim.Render(p.off)
+		}
+		if i == f.focus {
+			title = fSelected.Render(title)
+			b.WriteString(fSelected.Render("› ") + box + " " + title + "  " + truncateWidth(line, max(20, width-titleW-8)) + "\n")
+		} else {
+			b.WriteString("  " + box + " " + title + "  " + truncateWidth(line, max(20, width-titleW-8)) + "\n")
+		}
+	}
+	b.WriteString("\n" + button(f.focus == len(f.parts), "Next") + "\n")
+	if f.focus < len(f.parts) {
+		p := f.parts[f.focus]
+		b.WriteString("\n  " + lipgloss.NewStyle().Bold(true).Render(p.title) + "\n")
+		b.WriteString(paragraphs(p.about, max(40, width-6), "  ") + "\n")
+	}
+	return b.String()
+}
+
+// overlay is the dialog over the list, if one is open: its title and body.
+func (f *installForm) overlay() (string, string) {
+	if f.err != "" {
+		return "Not yet", f.err + "\n\n" + sDim.Render("any key to go back")
+	}
+	if f.dialog != nil {
+		return f.dialog.Title, f.dialog.view(max(8, f.height-8))
+	}
+	return "", ""
+}
+
+// keys is the key bar for the list or its dialog.
+func (f *installForm) keys() string {
+	switch {
+	case f.err != "":
+		return "any key back"
+	case f.dialog != nil:
+		return setupDialogKeys(f.dialog)
+	}
+	return "↑↓ move · Space on/off · Enter settings, or on Next go on · Ctrl+C leave"
+}
+
+// planView says what will be installed and what will not, part by part, in
+// words: the last look before anything is done.
+func (f *installForm) planView(width int) string {
+	var b strings.Builder
+	b.WriteString("\n  " + lipgloss.NewStyle().Bold(true).Render("Installed on "+f.host) + "\n\n")
+	var left []*installPart
+	for _, p := range f.parts {
+		if !p.on {
+			left = append(left, p)
+			continue
+		}
+		fmt.Fprintf(&b, "  %s %s\n      %s\n", sOK.Render("✓"), p.title, wrap(p.summary(), max(40, width-8), "      "))
+	}
+	if len(left) > 0 {
+		b.WriteString("\n  " + lipgloss.NewStyle().Bold(true).Render("Left out") + "\n\n")
+		for _, p := range left {
+			fmt.Fprintf(&b, "  %s %s\n      %s\n", sDim.Render("-"), p.title, sDim.Render(wrap(p.off, max(40, width-8), "      ")))
+		}
+	}
+	return b.String()
+}

internal/cli/tui_console.go

@@ -90,7 +90,10 @@ type consoleData struct {
 	// federation is the other llmgw clusters whose models are offered
 	// here; empty on a control plane without a store.
 	federation adminapi.FederationView
-	err        error
+	// presets is the models that come with llmgw as they stand here; nil
+	// from a control plane that cannot say.
+	presets *adminapi.PresetsView
+	err     error
 }
 
 type (
@@ -275,6 +278,10 @@ func (m consoleModel) fetch() tea.Cmd {
 		_ = c.get(ctx, "/api/v1/jobs", &d.jobs)
 		_ = c.get(ctx, "/api/v1/audit?since=7d&limit=300", &d.audit)
 		_ = c.get(ctx, "/api/v1/federation", &d.federation)
+		var presets adminapi.PresetsView
+		if c.get(ctx, "/api/v1/presets", &presets) == nil {
+			d.presets = &presets
+		}
 		return consoleDataMsg(d)
 	}
 }
@@ -599,6 +606,10 @@ func (m consoleModel) key(k tea.KeyMsg) (tea.Model, tea.Cmd) {
 			m.hf.models, m.hf.err, m.row = nil, nil, 0
 			return m, m.fetchHF()
 		}
+	case "p":
+		if m.menu == cModels && m.inPanel && m.data.presets != nil {
+			m.autoPresetsConfirm()
+		}
 	case "a":
 		switch m.menu {
 		case cQuotas:
@@ -1237,9 +1248,13 @@ func (m consoleModel) panel() (title, body, keys string) {
 				strings.Join(md.Profiles, ","), upd, warn})
 		}
 		if m.inPanel {
-			keys = "↑↓ row · Enter actions · A add from a file · ← back · Q leave"
+			keys = "↑↓ row · Enter actions · A add a model · ← back · Q leave"
+			if m.data.presets != nil {
+				keys = "↑↓ row · Enter actions · A add a model · P pictures and 3D added by themselves · ← back · Q leave"
+			}
 		}
-		return "Models", "\n" + table([]string{"MODEL", "READY", "STATUS", "CLASS", "PROFILES", "UPDATE", ""}, rows, m.row, pw, m.inPanel), keys
+		return "Models", "\n" + table([]string{"MODEL", "READY", "STATUS", "CLASS", "PROFILES", "UPDATE", ""}, rows, m.row, pw, m.inPanel) +
+			presetsBlock(m.data.presets, pw), keys
 	case cReplicas:
 		var rows [][]string
 		for _, r := range m.data.replicas {

internal/cli/tui_form.go

@@ -0,0 +1,322 @@
+package cli
+
+import (
+	"strings"
+
+	tea "github.com/charmbracelet/bubbletea"
+	"github.com/charmbracelet/lipgloss"
+	"github.com/charmbracelet/x/ansi"
+)
+
+// A form in a dialog: text to type, one of a few choices, a thing on or off,
+// and headings between them. The setup's settings for each part are one of
+// these, opened over the list of parts.
+
+type fieldKind int
+
+const (
+	fkText fieldKind = iota
+	// fkChoice is one of Options, changed with ← →.
+	fkChoice
+	// fkToggle is on or off, changed with Space.
+	fkToggle
+	// fkHeading is a title between fields; it takes no focus.
+	fkHeading
+)
+
+type setupField struct {
+	Label string
+	// Hint is said under the field; Notes, for a choice, under each option
+	// as it is chosen.
+	Hint  string
+	Notes []string
+	Kind  fieldKind
+
+	Text    textField
+	Options []string
+	Choice  int
+	On      bool
+	// Show, when set, says whether the field is shown, and so whether it
+	// counts: a directory for a mirror kept elsewhere is neither.
+	Show func() bool
+}
+
+func textSetupField(label, value, placeholder, hint string) *setupField {
+	t := newTextField()
+	t.SetValue(value)
+	t.Placeholder, t.CharLimit, t.Width = placeholder, 800, 40
+	return &setupField{Label: label, Hint: hint, Kind: fkText, Text: t}
+}
+
+func choiceField(label string, options []string, choice int, hint string) *setupField {
+	return &setupField{Label: label, Hint: hint, Kind: fkChoice, Options: options, Choice: choice}
+}
+
+func toggleField(label string, on bool, hint string) *setupField {
+	return &setupField{Label: label, Hint: hint, Kind: fkToggle, On: on}
+}
+
+func headingField(label string) *setupField {
+	return &setupField{Label: label, Kind: fkHeading}
+}
+
+func (f *setupField) shown() bool { return f.Show == nil || f.Show() }
+
+func (f *setupField) Value() string { return strings.TrimSpace(f.Text.Value()) }
+
+// setupDialog is a form over the screen, with what it is for above it.
+type setupDialog struct {
+	Title  string
+	About  string
+	Fields []*setupField
+	focus  int
+}
+
+// focusable is whether a field can have the focus now.
+func (d *setupDialog) focusable(i int) bool {
+	f := d.Fields[i]
+	return f.Kind != fkHeading && f.shown()
+}
+
+// first puts the focus on the first field that takes it.
+func (d *setupDialog) first() {
+	d.focus = -1
+	d.move(1)
+}
+
+// focusOn puts the focus on a field, as when it is what is wrong.
+func (d *setupDialog) focusOn(f *setupField) {
+	for i, x := range d.Fields {
+		if x == f {
+			d.focus = i
+		}
+	}
+	d.blurAll()
+}
+
+func (d *setupDialog) move(dir int) {
+	n := len(d.Fields)
+	for range n {
+		d.focus = (d.focus + dir + n) % n
+		if d.focusable(d.focus) {
+			break
+		}
+	}
+	d.blurAll()
+}
+
+// blurAll leaves only the focused text field with a cursor.
+func (d *setupDialog) blurAll() {
+	for i, f := range d.Fields {
+		if f.Kind != fkText {
+			continue
+		}
+		if i == d.focus {
+			f.Text.Focus()
+		} else {
+			f.Text.Blur()
+		}
+	}
+}
+
+// hasFields is whether there is anything to set, rather than only to read.
+func (d *setupDialog) hasFields() bool {
+	for i := range d.Fields {
+		if d.focusable(i) {
+			return true
+		}
+	}
+	return false
+}
+
+// lastFocusable is the last field that takes the focus now.
+func (d *setupDialog) lastFocusable() int {
+	for i := len(d.Fields) - 1; i >= 0; i-- {
+		if d.focusable(i) {
+			return i
+		}
+	}
+	return -1
+}
+
+// key takes a key and says whether the dialog is done: Esc, or Enter on
+// the last field.
+func (d *setupDialog) key(k tea.KeyMsg) (done bool) {
+	switch k.Type {
+	case tea.KeyEsc:
+		return true
+	case tea.KeyEnter:
+		if !d.hasFields() || d.focus == d.lastFocusable() {
+			return true
+		}
+		d.move(1)
+		return false
+	case tea.KeyTab, tea.KeyDown:
+		if d.hasFields() {
+			d.move(1)
+		}
+		return false
+	case tea.KeyShiftTab, tea.KeyUp:
+		if d.hasFields() {
+			d.move(-1)
+		}
+		return false
+	}
+	if d.focus < 0 || d.focus >= len(d.Fields) || !d.focusable(d.focus) {
+		return false
+	}
+	f := d.Fields[d.focus]
+	switch f.Kind {
+	case fkText:
+		f.Text, _ = f.Text.Update(k)
+	case fkChoice:
+		switch k.String() {
+		case "left", "h":
+			f.Choice = (f.Choice + len(f.Options) - 1) % len(f.Options)
+		case "right", "l", " ":
+			f.Choice = (f.Choice + 1) % len(f.Options)
+		}
+	case fkToggle:
+		if k.String() == " " || k.String() == "x" {
+			f.On = !f.On
+		}
+	}
+	return false
+}
+
+// dialogWidth is how wide the text in a dialog is wrapped.
+const dialogWidth = 66
+
+// view draws the form in at most maxLines lines, the part around the focus
+// when it is longer: a long form scrolls as the focus moves.
+func (d *setupDialog) view(maxLines int) string {
+	var lines []string
+	add := func(s string) { lines = append(lines, strings.Split(s, "\n")...) }
+	if d.About != "" {
+		add(paragraphs(d.About, dialogWidth, ""))
+	}
+	if !d.hasFields() {
+		add("")
+		add(sDim.Render("Nothing to set for this part. Esc or Enter to go back."))
+		return clipLines(lines, 0, 0, maxLines)
+	}
+	add("")
+	focusStart, focusEnd := 0, 0
+	for i, f := range d.Fields {
+		if !f.shown() {
+			continue
+		}
+		focused := i == d.focus
+		if focused {
+			focusStart = len(lines)
+		}
+		label := func(s string) string {
+			if focused {
+				return fSelected.Render("› " + s)
+			}
+			return "  " + s
+		}
+		switch f.Kind {
+		case fkHeading:
+			add("")
+			add("  " + lipgloss.NewStyle().Bold(true).Render(f.Label))
+			continue
+		case fkText:
+			add(label(f.Label))
+			add("    " + f.Text.View())
+		case fkChoice:
+			var opts []string
+			for j, o := range f.Options {
+				if j == f.Choice {
+					opts = append(opts, "("+sOK.Render("•")+") "+o)
+				} else {
+					opts = append(opts, "( ) "+sDim.Render(o))
+				}
+			}
+			add(label(f.Label))
+			// Side by side while they fit, else one a line.
+			if row := strings.Join(opts, "  "); ansi.StringWidth(row) <= dialogWidth-4 {
+				add("    " + row)
+			} else {
+				for _, o := range opts {
+					add("    " + o)
+				}
+			}
+			if f.Choice < len(f.Notes) && f.Notes[f.Choice] != "" {
+				add("    " + sDim.Render(wrap(f.Notes[f.Choice], dialogWidth-4, "    ")))
+			}
+		case fkToggle:
+			box := "[ ]"
+			if f.On {
+				box = "[" + sOK.Render("x") + "]"
+			}
+			add(label(box) + " " + f.Label)
+		}
+		if f.Hint != "" {
+			add("    " + sDim.Render(wrap(f.Hint, dialogWidth-4, "    ")))
+		}
+		if focused {
+			focusEnd = len(lines) - 1
+		}
+		if f.Kind != fkToggle {
+			add("")
+		}
+	}
+	for len(lines) > 0 && lines[len(lines)-1] == "" {
+		lines = lines[:len(lines)-1]
+	}
+	return clipLines(lines, focusStart, focusEnd, maxLines)
+}
+
+// clipLines is at most n of lines, keeping lines from to through in sight
+// as far as they fit, with a mark at an edge that has more beyond it.
+func clipLines(lines []string, from, through, n int) string {
+	if n <= 2 || len(lines) <= n {
+		return strings.Join(lines, "\n")
+	}
+	top := 0
+	// The last line shown is a mark when there is more below: the focus
+	// ends a line above it.
+	if through > n-2 {
+		top = through - (n - 2)
+	}
+	// Its first line wins over its last, under the mark above.
+	if from > 0 && top > from-1 {
+		top = from - 1
+	}
+	top = max(0, min(top, len(lines)-n))
+	out := append([]string{}, lines[top:top+n]...)
+	if top > 0 {
+		out[0] = sDim.Render("  ↑ more")
+	}
+	if top+n < len(lines) {
+		out[n-1] = sDim.Render("  ↓ more")
+	}
+	return strings.Join(out, "\n")
+}
+
+// paragraphs wraps text paragraph by paragraph, blank lines kept between.
+func paragraphs(s string, width int, indent string) string {
+	var out []string
+	for _, p := range strings.Split(s, "\n\n") {
+		out = append(out, indent+wrap(p, width, indent))
+	}
+	return strings.Join(out, "\n\n")
+}
+
+// setupDialogKeys is the key bar under a dialog.
+func setupDialogKeys(d *setupDialog) string {
+	if !d.hasFields() {
+		return "Esc or Enter back"
+	}
+	keys := "Tab/↑↓ move"
+	if d.focus >= 0 && d.focus < len(d.Fields) {
+		switch d.Fields[d.focus].Kind {
+		case fkChoice:
+			keys += " · ←→ choose"
+		case fkToggle:
+			keys += " · Space tick"
+		}
+	}
+	return keys + " · Esc done"
+}

internal/cli/tui_init.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"fmt"
 	"io"
-	"net/mail"
 	"os"
 	"path/filepath"
 	"strings"
@@ -47,33 +46,16 @@ func (w *lineWriter) Write(p []byte) (int, error) {
 }
 
 // Form fields, in order.
-const (
-	fAdmin = iota
-	fHosts
-	fPostgres
-	fMirror
-	fNode
-	fModel
-	fGuard
-	fBundle
-	fBundleSHA
-	fStart
-	fCount
-)
-
 type initModel struct {
 	in    *serverInit
 	found []string // this machine's addresses
 
-	// The form, until it is submitted.
-	form      bool
-	focus     int
-	admin     textField
-	hosts     textField
-	bundle    textField
-	bundleSHA textField
-	toggles   [fCount]bool
-	formError string
+	// The parts to install, until they are chosen and the plan agreed to.
+	form    bool
+	plan    bool
+	choices *installForm
+	// scroll is how far the panel is scrolled, back to the top on each page.
+	scroll int
 
 	// Then the run.
 	running  bool
@@ -93,38 +75,9 @@ type initModel struct {
 }
 
 func newInitModel(in *serverInit, found []string, askForm bool) initModel {
-	admin := newTextField()
-	admin.Placeholder = "you@example.com"
-	admin.SetValue(in.admin)
-	admin.CharLimit = 200
-	admin.Width = 40
-	hosts := newTextField()
-	hosts.Placeholder = "llm.example.com, 203.0.113.10"
-	hosts.SetValue(strings.Join(in.hosts, ", "))
-	hosts.CharLimit = 400
-	hosts.Width = 40
-	bundle := newTextField()
-	bundle.Placeholder = "/media/usb/llmgw-bundle.tar"
-	bundle.SetValue(in.bundle)
-	bundle.CharLimit = 400
-	bundle.Width = 40
-	bundleSHA := newTextField()
-	bundleSHA.Placeholder = "the sha256 'llmgw bundle create' printed"
-	bundleSHA.SetValue(in.bundleSHA)
-	bundleSHA.CharLimit = 64
-	bundleSHA.Width = 64
-	sp := newSpinner()
-	m := initModel{in: in, found: found, form: askForm, admin: admin, hosts: hosts,
-		bundle: bundle, bundleSHA: bundleSHA, spin: sp, width: 100}
-	m.toggles[fPostgres] = in.postgres
-	m.toggles[fMirror] = !in.noMirror
-	m.toggles[fNode] = !in.noNode
-	m.toggles[fModel] = !in.noModel
-	m.toggles[fGuard] = !in.noGuardModel
-	if askForm {
-		m.admin.Focus()
-	}
-	return m
+	host, _ := os.Hostname()
+	return initModel{in: in, found: found, form: askForm, choices: newInstallForm(in, host, found, false),
+		spin: newSpinner(), width: 100, height: 30}
 }
 
 func (m initModel) Init() tea.Cmd {
@@ -140,6 +93,7 @@ func (m initModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 	switch msg := msg.(type) {
 	case tea.WindowSizeMsg:
 		m.width, m.height = msg.Width, msg.Height
+		m.choices.height = msg.Height
 		if m.framed {
 			m.width = msg.Width - navWidth - 6
 		}
@@ -202,100 +156,32 @@ func (m *initModel) addLine(l string) {
 
 func (m initModel) formKey(k tea.KeyMsg) (tea.Model, tea.Cmd) {
 	switch k.Type {
-	case tea.KeyTab, tea.KeyDown:
-		m.moveFocus(1)
+	case tea.KeyPgDown:
+		m.scroll += max(1, m.height-8)
 		return m, nil
-	case tea.KeyShiftTab, tea.KeyUp:
-		m.moveFocus(-1)
+	case tea.KeyPgUp:
+		m.scroll = max(0, m.scroll-max(1, m.height-8))
 		return m, nil
-	case tea.KeyEnter:
-		if m.focus != fStart {
-			m.moveFocus(1)
-			return m, nil
-		}
-		admin := strings.TrimSpace(m.admin.Value())
-		if admin != "" {
-			if _, err := mail.ParseAddress(admin); err != nil {
-				m.formError = "the administrator's email is not an address"
-				m.focus = fAdmin
-				m.admin.Focus()
-				return m, nil
-			}
-		}
-		bundle, sum := strings.TrimSpace(m.bundle.Value()), strings.ToLower(strings.TrimSpace(m.bundleSHA.Value()))
-		switch {
-		case bundle != "" && sum == "":
-			m.formError = "give the bundle's sha256, as 'llmgw bundle create' printed it"
-			m.focus = fBundleSHA
-			m.moveFocus(0)
-			return m, nil
-		case bundle != "" && !m.toggles[fMirror] && m.in.mirrorURL == "":
-			m.formError = "an offline bundle goes into the model mirror: tick it"
-			m.focus = fMirror
-			m.moveFocus(0)
-			return m, nil
-		}
-		m.in.bundle, m.in.bundleSHA = bundle, sum
-		m.in.admin = admin
-		m.in.hosts = nil
-		for _, h := range strings.Split(m.hosts.Value(), ",") {
-			if h = strings.TrimSpace(h); h != "" {
-				m.in.hosts = append(m.in.hosts, h)
-			}
-		}
-		m.in.postgres = m.toggles[fPostgres]
-		m.in.noMirror = !m.toggles[fMirror]
-		m.in.noNode = !m.toggles[fNode]
-		m.in.noModel = !m.toggles[fModel]
-		m.in.noGuardModel = !m.toggles[fGuard]
-		m.form = false
-		return m, tea.Batch(m.spin.Tick, func() tea.Msg { return startInitMsg{} })
 	}
-	switch m.focus {
-	case fAdmin:
-		var cmd tea.Cmd
-		m.admin, cmd = m.admin.Update(k)
-		return m, cmd
-	case fHosts:
-		var cmd tea.Cmd
-		m.hosts, cmd = m.hosts.Update(k)
-		return m, cmd
-	case fBundle:
-		var cmd tea.Cmd
-		m.bundle, cmd = m.bundle.Update(k)
-		return m, cmd
-	case fBundleSHA:
-		var cmd tea.Cmd
-		m.bundleSHA, cmd = m.bundleSHA.Update(k)
-		return m, cmd
-	case fPostgres, fMirror, fNode, fModel, fGuard:
-		if k.String() == " " || k.String() == "x" {
-			m.toggles[m.focus] = !m.toggles[m.focus]
+	if m.plan {
+		switch k.Type {
+		case tea.KeyEsc:
+			m.plan, m.scroll = false, 0
+		case tea.KeyEnter:
+			m.form, m.plan, m.scroll = false, false, 0
+			return m, tea.Batch(m.spin.Tick, func() tea.Msg { return startInitMsg{} })
 		}
+		return m, nil
+	}
+	if m.choices.key(k, m.in) {
+		m.plan, m.scroll = true, 0
 	}
 	return m, nil
 }
 
-func (m *initModel) moveFocus(d int) {
-	m.focus = (m.focus + d + fCount) % fCount
-	// With --mirror there is no mirror to run here, so nothing to tick.
-	if m.focus == fMirror && m.in.mirrorURL != "" {
-		m.focus = (m.focus + d + fCount) % fCount
-	}
-	m.admin.Blur()
-	m.hosts.Blur()
-	m.bundle.Blur()
-	m.bundleSHA.Blur()
-	switch m.focus {
-	case fAdmin:
-		m.admin.Focus()
-	case fHosts:
-		m.hosts.Focus()
-	case fBundle:
-		m.bundle.Focus()
-	case fBundleSHA:
-		m.bundleSHA.Focus()
-	}
+// command is this install as a command line, for doing it again from a script.
+func (in *serverInit) command() string {
+	return strings.Join(append([]string{"sudo llmgw server init"}, in.initFlags()...), " \\\n    ")
 }
 
 func (m initModel) View() string {
@@ -306,27 +192,50 @@ func (m initModel) View() string {
 	if i := strings.Index(body, "\n\n"); i >= 0 {
 		body = body[i+1:]
 	}
-	steps := []navItem{{Label: "Start", State: "done"}, {Label: "Settings", State: "current"}, {Label: "Install", State: "todo"}}
-	keys := "Tab/↑↓ move · Space tick · Enter on Set up · Ctrl+C leave"
-	if !m.form {
+	steps := []navItem{{Label: "Start", State: "done"}, {Label: "Choices", State: "current"},
+		{Label: "Plan", State: "todo"}, {Label: "Install", State: "todo"}}
+	keys := m.choices.keys()
+	title := "What to install"
+	switch {
+	case m.form && m.plan:
 		steps[1].State, steps[2].State = "done", "current"
-		keys = "Ctrl+C stop"
+		keys, title = "Enter install · Esc back to the choices · PgUp/PgDn scroll · Ctrl+C leave", "Plan"
+	case !m.form:
+		steps[1].State, steps[2].State, steps[3].State = "done", "done", "current"
+		keys, title = "Ctrl+C stop", "Installing"
 		if m.done {
-			steps[2].State = "done"
+			steps[3].State = "done"
 			keys = "Enter close"
 		}
 	}
-	host, _ := os.Hostname()
-	return frame{Width: m.width + navWidth + 6, Height: m.height, Title: "llmgw setup", Where: host,
-		NavTitle: "Steps", Nav: steps, PanelTitle: "This machine as a control plane", Body: body, Keys: keys}.render()
+	f := frame{Width: m.width + navWidth + 6, Height: m.height, Title: "llmgw setup",
+		NavTitle: "Steps", Nav: steps, PanelTitle: title, Body: body, Keys: keys, Scroll: m.scroll}
+	if m.form && !m.plan {
+		f.DialogTitle, f.Dialog = m.choices.overlay()
+	}
+	f.Where, _ = os.Hostname()
+	return f.render()
 }
 
 // plainView is the screen as text, for a panel or a terminal that is not one.
 func (m initModel) plainView() string {
 	var b strings.Builder
 	b.WriteString(sTitle.Render("llmgw · setting up this machine as a control plane") + "\n\n")
+	if m.form && m.plan {
+		b.WriteString(m.choices.planView(m.width))
+		b.WriteString("\n  " + sDim.Render("The same from a script:") + "\n")
+		for _, l := range strings.Split(m.in.command(), "\n") {
+			b.WriteString("  " + l + "\n")
+		}
+		b.WriteString("\n" + button(true, "Enter to install") + "\n")
+		return b.String()
+	}
 	if m.form {
-		return b.String() + m.formView()
+		b.WriteString(m.choices.view(m.width))
+		if title, d := m.choices.overlay(); d != "" && !m.framed {
+			b.WriteString("\n" + sTitle.Render(title) + "\n" + d + "\n")
+		}
+		return b.String()
 	}
 	for _, l := range m.visibleLines() {
 		b.WriteString(m.lineView(l) + "\n")
@@ -386,51 +295,6 @@ func (m initModel) lineView(l string) string {
 	return "    " + t
 }
 
-func (m initModel) formView() string {
-	var b strings.Builder
-	label := func(i int, s string) string {
-		if m.focus == i {
-			return sTitle.Render("› " + s)
-		}
-		return "  " + s
-	}
-	check := func(i int, s, hint string) string {
-		box := "[ ]"
-		if m.toggles[i] {
-			box = "[" + sOK.Render("x") + "]"
-		}
-		return fmt.Sprintf("%s %s %s\n", label(i, box), s, sDim.Render(hint))
-	}
-	fmt.Fprintf(&b, "%s\n    %s\n", label(fAdmin, "Administrator's email"), m.admin.View())
-	b.WriteString("    " + sDim.Render("A password is generated and shown once. Leave empty to create accounts later.") + "\n\n")
-	fmt.Fprintf(&b, "%s\n    %s\n", label(fHosts, "Other names nodes will reach this machine by"), m.hosts.View())
-	found := "none found"
-	if len(m.found) > 0 {
-		found = strings.Join(m.found, ", ")
-	}
-	b.WriteString("    " + sDim.Render("Already in the certificate: "+found+". Add a DNS name or NAT address here.") + "\n\n")
-	b.WriteString(check(fPostgres, "PostgreSQL", "rather than SQLite; installed here, for several control planes or a larger store"))
-	if m.in.mirrorURL != "" {
-		b.WriteString("  Model mirror " + sDim.Render("at "+m.in.mirrorURL+", from --mirror") + "\n")
-	} else {
-		b.WriteString(check(fMirror, "Model mirror", "downloads model files once for every node"))
-	}
-	b.WriteString(check(fNode, "This machine as a node", "serves models here too, on its GPUs or CPU"))
-	b.WriteString(check(fModel, "Starter model", "a small Qwen, so there is something to ask at once"))
-	b.WriteString(check(fGuard, "Guardrails' judge", "Llama Guard 3 1B on a CPU, refusing violent, criminal and abusive requests"))
-	fmt.Fprintf(&b, "\n%s\n    %s\n", label(fBundle, "Offline bundle"), m.bundle.View())
-	b.WriteString("    " + sDim.Render("For a site with no internet: engines, releases and models from 'llmgw bundle create'. Empty downloads them.") + "\n")
-	fmt.Fprintf(&b, "%s\n    %s\n", label(fBundleSHA, "Its sha256"), m.bundleSHA.View())
-	b.WriteString("\n" + label(fStart, lipgloss.NewStyle().Bold(true).Render("Set up")) + "\n")
-	if m.formError != "" {
-		b.WriteString("\n" + sBad.Render(m.formError) + "\n")
-	}
-	if !m.framed { // the frame's key bar says it
-		b.WriteString("\n" + sDim.Render("tab or ↑↓ to move · space to tick · enter on Set up to start · ctrl+c to leave") + "\n")
-	}
-	return b.String()
-}
-
 // runInitTUI runs init with the screen above, asking the form first when
 // the flags left the administrator unset.
 func (in *serverInit) runInitTUI(ctx context.Context, out io.Writer) error {

internal/cli/tui_init_test.go

@@ -3,6 +3,7 @@ package cli
 import (
 	"strings"
 	"testing"
+	"time"
 
 	tea "github.com/charmbracelet/bubbletea"
 )
@@ -11,21 +12,54 @@ func typeIn(m tea.Model, s string) tea.Model {
 	return send(m, tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune(s)})
 }
 
+// toPart moves the focus in the list of parts to the one titled so.
+func toPart(t *testing.T, m tea.Model, title string) tea.Model {
+	t.Helper()
+	f := m.(initModel).choices
+	for i := 0; i <= len(f.parts); i++ {
+		if f.focus < len(f.parts) && f.parts[f.focus].title == title {
+			return m
+		}
+		m = press(m, "down")
+	}
+	t.Fatalf("no part %q", title)
+	return m
+}
+
+// toNext moves the focus to the button that goes on, and presses it.
+func toNext(m tea.Model) tea.Model {
+	f := m.(initModel).choices
+	for f.focus != len(f.parts) {
+		m = press(m, "down")
+	}
+	return press(m, "enter")
+}
+
 func TestTheInitFormBecomesInitsSettings(t *testing.T) {
 	in := &serverInit{pkiDir: "/etc/llmgw/pki"}
 	var m tea.Model = newInitModel(in, []string{"10.0.0.140"}, true)
-	if v := m.View(); !strings.Contains(v, "Already in the certificate: 10.0.0.140") {
+	m = press(toPart(t, m, "Control plane"), "enter")
+	m = typeIn(m, "ops@example.com")
+	m = press(m, "tab")
+	if v := m.View(); !strings.Contains(v, "Already in its certificate: 10.0.0.140") {
 		t.Fatalf("the addresses found are not shown:\n%s", v)
 	}
-	m = typeIn(m, "ops@example.com")
-	m = send(m, tea.KeyMsg{Type: tea.KeyTab})
 	m = typeIn(m, "llm.example.com, 203.0.113.10")
-	m = send(m, tea.KeyMsg{Type: tea.KeyTab}, tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune(" ")}) // PostgreSQL on
-	m = send(m, tea.KeyMsg{Type: tea.KeyTab}, tea.KeyMsg{Type: tea.KeyTab}, tea.KeyMsg{Type: tea.KeyTab},
-		tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune(" ")}) // starter model off
-	m = send(m, tea.KeyMsg{Type: tea.KeyTab}, tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune(" ")})         // judge off
-	m = send(m, tea.KeyMsg{Type: tea.KeyTab}, tea.KeyMsg{Type: tea.KeyTab}, tea.KeyMsg{Type: tea.KeyTab}) // no bundle
-	m = send(m, tea.KeyMsg{Type: tea.KeyEnter})
+	m = press(m, "esc")
+	m = press(toPart(t, m, "Store"), "enter", "right", "esc") // PostgreSQL
+	// Turning notifications on asks for the webhook at once.
+	m = press(toPart(t, m, "Notifications"), "space")
+	if m.(initModel).choices.dialog == nil {
+		t.Fatal("notifications turned on without asking where")
+	}
+	m = typeIn(m, "https://hooks.slack.com/services/T1/B2/x, json:https://alerts.example.com/in")
+	m = press(m, "esc")
+	m = press(toPart(t, m, "Starter model"), "space")     // off
+	m = press(toPart(t, m, "Guardrails' judge"), "space") // off
+	m = toNext(m)
+	if !m.(initModel).plan {
+		t.Fatalf("Next did not lead to the plan: %s", m.(initModel).choices.err)
+	}
 
 	if in.admin != "ops@example.com" || strings.Join(in.hosts, "|") != "llm.example.com|203.0.113.10" {
 		t.Errorf("admin %q hosts %q", in.admin, in.hosts)
@@ -33,8 +67,36 @@ func TestTheInitFormBecomesInitsSettings(t *testing.T) {
 	if !in.postgres || in.noMirror || in.noNode || !in.noModel || !in.noGuardModel {
 		t.Errorf("toggles: postgres %v mirror %v node %v model %v", in.postgres, !in.noMirror, !in.noNode, !in.noModel)
 	}
+	if hooks, err := parseWebhooks(in.webhooks); err != nil || len(hooks) != 2 || hooks[0].Format != "slack" || hooks[1].Format != "json" {
+		t.Errorf("webhooks %q: %+v %v", in.webhooks, hooks, err)
+	}
+	v := m.View()
+	for _, want := range []string{"✓ Store", "PostgreSQL on this machine", "Left out", "Starter model", "--postgres", "--no-model"} {
+		if !strings.Contains(v, want) {
+			t.Errorf("the plan lacks %q:\n%s", want, v)
+		}
+	}
+	m = press(m, "enter")
 	if m.(initModel).form {
-		t.Error("the form stayed up after Set up")
+		t.Error("the form stayed up after the plan was agreed to")
+	}
+}
+
+func TestAWebhookThatIsNoAddressKeepsTheFormUp(t *testing.T) {
+	in := &serverInit{}
+	var m tea.Model = newInitModel(in, nil, true)
+	m = press(toPart(t, m, "Notifications"), "space")
+	m = typeIn(m, "hooks.slack.com/services/x")
+	m = toNext(press(m, "esc"))
+	im := m.(initModel)
+	if !im.form || im.plan || !strings.Contains(m.View(), "http(s) address") {
+		t.Fatalf("an address without its scheme was taken:\n%s", m.View())
+	}
+	// Closing the message opens the field that is wrong.
+	m = press(m, "q")
+	d := m.(initModel).choices.dialog
+	if d == nil || d.Fields[d.focus] != m.(initModel).choices.webhooks {
+		t.Errorf("the webhook was not given the cursor")
 	}
 }
 
@@ -44,34 +106,119 @@ func TestAnOfflineBundleIsGivenInTheFormWithItsDigest(t *testing.T) {
 	if v := m.View(); !strings.Contains(v, "Offline bundle") {
 		t.Fatalf("the form offers no bundle:\n%s", v)
 	}
-	for range fBundle {
-		m = send(m, tea.KeyMsg{Type: tea.KeyTab})
-	}
+	m = press(toPart(t, m, "Offline bundle"), "space")
 	m = typeIn(m, "/media/usb/b.tar")
-	m = send(m, tea.KeyMsg{Type: tea.KeyTab}, tea.KeyMsg{Type: tea.KeyTab}, tea.KeyMsg{Type: tea.KeyEnter})
-	if !m.(initModel).form || !strings.Contains(m.View(), "sha256") || m.(initModel).focus != fBundleSHA {
+	m = toNext(press(m, "esc"))
+	if m.(initModel).plan || !strings.Contains(m.View(), "sha256") {
 		t.Fatalf("a bundle without its digest was accepted:\n%s", m.View())
 	}
+	m = press(m, "q") // the message closed, the digest has the cursor
 	m = typeIn(m, strings.Repeat("AB", 32))
-	m = send(m, tea.KeyMsg{Type: tea.KeyTab}, tea.KeyMsg{Type: tea.KeyEnter})
-	if m.(initModel).form || in.bundle != "/media/usb/b.tar" || in.bundleSHA != strings.Repeat("ab", 32) {
-		t.Errorf("bundle %q sha %q, form up %v", in.bundle, in.bundleSHA, m.(initModel).form)
+	m = toNext(press(m, "esc"))
+	if !m.(initModel).plan || in.bundle != "/media/usb/b.tar" || in.bundleSHA != strings.Repeat("ab", 32) {
+		t.Errorf("bundle %q sha %q, plan %v: %s", in.bundle, in.bundleSHA, m.(initModel).plan, m.(initModel).choices.err)
 	}
 }
 
 func TestAnEmailThatIsNotOneIsSaidSo(t *testing.T) {
 	in := &serverInit{}
 	var m tea.Model = newInitModel(in, nil, true)
+	m = press(m, "enter") // the control plane, first
 	m = typeIn(m, "not an address")
-	for range fStart {
-		m = send(m, tea.KeyMsg{Type: tea.KeyTab})
-	}
-	m = send(m, tea.KeyMsg{Type: tea.KeyEnter})
-	if !m.(initModel).form || !strings.Contains(m.View(), "not an address") {
+	m = toNext(press(m, "esc"))
+	if m.(initModel).plan || !strings.Contains(m.View(), "not an address") {
 		t.Errorf("a bad email was accepted:\n%s", m.View())
 	}
 }
 
+func TestEachPartsSettingsReachInit(t *testing.T) {
+	in := &serverInit{}
+	var m tea.Model = newInitModel(in, nil, true)
+	m = press(toPart(t, m, "Control plane"), "enter", "tab", "tab", "right", "tab", "right", "esc") // Türkçe, sign-up open
+	// The starter: qwen3-8b, the fifth, with 8192 tokens.
+	m = press(toPart(t, m, "Starter model"), "enter", "right", "right", "right", "right", "tab")
+	m = send(m, tea.KeyMsg{Type: tea.KeyCtrlU})
+	m = press(typeIn(m, "8192"), "esc")
+	// The judge: serving flagged, three copies, 3s, and PII too.
+	m = press(toPart(t, m, "Guardrails' judge"), "enter", "right", "tab")
+	m = send(m, tea.KeyMsg{Type: tea.KeyCtrlU})
+	m = press(typeIn(m, "3"), "tab")
+	m = send(m, tea.KeyMsg{Type: tea.KeyCtrlU})
+	m = typeIn(m, "3s")
+	for range 6 { // past the five ticked, to PII
+		m = press(m, "tab")
+	}
+	m = press(m, "space", "esc")
+	m = press(toPart(t, m, "Pictures and 3D"), "space")
+	m = press(toPart(t, m, "Limits and keys"), "enter")
+	m = send(m, tea.KeyMsg{Type: tea.KeyCtrlU})
+	m = press(typeIn(m, "120"), "tab", "tab")
+	m = send(m, tea.KeyMsg{Type: tea.KeyCtrlU})
+	m = press(typeIn(m, "30"), "esc")
+	m = press(toPart(t, m, "Taking turns on a card"), "enter")
+	m = send(m, tea.KeyMsg{Type: tea.KeyCtrlU})
+	m = press(typeIn(m, "1m"), "tab")
+	m = send(m, tea.KeyMsg{Type: tea.KeyCtrlU})
+	m = press(typeIn(m, "1m"), "esc")
+	m = press(toPart(t, m, "Model mirror"), "enter", "tab")
+	m = send(m, tea.KeyMsg{Type: tea.KeyCtrlU})
+	m = press(typeIn(m, "/data/models"), "esc")
+	m = toNext(m)
+	if !m.(initModel).plan {
+		t.Fatalf("not taken: %s", m.(initModel).choices.err)
+	}
+	switch {
+	case in.language != "tr" || !in.signupOpen:
+		t.Errorf("language %q signup %v", in.language, in.signupOpen)
+	case in.starter.Name != "qwen3-8b" || in.starterCtx != 8192:
+		t.Errorf("starter %q ctx %d", in.starter.Name, in.starterCtx)
+	case in.judge.Fail != "open" || in.judge.Replicas != 3 || in.judge.Budget != 3*time.Second ||
+		len(in.judge.Categories) != 6 || in.judge.Categories[5] != "PII":
+		t.Errorf("judge %+v", in.judge)
+	case !in.media:
+		t.Error("pictures and 3D not taken")
+	case in.defaultRPM != 120 || in.defaultTPM != defaultTPM || in.maxKeyTTL != 30*24*time.Hour:
+		t.Errorf("limits %d %d %s", in.defaultRPM, in.defaultTPM, in.maxKeyTTL)
+	case in.evictAfterIdle != time.Minute || in.minLifetime != time.Minute:
+		t.Errorf("turns %s %s", in.evictAfterIdle, in.minLifetime)
+	case in.mirrorPath != "/data/models":
+		t.Errorf("mirror %q", in.mirrorPath)
+	}
+	v := m.View()
+	for _, want := range []string{"--starter qwen3-8b", "--starter-context 8192", "--judge-fail open", "--judge-replicas 3",
+		"--language tr", "--media", "--mirror-dir /data/models", "--evict-after-idle 1m", "--max-key-ttl 720h"} {
+		if !strings.Contains(v, want) {
+			t.Errorf("the command lacks %q:\n%s", want, v)
+		}
+	}
+}
+
+func TestAStarterModelWantsTheMirror(t *testing.T) {
+	in := &serverInit{}
+	var m tea.Model = newInitModel(in, nil, true)
+	m = toNext(press(toPart(t, m, "Model mirror"), "space"))
+	if m.(initModel).plan || !strings.Contains(m.View(), "turn the mirror on") {
+		t.Errorf("a starter model with no mirror to fetch it into was taken:\n%s", m.View())
+	}
+}
+
+func TestALongDialogScrollsWithItsFocus(t *testing.T) {
+	in := &serverInit{}
+	m := newInitModel(in, nil, true)
+	m.choices.height = 24
+	var tm tea.Model = press(toPart(t, m, "Guardrails' judge"), "enter")
+	_, top := tm.(initModel).choices.overlay()
+	if !strings.Contains(top, "↓ more") || strings.Contains(top, "Copyright Violation") {
+		t.Fatalf("a dialog taller than the screen is not cut:\n%s", top)
+	}
+	for range 11 {
+		tm = press(tm, "tab")
+	}
+	if _, bottom := tm.(initModel).choices.overlay(); !strings.Contains(bottom, "Copyright Violation") {
+		t.Errorf("the focus went where it cannot be seen:\n%s", bottom)
+	}
+}
+
 func TestInitsLinesAreFiledAndThePasswordKeptInView(t *testing.T) {
 	in := &serverInit{admin: "ops@example.com", pkiDir: "/etc/llmgw/pki"}
 	var m tea.Model = newInitModel(in, nil, false)
@@ -111,16 +258,14 @@ func TestInitsLinesAreFiledAndThePasswordKeptInView(t *testing.T) {
 	}
 }
 
-func TestWithAMirrorElsewhereTheFormDoesNotOfferOne(t *testing.T) {
+func TestWithAMirrorElsewhereTheFormSaysSo(t *testing.T) {
 	in := &serverInit{mirrorURL: "http://10.0.0.150:8082"}
 	var m tea.Model = newInitModel(in, nil, true)
-	if v := m.View(); !strings.Contains(v, "at http://10.0.0.150:8082, from --mirror") {
+	if v := m.View(); !strings.Contains(v, "at http://10.0.0.150:8082") {
 		t.Errorf("the mirror in use is not shown:\n%s", v)
 	}
-	// Tab from the addresses goes past the mirror line to PostgreSQL, then
-	// the node.
-	m = send(m, tea.KeyMsg{Type: tea.KeyTab}, tea.KeyMsg{Type: tea.KeyTab}, tea.KeyMsg{Type: tea.KeyTab})
-	if f := m.(initModel).focus; f != fNode {
-		t.Errorf("focus %d, want the node toggle %d", f, fNode)
+	m = toNext(m)
+	if !m.(initModel).plan || in.mirrorURL != "http://10.0.0.150:8082" || !in.noMirror {
+		t.Errorf("mirror %q noMirror %v: %s", in.mirrorURL, in.noMirror, m.(initModel).choices.err)
 	}
 }

internal/cli/tui_mirror.go

@@ -12,6 +12,7 @@ import (
 	tea "github.com/charmbracelet/bubbletea"
 
 	"gitea.mynodes.xyz/ilker/llmgw/internal/config"
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/catalog"
 	"gitea.mynodes.xyz/ilker/llmgw/internal/mirror"
 )
 
@@ -253,19 +254,42 @@ func (m consoleModel) mirrorPanel(pw int) (string, string, string) {
 	return "Mirror", head + table([]string{"MODEL", "VERSION", "FILE", "STATE", "SIZE", "USED BY"}, rows, m.row, pw, m.inPanel), keys
 }
 
-// addModelForm adds a model from a definition file on this machine: the
-// same YAML a model takes in server.yaml.
+// fromFile is the add-model choice that reads a definition file rather
+// than naming a preset.
+const fromFile = "from a file"
+
+// addModelForm adds a model that comes with llmgw, or one from a definition
+// file on this machine: the same YAML a model takes in server.yaml.
 func (m *consoleModel) addModelForm() {
 	server := "--server=" + m.client.base
+	var note strings.Builder
+	note.WriteString("A model that comes with llmgw, tried and with its licence:\n")
+	for _, p := range catalog.Presets() {
+		fmt.Fprintf(&note, "  %s: %s, %s, %s\n", p.Model.Name, p.Makes, presetCard(p.Model), presetLicence(p.Model))
+	}
+	note.WriteString("A ComfyUI one has the nodes install ComfyUI if the cluster has none.\n" +
+		"Or a definition file: the YAML a model takes in server.yaml's models.")
+	var choices []string
+	for _, n := range catalog.PresetNames() {
+		choices = append(choices, presetChoice(m.data.presets, n))
+	}
 	m.openForm(&formDialog{title: "Add a model",
-		note: "From a definition file on this machine: the YAML a model takes in\nserver.yaml's models. Serve a model, under Do, needs none.",
+		note: note.String(),
 		fields: []formField{
-			textF("file", "", "like /root/qwen.yaml"),
+			choiceF("model", append(choices, fromFile), choices[0]),
+			textF("file", "", "for "+fromFile+": like /root/qwen.yaml"),
 		},
 		submit: func(m *consoleModel, v []string) (tea.Cmd, error) {
-			if _, err := os.Stat(v[0]); err != nil {
+			if v[0] != fromFile {
+				// The name, without what the choice says beside it.
+				return m.addPreset(strings.Fields(v[0])[0]), nil
+			}
+			if v[1] == "" {
+				return nil, fmt.Errorf("a file, or a model that comes with llmgw")
+			}
+			if _, err := os.Stat(v[1]); err != nil {
 				return nil, err
 			}
-			return m.runCLI("Add a model", "ctl", server, "model", "add", "-f", v[0]), nil
+			return m.runCLI("Add a model", "ctl", server, "model", "add", "-f", v[1]), nil
 		}})
 }

internal/cli/tui_presets.go

@@ -0,0 +1,128 @@
+package cli
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/url"
+	"strings"
+
+	tea "github.com/charmbracelet/bubbletea"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+)
+
+// presetsBlock is the models that come with llmgw, under the models table:
+// whether each fits a card here and whether it is in the catalog, and
+// whether the leader adds them by itself. Empty from a control plane that
+// cannot say.
+func presetsBlock(v *adminapi.PresetsView, width int) string {
+	if v == nil || len(v.Presets) == 0 {
+		return ""
+	}
+	var rows [][]string
+	var why []string
+	for _, p := range v.Presets {
+		rows = append(rows, []string{p.Name, p.Makes, orDash(strings.Join(p.FitsClasses, ",")), presetState(p)})
+		// Why the leader leaves it, under the table: a reason is longer than
+		// any column the panel has room for. Automatic adding being off is
+		// said once, below.
+		if p.Blocked != "" && !strings.HasPrefix(p.Blocked, "presets.auto") && !p.Declined {
+			why = append(why, "  "+wrap(p.Name+": "+p.Blocked, width-4, "    "))
+		}
+	}
+	auto := "Added by themselves where a card fits · P stops that"
+	if !v.Auto {
+		auto = "Not added by themselves · P starts that · A adds one"
+	}
+	out := "\n\n  Pictures and 3D models that come with llmgw\n" +
+		table([]string{"PRESET", "MAKES", "FITS", "HERE"}, rows, -1, width, false)
+	if len(why) > 0 {
+		out += "\n" + sDim.Render(strings.Join(why, "\n"))
+	}
+	return out + "\n  " + sDim.Render(auto)
+}
+
+// presetChoice is how a preset is offered in the add dialog: its name, and
+// where it stands when that is worth knowing before choosing it.
+func presetChoice(v *adminapi.PresetsView, name string) string {
+	if v == nil {
+		return name
+	}
+	for _, p := range v.Presets {
+		if p.Name != name {
+			continue
+		}
+		switch {
+		case p.InCatalog:
+			return name + " (already here)"
+		case presetAddsComfyUI(v, p):
+			return name + " (installs ComfyUI too)"
+		case !p.Fits:
+			return name + " (no card here fits it)"
+		case p.Declined:
+			return name + " (removed before)"
+		}
+	}
+	return name
+}
+
+// presetAddsComfyUI is whether adding a preset by hand also sets
+// engines.comfyui, which has the GPU nodes install it and the control planes
+// restart on the setting.
+func presetAddsComfyUI(v *adminapi.PresetsView, p adminapi.PresetView) bool {
+	return v != nil && !p.InCatalog && v.ComfyUI == ""
+}
+
+// addPreset adds a preset through the control plane, or, from one from
+// before it could, the way the release that brought presets did. One whose
+// adding installs ComfyUI and restarts the control planes is asked about
+// first.
+func (m *consoleModel) addPreset(name string) tea.Cmd {
+	if m.data.presets != nil {
+		for _, p := range m.data.presets.Presets {
+			if p.Name == name && presetAddsComfyUI(m.data.presets, p) {
+				m.confirmD = &confirmDialog{title: "Add " + name + " and ComfyUI",
+					text: "The cluster installs no ComfyUI yet. Adding " + name + " sets engines.comfyui:\n" +
+						"every GPU node installs it, about 10 GB each, and the control planes restart\n" +
+						"on the setting, standbys first. Engines keep serving.",
+					yes: func(m *consoleModel) tea.Cmd { return m.postPreset(name) }}
+				return nil
+			}
+		}
+	}
+	return m.postPreset(name)
+}
+
+func (m *consoleModel) postPreset(name string) tea.Cmd {
+	if m.data.presets == nil {
+		return m.runCLI("Add "+name, "ctl", "--server="+m.client.base, "model", "add", name)
+	}
+	return m.call("Add "+name, http.MethodPost, "/api/v1/presets/"+url.PathEscape(name), map[string]string{},
+		func(_ json.RawMessage) string {
+			return name + " is added, and ComfyUI with it where the cluster had none.\n" +
+				"It is placed on the next pass, and loads when first asked for."
+		})
+}
+
+// autoPresetsConfirm turns the adding of presets by themselves on or off,
+// after saying what that does.
+func (m *consoleModel) autoPresetsConfirm() {
+	on := !m.data.presets.Auto
+	title, text := "Stop adding pictures and 3D models by themselves",
+		"Presets already added stay. A preset is added only when somebody adds it."
+	if on {
+		title, text = "Add pictures and 3D models by themselves",
+			"Where a card fits one and the catalog has nothing that makes what it makes, the leader adds it.\n"+
+				"That also has every GPU node install ComfyUI, about 10 GB each, and the mirror fetch its weights.\n"+
+				"A preset somebody removed is not added again."
+	}
+	m.confirmD = &confirmDialog{title: title, text: text, yes: func(m *consoleModel) tea.Cmd {
+		return m.call(title, http.MethodPut, "/api/v1/presets/auto", adminapi.PresetsAutoRequest{On: on},
+			func(_ json.RawMessage) string {
+				if on {
+					return "Presets are added by themselves where a card fits."
+				}
+				return "Presets are no longer added by themselves."
+			})
+	}}
+}

internal/cli/tui_presets_test.go

@@ -0,0 +1,63 @@
+package cli
+
+import (
+	"strings"
+	"testing"
+
+	tea "github.com/charmbracelet/bubbletea"
+
+	"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
+)
+
+func presetsHere() *adminapi.PresetsView {
+	return &adminapi.PresetsView{Auto: true, Presets: []adminapi.PresetView{
+		{Name: "flux-schnell", Makes: "pictures", Card: "cc 7.0+, 24 GB+", Fits: true, FitsClasses: []string{"v100-32g"},
+			Blocked: "the cluster installs no ComfyUI (engines.comfyui); adding it by hand sets that"},
+		{Name: "triposr", Makes: "meshes", Card: "cc 7.0+, 8 GB+", Fits: true, InCatalog: true, AddedBy: "auto"},
+	}}
+}
+
+func TestThePresetsAreOnTheModelsScreen(t *testing.T) {
+	m, _ := consoleWith(t, cModels)
+	m.data.presets = presetsHere()
+	v := m.View()
+	for _, want := range []string{"Pictures and 3D models that come with llmgw", "flux-schnell", "v100-32g",
+		"installs no ComfyUI", "added by itself", "P pictures and 3D"} {
+		if !strings.Contains(v, want) {
+			t.Errorf("%q not shown:\n%s", want, v)
+		}
+	}
+	// A control plane that cannot say shows none of it.
+	m.data.presets = nil
+	if v := m.View(); strings.Contains(v, "come with llmgw") || strings.Contains(v, "P pictures") {
+		t.Errorf("presets shown from nothing:\n%s", v)
+	}
+}
+
+func TestAPresetThatInstallsComfyUIIsAddedOnlyWhenConfirmed(t *testing.T) {
+	m, s := consoleWith(t, cModels)
+	m.data.presets = presetsHere()
+	var tm tea.Model = m
+	tm = press(tm, "a")
+	f := tm.(consoleModel).formD
+	if f == nil || !strings.Contains(f.fields[0].value(), "installs ComfyUI too") {
+		t.Fatalf("no add dialog saying what flux-schnell brings: %+v", f)
+	}
+	tm = press(tm, "enter", "enter", "enter")
+	if tm.(consoleModel).confirmD == nil || s.last() != "" {
+		t.Fatalf("added without asking: %q", s.last())
+	}
+	tm = pressRun(tm, "y")
+	if got := s.last(); got != "POST /api/v1/presets/flux-schnell {}" {
+		t.Fatalf("sent %q", got)
+	}
+
+	tm = press(tm, "esc", "p") // past what the add said
+	if c := tm.(consoleModel).confirmD; c == nil || !strings.HasPrefix(c.title, "Stop adding") {
+		t.Fatalf("P did not ask to stop: %+v", c)
+	}
+	_ = pressRun(tm, "y")
+	if got := s.last(); got != `PUT /api/v1/presets/auto {"on":false}` {
+		t.Fatalf("sent %q", got)
+	}
+}

internal/cli/tui_setup.go

@@ -5,7 +5,6 @@ import (
 	"fmt"
 	"io"
 	"net"
-	"net/mail"
 	"os"
 	"strings"
 	"sync"
@@ -35,7 +34,8 @@ type setupPage int
 
 const (
 	pWelcome setupPage = iota
-	pAdmin
+	// pChoices is what is installed, part by part, each with its settings.
+	pChoices
 	pMachines
 	// pWait shows the codes for machines joining rather than logged into,
 	// until they have all dialled in.
@@ -112,6 +112,10 @@ func newDBMachine(n int) dbMachine {
 	if os.Getenv("SSH_AUTH_SOCK") == "" {
 		m.auth = authKey
 	}
+	// As choosing the way to log in sets them: a key file's path is not a
+	// secret to hide.
+	m.secret.Mask = m.auth == authPassword
+	m.secret.Placeholder = map[int]string{authKey: "/root/.ssh/id_ed25519", authPassword: "the user's ssh password"}[m.auth]
 	return m
 }
 
@@ -150,8 +154,7 @@ type setupModel struct {
 	ips    []string
 	choice int // 0 one machine, 1 high availability
 
-	admin, names textField
-	afocus       int // admin, names, next
+	choices *installForm
 
 	db     [2]dbMachine
 	mfocus int // over both machines' fields, then the check button
@@ -180,12 +183,15 @@ type setupModel struct {
 }
 
 func newSetupModel(host string, ips []string) setupModel {
-	admin := newTextField()
-	admin.Placeholder, admin.CharLimit, admin.Width = "you@example.com", 200, 40
-	names := newTextField()
-	names.Placeholder, names.CharLimit, names.Width = "llm.example.com, 203.0.113.10", 400, 40
+	in := newDefaultServerInit()
+	// The control plane of a replicated setup is not where models run;
+	// nodes are added once it is up. Either can still be chosen.
+	in.noNode, in.noModel = true, true
+	in.standbys = true
+	// Two judges, on two of the three machines' nodes.
+	in.judge.Replicas = 2
 	return setupModel{
-		ref: &progRef{}, host: host, ips: ips, admin: admin, names: names,
+		ref: &progRef{}, host: host, ips: ips, in: &in, choices: newInstallForm(&in, host, ips, true),
 		db: [2]dbMachine{newDBMachine(1), newDBMachine(2)}, spin: newSpinner(), width: 100, height: 30,
 		log: &[]string{}, logMu: &sync.Mutex{},
 	}
@@ -204,6 +210,7 @@ func (m setupModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 	switch msg := msg.(type) {
 	case tea.WindowSizeMsg:
 		m.width, m.height = msg.Width, msg.Height
+		m.choices.height = msg.Height
 		m.run.width = msg.Width - navWidth - 6
 	case spinTickMsg:
 		var cmd tea.Cmd
@@ -241,6 +248,11 @@ func (m setupModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 }
 
 func (m setupModel) key(k tea.KeyMsg) (tea.Model, tea.Cmd) {
+	// The choices' own dialogs take their keys, Esc among them.
+	if m.page == pChoices && (m.choices.dialog != nil || m.choices.err != "") {
+		m.choices.key(k, m.in)
+		return m, nil
+	}
 	// A dialog open takes the next key, whatever it is, to close it.
 	if m.formErr != "" {
 		m.formErr = ""
@@ -272,12 +284,13 @@ func (m setupModel) key(k tea.KeyMsg) (tea.Model, tea.Cmd) {
 				m.single = true
 				return m, tea.Quit
 			}
-			m.page = pAdmin
-			m.afocus = 0
-			m.admin.Focus()
+			m.page = pChoices
+		}
+	case pChoices:
+		if m.choices.key(k, m.in) {
+			m.page, m.mfocus = pMachines, 0
+			m.focusMachine()
 		}
-	case pAdmin:
-		return m.adminKey(k)
 	case pMachines:
 		return m.machinesKey(k)
 	case pCheck:
@@ -306,51 +319,6 @@ func (m setupModel) key(k tea.KeyMsg) (tea.Model, tea.Cmd) {
 	return m, nil
 }
 
-func (m setupModel) adminKey(k tea.KeyMsg) (tea.Model, tea.Cmd) {
-	move := func(d int) {
-		m.afocus = (m.afocus + d + 3) % 3
-		m.admin.Blur()
-		m.names.Blur()
-		switch m.afocus {
-		case 0:
-			m.admin.Focus()
-		case 1:
-			m.names.Focus()
-		}
-	}
-	switch k.Type {
-	case tea.KeyTab, tea.KeyDown:
-		move(1)
-		return m, nil
-	case tea.KeyShiftTab, tea.KeyUp:
-		move(-1)
-		return m, nil
-	case tea.KeyEnter:
-		if m.afocus < 2 {
-			move(1)
-			return m, nil
-		}
-		if _, err := mail.ParseAddress(strings.TrimSpace(m.admin.Value())); err != nil {
-			m.formErr = "the administrator's email is needed, and that is not one"
-			m.afocus = 0
-			move(0)
-			return m, nil
-		}
-		m.formErr = ""
-		m.page, m.mfocus = pMachines, 0
-		m.db[0].addr.Focus()
-		return m, nil
-	}
-	var cmd tea.Cmd
-	switch m.afocus {
-	case 0:
-		m.admin, cmd = m.admin.Update(k)
-	case 1:
-		m.names, cmd = m.names.Update(k)
-	}
-	return m, cmd
-}
-
 func (m *setupModel) focusMachine() {
 	for i := range m.db {
 		for f := 0; f < mfCount; f++ {
@@ -509,7 +477,7 @@ func (m *setupModel) startCheck() tea.Cmd {
 		if d.auth == authJoin {
 			m.conns = append(m.conns, dbConn{remote: d.joined, addr: d.joined.Addr, joined: d.joined})
 			machines = append(machines, preflight.Machine{Name: d.joined.Hostname + " (" + d.joined.Addr + ", joined)",
-				Addr: d.joined.Addr, Roles: []preflight.Role{preflight.RoleDatabase}, Remote: d.joined})
+				Addr: d.joined.Addr, Roles: m.dbRoles(), Remote: d.joined})
 			continue
 		}
 		g := &onboard.GoSSH{
@@ -524,7 +492,7 @@ func (m *setupModel) startCheck() tea.Cmd {
 		}
 		m.conns = append(m.conns, dbConn{remote: g, addr: g.Addr, ssh: g})
 		machines = append(machines, preflight.Machine{Name: g.Addr, Addr: g.Addr,
-			Roles: []preflight.Role{preflight.RoleDatabase}, Remote: g})
+			Roles: m.dbRoles(), Remote: g})
 	}
 	m.checking = true
 	m.report = preflight.Report{}
@@ -555,6 +523,15 @@ func (m *setupModel) startCheck() tea.Cmd {
 	}
 }
 
+// dbRoles are what the other two machines are to be: the store, and a
+// control plane too when they stand by.
+func (m setupModel) dbRoles() []preflight.Role {
+	if m.in.standbys {
+		return []preflight.Role{preflight.RoleDatabase, preflight.RoleControl}
+	}
+	return []preflight.Role{preflight.RoleDatabase}
+}
+
 // targets are the database machines as user@address, for the command line.
 func (m setupModel) targets() []string {
 	var out []string
@@ -568,43 +545,20 @@ func (m setupModel) targets() []string {
 	return out
 }
 
-func (m setupModel) namesList() []string {
-	var out []string
-	for _, h := range strings.Split(m.names.Value(), ",") {
-		if h = strings.TrimSpace(h); h != "" {
-			out = append(out, h)
-		}
-	}
-	return out
-}
-
 // command is what this setup is on the command line, for doing it again
 // from a script — with keys in place, since a password cannot be given there.
 func (m setupModel) command() string {
-	parts := []string{"sudo --preserve-env=SSH_AUTH_SOCK llmgw server init",
-		"--admin " + strings.TrimSpace(m.admin.Value())}
-	for _, h := range m.namesList() {
-		parts = append(parts, "--host "+h)
-	}
-	for _, t := range m.targets() {
-		parts = append(parts, "--patroni "+t)
-	}
-	parts = append(parts, "--no-node", "--no-model")
-	return strings.Join(parts, " \\\n    ")
+	in := *m.in
+	in.patroni = m.targets()
+	return strings.Join(append([]string{"sudo --preserve-env=SSH_AUTH_SOCK llmgw server init"}, in.initFlags()...), " \\\n    ")
 }
 
 // startRun installs: sudo granted where it asks for a password, the control
 // plane here, the store on the other two, then sudo taken back.
 func (m *setupModel) startRun() tea.Cmd {
-	in := newDefaultServerInit()
-	in.admin = strings.TrimSpace(m.admin.Value())
-	in.hosts = m.namesList()
+	in := m.in
 	in.patroni = m.targets()
-	// The control plane of a replicated setup is not where models run;
-	// nodes are added once it is up.
-	in.noNode, in.noModel = true, true
-	m.in = &in
-	m.run = newInitModel(&in, nil, false)
+	m.run = newInitModel(in, nil, false)
 	m.run.running, m.run.width, m.run.spin = true, m.width, m.spin
 	ref, conns, logp, mu, listener := m.ref, m.conns, m.log, m.logMu, m.listener
 	return func() tea.Msg {
@@ -659,7 +613,7 @@ var setupSteps = []struct {
 	label string
 	page  setupPage
 }{
-	{"Start", pWelcome}, {"Administrator", pAdmin}, {"Machines", pMachines},
+	{"Start", pWelcome}, {"Choices", pChoices}, {"Machines", pMachines},
 	{"Checks", pCheck}, {"Plan", pPlan}, {"Install", pRun},
 }
 
@@ -692,6 +646,9 @@ func (m setupModel) View() string {
 	if m.formErr != "" {
 		f.DialogTitle, f.Dialog = "Not yet", m.formErr+"\n\n"+sDim.Render("any key to go back")
 	}
+	if m.page == pChoices {
+		f.DialogTitle, f.Dialog = m.choices.overlay()
+	}
 	return f.render()
 }
 
@@ -700,8 +657,12 @@ func (m setupModel) pageView() (string, string, string) {
 	switch m.page {
 	case pWelcome:
 		return "Start", m.welcomeView(), "↑↓ choose · Enter go on · Ctrl+C leave"
-	case pAdmin:
-		return "Administrator", m.adminView(), "Tab/↑↓ move · Enter next · Esc back · Ctrl+C leave"
+	case pChoices:
+		keys := m.choices.keys()
+		if m.choices.dialog == nil && m.choices.err == "" {
+			keys = strings.Replace(keys, " · Ctrl+C", " · Esc back · Ctrl+C", 1)
+		}
+		return "What to install", m.choices.view(m.width - navWidth - 6), keys
 	case pMachines:
 		return "Database machines", m.machinesView(), "Tab/↑↓ move · ←→ how to log in · Enter next · Esc back · PgUp/PgDn scroll"
 	case pWait:
@@ -742,24 +703,8 @@ func (m setupModel) welcomeView() string {
 	}
 	opt(0, "One machine", "This machine runs everything: control plane, model mirror,\n      and models if it has room.")
 	opt(1, "High availability — three machines",
-		"This one is the control plane; two more keep the store, replicated,\n      so losing any one machine loses nothing.")
-	return b.String()
-}
-
-func (m setupModel) adminView() string {
-	var b strings.Builder
-	label := func(i int, s string) string {
-		if m.afocus == i {
-			return fSelected.Render("› " + s)
-		}
-		return "  " + s
-	}
-	b.WriteString("\n")
-	fmt.Fprintf(&b, "%s\n    %s\n    %s\n\n", label(0, "Administrator's email"), m.admin.View(),
-		sDim.Render("A password is generated and shown once, at the end."))
-	fmt.Fprintf(&b, "%s\n    %s\n    %s\n\n", label(1, "Other names nodes will reach this machine by"), m.names.View(),
-		sDim.Render("Known: "+strings.Join(append([]string{m.host}, m.ips...), ", ")+". Add a DNS name or a floating address."))
-	b.WriteString(button(m.afocus == 2, "Next") + "\n")
+		"Each of the three can run the gateway; two keep the store, replicated,\n"+
+			"      and etcd votes on all three, so losing any one machine loses nothing.")
 	return b.String()
 }
 
@@ -876,17 +821,25 @@ func (m setupModel) checkView() string {
 
 func (m setupModel) planView() string {
 	var b strings.Builder
-	b.WriteString("\n  What will be installed:\n\n")
-	fmt.Fprintf(&b, "  %s  %s\n      %s\n", lipgloss.NewStyle().Bold(true).Render(m.host), sDim.Render(m.thisAddr()),
-		"control plane and gateway, model mirror, etcd (the third vote)")
-	fmt.Fprintf(&b, "      administrator %s\n", strings.TrimSpace(m.admin.Value()))
+	b.WriteString(m.choices.planView(m.width - navWidth - 6))
+	b.WriteString("\n  " + lipgloss.NewStyle().Bold(true).Render("The three machines") + "\n")
+	here := "control plane, leading at first; model mirror; etcd"
+	there := "PostgreSQL under Patroni, etcd"
+	if m.in.standbys {
+		there = "control plane, standing by; " + there
+	}
+	if m.in.vip != "" {
+		here += "; keepalived"
+		there += "; keepalived"
+	}
+	fmt.Fprintf(&b, "  %s  %s\n      %s\n", lipgloss.NewStyle().Bold(true).Render(m.host), sDim.Render(m.thisAddr()), here)
 	granted := false
 	for _, d := range m.db {
 		addr := strings.TrimSpace(d.addr.Value())
 		if d.joined != nil {
 			addr = d.joined.Hostname + "  " + sDim.Render(d.joined.Addr+", joined")
 		}
-		fmt.Fprintf(&b, "  %s\n      PostgreSQL under Patroni, etcd\n", lipgloss.NewStyle().Bold(true).Render(addr))
+		fmt.Fprintf(&b, "  %s\n      %s\n", lipgloss.NewStyle().Bold(true).Render(addr), there)
 		granted = granted || d.sudo.Value() != ""
 	}
 	b.WriteString("\n  The store is replicated from the first to the second; if the primary is lost\n" +

internal/cli/tui_setup_test.go

@@ -26,6 +26,12 @@ func press(m tea.Model, keys ...string) tea.Model {
 			msg = tea.KeyMsg{Type: tea.KeyTab}
 		case "down":
 			msg = tea.KeyMsg{Type: tea.KeyDown}
+		case "up":
+			msg = tea.KeyMsg{Type: tea.KeyUp}
+		case "space":
+			msg = tea.KeyMsg{Type: tea.KeySpace, Runes: []rune(" ")}
+		case "left":
+			msg = tea.KeyMsg{Type: tea.KeyLeft}
 		case "esc":
 			msg = tea.KeyMsg{Type: tea.KeyEsc}
 		case "right":
@@ -41,20 +47,28 @@ func press(m tea.Model, keys ...string) tea.Model {
 func TestTheSetupAsksForWhatHighAvailabilityNeedsAndRefusesWhatWillNotDo(t *testing.T) {
 	m := tea.Model(newSetupModel("ctl", []string{"10.0.0.5"}))
 	m = press(m, "down", "enter")
-	if s := m.(setupModel); s.page != pAdmin {
-		t.Fatalf("high availability did not lead to the administrator: page %d", s.page)
+	if s := m.(setupModel); s.page != pChoices {
+		t.Fatalf("high availability did not lead to the choices: page %d", s.page)
+	}
+	// Three machines, each a control plane, unless told otherwise.
+	if v := m.View(); !strings.Contains(v, "Control plane on all three") || !strings.Contains(v, "two standbys") {
+		t.Errorf("the standbys are not offered, ticked:\n%s", v)
 	}
 	// No email: refused, with a reason.
-	m = press(m, "tab", "tab", "enter")
-	if s := m.(setupModel); s.page != pAdmin || !strings.Contains(s.formErr, "email") {
-		t.Fatalf("went on without an administrator: %+v", s.formErr)
+	m = press(m, "up", "enter")
+	if s := m.(setupModel); s.page != pChoices || !strings.Contains(s.choices.err, "email") {
+		t.Fatalf("went on without an administrator: %+v", s.choices.err)
 	}
-	// The refusal is a dialog; a key closes it, and the cursor is back on
-	// the email.
+	// The refusal is a dialog; a key closes it, and the control plane's
+	// settings open with the cursor on the email.
 	if !strings.Contains(m.View(), "Not yet") {
 		t.Error("the refusal was not shown as a dialog")
 	}
-	m = press(m, "x", "a@example.com", "tab", "tab", "enter")
+	m = press(m, "q")
+	if s := m.(setupModel); s.choices.dialog == nil || s.choices.dialog.Fields[s.choices.dialog.focus] != s.choices.admin {
+		t.Fatal("the email was not given the cursor")
+	}
+	m = press(m, "a@example.com", "esc", "enter")
 	s := m.(setupModel)
 	if s.page != pMachines {
 		t.Fatalf("page %d: %s", s.page, s.formErr)
@@ -78,7 +92,7 @@ func TestTheSetupAsksForWhatHighAvailabilityNeedsAndRefusesWhatWillNotDo(t *test
 		t.Errorf("a valid pair refused: %s", err)
 	}
 	cmd := s.command()
-	for _, want := range []string{"--admin a@example.com", "--patroni ubuntu@10.0.0.6", "--patroni ubuntu@10.0.0.7", "--no-node"} {
+	for _, want := range []string{"--admin a@example.com", "--patroni ubuntu@10.0.0.6", "--patroni ubuntu@10.0.0.7", "--no-node", "--standbys"} {
 		if !strings.Contains(cmd, want) {
 			t.Errorf("command lacks %q:\n%s", want, cmd)
 		}