Rapid-MLX 1.0.1 Tutorial: Run Claude Code and Codex with Local Models on Apple Silicon (2026)

Last checked: 6 November 2026. You do not need to send every coding prompt to a hosted model just to use a modern coding-agent workflow. On an Apple Silicon Mac, Rapid-MLX can serve an MLX model on loopback and expose both OpenAI-compatible and Anthropic-compatible APIs. That lets tools such as Claude Code and Codex talk to a model running on your own machine.

This guide walks through Rapid-MLX 1.0.1: installation, model selection, a local API smoke test, connecting a coding agent, and the security settings that matter before you point it at a real repository.

Who this guide is for

• Mac developers who want to experiment with local coding agents.
• People already using Claude Code, Codex CLI, or an OpenAI-compatible Python client.
• Developers who want to keep model inference on their own Apple Silicon computer.
• Teams evaluating a local inference endpoint before building a larger workflow.

Rapid-MLX is not a general cross-platform runtime. It is built around Apple's MLX framework and currently targets Apple Silicon Macs. If you need Windows, Linux, Intel Mac, or a graphical model manager first, compare it with the alternatives discussed later in this guide.

What changed in Rapid-MLX 1.0.1?

The project published Rapid-MLX 1.0.1 on 2 November 2026. The release notes document several practical changes:

• Python 3.12 or newer is now required for the Python-based installer and package paths. Homebrew and the Desktop app handle their own environment and do not require you to migrate a manually managed Python environment.
• Model memory preflight: the server checks whether a catalogue model is likely to fit before downloading it and can suggest a smaller option.
• Five speech aliases: Granite Speech, FireRedASR2 and Nemotron ASR for speech-to-text, plus VoxCPM2 and MOSS-TTS-Nano for text-to-speech.
• More reliable upgrades and downloads: the release notes describe version verification after upgrades, cancellable downloads that can resume from cached files, and fixes for strict JSON-schema stalls.
• Benchmark configuration follows serving settings: the benchmark command can use the same acceleration flags as the server, making a comparison easier to interpret.

These are release-note statements from the project, not independent performance findings. The current Homebrew formula listed Rapid-MLX 1.0.1 as stable when this guide was checked on 6 November 2026.

Prerequisites

• An Apple Silicon Mac with an M-series chip (M1 or newer).
• macOS 14 Sonoma or later.
• Homebrew for the simplest installation path.
• Internet access for the initial install and model download. After the model is cached, local inference does not require a hosted model API.
• Enough free unified memory and disk space for the model, context/KV cache, macOS, and your other applications.
• Optional: Claude Code or Codex CLI if you want to connect a coding agent. Install the agent separately from its official source.

Rapid-MLX does not support Intel Macs, Windows, or Linux. The underlying MLX framework is designed for Apple Silicon. Do not follow this tutorial on a Windows laptop or an Ubuntu VPS expecting the same commands to work.

1. Confirm your Mac and macOS version

Open Terminal and inspect the machine before installing anything:

uname -m
sw_vers -productVersion
system_profiler SPHardwareDataType | grep -E "Chip|Memory"

On an Apple Silicon Mac, uname -m should report arm64. Confirm that the macOS version is 14 or newer. If Terminal is running under Rosetta, check that your Homebrew and Python installations are native ARM64 rather than mixing Intel and Apple Silicon packages.

2. Install Rapid-MLX 1.0.1

For most Mac users, Homebrew is the straightforward route:

brew update
brew install rapid-mlx

Verify the installed CLI and run its environment diagnostic:

rapid-mlx --version
rapid-mlx doctor

The version command should report the installed release. The doctor command checks the Mac, Python/runtime packages, optional components, model cache, and network-related setup. Keep its output if you need to report an installation problem.

If you do not use Homebrew, the project also documents a guided installer:

curl -fsSL https://rapidmlx.com/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
rapid-mlx --version
rapid-mlx doctor

Review an installer before executing it if that is your normal security policy. The project documents the installer as creating an environment under ~/.rapid-mlx and placing the CLI in ~/.local/bin. Avoid mixing several installation methods in the same shell: an old executable earlier in PATH can make the version check misleading.

Important Python 3.12 migration note

Rapid-MLX 1.0.1 requires Python 3.12 or newer for pip-managed and Python-tool installations. The project specifically warns that on Python 3.10 or 3.11, a normal pip install -U rapid-mlx can leave the environment on 1.0.0 rather than upgrading to 1.0.1. Homebrew and the Desktop app are unaffected by that manual Python issue.

If you manage the package yourself with pip, create a fresh Python 3.12 virtual environment:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --upgrade rapid-mlx
rapid-mlx --version

Do not assume that a successful pip exit code proves you are on 1.0.1. Check the version that actually runs.

3. Choose a model that fits your memory

Model size is only one part of the memory requirement. The model weights, context window, KV cache, active requests, macOS, and your editor all compete for unified memory. A model that downloads successfully can still be uncomfortable to use if the system begins swapping.

Start with the CLI's own recommendation:

rapid-mlx recipe

The project publishes separate smart and fast picks by memory tier. Its current hardware guide lists a 4-bit Qwen 3.5 4B model as the general-purpose pick for a 16 GB Mac, and a Qwen 3.5 9B 4-bit model in the 18 GB tier. The coding-agent guides recommend a stronger starting point for multi-step tool use: Qwen 3.5 9B for the 16–23 GB range and Qwen 3.6 35B 4-bit on 32 GB or more. These are project recommendations, not a guarantee that every workload will fit or perform well.

For a first API check, use the small quick-start alias:

qwen3.5-4b-4bit

For a coding agent, use rapid-mlx recipe and the agent-specific hardware guide before selecting a larger alias. If your Mac has 16 GB, do not blindly force a 9B model while several memory-heavy apps are open. Start smaller, check memory pressure, then move up only if the model and context fit comfortably.

4. Start the local inference server

Start with the quick-start model and a fixed port:

rapid-mlx serve qwen3.5-4b-4bit --port 8000

On the first run, Rapid-MLX downloads the model if it is not already cached. Keep this terminal window open while testing. The documented default listener is 127.0.0.1, which means the service is reachable from the Mac itself, not from every device on your network.

In a second Terminal window, check health and model discovery:

curl -fsS http://127.0.0.1:8000/health
curl -fsS http://127.0.0.1:8000/v1/models

The first request checks that the server is responding. The second returns the model names the API accepts. Use the served alias from that response in client requests rather than guessing a different model identifier.

5. Send a test request with cURL

Rapid-MLX exposes an OpenAI-compatible Chat Completions endpoint. Send a small request before connecting an agent:

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5-4b-4bit",
    "messages": [
      {"role": "user", "content": "Explain what a Python virtual environment does in two sentences."}
    ],
    "max_tokens": 120
  }'

You should receive a JSON response containing a model-generated answer. If the request fails, check the server terminal first; it usually contains the more useful startup or memory error.

6. Call the same endpoint from Python

Use a project-local virtual environment for your client dependencies:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install openai

Create a small test file named local_llm.py:

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8000/v1",
    api_key="local-placeholder",
)

response = client.chat.completions.create(
    model="qwen3.5-4b-4bit",
    messages=[
        {
            "role": "user",
            "content": "Give me three checks to run before opening a pull request."
        }
    ],
    max_tokens=180,
)

print(response.choices[0].message.content)

Run it while the Rapid-MLX server is still running:

python local_llm.py

The placeholder key works with the default local server because it does not enforce authentication unless you configure an API key. The OpenAI SDK itself expects a non-empty key string, so the placeholder satisfies the client library; it is not a real credential.

7. Connect Claude Code or Codex CLI

Rapid-MLX supports both the OpenAI Responses API used by Codex CLI and the Anthropic Messages API used by Claude Code. The project provides a private launch profile for each agent. This is useful because the launch profile keeps Rapid-MLX's connection settings separate from your normal agent configuration.

Option A: Claude Code

Install Claude Code from Anthropic's official instructions. The documented npm installation command is:

npm install -g @anthropic-ai/claude-code

Then launch it through Rapid-MLX:

rapid-mlx launch claude-code

Rapid-MLX selects a model for the Mac, starts the local server if needed, waits for it to become ready, and opens Claude Code with its private profile. Run the same command next time to reconnect. To choose a particular model, pass --model with an alias that fits your machine:

rapid-mlx launch claude-code --model qwen3.5-9b-4bit

The Claude Code guide documents a 9B 4-bit starting point for 16–23 GB Macs and a 35B 4-bit option for 32 GB or more. Treat those as agent-specific recommendations; check your actual free memory and context needs before using them.

Option B: Codex CLI

Install Codex CLI using OpenAI's official package:

npm install -g @openai/codex

Then run:

rapid-mlx launch codex

For a deliberate model choice, use the documented override:

rapid-mlx launch codex --model qwen3.5-9b-4bit

Rapid-MLX's private launch profile does not overwrite your existing Codex configuration. The project documents rapid-mlx launch codex --remove to remove only its own private profile.

What if you prefer manual environment variables?

For a temporary Claude Code session against a server that does not require a key, the Anthropic base URL is the server root, without /v1:

export ANTHROPIC_BASE_URL=http://127.0.0.1:8000
export ANTHROPIC_API_KEY=local-placeholder
claude

For an OpenAI SDK-based script, use:

export OPENAI_BASE_URL=http://127.0.0.1:8000/v1
export OPENAI_API_KEY=local-placeholder
python local_llm.py

The base URL difference is important. OpenAI clients use /v1; Anthropic's SDK appends its own /v1/messages path, so its base URL should be the server root. Adding /v1 to the Anthropic base URL can produce a duplicated path and a 404.

8. Understand model and agent compatibility

API compatibility does not mean every model behaves identically. Rapid-MLX's catalogue aliases carry model-specific tool-call and reasoning parser settings. That is why the quick-start commands use an alias such as qwen3.5-4b-4bit rather than an arbitrary display name.

When you serve a model outside the catalogue, you may need to provide the tool-call parser explicitly. The troubleshooting guide documents the pattern:

rapid-mlx serve org/model-name \
  --enable-auto-tool-choice \
  --tool-call-parser parser-name

Use the parser name supported by that model's output format. Do not copy a parser from a different model family simply because both models are instruction-tuned.

The project publishes an integration matrix for agent and model-family combinations. It distinguishes end-to-end Tier-1 checks from wire-level smoke tests and lists known expected failures. Consult that matrix for your exact model and agent version; do not treat a general OpenAI-compatible endpoint as proof that every tool call, reasoning format, or agent feature is supported.

9. Keep the local endpoint private

Local inference reduces the need to send prompts to a hosted model provider, but it does not automatically make the whole coding workflow private or safe.

• Keep the default loopback binding. The server listens on 127.0.0.1 by default. Do not change it to 0.0.0.0 unless you deliberately need LAN access.
• Enable authentication before sharing. If you must expose the server to another device, configure an API key and a narrow trusted-host list. The project documents --api-key, RAPID_MLX_API_KEY, and --trusted-hosts for that purpose.
• Do not publish the raw port to the internet. For remote access, use a separately managed authenticated TLS reverse proxy or a private network tunnel. Avoid unauthenticated public tunnels.
• Review agent permissions. A coding agent can read files, run commands, and potentially alter a repository. Start in a disposable Git branch or test repository, inspect proposed commands, and keep backups.
• Protect secrets in the workspace. Do not give an agent access to production environment files, SSH keys, cloud credentials, or unrelated private folders unless the task genuinely requires them.
• Remember model downloads are network activity. Initial model files come from Hugging Face or the project's mirror. A local inference endpoint does not mean the initial download is offline.

Telemetry and privacy settings

One important detail is easy to miss: the current Rapid-MLX telemetry documentation says anonymous product analytics are sent by default after a notice, not that telemetry is always off. The published event contract excludes prompts, model outputs, file contents, API keys, and raw file paths from the engine event properties, but it can include metadata such as app version, operating system, chip family, rounded memory, command category, and public catalogue model aliases. The Desktop app has a separate event stream with its own disclosure.

If you do not want usage telemetry, turn it off explicitly:

rapid-mlx telemetry off

You can inspect the effective setting and the event preview with:

rapid-mlx telemetry status
rapid-mlx telemetry preview

The project also documents RAPID_MLX_TELEMETRY=0 and DO_NOT_TRACK=1 as per-process switches. Review the current telemetry and privacy pages if your organisation has a strict data-handling policy. These are project-published disclosures, not an independent privacy audit.

10. Troubleshooting common problems

Rapid-MLX still reports version 1.0.0

Check which executable is running with which rapid-mlx and rapid-mlx --version. If you installed with pip under Python 3.10 or 3.11, move to Python 3.12 and create a new environment. If you installed with Homebrew, use brew upgrade rapid-mlx and then check the version again. Avoid leaving an older pip or installer copy earlier in PATH.

The model is refused or macOS becomes very slow

Run rapid-mlx recipe, choose a smaller model or quantization, and close memory-heavy applications before serving. Long context increases KV-cache use. The project documents --context-length to cap the per-request window and --kv-cache-dtype int8 as a memory-saving option with a possible decode-speed trade-off. Do not increase memory limits blindly if the machine is already swapping.

The server returns HTTP 503

The documented 503 responses include a Metal-memory-limit refusal and a separate concurrency-limit response. For memory pressure, shorten the prompt, reduce max_tokens, wait for active requests to finish, or use a smaller model. For the concurrency cap, respect the returned Retry-After header and review the configured request limits.

Port 8000 is already in use

Find the process using the port:

lsof -i :8000
rapid-mlx ps

Without an explicit port, Rapid-MLX can select another free port in its documented 8000–8009 range. If you specify --port 8000, it will not silently fall back. Choose a free port and update the client base URL to match.

The model answers but tool calls appear as plain text

Try a catalogue alias first, because its profile selects the expected parser automatically. For a custom model, check its documented tool-call format and set the matching parser with --enable-auto-tool-choice and --tool-call-parser. A model that does not reliably emit structured tool calls may not be suitable for agent use even if ordinary chat works.

Claude Code returns 404

Check the Anthropic base URL. It should be the server root, for example http://127.0.0.1:8000, not http://127.0.0.1:8000/v1. Also confirm that the server is still running and that the agent is using the Rapid-MLX profile.

A model repository is rejected

Rapid-MLX uses MLX-compatible model formats. The project documentation says GGUF and binary-only repositories are not served directly by this runtime. Use a compatible MLX checkpoint, or follow the documented import/conversion path for a supported safetensors model. Do not rename a GGUF file and expect it to become an MLX checkpoint.

Rapid-MLX vs Ollama vs LM Studio: when should you use each?

These tools solve overlapping but not identical problems. Rapid-MLX is worth evaluating when the Mac itself is the inference machine and your main goal is to connect coding agents to an MLX-backed endpoint. For a broader workflow comparison, see GyanAangan's Unsloth vs LM Studio guide and its Unsloth vs Ollama comparison.

Frequently asked questions

Can I run Rapid-MLX on an Intel Mac, Windows, or Linux?

No. The current project documentation targets Apple Silicon Macs running macOS 14 or later. It does not provide a Windows, Linux, or Intel Mac server build.

Does Rapid-MLX send my prompts to a cloud model?

Inference is performed on your Mac. However, initial model downloads contact Hugging Face or the project's mirror, optional online tools can send data to their own services, and anonymous product telemetry is enabled by default after notice unless you turn it off. Read the current privacy disclosure before using it with sensitive work.

Can I use any OpenAI-compatible client?

Many clients can connect through the documented OpenAI-compatible endpoints, but compatibility is not identical to the entire hosted OpenAI API. Check the API reference for supported routes, model-specific capabilities, and known differences.

Can I load a GGUF model?

Not directly. Rapid-MLX is based on MLX and expects compatible MLX model files. Its documentation describes importing supported safetensors models; GGUF is not a drop-in format for this server.

Does a local coding agent work completely offline?

Model inference can run locally after the runtime, agent, and model are installed. The agent may still use the network for package installation, Git hosting, documentation, browser tools, MCP servers, or other commands. Local inference does not disable those separate network paths.

Is Rapid-MLX automatically safer than a hosted coding agent?

It changes where inference runs, but it does not make generated code trustworthy or agent actions harmless. Keep the endpoint private, restrict the agent's filesystem scope, review command approvals, and test changes in a Git branch.

Useful GyanAangan follow-up guides

• Trace local LLM applications with OpenTelemetry and Phoenix — add observability after your local endpoint works.
• Secure multi-tenant MCP servers with OAuth and tenant isolation — useful when a local agent later needs controlled tool access.
• Access a local Ollama API remotely with Tailscale Serve — a related example of keeping a local inference service private when remote access is required.
• Run multiple GGUF models behind llama.cpp Router Mode — a different runtime architecture for developers working with GGUF models.

Official sources and further reading

• Rapid-MLX v1.0.1 GitHub release — release date, Python requirement, memory preflight, speech models, and fixes.
• Rapid-MLX changelog — version-by-version changes.
• Homebrew formula — stable package version, supported macOS floor, and package dependencies.
• Install and first request — official requirements, installation, and local API smoke test.
• Hardware tiers — model recommendations and the machines used for published measurements.
• OpenAI-compatible server reference — base URLs, ports, authentication, host checks, and API routes.
• Coding-agent integration guides — supported clients, private launch profiles, and configuration behavior.
• Claude Code local-model guide and Codex CLI local-model guide — agent-specific commands and limitations.
• Agent integration matrix — tested model-family and agent combinations, including expected failures.
• Troubleshooting reference — memory, parser, port, Python, and model-format issues.
• Telemetry disclosure and Privacy policy — current data fields, destinations, and opt-out controls.
• Apple MLX repository — the underlying Apple Silicon machine-learning framework.
• OpenAI Codex CLI repository and Anthropic Claude Code repository — official agent installation and project information.

Final recommendation

Rapid-MLX 1.0.1 is worth testing if you have an Apple Silicon Mac and want Claude Code, Codex, or your own Python application to call a local MLX model through familiar API shapes. Start with a small catalogue model, prove the local endpoint works, then connect one agent and test it in a disposable repository. Keep the server on loopback, review telemetry preferences, and treat model quality and tool compatibility as things to measure on your own machine—not as guarantees from a compatibility label or a benchmark headline.

Editorial note: This guide was prepared from the project's release notes, official documentation, repository, and Homebrew formula checked on 6 November 2026. The commands were reviewed against those sources but were not executed on a live Mac as part of this article.