docs(local-model): the install guide, the API and the rules

docs/local-models.md is the guide: the steps, the layout on disk, what is
written outside the folder, the failures and their next steps. The API
reference documents the install object and the five verbs, and how the list
is ordered. The rules for the server side are in CLAUDE.md and
architecture-invariants.md, the user-facing pages in the wiki.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Codeman maintainer committed 2026-11-06 22:16:38 +01:00
1 parent 84d5c691ff
commit 7238ced571
8 files changed
+475 -38

No files matched your search

+18 -11
View File
@@ -86,18 +86,25 @@ covered like any other stable behavior. Other agent commands and API routes keep
their existing guarantees. Promotion to stable requires an explicit documented
decision.
### Experimental local model recommendation
### Experimental local model routes
`GET /api/v1/local-model` (and its `/api` alias) is labeled experimental, so item 3
above applies to it: its path, its payload (the hardware facts, the verdicts and
reasons, the candidate fields and the English sentences in `headline` and
`notes`) and its behavior may change or be removed in a MINOR or PATCH release.
It is read-only today: it looks at the Mac the server runs on and says which
local model fits. The step that sets a model up from Codeman is not built yet
and will change what the route reports, which is why the shape is not promised.
It is not behind a setting (it writes nothing and adds no settings key); it is
admin only in multi-user mode. Promotion to stable requires an explicit
documented decision.
`GET /api/v1/local-model`, `POST /api/v1/local-model/install`, `/cancel`, `/resume`
and `/runtime`, and `DELETE /api/v1/local-model` (and their `/api` aliases) are
labeled experimental, so item 3 above applies to them: their paths, their payloads
(the hardware facts, the verdicts and reasons, the candidate fields, the `install`
object with its states, steps, error codes and actions, the 409 conflict shape and
every English sentence) and their behavior may change or be removed in a MINOR or
PATCH release. They look at the Mac the server runs on, say which local model fits,
and install, start, stop and remove one ([local-models.md](local-models.md)).
They are not behind a setting. Reading changes nothing; an install starts only on an
explicit request that carries the size the person confirmed. All of them are admin
only in multi-user mode. What an install leaves behind is ordinary, stable state: one
saved model endpoint with the id `local-ollama` and the `customModelEndpointsEnabled`
setting switched on, both of which the stable custom model endpoint routes read like
any other endpoint. On-disk state (`local-model.json`, the `local-model/` folder) is
internal, as for every other file in the data directory. Promotion to stable requires
an explicit documented decision.
## Deprecation policy