# Run One Large LLM Across Several Macs with MLX: Lesson 03. Test the link before loading weights

Lesson id: `mlx-distributed-mac-cluster/03-test-the-link-first`
Human lesson: https://edgefde.dev/courses/mlx-distributed-mac-cluster/03-test-the-link-first.html

## Goal

Prove the cluster link works and record latency and bandwidth before loading any model.

## Prerequisites

- Lessons 01 and 02 done
- `check_link.py` at the same path on every Mac

## Inputs

- `jaccl.json`
- Expected number of Macs

## Outputs and artifacts

- Local ring test output
- Cluster JACCL test output saved as a baseline

## Steps

1. Copy `check_link.py` to `~/mlx-cluster/` on every Mac.
2. Run the local test: `EXPECTED_WORLD_SIZE=2 CHECK_BACKEND=ring uv run mlx.launch -n 2 --backend ring --python "$PWD/.venv/bin/python" check_link.py`.
3. Run the cluster test: `uv run mlx.launch --verbose --hostfile jaccl.json --backend jaccl --env EXPECTED_WORLD_SIZE=N --env CHECK_BACKEND=jaccl --python ~/mlx-cluster/.venv/bin/python check_link.py`.
4. Confirm the line `ok: N ranks, all_sum correct` appears. Do not rely on the exit code.
5. Save the timing lines with the date, macOS build, MLX version, and cable layout.

## Constraints

- Do not load a model until the test passes.
- Do not report JACCL numbers you did not measure.

## Acceptance checks

- Output contains `ok: N ranks`.
- Baseline file exists with versions and timings.

## Key concepts

- A broken link fails at `mx.distributed.init()`, before any weights load.
- `all_sum` with known inputs gives a correctness check: the result must be 1 + 2 + ... + N.
- `mlx.launch` can return 0 even when ranks fail, so check the output text.
- Small-message time is latency (matters for tensor). Large-message time is bandwidth.

## Takeaways

- Run `check_link.py` locally, then on the cluster, before every model launch.
- Pass variables with `--env` and the interpreter with `--python`.
- Keep a baseline per cable layout and compare after every change.