Interactive MLX Server

Current version: v0.11

Interactive MLX Server is a menu-driven zsh script for macOS that helps you install MLX, manage MLX-compatible models, and run an mlx-lm server from one terminal interface. This repository is currently documented as version v0.11.

It is designed for Apple Silicon users who want a guided workflow instead of manually running multiple python3 and pip commands.

Features

• Checks whether python3 is installed and shows the current version.
• Detects whether mlx, mlx-lm, and huggingface_hub are installed.
• Checks for newer MLX package versions and offers guided updates.
• Uses ~/.cache/huggingface as the original default model location unless you change it.
• Lets you switch to ~/MLX-Models or set a custom folder for downloaded models.
• Downloads MLX-compatible Hugging Face models with progress output.
• Detects whether a downloaded model is compatible with the MLX text-generation server.
• Lets you choose a model to run with the MLX server.
• Starts and stops the MLX server from the script menu.
• Shows runtime status, including CPU use, memory usage, and best-effort macOS GPU stats.
• Removes downloaded models from the menu.
• Completely uninstalls the MLX stack and server tools if needed.
• Prompts to stop the MLX server when quitting if it is still running.

Requirements

• macOS on Apple Silicon
• zsh
• python3
• Internet access for package installs, update checks, and model downloads
• MLX-compatible Hugging Face model repositories for server use

Quick Start

Clone or copy the project files into a folder, then run:

chmod +x interactive-mlx-setup.zsh
./interactive-mlx-setup.zsh

If you prefer, you can also run:

zsh interactive-mlx-setup.zsh

Usage Example

Typical first-use flow:

1. Launch the script.
2. Let it check python3, mlx, and mlx-lm.
3. Choose whether to keep ~/.cache/huggingface, switch to ~/MLX-Models, or enter a custom model folder.
4. Select the download menu option when you want to add a model.
5. Paste a Hugging Face model name when prompted.
6. Choose a compatible server model and start the MLX server.

Example:

./interactive-mlx-setup.zsh

Download Model Example

To find MLX-compatible models, visit mlx-community models.

When the script asks for a Hugging Face URL or repo id, copy the model name from Hugging Face and paste it directly into the prompt.

Example model name:

mlx-community/Llama-3.2-3B-Instruct-4bit

Example interaction:

Choose an option: 5
Hugging Face URL or repo id (q to quit): mlx-community/Llama-3.2-3B-Instruct-4bit

You can paste either:

• A full Hugging Face URL
• A repo id such as mlx-community/Llama-3.2-3B-Instruct-4bit

What The Script Does

When launched, the script will guide you through:

1. Checking the local python3 installation.
2. Detecting MLX package status.
3. Installing or updating mlx, mlx-lm, and huggingface_hub.
4. Choosing a model storage folder.
5. Listing existing model downloads.
6. Downloading new MLX-compatible models from Hugging Face.
7. Validating whether a model can be used by the MLX server.
8. Starting, stopping, and monitoring the MLX server.

Home Menu

The script currently includes these menu actions:

1. Show Python and MLX status
2. Install or update MLX
3. Set model folder
4. Show downloaded models
5. Download MLX model from Hugging Face
6. Choose model for MLX server
7. Start MLX server
8. Show running server details
9. Stop running server
10. Remove downloaded model
11. Completely uninstall MLX and server
12. q to quit

Model Notes

• Not every MLX-converted model is usable with the mlx-lm text-generation server.
• Embedding-style models such as bge families are useful for retrieval or embeddings, but they are not valid chat/completion server models.
• For server use, choose supported text-generation or instruct models such as Llama, Qwen, Gemma, Mistral, and other model families supported by your installed mlx-lm version.

Runtime Notes

• The script uses python3 explicitly for macOS compatibility.
• The original default model folder is ~/.cache/huggingface.
• On startup, the script offers Y to use ~/MLX-Models, N to keep ~/.cache/huggingface, or C to enter a custom path.
• Memory output is shown in a human-readable format.
• GPU stats on macOS are best-effort and come from ioreg, so they may vary by system and OS version.
• The script stores local configuration and server state in ~/.interactive-mlx-setup/ when possible, with a local fallback if needed.
• The script accepts q in prompts and can also ask whether to stop the running MLX server before quitting.

Project Files

• interactive-mlx-setup.zsh Main interactive script.
• README.md Usage and feature overview.
• LICENSE MIT license for free use and modification.
• GitWorkflow.md Separate Git and GitHub publishing notes.
• .gitignore Ignore rules for local state and machine-specific files.

Git and GitHub upload instructions have been moved to GitWorkflow.md so the main README stays focused on usage.

Credits

• Script workflow built around MLX and mlx-lm
• Script header note states it was generated and edited with the Codex App