Run Coding Agents with Local MLX Models on Mac
Run a local coding agent on Mac with one command. Rapid-MLX saves its own profile, starts a local model when needed, and leaves your existing agent settings untouched.
$ rapid-mlx launch codex $ rapid-mlx launch claude-code $ rapid-mlx launch opencode $ rapid-mlx launch pi $ rapid-mlx launch hermes $ rapid-mlx launch goose $ rapid-mlx launch crush
Install Rapid-MLX with curl -fsSL https://rapidmlx.com/install.sh | bash, restart Terminal (or run export PATH="$HOME/.local/bin:$PATH"), and install your agent. Then run its command above. Run the same command tomorrow. rapid-mlx launch codex --remove removes only Rapid's private Codex profile. For a starting model, use qwen3.5-4b-4bit on a 16 GB Mac, qwen3.5-9b-4bit on an 18–23 GB Mac, and qwen3.8-27b-4bit on 32 GB or more. New in 1.0.3: on base and Pro chip Macs with 48 GB or more, start with Qwen3.6 35B-A3B MoE (qwen3.6-35b-4bit); Max and Ultra Macs keep the dense 27B first. On an 8–15 GB Mac, the installer suggests lfm2.5-2.6b-4bit; small models may struggle with multi-step coding tasks. See the RAM guide. For Goose, the verified starting point is qwen3.5-9b-4bit on a Mac with at least 16 GB; run rapid-mlx launch goose --model qwen3.5-9b-4bit and see the Goose guide for the tested scope. 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.
How do I use Claude Code with a local model on Mac? Run rapid-mlx launch claude-code. For Codex, OpenCode, Pi, Hermes, Goose or Crush, replace the agent name in the command. Claude Desktop uses its in-app Gateway setup.
In 1.0.3, dotted or slash-separated tool names resolve to a unique declared tool after separators are normalized to underscores; exact names take precedence. Gemma 3 12B and 27B support structured tool calls, including streaming, parallel calls and tool-result history; the 1B and 4B catalog variants no longer advertise tool support. Agent setup skips servers that need a missing key or serve non-chat models and gives a working next step.
Manual agent configuration
The older rapid-mlx agents <agent> --setup path edits the agent's normal configuration and remains available when you want that behavior.
env block in ~/.claude/settings.json, with a diff preview and a backup.~/.codex/config.toml.~/.pi/agent/models.json, with a diff preview and a backup.
--setup can finish before the server starts. When reachable, it asks which model the server serves (and,
for configs that record it, the model's context window). Pass
--model or --base-url (default
http://localhost:8000/v1, see
port and base URL) to override, and
--dry-run to preview without writing.
rapid-mlx start <agent> starts the server and
configures the agent in one step.
Keep your local agent connected tomorrow
In Rapid Desktop, start a coding model, open Launch, and click
Launch next to your agent. Rapid saves a private profile and
opens the agent in Terminal. Your existing agent settings stay untouched.
The same short rapid-mlx launch <agent> command works in a new terminal after a restart.
# First launch, and the same command tomorrow: $ rapid-mlx launch codex # Or launch Claude Code: $ rapid-mlx launch claude-code # Or launch Goose: $ rapid-mlx launch goose # Remove only Rapid's private Codex profile: $ rapid-mlx launch codex --remove
Replace codex with claude-code, pi,
opencode, hermes, goose,
qwen-code, crush, or aider.
The short command checks the saved key, port, and model, starts the local
server if needed, waits for readiness, and opens the agent. The connection stays on
127.0.0.1, and its key and profiles are owner-only files.
Rapid does not add a login item. Desktop also keeps one-session commands
for Claude Code, Codex, and Hermes when you do not want a saved profile.
Connect Claude Desktop through Gateway
Start a tool-capable local model in Rapid Desktop, open Launch,
and choose Claude Desktop to copy the Gateway URL and API key.
Run the displayed rapid-mlx launch claude-desktop command to enable
Rapid's local opus, sonnet, and haiku model choices. You can also do the
setup and start the server from Terminal with a matching model, port, and saved key:
$ rapid-mlx launch claude-desktop --model qwen3.5-4b-4bit --port 7659 $ RAPID_MLX_API_KEY="$(cat ~/.rapid-mlx/connect/api-key)" rapid-mlx serve qwen3.5-4b-4bit --port 7659
The setup command prints the Gateway URL and API key; it saves Rapid's tier mapping but does not start the server or change Claude Desktop files. Keep the server running while using Claude Desktop. If it is already running with a different key or model, restart it with the saved key and selected model before testing.
- In Claude Desktop, open Help → Troubleshooting → Enable Developer Mode.
- Open Developer → Configure Third-Party Inference and choose Gateway.
- Paste Rapid's
http://127.0.0.1:7659Gateway URL and the API key printed by the setup command (or copied from Desktop), then choose Test. - Choose Apply Changes in Claude Desktop.
Claude Desktop makes the configuration change in its own window. Rapid only
advertises the three Claude tier choices while its mapping is enabled; use
rapid-mlx launch claude-desktop --remove to disable that mapping.
If you use another port, paste the URL printed by your setup command.
Supported agents
| Agent | Setup | Writes |
|---|---|---|
| Claude Desktop | rapid-mlx launch claude-desktop, then configure Gateway in Claude Desktop | Rapid's private tier mapping; Claude Desktop changes only through its own window |
| Claude Code | rapid-mlx launch claude-code for a private profile; rapid-mlx agents claude-code --setup for editable global setup | Private launch: ~/.rapid-mlx/connect/agents/claude-code/settings.json; global setup: ~/.claude/settings.json |
| Codex CLI | rapid-mlx agents codex --setup | ~/.codex/config.toml + rapid-mlx-model-catalog.json (or under $CODEX_HOME) |
| Pi | rapid-mlx agents pi --setup | ~/.pi/agent/models.json (or $PI_CODING_AGENT_DIR) |
| OpenCode | rapid-mlx agents opencode --setup | ~/.config/opencode/opencode.json |
| Hermes Agent | rapid-mlx agents hermes --setup | ~/.hermes/config.yaml (or $HERMES_HOME) |
| DeepSeek Harness | rapid-mlx agents dsh --setup | ~/.dsh/cordis.patch.yml + .credentials.yaml (or $DSH_HOME) |
| Qwen Code | rapid-mlx agents qwen-code --setup | ~/.qwen/settings.json |
| Kilo Code | rapid-mlx agents kilo-code --setup | ~/.config/kilo/kilo.json |
| Aider | rapid-mlx agents aider --setup | prints OPENAI_API_BASE, OPENAI_API_KEY, AIDER_MODEL |
| OpenHands | rapid-mlx agents openhands --setup | prints LLM_BASE_URL, LLM_API_KEY, LLM_MODEL |
| Continue.dev | rapid-mlx agents continue --setup or rapid-mlx launch continue-dev | ~/.continue/config.yaml (a rapid-mlx model entry) |
| Cursor | rapid-mlx launch cursor --server-url https://… | Cursor's settings. Needs a public HTTPS URL. |
| Goose | rapid-mlx launch goose for a private profile; rapid-mlx agents goose --setup for editable global setup | Private launch: Rapid's own agent profile; global setup: ~/.config/goose/custom_providers/custom_rapid_mlx.json |
| Crush | rapid-mlx agents crush --setup | ~/.config/crush/crush.json (or $CRUSH_GLOBAL_CONFIG/crush.json) |
| Cline | rapid-mlx agents cline --setup | ~/.cline/data/settings/providers.json (Cline CLI; prints the VS Code settings steps) |
Framework profiles (rapid-mlx agents langchain,
pydanticai, smolagents) print environment
variables (OPENAI_BASE_URL …) instead of writing files. See the framework
guides. Other OpenAI-compatible clients (GitHub Copilot, the OpenAI
SDK with gpt-oss) have hand-written guides in the sidebar.
How setup treats your existing config
Each agent's setup uses one of three flows:
Preview + backup
Claude Code · Pi · DeepSeek Harness · Continue
- Prints an exact diff, then asks
Apply this configuration? [y/N]. Use--yesin scripts; without it, a non-interactive run writes nothing. - Copies the old file to
<file>.bak.<unix-time>. - Writes atomically, and refuses if the file changed after the preview.
- Checks
/healthand/v1/modelsafterwards (--no-checkskips this).
Merge
Codex CLI · OpenCode · Hermes · Qwen Code · Kilo Code · Goose · Crush
Merges the rapid-mlx keys into the existing file and keeps your other keys. A list the template sets is replaced, not merged. For Qwen Code that's modelProviders.openai, so other OpenAI-provider entries there are dropped. Hermes's cli toolset list is the exception, and is merged. TOML/YAML comments are not kept, and no backup is made, so copy the file first if it matters. --dry-run says what would change and writes nothing. Setup uses /health and /v1/models when reachable and can also write the config before the server starts; a file that is already current is left untouched.
Print env vars
Aider · OpenHands
Prints export lines for your shell and writes no files.
Servers with an API key
A bare rapid-mlx serve needs no key. The desktop app, and
any server started with --api-key or
RAPID_MLX_API_KEY, require one. Export
RAPID_MLX_API_KEY in the shell where you run setup:
setup sends it when it checks the server, and Codex, OpenCode and Pi get
a reference to the environment variable rather than the key itself
(keep it exported when you run the agent). Claude Code and Continue
read the key from their own config file (settings.json,
config.yaml), so setup writes the value there and hides it
in the preview.
Test an integration
$ rapid-mlx agents opencode --test
--test runs the agent's integration checks against the
running server. Where the profile has a headless mode, that includes a
real one-shot task. Pass --agent-version when an agent's
config format depends on its version.
Walkthroughs
Step-by-step guides, from a fresh install to a working agent session on a local model: Claude Code · Codex CLI · Pi · OpenCode · Aider · Continue · Cline · Goose · Cursor. Writing your own code instead? Call a local LLM from Python.