Install

Overview

This setup uses these tools:

OpenCode as the coding agent
MTPLX as the local OpenAI-compatible model server
Headroom as an optional proxy in front of MTPLX
Docker to run Headroom without a separate Python install

Installation options

OpenCode

Recommended options:

Install script:

curl -fsSL https://opencode.ai/install | bash

Homebrew:

brew install anomalyco/tap/opencode

npm:

npm install -g opencode-ai

MTPLX

MTPLX ships as both a macOS native app (with a GUI) and a CLI — you can use either.

macOS app (GUI):

The app provides the same functionality as the CLI in a native window.
A .dmg is attached to every GitHub release.
Also available from mtplx.com.

CLI (recommended for automation / OpenCode integration):

Homebrew:
```
brew install youssofal/mtplx/mtplx
```
pip:
```
python3 -m pip install mtplx
```

Notes:

MTPLX requires Apple Silicon and macOS.
MTPLX exposes an OpenAI-compatible API that OpenCode can use directly.

Headroom

Recommended options:

Docker image:

docker pull ghcr.io/chopratejas/headroom:latest

Python package:

pip install "headroom-ai[all]"

npm package:

npm install headroom-ai

For this setup, the Docker image is the simplest option.

Docker

Install Docker Desktop on macOS from:

https://www.docker.com/products/docker-desktop/

This is needed if Headroom is run as a container.

What to install for a fresh start

Minimum setup:

Install OpenCode
Install MTPLX
Install Docker Desktop
Optionally install Headroom through Docker only

Setup

Goal

Set up a local AI workflow where:

OpenCode talks directly to MTPLX, or
OpenCode talks to Headroom, which proxies to MTPLX

Fresh-start setup order

Install OpenCode
Install MTPLX
Install Docker Desktop
Start and validate MTPLX
Add the OpenCode provider configuration
Optionally start Headroom and use the proxied provider

Step 1: prepare MTPLX

Use the MTPLX CLI or the macOS app (.dmg in each GitHub release) to install or configure a local model.

Typical CLI commands:

mtplx start

or API-server-only mode:

mtplx quickstart --profile sustained --port 8000

Useful commands:

mtplx status
mtplx models
mtplx tune --retune

Current local setup details:

CLI path: /opt/homebrew/bin/mtplx
Installed version: 1.0.4
API base URL: http://127.0.0.1:8000/v1
Current model path: /Users/depechie/.mtplx/models/Youssofal--Qwen3.6-27B-MTPLX-Optimized-Speed-FP16
Current model: qwen 3.6 27b optimized

Step 2: confirm the model details

The active local MTPLX model metadata shows:

Base trunk: mlx-community/Qwen3.6-27B-4bit
Precision variant: fp16
MTP depth max: 3
Recommended profile: sustained

The tuning metadata on this machine also shows:

Hardware: Apple M2 Pro
MTPLX version: 1.0.4

Step 3: configure OpenCode

The active user-level config is stored in:

~/.config/opencode/opencode.jsonc

Current config:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "mtplx": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "MTPLX (local)",
      "options": {
        "baseURL": "http://127.0.0.1:8000/v1"
      },
      "models": {
        "mtplx": {
          "name": "MTPLX"
        }
      }
    },
    "mtplx-headroom": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "MTPLX-Headroom",
      "options": {
        "baseURL": "http://127.0.0.1:8787/v1"
      },
      "models": {
        "mtplx": {
          "name": "MTPLX"
        }
      }
    }
  }
}

Step 4: use OpenCode directly with MTPLX

Use the mtplx provider when OpenCode should connect straight to the local model server.

Base URL: http://127.0.0.1:8000/v1
Provider name: MTPLX (local)
Model entry: mtplx

Flow:

OpenCode -> MTPLX -> qwen 3.6 27b optimized

Step 5: start Headroom

Start Headroom with Docker:

docker run --rm -p 8787:8787 ghcr.io/chopratejas/headroom:latest --host 0.0.0.0 --openai-api-url http://host.docker.internal:8000

Important detail:

The container image already uses headroom proxy as its entrypoint.
Only pass the extra flags in the Docker command.

Step 6: use OpenCode through Headroom

Use the mtplx-headroom provider when requests should be routed through Headroom.

Headroom URL: http://127.0.0.1:8787/v1
Upstream MTPLX URL from inside Docker: http://host.docker.internal:8000