Run Pi Coding Agent with a Local Model on Mac
Run Pi Coding Agent with a local model on your Mac using one command. Rapid-MLX saves a private agent profile and starts a local model when needed.
One command to launch Pi Coding Agent
First install Rapid-MLX and install Pi Coding Agent. If you used the install script, restart Terminal or run export PATH="$HOME/.local/bin:$PATH" first. Then run:
$ rapid-mlx launch pi
Tomorrow: Run rapid-mlx launch pi again. Rapid reuses the saved profile, model, loopback key and port. It does not change your existing Pi Coding Agent configuration. To remove only Rapid's private profile, run rapid-mlx launch pi --remove.
Choose a model by Mac RAM: Start with qwen3.5-9b-4bit on a 16–23 GB Mac; this agent needs a stronger model for multi-step tool use. On 32 GB or more, try qwen3.6-35b-4bit. On 8–15 GB, there is no broadly reliable recommendation for this agent; the installer’s smaller chat model is for simpler tasks. See the RAM guide. Override the suggested model with rapid-mlx launch pi --model qwen3.5-9b-4bit when it fits your Mac.
First reply: The first reply can take longer than later turns: an uncached model must download, the server must load it, and the agent may send a long prompt that takes time to prefill. Wait for the model to become ready; there is no fixed first-reply time. A warm, cached model is usually quicker.
Quick answer
How do I use Pi Coding Agent with a local model on Mac? Install Rapid-MLX, then run rapid-mlx launch pi. The same command reconnects on another day; --remove removes Rapid's private profile.
The agent hub covers the other supported agents. The manual setup below is useful when you intentionally want to edit your regular agent configuration.
Quick start
Needs: Pi 1.1.0 (npm install -g @earendil-works/pi-coding-agent@1.1.0).
$ rapid-mlx serve qwen3.5-4b-4bit --port 8000 # In another terminal: $ rapid-mlx agents pi --setup --yes $ pi --print --no-session --provider rapid-mlx --model qwen3.5-4b-4bit \ "Use the read tool to read README.md and report its title"
--provider and --model pin the local route even if Pi has other credentials. rapid-mlx agents pi --test runs the integration check.
/v1/chat/completions (pi's
openai-completions API) ·
Setup: rapid-mlx agents pi --setup
Re-verified 2026-10-11 — Pi 1.1.0 called its
read tool and returned a file marker through
rapid-mlx on an M2 Pro Mac mini, using
qwen3.5-4b-4bit.
Install
$ npm install -g @earendil-works/pi-coding-agent
Setup
$ rapid-mlx serve qwen3.5-4b-4bit # in another terminal $ rapid-mlx agents pi --setup --dry-run # preview only $ rapid-mlx agents pi --setup # preview, confirm, write
--setup reads the model id and context window from the
running server. It then:
- prints an exact diff of
~/.pi/agent/models.json(or$PI_CODING_AGENT_DIR/models.json) - asks
Apply this configuration? [y/N]. Pass--yesin scripts, because a non-interactive run without it writes nothing. - copies an existing file to
models.json.bak.<unix-time> - writes atomically, owner-only (
0600). Ifmodels.jsonis a symlink, it updates the file the link points to. - refuses to write if the file changed between preview and confirmation
- checks the server's
/healthand/v1/models(skip this with--no-check)
Your other providers are kept. Under the rapid-mlx
provider, models are merged by id, so models you added there
yourself are kept too. The block it writes:
// ~/.pi/agent/models.json { "providers": { "rapid-mlx": { "baseUrl": "http://localhost:8000/v1", "api": "openai-completions", "apiKey": "not-needed", "models": [ { "id": "qwen3.5-4b-4bit", "name": "qwen3.5-4b-4bit (Rapid-MLX)", "contextWindow": 262144, "maxTokens": 8192, "input": ["text"], "reasoning": false } ] } } }
id and contextWindow come from the running
server. The values above are for qwen3.5-4b-4bit.
Run
$ pi # interactive $ pi --print --no-session --provider rapid-mlx --model qwen3.5-4b-4bit "summarize this repo"
If rapid-mlx is the only provider pi has credentials for, no flags are
needed. Otherwise see the first gotcha below. Recommended aliases (per
rapid-mlx agents pi): qwen3.6-35b-4bit,
qwen3.5-9b-4bit, qwen3-coder-30b-4bit.
rapid-mlx start pi starts a recommended model and then
runs the same setup.
Gotchas
-
Other providers can win. If pi has other providers authenticated
(its
auth.jsonor provider env keys), it may default to one of them. Pick the local model with/model(Ctrl+S saves it as the default), or pass--provider rapid-mlx --model <id>. -
"reasoning": falseis the setting we verified. pi then sends no reasoning preference, and rapid-mlx turns thinking off on tool turns."reasoning": true(so pi's/thinkingdrivesreasoning_effort) has not been verified. -
Keyed servers. The Rapid-MLX desktop app (and any server
started with
--api-keyorRAPID_MLX_API_KEY) needs a key. ExportRAPID_MLX_API_KEYbefore running setup and keep it exported when you run pi: setup writes"apiKey": "$RAPID_MLX_API_KEY"(pi expands$NAMEinmodels.json), so the key itself is not stored in the file. Without the variable it writes"not-needed", as above. -
pi's own telemetry.
PI_TELEMETRY=0turns off pi's install/update telemetry and provider attribution headers.PI_OFFLINE=1stops its catalog refreshes.