4 Pointing pi at a local model
You can register an LM Studio model with pi through ~/.pi/agent/models.json, list it, and understand the compatibility flags that local OpenAI-compatible servers need.
4.1 The idea
pi already knows how to speak the OpenAI Chat Completions protocol, and LM Studio serves that protocol at http://localhost:1234/v1. So “use a local model instead of Claude” is really just: define a provider in models.json that points pi at that local URL (uniform resource locator).
4.2 Minimal configuration
Create ~/.pi/agent/models.json:
{
"providers": {
"lmstudio": {
"baseUrl": "http://localhost:1234/v1",
"api": "openai-completions",
"apiKey": "lmstudio",
"compat": { "supportsDeveloperRole": false, "supportsReasoningEffort": false },
"models": [
{ "id": "qwen3-coder-30b-a3b-instruct", "reasoning": false },
{ "id": "openai/gpt-oss-20b", "reasoning": true }
]
}
}
}Field by field:
baseUrl: LM Studio’s OpenAI-compatible endpoint. Always/v1.api: "openai-completions": the protocol pi speaks to this provider.apiKey: "lmstudio": required by pi, but LM Studio ignores its value. Any non-empty string works.compat: local servers do not implement every OpenAI extension. For reasoning models such asgpt-oss, setsupportsDeveloperRole: false(pi then sends the system prompt as asystemmessage rather than the newerdeveloperrole) andsupportsReasoningEffort: false. These can sit at the provider level (all models) or per model.models[].id: must match the identifier the server advertises exactly (lms ps, orcurl http://localhost:1234/v1/models).reasoning:truefor models that “think” (e.g.gpt-oss);falseotherwise.
For local models that is genuinely all you need: name, contextWindow, maxTokens, and cost are optional and default sensibly (cost defaults to zero, which is correct for a model running on your own hardware). A fuller entry looks like:
{
"id": "openai/gpt-oss-20b",
"name": "GPT-OSS 20B (LM Studio, local)",
"reasoning": true,
"input": ["text"],
"contextWindow": 131072,
"maxTokens": 32000,
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
}The contextWindow you declare here only tells pi when to compact the conversation. The actual served context is the window the model was loaded with in LM Studio (default 8192; see Section 2.3). If you declare 131072 but leave the model loaded at 8192, long sessions still truncate. Reload the model with a larger context to match.
4.3 Adding the MLX provider
The same providers map holds one block per backend (Chapter 2). Add mlx next to lmstudio; both speak openai-completions and want the same compat flags. models.json is re-read whenever you open /model, so no restart is needed.
{
"providers": {
"lmstudio": { "...": "as above" },
"mlx": {
"baseUrl": "http://localhost:8080/v1",
"api": "openai-completions",
"apiKey": "mlx",
"compat": { "supportsDeveloperRole": false, "supportsReasoningEffort": false },
"models": [
{ "id": "mlx-community/Qwen2.5-Coder-7B-Instruct-4bit", "reasoning": false }
]
}
}
}Each id must match what the server advertises: for mlx it is the Hugging Face repo (curl http://localhost:8080/v1/models); for lmstudio it is the loaded model’s identifier (lms ps). Launch against either provider:
pi --provider lmstudio --model 'qwen3-coder-30b-a3b-instruct' # MLX, tool-calling
pi --offline --list-models mlx # what mlx servesmlx provider is for generation, not pi’s tools
mlx_lm.server does not return structured tool_calls (Section 2.2), so a run with --provider mlx will not execute pi’s tools, so keep it for plain generation. For pi’s agent loop, use the lmstudio provider. See Chapter 8.
4.4 Confirm pi sees the model
models.json is re-read every time you open /model, so no restart is needed. List your provider’s models:
pi --offline --list-models lmstudioprovider model context max-out thinking images
lmstudio qwen3-coder-30b-a3b-instruct 131.1K 32K no no
lmstudio openai/gpt-oss-20b 131.1K 32K yes no
--offline skips pi’s startup network calls, appropriate when you are only using local models.
4.5 Choosing and switching models
- At launch:
--provider lmstudio --model 'qwen3-coder-30b-a3b-instruct'. - Mid-session in the terminal user interface (TUI): type
/model(orCtrl+Pto cycle a shortlist). - The
--modelflag accepts patterns andprovider/idform, e.g.--model lmstudio/qwen3-coder-30b-a3b-instruct.
Favor models with genuine tool-calling support (the qwen3-coder, gpt-oss, and llama3.3 families all work). Pick the size your random-access memory (RAM) and patience allow: a 13 GB model is snappy; a 40+ GB model is capable but slower to load. Gemma-family models currently lack tool-calling templates and will not drive pi’s agent loop. See Chapter 8.
- Add a third model you have downloaded (
lms ls) tomodels.jsonand confirm it appears inpi --list-models lmstudio. - Remove the
compatblock, re-run agpt-ossprompt, and observe what breaks. Then put it back. - Set a deliberately tiny
contextWindow(e.g. 2048) and watch when pi decides to compact during a longer task.
Add a new entry to the
lmstudioprovider’smodelsarray whoseidmatches the identifier fromlms lsexactly, then list the provider again (no restart needed, sincemodels.jsonis re-read whenever you open/model):{ "id": "qwen2.5-coder-7b-instruct", "reasoning": false }pi --offline --list-models lmstudioThe new model appears as a row in the table alongside the existing ones.
Removing
compatdropssupportsDeveloperRole: falseandsupportsReasoningEffort: false. pi then sends the system prompt with the newerdeveloperrole and may pass a reasoning-effort parameter, which local OpenAI-compatible endpoints such as LM Studio’s do not implement. The result is errors or degraded behaviour for thegpt-ossreasoning model. Restoring thecompatblock fixes it.With
contextWindowset to 2048, pi treats the conversation budget as tiny and decides to compact (summarize earlier turns) very early in a longer task, sincecontextWindowis pi’s own bookkeeping for when to compact, not the served limit. Note the served context is still governed by the window the model was loaded with in LM Studio, so a too-small value there causes truncation independently of this setting.