Agent guides
Server running? One command wires your agent to it.
$ rapid-mlx serve qwen3.6-35b-4bit # in another terminal, pick your agent: $ rapid-mlx agents claude-code --setup $ rapid-mlx agents codex --setup $ rapid-mlx agents pi --setup
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.
Supported agents
| Agent | Setup | Writes |
|---|---|---|
| Claude Code | rapid-mlx agents claude-code --setup or rapid-mlx launch claude-code | ~/.claude/settings.json (env block) |
| 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 agents goose --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.