Agent guide · rapid-mlx 1.0.3

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.

--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.

  1. In Claude Desktop, open Help → Troubleshooting → Enable Developer Mode.
  2. Open Developer → Configure Third-Party Inference and choose Gateway.
  3. Paste Rapid's http://127.0.0.1:7659 Gateway URL and the API key printed by the setup command (or copied from Desktop), then choose Test.
  4. 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

AgentSetupWrites
Claude Desktoprapid-mlx launch claude-desktop, then configure Gateway in Claude DesktopRapid's private tier mapping; Claude Desktop changes only through its own window
Claude Coderapid-mlx launch claude-code for a private profile; rapid-mlx agents claude-code --setup for editable global setupPrivate launch: ~/.rapid-mlx/connect/agents/claude-code/settings.json; global setup: ~/.claude/settings.json
Codex CLIrapid-mlx agents codex --setup~/.codex/config.toml + rapid-mlx-model-catalog.json (or under $CODEX_HOME)
Pirapid-mlx agents pi --setup~/.pi/agent/models.json (or $PI_CODING_AGENT_DIR)
OpenCoderapid-mlx agents opencode --setup~/.config/opencode/opencode.json
Hermes Agentrapid-mlx agents hermes --setup~/.hermes/config.yaml (or $HERMES_HOME)
DeepSeek Harnessrapid-mlx agents dsh --setup~/.dsh/cordis.patch.yml + .credentials.yaml (or $DSH_HOME)
Qwen Coderapid-mlx agents qwen-code --setup~/.qwen/settings.json
Kilo Coderapid-mlx agents kilo-code --setup~/.config/kilo/kilo.json
Aiderrapid-mlx agents aider --setupprints OPENAI_API_BASE, OPENAI_API_KEY, AIDER_MODEL
OpenHandsrapid-mlx agents openhands --setupprints LLM_BASE_URL, LLM_API_KEY, LLM_MODEL
Continue.devrapid-mlx agents continue --setup or rapid-mlx launch continue-dev~/.continue/config.yaml (a rapid-mlx model entry)
Cursorrapid-mlx launch cursor --server-url https://…Cursor's settings. Needs a public HTTPS URL.
Gooserapid-mlx launch goose for a private profile; rapid-mlx agents goose --setup for editable global setupPrivate launch: Rapid's own agent profile; global setup: ~/.config/goose/custom_providers/custom_rapid_mlx.json
Crushrapid-mlx agents crush --setup~/.config/crush/crush.json (or $CRUSH_GLOBAL_CONFIG/crush.json)
Clinerapid-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 --yes in 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 /health and /v1/models afterwards (--no-check skips 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.

See also