Connect your Mac

Install the Azul agent on an Apple Silicon Mac. Covers what a Mac can and can't run.

An Apple Silicon Mac can train and serve models like a Linux machine with an NVIDIA GPU, and it connects with the same command. No Docker is involved. Azul runs directly on macOS using MLX, Apple's machine-learning framework, and the GPU shares the Mac's regular memory.

Requirements

Your Mac needs:

  • Apple Silicon (M1 or newer). Intel Macs aren't supported.
  • macOS 14 or newer. macOS 15 or newer is recommended, because it lets large models use more memory. See Training large models.
  • Python 3.11 to 3.14, built for Apple Silicon. The Python that comes with the Xcode command line tools is too old. If you have Homebrew and Python is the only missing requirement, the installer offers to run brew install python@3.12. A Python from python.org works too.
  • At least 20 GB of free disk space in your home folder, for the Python environment and the models.
  • Outbound HTTPS to azulai.dev. Nothing connects inbound to your Mac, so there are no ports to open.

You don't need Docker or sudo.

Memory. Azul works best on Macs with 64 GB or more. With less, the Mac still connects, but only small models fit. The installer tells you when that's the case.

Get your connect command

  1. In Azul, open Settings and find the Connect infrastructure card.
  2. Click Generate connect command, or reuse the one you already have for your other machines. The command contains your account's token:
curl -fsSL https://azulai.dev/install.sh | bash -s -- azen_XXXXXXXXXXXXXXXX https://azulai.dev

Install the agent

Open Terminal on the Mac and paste the command. Don't use sudo, and don't run it over SSH. The agent only runs while you're logged in, so you need to be logged in at the Mac itself. Screen Sharing is fine.

The installer:

  1. Checks the requirements above and lists every missing one at once. It writes nothing until every check passes.
  2. Writes its setup to ~/azul-workstation: a settings file with your token, a startup script, a work folder for models, and a logs folder.
  3. Registers the agent with macOS (launchd), so it starts when you log in and restarts if it stops.

The first start builds a Python environment and downloads the agent, which takes a few minutes.

Confirm it's online

In Settings, the Mac appears under Connect infrastructure, named after its hostname. It shows Connecting, then Online. The line under it reads something like Apple M1 Max · 52 GiB usable · MLX.

"Usable" is the memory macOS lets the GPU use, about 80 percent of the Mac's RAM. Azul uses that number to decide which runs fit.

From then on, the Mac is listed under Where to train on the training page, like any other machine.

Keep it awake and logged in

The agent only works while you're logged in and the Mac is awake.

During a training run, the agent keeps the Mac from falling asleep when it's idle. Closing a laptop's lid still puts it to sleep, unless it's plugged in and connected to an external display.

Nothing keeps the Mac awake for serving. If you deploy a model to your Mac, turn off automatic sleep in System Settings > Energy (Battery on a laptop).

If the Mac restarts, it stays Offline until someone logs in. If nobody usually sits at the Mac, turn on automatic login in System Settings > Users & Groups. Logging out stops the agent. Locking the screen doesn't.

While the Mac is asleep or logged out, Settings shows it as Offline, and runs started for it wait as Pending for up to a day.

What a Mac can train

A Mac can run LoRA and full fine-tunes on datasets you upload, and LoRA on a 4-bit base. Qwen and Llama models are the most tested. The result is a normal full-precision (bf16) model, the same as from an NVIDIA machine. You can download it, push it to Hugging Face, or deploy it to any of your machines.

Before a run starts, the Mac checks that the run fits in memory. If it doesn't, the run stops within seconds and suggests what to change: a smaller model, a 4-bit base, a shorter max length or a smaller batch size. You find out right away, not an hour in when the Mac slows to a crawl.

These don't work on a Mac yet. If you pick one, the run doesn't start, and the training page says why:

  • DPO, including Improve with feedback.
  • Full fine-tunes on top of a 4-bit base.
  • Datasets that pull from connected sources like GitHub. Upload the data instead.
  • Prepare for refinement.

For Serving quantization, a Mac offers Auto, bf16 and MLX 4-bit. MLX 4-bit saves a smaller copy of the model that answers faster, especially on M1 and M2 chips. Azul keeps the full-precision model too.

Serving on a Mac

Deploying to a Mac works the way Deploy and chat with your model describes, with these differences.

A Mac has no GPU map. Its one GPU does both training and serving, so there's nothing to assign.

A Mac can train or serve, not both at once. While it's serving a model, new runs for it wait, and the training page says why. To let them start, press Stop on the Mac's serving row in Settings. You also can't deploy to a Mac while it's training.

The first deploy is quicker than on Linux, because there's no serving software to install. The model is usually up in a minute or two.

By default, only the Mac itself can reach the model. To use it from other computers on your network, set AZUL_SERVE_BIND=0.0.0.0 in ~/azul-workstation/.env and run the connect command again. It listens on port 8000 unless you set AZUL_SERVE_PORT in the same file.

Training large models

On macOS 15 or newer, you can let the GPU use more of the Mac's memory than it normally would. If a run comes close to the limit, its Training Logs show a warning with the command to run. It looks like this:

sudo sysctl iogpu.wired_limit_mb=57344

The change lasts until the Mac restarts. It also leaves less memory for everything else, so quit other big apps while the run trains.

On a 192 GB or 256 GB Mac, try a 32B LoRA before a 70B. A finished 70B model is about 140 GB. The Mac uploads that much when the run ends, and the same amount downloads wherever you deploy it.

Everyday use

Updates

The agent updates itself between runs. There's nothing for you to do.

Logs

To follow what the agent is doing:

tail -f ~/azul-workstation/logs/agent.log ~/azul-workstation/logs/launchd.log

Stop the agent

launchctl bootout gui/$(id -u)/dev.azulai.agent

Run the connect command again to start it back up.

Removing your Mac

First remove it in Settings. Then stop the agent with the command above, and delete ~/azul-workstation and ~/Library/LaunchAgents/dev.azulai.agent.plist. If you connected it with the same command you use for your other machines, generate a new one too. Otherwise the Mac can add itself back.

Troubleshooting

The installer says Python is missing. Install it with Homebrew (brew install python@3.12) or from python.org, then paste the command again. In a terminal running under Rosetta, the installer still finds the right Python, as long as it's an Apple Silicon build.

"launchd would not start the agent." The command was most likely run over SSH, where there's no login session. Run it in Terminal on the Mac itself, or over Screen Sharing.

The Mac never shows up in Settings. Check the logs (see Logs above). The usual cause is a connect command that was replaced after you copied it. Generate a new one and run it again. Otherwise, the Mac can't reach azulai.dev.

It shows Offline. The Mac is asleep or logged out, or it lost its network connection. Wake it and log in. It reconnects on its own.

A run sits in Pending. The Mac is Offline, or it's busy serving a model. Bring it back online, or stop serving in Settings.

A run failed with "This run needs about N GB of memory." The model doesn't fit this Mac. Turn on LoRA, set Base Quantization to 4-bit, lower the max length or the batch size, or pick a smaller model.