OpenCode

OpenCode is an OpenAI-compatible TUI that talks /v1/chat/completions. It uses the AI SDK's openai-compatible provider, so you point it at rapid-mlx's base URL and any served alias just works.

Quick start

Needs: OpenCode 2.x (npm install -g @opencode/cli@2); start the server before sending requests (rapid-mlx serve qwen3.5-4b-4bit).

$ rapid-mlx serve qwen3.5-4b-4bit --port 8000
# In another terminal:
$ rapid-mlx agents opencode --setup --yes
$ opencode models
$ opencode run --standalone "Use a tool to read README.md and report its title"

A reply means OpenCode is using your local model. rapid-mlx agents opencode --test runs the full integration check, including a real headless task.

Install

$ npm install -g @opencode/cli@2

Config

rapid-mlx agents opencode --setup writes ~/.config/opencode/opencode.json. Start the server first so setup can detect the served model; to prepare offline, pass --model qwen3.5-4b-4bit --no-check. OpenCode 2.x uses the plural providers entry and the @opencode/ai/providers/openai-compatible package; setup also keeps a singular provider entry for 1.x compatibility. Run --dry-run to preview changes. Re-run setup after changing OpenCode major versions.

{
  "providers": {
    "rapid-mlx": {
      "package": "@opencode/ai/providers/openai-compatible",
      "name": "Rapid-MLX",
      "settings": {"baseURL": "http://localhost:8000/v1", "apiKey": "not-needed"},
      "models": {"qwen3.5-4b-4bit": {
        "name": "qwen3.5-4b-4bit",
        "limit": {"context": 32768, "output": 8192},
        "capabilities": {"tools": true, "input": ["text"], "output": ["text"]}
      }}
    }
  },
  "model": "rapid-mlx/qwen3.5-4b-4bit"
}

If the server requires an API key, export RAPID_MLX_API_KEY before setup; the config uses {env:RAPID_MLX_API_KEY}. If OpenCode is missing from PATH, use --agent-version 2.0.26 to choose the 2.x config shape.

Run

$ rapid-mlx serve qwen3.5-4b-4bit
$ opencode                                            # TUI
$ opencode run --standalone "add a --verbose flag to cli.py"          # headless one-shot
$ opencode models                                      # inspect provider models

Recommended aliases (per rapid-mlx agents opencode): qwen3-coder-30b-4bit, qwen3.5-9b-4bit, qwen3.6-35b-4bit, qwen3.5-4b-4bit.

Gotchas

• OpenCode 2.x uses opencode serve --service for its persistent background service. TUI, desktop, web and opencode run may connect to it.
• If opencode models is empty just after service startup, repeat it. If the list stays stale after setup, run opencode service restart and check opencode debug config.
• rapid-mlx agents opencode --test uses --standalone on 2.x to start and close a private headless test server.

Empirical

OpenCode 2.0.26 called read and returned a file marker through the local Qwen 3.5-4B server on 2026-10-11. The opencode row of the integration matrix is ✅ on Qwen 3.6, Gemma 4, and gpt-oss; DeepSeek R1-Distill XFAIL(arch) per the shared R1-Distill tool-emission gap. Source of truth for this page: TestOpenCode + rapid-mlx agents opencode.

See also