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

+19 -13
View File
@@ -193,19 +193,25 @@ attached.
section to the Run dropdown, for pointing a harness at your own OpenAI-compatible server
instead of its native cloud backend. See [Custom Model Endpoints](Custom-Model-Endpoints).
**Model on this Mac** is not a setting: it is a read-only answer. When the Codeman server
runs on a Mac with Apple silicon, it shows that Mac's chip, memory and free disk space, the
local coding model that fits it best with the agent CLI to run it, what the model needs of
the memory the Mac can give one, its download size and an estimated speed, and the other
models that fit (Good or Tight for the memory, Slow or Speed unknown for the speed). A Mac
that can only run a model under 12 billion parameters is told so in plain words, and a Mac
with too little memory, too little free disk space or an Intel processor is told why nothing
is offered. The numbers are estimates from a catalogue that ships with each release; nothing
has been tested on your Mac. **Nothing is downloaded or installed from here yet**: setting
the model up from Codeman is the next step and is not built. The same answer appears as a
card on the welcome screen, which you can hide per device (it stays here). The group is not
shown when the server runs on Linux or Windows, and in multi-user mode only an admin sees
it. The "Mac" is always the machine the server runs on, not the device you are reading on.
**Model on this Mac** is not a setting: it is the state of a model Codeman can run for you
on the Mac the server runs on, with a button that opens the local model window. The same
window opens from the **Run a local model** button on the welcome screen. It shows that
Mac's chip, memory and free disk space, a bar for how much of the memory the selected model
takes, and the models that fit, each with one tag (Best fit, Tight, Slow, Small model, or
"Tested on a Mac like this"), a speed and a download size. **Install on this Mac** asks you
to confirm the sizes once, then downloads a model runtime and the model into
`~/.codeman/local-model`, checks that the model loads and can call a tool, installs the
coding agent if it is missing, and ends on **Start a session**. No account, no API key and
no administrator password. You can close the window while it downloads, cancel and continue
later; after a Codeman restart an unfinished install waits for you to press Continue. Once a
model is installed the window offers Start a session, Stop or Start, and Remove. Installing
switches **Custom model endpoints** on and saves one endpoint named "This Mac"; Remove takes
the endpoint away again and switches the setting back off if nothing else uses it. A Mac
that can only run a small model is told so in plain words, and a Mac with too little memory,
too little free disk space or an Intel processor is told why nothing is offered. The group
is not shown when the server runs on Linux or Windows, and in multi-user mode only an admin
sees it. The "Mac" is always the machine the server runs on, not the device you are reading
on. Details: [Custom Model Endpoints](Custom-Model-Endpoints#a-model-that-runs-on-this-mac).
### Agents & CLIs