omarchy-cluster
Runs one local model across networked machines as one OpenAI-compatible endpoint.
Tested on macOS and Linux
Use it
macOS arm64
You need first
- Runtimes:
Python 3.9+ - System packages:
Avahi,dns-sd - Needs the network
create venv ~/mlx and pip install mlx mlx-lm omarchy-cluster from git
python3 -m venv ~/mlx && ~/mlx/bin/pip install --upgrade pip && ~/mlx/bin/pip install mlx mlx-lm git+https://github.com/joshuaswarren/omarchy-cluster.gitsymlink binary to ~/.local/bin and verify --help works
mkdir -p ~/.local/bin && ln -sf ~/mlx/bin/omarchy-cluster ~/.local/bin/omarchy-cluster && omarchy-cluster --help
Check that it works
omarchy-cluster --version
The output should contain “0.3.2”.
First thing to try
omarchy-cluster discover
Run omarchy-cluster discover to find cluster nodes on your network.
Linux x86_64
You need first
- Runtimes:
Python 3.9+ - System packages:
Avahi,dns-sd - Needs the network
Install omarchy-cluster via venv pip and expose on PATH
python3 -m venv ~/.local/share/omarchy-cluster/venv && ~/.local/share/omarchy-cluster/venv/bin/pip install --quiet git+https://github.com/joshuaswarren/omarchy-cluster.git && ln -sf ~/.local/share/omarchy-cluster/venv/bin/omarchy-cluster ~/.local/bin/omarchy-cluster && ~/.local/bin/omarchy-cluster --help
Check that it works
omarchy-cluster --versionThe output should contain “0.3.2”.
First thing to try
omarchy-cluster discoverRun omarchy-cluster discover to find cluster nodes on your network.
What it does
- Run one local model across several networked machinesNot tested
- Serve the cluster as an OpenAI-compatible endpointNot tested
- Find nodes over mDNS and test routes between themNot shown working
How far pickfit got
macOS arm64
- Installs
- Starts
- 0 of 3 features work
- Works offline
Linux x86_64
- Installs
- Starts
- 0 of 3 features work
- Works offline
Other systems
Good for
- Serve a split model as one OpenAI-compatible endpoint on :8020
- Find cluster nodes over mDNS
- Measure every node pair to pin fastest route
- Check model fit and print each node's layer cap
- Split a model that does not fit on one machine across nodes
How pickfit tested it
Each run starts from a clean machine and follows the steps above. How pickfit verifies
macOS arm64
Its main function works
- Replayed from scratch
- Works offline
- Checked on 1 Nov 2026
- Version 0.3.2
Differences the test machine hit
- README: omarchy-cluster install-agent starts agent via launchd
In the test: launchd Load failed: 5 in VM but agent still runs manually via ~/mlx/bin/omarchy-cluster agent; discovery still works
Linux x86_64
Its main function works
- Replayed from scratch
- Works offline
- Checked on 30 Oct 2026
- Version 0.3.2
Differences the test machine hit
- README: venv pip install && omarchy-cluster install-agent
In the test: pip install plus symlink alone puts omarchy-cluster 0.3.2 on PATH and discover/status work; install-agent fails here with FileNotFoundError: systemctl