easy-mlx

Run local AI models on Apple Silicon with MLX in minutes.

---

easy-mlx is a lightweight developer platform for running MLX-based large language models locally on macOS. It installs MLX automatically, manages models, and provides both a CLI and OpenAI-compatible API.

---

⚡ Quickstart (macOS)

# 1. Clone the repository
git clone https://github.com/instax-dutta/easy-mlx
cd easy-mlx

# 2. Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 3. Install the package
pip install -e ".[mlx]"

# 4. Setup the platform
easy-mlx setup

# 5. Download a model
easy-mlx download tinyllama

# 6. Start chatting!
easy-mlx chat tinyllama

That's it! A model can run locally in a few minutes.

---

📋 Prerequisites

• Apple Silicon Mac (M1, M2, M3, M4) - arm64 architecture
• macOS 12.0+ (Monterey or later)
• Python 3.10+ (via Homebrew or python.org)
• Homebrew (recommended for installing Python)

Installing Python on macOS

If you don't have Python 3.10+ installed:

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python3

# Verify installation
python3 --version

---

🚀 Installation

1. Clone the repository

git clone https://github.com/instax-dutta/easy-mlx
cd easy-mlx

2. Create a virtual environment (Recommended)

It's best to use a virtual environment to avoid conflicts with other Python projects:

# Create virtual environment
python3 -m venv .venv

# Activate it
source .venv/bin/activate

# You should see (.venv) at the beginning of your terminal prompt

Tip: To deactivate the environment when done, simply run:

deactivate

3. Install easy-mlx

# Basic installation (CLI only)
pip install -e .

# With MLX dependencies (recommended)
pip install -e ".[mlx]"

# With API server
pip install -e ".[api]"

# With everything (MLX + API + dev tools)
pip install -e ".[all]"

---

💻 Setup & Usage

Initial Setup

# Activate your virtual environment (if not already active)
source .venv/bin/activate

# Run setup to verify your system
easy-mlx setup

This will:

• ✅ Check your hardware (Apple Silicon required)
• ✅ Create model directory (~/mlx_models)
• ✅ Create log directory (~/mlx_platform_logs)
• ✅ Verify/install MLX dependencies

Available Commands

Command	Description
easy-mlx setup	Initialize the platform and verify hardware
easy-mlx models	List all available models
easy-mlx download <model>	Download a model to local storage
easy-mlx chat <model>	Start an interactive chat session
easy-mlx serve	Start the API server
easy-mlx benchmark <model>	Run performance benchmarks
easy-mlx agent run	Run agent mode with tool usage
easy-mlx info	Show platform and system information

Shortcut Commands

All of these also work:

mlx setup          # Short alias
mlx-platform setup # Full name

---

🧠 Supported Models

Model	Size	RAM Required	Best For
TinyLlama	1.1B	~2.5GB	Quick inference, testing
OpenELM	1.1B	~2.2GB	Apple-optimized
Phi-2	2.7B	~3.0GB	Reasoning tasks
Qwen	1.8B	~3.5GB	Multilingual
Gemma	2B	~4.0GB	High quality
Mistral	7B	~6.0GB	High performance (16GB+)

All models are selected to work well on MacBook Air 8GB systems.

---

🌐 API Server

Start the API server:

easy-mlx serve

Then make requests:

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

The API is compatible with OpenAI-style clients:

import requests

response = requests.post("http://localhost:8080/v1/chat/completions", json={
    "model": "tinyllama",
    "messages": [{"role": "user", "content": "Explain gravity simply"}]
})

print(response.json()["choices"][0]["message"]["content"])

---

💻 Python Usage

from mlx_platform.core.orchestrator import create_orchestrator

# Initialize
orchestrator = create_orchestrator()
orchestrator.start()

# Load model
orchestrator.load_model("tinyllama")

# Generate
result = orchestrator.generate("What is Python?")
print(result.text)

---

🔧 Development

# Activate virtual environment
source .venv/bin/activate

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
python -m pytest tests/

# Validate platform
python scripts/validate_platform.py

# Format code
black mlx_platform/

# Type check
mypy mlx_platform/

---

⚠️ Troubleshooting

"command not found: easy-mlx"

Make sure your virtual environment is activated:

source .venv/bin/activate

"Apple Silicon required"

easy-mlx only works on Apple Silicon Macs (M1, M2, M3, M4). Intel Macs are not supported.

Memory issues

If you run out of memory, try a smaller model:

easy-mlx download tinyllama  # 2.5GB RAM
# instead of
easy-mlx download mistral   # 6GB+ RAM

Check what your system can handle:

easy-mlx info

---

📜 License

MIT License - see LICENSE

---

🔗 Links

• Documentation: docs/
• Issues: https://github.com/instax-dutta/easy-mlx/issues
• Discussions: https://github.com/instax-dutta/easy-mlx/discussions

---

easy-mlx - Run local AI on your Mac in minutes.