📦 Installation

1. Download MLXForge.dmg (24 MB).
2. Open the DMG and drag MLX Forge into Applications.
3. Launch it — on first run the app provisions its managed Python runtime automatically (via uv). No Terminal, no conda, no pain.

🧭 Core concepts

MLX Forge covers the full model lifecycle: Discover → Convert → Quantize → Evaluate → Fine-tune → Generate → Serve → Monitor → Deploy. Three ideas hold it together:

• No-code at the start, full code at the end. Every visual action can emit the equivalent reproducible code — Python mlx-lm, Swift MLX, CLI, or curl. Click around to learn; export code to productionize.
• The UI is a lens over a scriptable engine. A central orchestrator routes every job (conversion, training, serving) to the right runtime and owns the queue and progress — the interface just observes it.
• Managed runtimes. Python environments are created and supervised by the app through uv; the app talks to them over JSON-RPC. You never manage a venv by hand.

Navigate everything with the command palette — ⌘K.

🧮 Will it fit? — interactive calculator

Unified memory is the budget that matters on Apple Silicon. Estimate the footprint of a model before you download or quantize it:

🔎 Discover & Model Library

The Discover view browses the Hugging Face hub in-app: search by name, filter by architecture and size, then pull a model with a resumable download. Everything lands in the Model Library — your single organized inventory of base models, quantized variants and fine-tuned adapters, with disk usage and lineage for each.

⚗️ Convert & Quantize

The Conversion Studio turns compatible checkpoints into MLX format; the Quantization Studio then compresses them. Pick a bit-width, watch the size/quality trade-off, and read the exact command it maps to:

from mlx_lm import convert

convert(
    hf_path="Qwen/Qwen3-14B",
    mlx_path="./qwen3-14b-4bit",
    quantize=True,
    q_bits=4,
    q_group_size=64,
)

mlx_lm.convert \
  --hf-path Qwen/Qwen3-14B \
  --mlx-path ./qwen3-14b-4bit \
  -q --q-bits 4 --q-group-size 64

That code block above? That's the point — the studio generated it from your clicks. Paste it in CI and the run is reproducible forever.

📊 Evaluate

Before committing to a quantization, measure it. The Evaluation studio runs perplexity and benchmark suites against any model in your library and puts variants side by side:

• Perplexity on standard corpora or your own text.
• Throughput (tokens/sec, prompt vs generation) on your hardware.
• A/B comparisons: bf16 vs 8-bit vs 4-bit of the same base model.

Rule of thumb: 4-bit with group size 64 costs ~1–3% perplexity on most 7B+ models — usually invisible in chat, always visible in your RAM meter.

🎛️ Fine-tune (LoRA)

The Fine-tuning studio trains LoRA adapters on your own data with live loss curves and checkpointing — the Datasets view handles importing, inspecting and splitting your training data first.

mlx_lm.lora \
  --model ./qwen3-14b-4bit \
  --train --data ./my-dataset \
  --batch-size 2 --num-layers 16 --iters 1000 \
  --adapter-path ./adapters/support-bot

{"messages": [{"role": "user", "content": "…"},
               {"role": "assistant", "content": "…"}]}

Adapters live in the Model Library next to their base model — fuse them or load them dynamically in the Playground and the server.

🧪 Playground

Chat and completion against any local model with full control: system prompt, temperature, top-p, max tokens, repetition penalty. Compare models side by side, and export any session as code. The Vision Lab, Image Studio and Audio Studio extend the same idea to multimodal models.

🌐 OpenAI-compatible server

ForgeServer exposes any model on an OpenAI-compatible HTTP/SSE endpoint with generated API keys (mlxf-…). The wire format is transcribed from the OpenAI OpenAPI specification and verified two ways: a golden test with the unmodified openai Python SDK completing a streamed chat, and structural golden-file comparison of response bodies.

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8080/v1", api_key="mlxf-…")
stream = client.chat.completions.create(
    model="qwen3-14b-4bit",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer mlxf-…" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3-14b-4bit", "stream": true,
       "messages": [{"role": "user", "content": "Hello!"}]}'

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:8080/v1",
  apiKey: "mlxf-…",
});
const stream = await client.chat.completions.create({
  model: "qwen3-14b-4bit", stream: true,
  messages: [{ role: "user", content: "Hello!" }],
});

Manage everything from the Servers view: start/stop endpoints, rotate keys, watch request logs live.

🖥️ Cluster & deploy

The Cluster view discovers other Macs on your network via Bonjour (ForgeCluster) and fans work out to them — turn a desk of Apple Silicon machines into one lab. The Pipelines view chains stages (convert → quantize → evaluate → serve) into repeatable recipes, and Projects keeps each experiment's models, datasets and runs together.

📈 Monitoring & Metal Lab

• Live serving metrics — tokens/sec, time-to-first-token, request logs, memory pressure.
• Profiler — where the milliseconds go across prompt processing and generation.
• Metal Lab — GPU-level inspection for the performance-obsessed: kernel timings and memory bandwidth on your exact chip.

👨‍💻 Code generation

Every studio has an Export code action producing the exact equivalent of what you just did visually, in four dialects:

This is the app's core philosophy: the GUI teaches you the tool; the generated code makes it reproducible.

🏛️ Architecture

For the curious — the app is a thin SwiftUI layer over a scriptable engine:

MLXForge.app (SwiftUI)  —  Features → ViewModels → ForgeCore protocols
        │
  LocalOrchestrator (actor) — routes every job, owns queue & progress
   ├── ForgeEngine   MLX Swift inference (in-process)
   ├── ForgeBridge   Python runtimes over JSON-RPC 2.0 (unix socket)
   ├── ForgeServer   OpenAI-compatible HTTP/SSE (Hummingbird 2)
   └── ForgeCluster  remote Macs via Bonjour
        │
  forge_runtime (Python) — mlx, mlx-lm… one process per env,
                           spawned & supervised by the app

• UI code lives only in the app's Features layer (MVVM) — everything reusable is a Swift package.
• Python processes are spawned and supervised by the app; if one dies, the orchestrator restarts it.
• The server is verified against golden files and the real OpenAI SDK on every change.

🧰 CLI & Python SDK

MLX Forge ships two programmatic companions:

• mlxlab CLI (Swift) — drive the lab from the shell: list models, launch jobs, query servers.
• Python SDK (mlxlab) — talks to the app's local API for scripted workflows and integration into your existing tooling.

import mlxlab

lab = mlxlab.connect()          # talks to the running app
for model in lab.models.list():
    print(model.name, model.size_gb)

❓ FAQ