Installation

You need an Apple Silicon Mac running macOS 14 or later. Choose a standalone bundle, npm launcher, or source checkout.

Direct download (recommended)

No Homebrew, Bun, or git — just curl the install script. It downloads the signed, notarized self-contained binary from the latest release and puts mlx-bun on your PATH:

curl -fsSL https://mlx-bun.dev/install.sh | sh
mlx-bun

The bundle includes the executable and MLX runtime and is signed and notarized. It installs to ~/.mlx-bun by default — override with MLX_BUN_INSTALL_DIR, or pin a release with MLX_BUN_VERSION=v0.0.8.

Homebrew

A self-contained, signed + notarized binary — no toolchain to install by hand:

brew install joshuarossi/tap/mlx-bun
mlx-bun

That’s the whole thing. The bottle already bundles the MLX native runtime, so the native runtime does not need a separate first-run download. Upgrade later with brew upgrade mlx-bun.

bunx (no install)

Already have Bun ≥ 1.4.0? Run it straight from npm, nothing to install:

bunx mlx-bun

First run fetches the MLX native runtime (~52 MB) and the model into your caches, then serves.

Note

mlx-bun is Bun-only by design — npx mlx-bun under Node exits with a “requires Bun” notice. Use bunx.

From source

For development, or to use the library from a clone. Needs Bun ≥ 1.4.0 — no Python, no native library to install by hand:

# 1. Install Bun
curl -fsSL https://bun.sh/install | bash
exec $SHELL -l

# 2. Clone, install, link the CLI
git clone https://github.com/joshuarossi/mlx-bun.git && cd mlx-bun
bun install
bun run link-cli      # adds the `mlx-bun` command — or run `bun src/cli.ts <verb>`

# 3. Run it
mlx-bun

What happens on first run

Bare mlx-bun is an alias for mlx-bun serve. With no model named, it does everything for you:

1. pulls the MLX native runtime (~52 MB) into ~/Library/Caches/mlx-bun/ (skipped on the Homebrew/direct-download installs — the runtime ships in the bundle);
2. downloads the sub-GB MiniCPM5-1B starter and serves it; download time depends on your connection;
3. starts downloading gemma-4-e4b (the stronger 4B model) in the background — it becomes the default on your next mlx-bun serve, on a 16 GB+ Mac;
4. opens the chat UI in your browser at http://localhost:8080/#/chat (pass --no-open to skip).

Next: the Quickstart.