<!-- llms-explorer concept facts · https://llms-explorer.com/tree/mlx-launch-jaccl-backend-flags-and-hostfile-coor/ · pack 2026-10-05 · ~655 tokens -->

# mlx.launch jaccl backend flags and hostfile coordinator handling

> Backend selection falls back from `--backend` to the hostfile backend field, then to nccl when CUDA is available, else ring

Parent: [Mac local LLMs: Clusters, RDMA, exo and ds4](https://llms-explorer.com/tree/mac-local-llms-clusters-rdma-exo-ds4/) · 1 facets · 10 facts · page: https://llms-explorer.com/tree/mlx-launch-jaccl-backend-flags-and-hostfile-coor/

## Facts

- Backend selection falls back from `--backend` to the hostfile backend field, then to nccl when CUDA is available, else ring — [source](https://raw.githubusercontent.com/ml-explore/mlx/main/python/mlx/_distributed_utils/launch.py)
- `launch_jaccl` sets `MLX_JACCL_COORDINATOR` to the first IP of rank 0 plus `--starting-port` (default 32323) — [source](https://raw.githubusercontent.com/ml-explore/mlx/main/python/mlx/_distributed_utils/launch.py)
- The launcher errors if rank 0 lists no IP, if rdma list length differs from host count, or if a host's own rdma slot is not null — [source](https://raw.githubusercontent.com/ml-explore/mlx/main/python/mlx/_distributed_utils/launch.py)
- For jaccl-ring the launcher checks only neighbour pairs (i-1) mod n and (i+1) mod n; for jaccl mesh it checks all pairs — [source](https://raw.githubusercontent.com/ml-explore/mlx/main/python/mlx/_distributed_utils/launch.py)
- `jaccl-ring` sets `MLX_JACCL_RING=1`; both modes write the rdma matrix to a remote temp file exported as `MLX_IBV_DEVICES` — [source](https://raw.githubusercontent.com/ml-explore/mlx/main/python/mlx/_distributed_utils/launch.py)
- The remote launch script exports `--env` entries in order, then temp-file variables, then `MLX_RANK`, and finally `exec`s the command — [source](https://raw.githubusercontent.com/ml-explore/mlx/main/python/mlx/_distributed_utils/launch.py)
- Hostfile `envs` are prepended to `--env`, so command-line values override them — [source](https://raw.githubusercontent.com/ml-explore/mlx/main/python/mlx/_distributed_utils/launch.py)
- `--connections-per-ip` is read only by the ring backend launcher, not by the JACCL one — [source](https://raw.githubusercontent.com/ml-explore/mlx/main/python/mlx/_distributed_utils/launch.py)
- Wrapping `mlx_lm share` in `mlx.launch` hangs or fails silently according to the mlx-lm issue 955 author, who says its built-in launcher must be used — [source](https://github.com/ml-explore/mlx-lm/issues/955)
- The MLX docs recommend `mlx.distributed_config --auto-setup --backend jaccl --over thunderbolt` to produce the hostfile — [source](https://ml-explore.github.io/mlx/build/html/usage/distributed.html)
