Agent guide · rapid-mlx 1.1.0

Run Goose with a Local MLX Model on Mac

Run Goose 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 Goose

First install Rapid-MLX and install Goose. If you used the install script, restart Terminal or run export PATH="$HOME/.local/bin:$PATH" first. Then run:

$ rapid-mlx launch goose

Tomorrow: Run rapid-mlx launch goose again. Rapid reuses its saved profile, model, loopback key and port. It does not change your existing Goose configuration. To remove only Rapid's private profile, run rapid-mlx launch goose --remove.

Mac unified memoryModel choicesDownload and memory guidance
16 GBqwen3.5-4b-4bit fits 16 GB per the registry; not verified live on a 16 GB Mac.About 3 GB download.
18–36 GBqwen3.5-9b-4bit default; start with qwen3.5-4b-4bit on 18–24 GB.About 6 GB for 9B or 3 GB for 4B.
48 GB+qwen3.5-9b-4bit responsive default; qwen3.8-27b-4bit higher-capability option.About 6 GB for 9B or 16 GB for 27B; 27B needs roughly 20–26 GB free unified memory.

Download size is not runtime memory use. Leave room for the client, context and other applications; keep context short when memory is tight.

Historical measurement: Goose 1.55.0 passed the four-part first-turn acceptance matrix with qwen3.5-9b-4bit on an M4 Pro running Rapid-MLX 0.16.6; that result does not establish live verification on a 16 GB Mac.

First reply: The first reply can take longer than later turns: an uncached model must download, the server must load it, and Goose 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 Goose with a local model on Mac? Install Rapid-MLX and Goose, then run rapid-mlx launch goose. 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 Goose configuration.

Manual setup

The older setup flow writes a custom provider in Goose's regular configuration. Run the server and setup command in separate terminals.

$ rapid-mlx serve qwen3.5-4b-4bit
$ rapid-mlx agents goose --setup
$ goose run --provider custom_rapid_mlx --model qwen3.5-4b-4bit --no-session --text "Use a tool to inspect this directory, then summarize it."

Setup writes ~/.config/goose/custom_providers/custom_rapid_mlx.json. Use --base-url http://127.0.0.1:PORT/v1 if your server uses another port. The model name and context limit come from the running server; --model sets the alias explicitly. --dry-run previews without writing.

Connection

The generated provider uses engine: openai and a full /v1/chat/completions URL. Goose selects the custom_rapid_mlx provider, with a model matching the server alias. For a keyed server, export RAPID_MLX_API_KEY before setup and before running Goose; setup stores the variable name, never the key.

Goose reads providers from ~/.config/goose/custom_providers/ by default. If you set XDG_CONFIG_HOME, setup and Goose use $XDG_CONFIG_HOME/goose/custom_providers/. An absolute GOOSE_PATH_ROOT takes precedence over both and places the file under $GOOSE_PATH_ROOT/config/custom_providers/. Keep those variables set for both setup and Goose. The current provider schema and config path are in Goose 1.54.0 source.

Check it

$ rapid-mlx agents goose --test

This runs the integration checks and a headless Goose request against the local model.