[object Object]

← back to Exo

Update README.md (#925)

8bafd6fe682776afaecce83e3b0dc3f0b6d9b12e · 2025-12-19 14:38:40 +0000 · Alex Cheema

## Motivation

<!-- Why is this change needed? What problem does it solve? -->
<!-- If it fixes an open issue, please link to the issue here -->

## Changes

<!-- Describe what you changed in detail -->

## Why It Works

<!-- Explain why your approach solves the problem -->

## Test Plan

### Manual Testing
<!-- Hardware: (e.g., MacBook Pro M1 Max 32GB, Mac Mini M2 16GB,
connected via Thunderbolt 4) -->
<!-- What you did: -->
<!-- - -->

### Automated Testing
<!-- Describe changes to automated tests, or how existing tests cover
this change -->
<!-- - -->

Files touched

Diff

commit 8bafd6fe682776afaecce83e3b0dc3f0b6d9b12e
Author: Alex Cheema <41707476+AlexCheema@users.noreply.github.com>
Date:   Fri Dec 19 14:38:40 2025 +0000

    Update README.md (#925)
    
    ## Motivation
    
    <!-- Why is this change needed? What problem does it solve? -->
    <!-- If it fixes an open issue, please link to the issue here -->
    
    ## Changes
    
    <!-- Describe what you changed in detail -->
    
    ## Why It Works
    
    <!-- Explain why your approach solves the problem -->
    
    ## Test Plan
    
    ### Manual Testing
    <!-- Hardware: (e.g., MacBook Pro M1 Max 32GB, Mac Mini M2 16GB,
    connected via Thunderbolt 4) -->
    <!-- What you did: -->
    <!-- - -->
    
    ### Automated Testing
    <!-- Describe changes to automated tests, or how existing tests cover
    this change -->
    <!-- - -->
---
 README.md                                          |  74 +++++++++++++++++----
 .../mac-studio-cluster-ai-full-1-qwen3-235b.jpeg   | Bin 0 -> 526859 bytes
 ...studio-cluster-ai-full-2-deepseek-3.1-671b.jpeg | Bin 0 -> 531385 bytes
 ...-studio-cluster-ai-full-3-kimi-k2-thinking.jpeg | Bin 0 -> 497699 bytes
 docs/four-mac-studio-topology.png                  | Bin 0 -> 134429 bytes
 docs/macos-app-one-macbook.png                     | Bin 0 -> 175454 bytes
 6 files changed, 61 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 0924c931..6c3152bc 100644
--- a/README.md
+++ b/README.md
@@ -17,36 +17,84 @@ exo: Run your own AI cluster at home with everyday devices. Maintained by [exo l
 
 ---
 
+EXO connects all your devices into an AI cluster. It pools together the resources of all your devices in order to run large models. Not only does EXO enable running models larger than would fit on a single device, but with [day-0 support for RDMA over Thunderbolt](https://x.com/exolabs/status/2001817749744476256?s=20), makes models run faster as you add more devices.
+
 ## Features
 
-- **Automatic Device Discovery**: Devices running EXO automatically discover each other on your local network - no manual configuration.
-- **RDMA over Thunderbolt**: EXO ships with Day-0 support for RDMA over Thunderbolt 5, enabling 99% reduction in latency between devices.
-- **Auto Parallel**: EXO automatically splits up models to run distributed across devices.
+- **Automatic Device Discovery**: Devices running EXO automatically discover each other - no manual configuration.
+- **RDMA over Thunderbolt**: EXO ships with [day-0 support for RDMA over Thunderbolt 5](https://x.com/exolabs/status/2001817749744476256?s=20), enabling 99% reduction in latency between devices.
+- **Topology-Aware Auto Parallel**: EXO figures out the best way to split your model across all available devices based on a realtime view of your device topology. It takes into account device resources and network latency/bandwidth between each link.
 - **Tensor Parallelism**: EXO supports sharding models, for up to 1.8x speedup on 2 devices and 3.2x speedup on 4 devices.
 - **MLX Support**: EXO uses [ml-explore/mlx](https://github.com/ml-explore/mlx) as an inference backend and [MLX distributed](https://ml-explore.github.io/mlx/build/html/usage/distributed.html) for distributed communication.
 
+## Benchmarks
+
+<details>
+  <summary>Qwen3-235B (8-bit) on 4 × M3 Ultra Mac Studio with Tensor Parallel RDMA</summary>
+  <img src="docs/benchmarks/jeffgeerling/mac-studio-cluster-ai-full-1-qwen3-235b.jpeg" alt="Benchmark - Qwen3-235B (8-bit) on 4 × M3 Ultra Mac Studio with Tensor Parallel RDMA" width="80%" />
+  <p>
+    <strong>Source:</strong> <a href="https://www.jeffgeerling.com/blog/2025/15-tb-vram-on-mac-studio-rdma-over-thunderbolt-5">Jeff Geerling: 15 TB VRAM on Mac Studio – RDMA over Thunderbolt 5</a>
+  </p>
+</details>
+
+<details>
+  <summary>DeepSeek v3.1 671B (8-bit) on 4 × M3 Ultra Mac Studio with Tensor Parallel RDMA</summary>
+  <img src="docs/benchmarks/jeffgeerling/mac-studio-cluster-ai-full-2-deepseek-3.1-671b.jpeg" alt="Benchmark - DeepSeek v3.1 671B (8-bit) on 4 × M3 Ultra Mac Studio with Tensor Parallel RDMA" width="80%" />
+  <p>
+    <strong>Source:</strong> <a href="https://www.jeffgeerling.com/blog/2025/15-tb-vram-on-mac-studio-rdma-over-thunderbolt-5">Jeff Geerling: 15 TB VRAM on Mac Studio – RDMA over Thunderbolt 5</a>
+  </p>
+</details>
+
+<details>
+  <summary>Kimi K2 Thinking (native 4-bit) on 4 × M3 Ultra Mac Studio with Tensor Parallel RDMA</summary>
+  <img src="docs/benchmarks/jeffgeerling/mac-studio-cluster-ai-full-3-kimi-k2-thinking.jpeg" alt="Benchmark - Kimi K2 Thinking (native 4-bit) on 4 × M3 Ultra Mac Studio with Tensor Parallel RDMA" width="80%" />
+  <p>
+    <strong>Source:</strong> <a href="https://www.jeffgeerling.com/blog/2025/15-tb-vram-on-mac-studio-rdma-over-thunderbolt-5">Jeff Geerling: 15 TB VRAM on Mac Studio – RDMA over Thunderbolt 5</a>
+  </p>
+</details>
+
 ---
 
 ## Quick Start
 
-You need at least one Mac device running macOS Tahoe 26.2 (released December 12th 2025).
+Devices running EXO automatically discover each other, without needing any manual configuration. Each device provides an API and a dashboard for interacting with your cluster (runs at `http://localhost:52415`).
+
+There are two ways to run EXO:
 
-You can download the latest build here: [EXO-latest.dmg](https://assets.exolabs.net/EXO-latest.dmg). It will ask for permission to modify system settings and install a new Network profile. We hope to make this smoother in the future!
+### Run from Source (Mac & Linux)
 
-To run from source, clone the repo, build the dashboard with `cd dashboard && npm install && npm run build` and run `uv run exo`.
+Clone the repo, build the dashboard, and run EXO:
 
-After starting with either of these methods go to `http://localhost:52415` in your browser, and you'll have EXO.
+```bash
+cd dashboard && npm install && npm run build
+uv run exo
+```
+
+**One-liner:**
+
+```bash
+git clone https://github.com/exo-explore/exo && cd exo/dashboard && npm i && npm run build && cd .. && uv run exo
+```
 
 ---
 
-## Requirements
+### macOS App
+
+EXO ships a macOS app that runs in the background on your Mac.
+
+<img src="docs/macos-app-one-macbook.png" alt="EXO macOS App - running on a MacBook" width="80%" />
+
+The macOS app requires macOS Tahoe 26.2 or later.
+
+Download the latest build here: [EXO-latest.dmg](https://assets.exolabs.net/EXO-latest.dmg).
+
+The app will ask for permission to modify system settings and install a new Network profile. Improvements to this are being worked on.
+
+---
 
-- Mac devices with Apple Silicon (M-series chips)
-- macOS Tahoe 26.2 or later (released December 12th 2025)
-  - Older macOS versions may work without RDMA, but only 26.2+ is officially supported
-- For RDMA over Thunderbolt: a high quality Thunderbolt 5 cable
+## Hardware Accelerator Support
 
-We intend to add support for other hardware platforms [like the DGX Spark](https://x.com/exolabs/status/1978525767739883736) in the future, but they are not currently supported. If you'd like support for a new hardware platform, please search for an existing feature request and add a thumbs up so we know what hardware is important to the community.
+On macOS, EXO uses the GPU. On Linux, EXO currently runs on CPU. We are working on extending hardware accelerator support. If you'd like support for a new hardware platform, please search for an existing feature request and add a thumbs up so we know what hardware is important to the community.
 
 ---
 
diff --git a/docs/benchmarks/jeffgeerling/mac-studio-cluster-ai-full-1-qwen3-235b.jpeg b/docs/benchmarks/jeffgeerling/mac-studio-cluster-ai-full-1-qwen3-235b.jpeg
new file mode 100644
index 00000000..d2c692fa
Binary files /dev/null and b/docs/benchmarks/jeffgeerling/mac-studio-cluster-ai-full-1-qwen3-235b.jpeg differ
diff --git a/docs/benchmarks/jeffgeerling/mac-studio-cluster-ai-full-2-deepseek-3.1-671b.jpeg b/docs/benchmarks/jeffgeerling/mac-studio-cluster-ai-full-2-deepseek-3.1-671b.jpeg
new file mode 100644
index 00000000..37ec22fa
Binary files /dev/null and b/docs/benchmarks/jeffgeerling/mac-studio-cluster-ai-full-2-deepseek-3.1-671b.jpeg differ
diff --git a/docs/benchmarks/jeffgeerling/mac-studio-cluster-ai-full-3-kimi-k2-thinking.jpeg b/docs/benchmarks/jeffgeerling/mac-studio-cluster-ai-full-3-kimi-k2-thinking.jpeg
new file mode 100644
index 00000000..5f83ede6
Binary files /dev/null and b/docs/benchmarks/jeffgeerling/mac-studio-cluster-ai-full-3-kimi-k2-thinking.jpeg differ
diff --git a/docs/four-mac-studio-topology.png b/docs/four-mac-studio-topology.png
new file mode 100644
index 00000000..ef9da076
Binary files /dev/null and b/docs/four-mac-studio-topology.png differ
diff --git a/docs/macos-app-one-macbook.png b/docs/macos-app-one-macbook.png
new file mode 100644
index 00000000..6362d536
Binary files /dev/null and b/docs/macos-app-one-macbook.png differ

← f16afd72 nix: get rust build working on linux  ·  back to Exo  ·  Update README.md. (#932) f8483cfc →