MLXSmith

Fine-tune language models on Apple Silicon.

MLXSmith is a training toolkit built on MLX that brings supervised fine-tuning, preference optimization, reinforcement learning, knowledge distillation, and model serving to your Mac. Every training algorithm runs natively on the Metal GPU — no cloud required.

Status: Alpha (v0.1.9). Validated on Qwen3-4B and Qwen3-1.7B.

Installation

Requirements: macOS with Apple Silicon (M1 or later) and Python 3.10+. Data tools, configuration, and project scaffolding work on any platform.

pip install "mlxsmith[all]"

Install only what you need

# Core only — data tools, config, scaffolding (any platform)
pip install mlxsmith

# Training on Apple Silicon
pip install "mlxsmith[mlx,llm]"

# Training + serving
pip install "mlxsmith[mlx,llm,serve]"

Quick Start

# Create a project
mlxsmith init myproj && cd myproj

# Verify your environment
mlxsmith doctor

# Download a model
mlxsmith pull mlx-community/Qwen3-4B-Instruct-2507-4bit

# Download training data
mlxsmith data pull --preset alpaca

# Fine-tune with LoRA
mlxsmith sft \
  --model cache/mlx/mlx-community__Qwen3-4B-Instruct-2507-4bit \
  --data data/sft

# Serve the result
mlxsmith serve --model runs/sft_0001/adapter --port 8080

See Getting Started for a complete walkthrough.

Training

MLXSmith supports the full model improvement pipeline — from supervised learning through reinforcement and distillation.

Mode	Command	Data Format	Description
SFT	mlxsmith sft	{prompt, response}	Supervised fine-tuning with LoRA/QLoRA
Preference	mlxsmith pref	{prompt, chosen, rejected}	DPO, ORPO, IPO, CPO, SimPO, TDPO
KTO	mlxsmith kto	{prompt, response, label}	Binary good/bad feedback
GRPO	mlxsmith rft	Environment + verifier	Reward-driven reinforcement learning
Online DPO	mlxsmith online-dpo	{prompt}	Live preference tuning with LLM judge
Self-Verify	mlxsmith self-verify	{prompt}	Policy gradient from self-assessed rewards
Distillation	mlxsmith distill	{prompt}	Teacher-to-student knowledge transfer
Pipeline	mlxsmith pipeline	Combined	Chain SFT, preference, RFT, and RLM stages

See Concepts for an explanation of each training mode.

Tools

Tool	Command	Description
Data	mlxsmith data	Import, split, validate, and download datasets
Synthetic	mlxsmith synthetic	Generate and evolve training data
Eval	mlxsmith eval	Run evaluation suites with pass@k metrics
Bench	mlxsmith bench	Benchmark inference and training throughput
Serve	mlxsmith serve	OpenAI-compatible API server with streaming
RLM	mlxsmith rlm	Recursive self-improving training loop

External Model Backends

Use cloud models for data generation and judging while keeping training local on Apple Silicon.

CLI backend — shell out to Codex, Claude, or Gemini:

export MLXSMITH__MODEL__BACKEND=cli
export MLXSMITH_CLI_CODEX_CMD='codex exec --full-auto --model gpt-5.2'

mlxsmith synthetic prompts \
  --model codex \
  --seed-prompts data/seeds.jsonl \
  --num 100 \
  --out data/prompts.jsonl

OpenAI backend — any OpenAI-compatible API:

export MLXSMITH__MODEL__BACKEND=openai
export OPENAI_API_KEY="sk-..."

mlxsmith synthetic prompts \
  --model gpt-4o \
  --out data/prompts.jsonl

Training commands (sft, pref, rft, rlm) still require a local MLX backend.

Web Dashboard

MLXSmith includes a Next.js dashboard for managing models, training runs, evaluation, chat, and serving.

# Terminal 1: start the API
mlxsmith serve --model <model-or-adapter> --port 8080

# Terminal 2: start the dashboard
cd apps/web && npm install && npm run dev

A native macOS app is also available under apps/macos/.

Architecture

src/mlxsmith/
├── cli.py                  # CLI entry point (Typer)
├── config.py               # Pydantic config with env/file/CLI precedence
├── train/                  # Training algorithms (SFT, DPO, GRPO, KTO, ...)
├── rlm/                    # Recursive language model training loop
├── llm/                    # Backend abstraction (MLX, OpenAI, CLI, mock)
├── verifiers/              # Reward verifiers (regex, pytest, JSON schema, LLM judge, ...)
├── sdk/                    # Loss registry, training/sampling clients
├── api/                    # FastAPI handlers and schemas
├── orchestrator/           # Multi-process job scheduling
├── envs/                   # Environment plugin system
└── server.py               # OpenAI-compatible serving

Configuration

MLXSmith uses a layered configuration system. Settings are resolved in order of precedence:

1. CLI arguments (highest)
2. Config file (YAML, TOML, or JSON)
3. Environment variables (MLXSMITH__SECTION__KEY)
4. Defaults

# Show resolved configuration
mlxsmith config show

# Create a default config file
mlxsmith config init mlxsmith.yaml

# Validate a config file
mlxsmith config validate mlxsmith.yaml

See Configuration for the full reference.

Documentation

Section	Description
Getting Started	Installation and first training run
Concepts	Training modes explained
CLI Reference	All commands with examples
Configuration	Config system and options
Verifiers	Verifier API and composition
Environments	Task environment plugins
Project Format	Run artifacts and directory layout
Compatibility	Tested versions and models
Troubleshooting	Common issues and fixes
FAQ	Frequently asked questions

Contributing

See CONTRIBUTING.md for development setup, coding standards, and pull request guidelines.

License

MLXSmith is released under the MIT License.