How to use MLX Harness.

1Install MLX Harness

You'll need a Mac with Apple Silicon and macOS 14.5 or later. The inference engine ships inside the app, so there's nothing else to install: download it, move MLX Harness to Applications and open it.

MLX Harness is a modified version of vMLX by JANGQ AI, released under the Apache License 2.0. The engine underneath is vMLX's, unchanged; MLX Harness changes the app around it and adds the Network page.

2Pick and download a model

Models come from Hugging Face, most of them in the MLX format from the mlx-community organization. Before you download, check what fits: Compare shows which models your Mac's memory holds and roughly how fast each writes.

1. Open Models and choose Find & download. Search, and sort by downloads, trending, likes, recently updated or model size; the search lists MLX models.
2. Click a model to read its README, then download it. Downloads run in the background, and Downloads shows their progress.
3. For gated models such as Llama, add your Hugging Face token in the HF Token: field first, and accept the model's licence on huggingface.co.
4. Library & tools lists the models on your Mac. Inspect Model shows a model's metadata, Diagnose Model runs health checks and Convert Model turns a Hugging Face model into a quantized MLX one: Balanced (4-bit), Quality (8-bit) or Compact (3-bit).

Downloads go to your Hugging Face cache folder unless you choose another under Download to:. MLX Harness also finds models already in that cache, in ~/.mlxstudio/models and in folders you add under Directories.

3Chat and images

Chat and reasoning

1. Open Chat & Images, pick a model in the chat toolbar's model menu, or Add local model. It starts with its detected defaults; advanced options stay in Servers & API.
2. Type a message. Reasoning models show their thinking in a separate box. Enable Thinking in the chat settings sets it to Auto, On or Off, and Reasoning Effort sets its depth for models that support it.
3. Vision models take images: drop a file on the chat or use the attach button. Video, audio and text files work with models that accept them.
4. Chats are saved in the sidebar and searchable. Settings are saved per model.

You can also chat with a model somewhere else: Connect remote endpoint takes any OpenAI-compatible API address. Only then do your prompts leave the Mac.

Generate and edit images

In Chat & Images, choose Image. Image models run through mflux, and the image server loads a model from a folder on your Mac: Find mflux models opens the image search in Models, then Load selected folder starts it.

Some image models, such as Flux Dev, are gated on Hugging Face and need your token and an accepted licence before they download.

4Agents and tools

MLX Harness can let a model act on your Mac. In the chat settings, turn on Enable Built-in Coding Tools and choose a Working Directory: every file operation and command runs inside it. Then switch tool categories on or off:

Max Tool Iterations caps how many rounds of tool calls one message can take (10 by default). Shell and file tools act on real files, so point the working directory at a project, not your home folder, and use a model you trust with it.

5Use it from other apps: the local API

Every model you start is served on your Mac. The API Gateway at http://localhost:8080 routes each request to the right model by the name in the request, and starts a stopped model when it's asked for. Each model also has its own port, from 8000 up. By default only your Mac can reach them; turning on LAN opens them to your network.

Behind the API, the engine caches what it has already read. With Continuous Batching on, the Prefix Cache lets a long chat or a coding agent's repeated instructions skip work on the next turn, KV Cache Quantization shrinks that cache, and Disk Cache (Persistent) keeps it on the SSD. These are in each model's server settings.

A request in the OpenAI format, with the model name the API page shows:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR-MODEL",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Any OpenAI SDK works with base_url set to http://localhost:8080/v1; the key can be any text unless you set one on the session. For coding agents, Coding Tool Integration sets up Claude Code, Codex CLI, OpenCode, OpenClaw and Hermes Agent with Auto-Configure, or shows a Manual Setup. For Claude Code, that means merging this into ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:8080",
    "ANTHROPIC_MODEL": "YOUR-MODEL",
    "ANTHROPIC_API_KEY": "mlxstudio"
  }
}

6The Network page, and MLX Node

Network shows MLX Network live from mlx.app: Macs online and working, tokens per second, AI tokens today and countries. It checks whether MLX Node is installed on this Mac and running, and opens it or links to the download. Type your wallet name under Your wallet and press Show to watch its mined MLX count up; the name is kept on this Mac only.

MLX Harness itself never mines. It runs models for you. MLX Node is the separate menu bar app that lends your Mac's idle time to MLX Network and earns MLX Tokens: up to 1 MLX a day on a free seat, locked for 30 days. If you use both, they share the same memory and GPU, so MLX Node's Memory MLX may use limit and manual Start and Stop keep it out of your way. MLX Tokens can lose value; read the risks.

7Questions

Is MLX Harness free?

Yes. It's free and licensed under the Apache License 2.0, like vMLX, the project it's built on.

When can I download MLX Harness?

Now. It's a free download at harness.mlx.app and mlx.app/download, for Apple Silicon Macs on macOS 14.5 or later. The source is on GitHub at github.com/MLXapp/studio.

Which Macs does MLX Harness run on?

Macs with Apple Silicon (M1 or later) and macOS 14.5 or later. Your Mac's memory decides which models fit; Compare on mlx.app shows them.

Does MLX Harness send my prompts anywhere?

No. Local models run on your Mac, and the API listens only on your Mac unless you turn on LAN. Prompts leave the Mac only if you connect a remote endpoint.

Does MLX Harness earn MLX Tokens?

No. MLX Harness runs models for you and only reads public network figures. MLX Node is the app that earns MLX Tokens for AI work.