exo: handle -c flag for multiprocessing helpers in frozen apps

When Python's multiprocessing spawns child processes on macOS (using the "spawn" method), it also spawns helper processes like the resource tracker by executing: ./frozen_app -c "from multiprocessing.resource_tracker import main; main()" A frozen PyInstaller app doesn't understand `-c` natively - it just runs main(). This causes the resource tracker to fail silently. This adds a minimal `-c` handler that intercepts the flag, extracts the inline code, and exec()s it before main() runs. This is required for the Process() spawn in runner_supervisor.py to work correctly in the DMG. Note that the pyinstaller docs say `freeze_support` is supposed to make this work, but it doesn't. Test plan: Hardware setup: 3x Mac Studio M3 Ultra connected all-to-all with TB5 - Built a DMG[0]. - Installed on the Macs. - Started an instance. Got an error this time in ~/.exo/exo.log. The last DMG from main doesn't show anything when an instance starts, this now shows the errors. [0] https://github.com/exo-explore/exo/actions/runs/20464409279/job/58804485197
feat: conform to XDG Base Directory Specification on Linux (#988 )
2025-12-23 22:27:50 -05:00 · 2025-12-23 17:08:50 +00:00 · 2025-12-23 17:02:55 +00:00 · 2025-12-23 14:34:21 +00:00 · 2025-12-23 12:53:30 +00:00 · 2025-12-22 19:51:48 +00:00
22 changed files with 557 additions and 134 deletions
--- a/.github/workflows/build-app.yml
+++ b/.github/workflows/build-app.yml
@@ -4,10 +4,12 @@ on:
  push:
    tags:
      - "v*"
+    branches:
+      - "test-app"

 jobs:
  build-macos-app:
-    runs-on: [self-hosted, XCode262_Beta]
+    runs-on: "macos-26"
    env:
      SPARKLE_VERSION: 2.8.1
      SPARKLE_DOWNLOAD_PREFIX: ${{ secrets.SPARKLE_DOWNLOAD_PREFIX }}
@@ -21,6 +23,10 @@ jobs:
      EXO_LIBP2P_NAMESPACE: ${{ github.ref_name }}

    steps:
+      # ============================================================
+      # Checkout and tag validation
+      # ============================================================
+
      - name: Checkout
        uses: actions/checkout@v4
        with:
@@ -28,19 +34,24 @@ jobs:

      - name: Derive release version from tag
        run: |
-          VERSION="${GITHUB_REF_NAME#v}"
-          # Detect alpha tags
-          if [[ "$VERSION" == *-alpha* ]]; then
+          if [[ "$GITHUB_REF_NAME" == "test-app" ]]; then
+            VERSION="0.0.0-alpha.0"
            echo "IS_ALPHA=true" >> $GITHUB_ENV
          else
-            echo "IS_ALPHA=false" >> $GITHUB_ENV
+            VERSION="${GITHUB_REF_NAME#v}"
+            if [[ "$VERSION" == *-alpha* ]]; then
+              echo "IS_ALPHA=true" >> $GITHUB_ENV
+            else
+              echo "IS_ALPHA=false" >> $GITHUB_ENV
+            fi
          fi
          echo "RELEASE_VERSION=$VERSION" >> $GITHUB_ENV

      - name: Ensure tag commit is on main
+        if: github.ref_type == 'tag'
        run: |
          git fetch origin main
-          # Allow alpha tags on any branch, but require production tags to be on main
+          # Alpha tags can be on any branch, production tags must be on main
          if [[ "$IS_ALPHA" == "true" ]]; then
            echo "Alpha tag detected, skipping main branch check"
          elif ! git merge-base --is-ancestor origin/main HEAD; then
@@ -48,27 +59,20 @@ jobs:
            exit 1
          fi

-      - name: Add Homebrew to PATH      
-        run: |      
-          if [ -f /opt/homebrew/bin/brew ]; then      
-            echo "/opt/homebrew/bin" >> $GITHUB_PATH      
-          elif [ -f /usr/local/bin/brew ]; then      
-            echo "/usr/local/bin" >> $GITHUB_PATH      
-          fi
+      # ============================================================
+      # Install dependencies
+      # ============================================================

-      - name: Check Metal toolchain is installed
+      - name: Select Xcode 26.2
        run: |
+          sudo xcode-select -s /Applications/Xcode_26.2.app
          if ! xcrun -f metal >/dev/null 2>&1; then
-            echo "Metal toolchain is not installed. Run 'xcodebuild -downloadComponent MetalToolchain' on the runner host."
+            echo "Metal toolchain is not installed."
            exit 1
          fi
-          echo "Metal toolchain is installed."

-      - name: Install Just
-        run: brew install just
-
-      - name: Install AWS CLI
-        run: brew install awscli
+      - name: Install Homebrew packages
+        run: brew install just awscli macmon

      - name: Install UV
        uses: astral-sh/setup-uv@v6
@@ -76,17 +80,25 @@ jobs:
          enable-cache: true
          cache-dependency-glob: uv.lock

-      - name: Setup Python (UV)
+      - name: Setup Python
        run: |
          uv python install
          uv sync --locked

-      - name: Install macmon
-        run: brew install macmon
-
-      - name: Build PyInstaller bundle
+      - name: Build dashboard
        run: |
-          uv run pyinstaller packaging/pyinstaller/exo.spec
+          cd dashboard
+          npm ci
+          npm run build
+
+      - name: Install Sparkle CLI
+        run: |
+          CLI_URL="${SPARKLE_CLI_URL:-https://github.com/sparkle-project/Sparkle/releases/download/${SPARKLE_VERSION}/Sparkle-${SPARKLE_VERSION}.tar.xz}"
+          echo "Downloading Sparkle CLI from: $CLI_URL"
+          mkdir -p /tmp/sparkle
+          curl --fail --location --output /tmp/sparkle.tar.xz "$CLI_URL"
+          tar -xJf /tmp/sparkle.tar.xz -C /tmp/sparkle --strip-components=1
+          echo "SPARKLE_BIN=/tmp/sparkle/bin" >> $GITHUB_ENV

      - name: Prepare code-signing keychain
        env:
@@ -95,43 +107,47 @@ jobs:
          PROVISIONING_PROFILE: ${{ secrets.PROVISIONING_PROFILE }}
        run: |
          KEYCHAIN_PATH="$HOME/Library/Keychains/build.keychain-db"
-          
-          # Remove stale keychain from previous failed runs
-          security delete-keychain "$KEYCHAIN_PATH" 2>/dev/null || true
-          
+
          # Create fresh keychain
          security create-keychain -p "$MACOS_CERTIFICATE_PASSWORD" "$KEYCHAIN_PATH"
-          
+
          # Disable auto-lock (no timeout, no lock-on-sleep)
          security set-keychain-settings "$KEYCHAIN_PATH"
-          
+
          # Add to search list while preserving existing keychains
          security list-keychains -d user -s "$KEYCHAIN_PATH" $(security list-keychains -d user | tr -d '"')
-          
+
          # Set as default and unlock
          security default-keychain -s "$KEYCHAIN_PATH"
          security unlock-keychain -p "$MACOS_CERTIFICATE_PASSWORD" "$KEYCHAIN_PATH"
-          
+
          # Import certificate with full access for codesign
          echo "$MACOS_CERTIFICATE" | base64 --decode > /tmp/cert.p12
          security import /tmp/cert.p12 -k "$KEYCHAIN_PATH" -P "$MACOS_CERTIFICATE_PASSWORD" \
            -T /usr/bin/codesign -T /usr/bin/security -T /usr/bin/productbuild
          rm /tmp/cert.p12
-          
+
          # Allow codesign to access the key without prompting
          security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "$MACOS_CERTIFICATE_PASSWORD" "$KEYCHAIN_PATH"
-          
+
          # Verify keychain is unlocked and identity is available
          echo "Verifying signing identity..."
          security find-identity -v -p codesigning "$KEYCHAIN_PATH"
-          
+
          # Setup provisioning profile
          mkdir -p "$HOME/Library/Developer/Xcode/UserData/Provisioning Profiles"
          echo "$PROVISIONING_PROFILE" | base64 --decode > "$HOME/Library/Developer/Xcode/UserData/Provisioning Profiles/EXO.provisionprofile"
-          
+
          # Export keychain path for other steps
          echo "BUILD_KEYCHAIN_PATH=$KEYCHAIN_PATH" >> $GITHUB_ENV

+      # ============================================================
+      # Build the bundle
+      # ============================================================
+
+      - name: Build PyInstaller bundle
+        run: uv run pyinstaller packaging/pyinstaller/exo.spec
+
      - name: Build Swift app
        env:
          MACOS_CERTIFICATE_PASSWORD: ${{ secrets.MACOS_CERTIFICATE_PASSWORD }}
@@ -162,7 +178,7 @@ jobs:
          mkdir -p output/EXO.app/Contents/Resources
          cp -R dist/exo output/EXO.app/Contents/Resources/exo

-      - name: Codesign PyInstaller runtime payload
+      - name: Codesign PyInstaller runtime
        env:
          MACOS_CERTIFICATE_PASSWORD: ${{ secrets.MACOS_CERTIFICATE_PASSWORD }}
        run: |
@@ -226,47 +242,47 @@ jobs:

      - name: Generate Sparkle appcast
        env:
-          SPARKLE_VERSION: ${{ env.SPARKLE_VERSION }}
          SPARKLE_DOWNLOAD_PREFIX: ${{ env.SPARKLE_DOWNLOAD_PREFIX }}
          SPARKLE_ED25519_PRIVATE: ${{ secrets.SPARKLE_ED25519_PRIVATE }}
-          SPARKLE_CLI_URL: ${{ secrets.SPARKLE_CLI_URL }}
          IS_ALPHA: ${{ env.IS_ALPHA }}
        run: |
          set -euo pipefail
          cd output
          DOWNLOAD_PREFIX="${SPARKLE_DOWNLOAD_PREFIX:-https://assets.exolabs.net}"
-          mkdir -p sparkle
-          CLI_URL="${SPARKLE_CLI_URL:-}"
-          if [[ -z "$CLI_URL" ]]; then
-            CLI_URL="https://github.com/sparkle-project/Sparkle/releases/download/${SPARKLE_VERSION}/Sparkle-${SPARKLE_VERSION}.tar.xz"
-          fi
-          echo "Downloading Sparkle CLI from: $CLI_URL"
-          curl --fail --location --output sparkle.tar.xz "$CLI_URL"
-          tar -xJf sparkle.tar.xz -C sparkle --strip-components=1
          echo "$SPARKLE_ED25519_PRIVATE" > sparkle_ed25519.key
          chmod 600 sparkle_ed25519.key

-          # Add --channel alpha flag for alpha builds
          CHANNEL_FLAG=""
          if [[ "$IS_ALPHA" == "true" ]]; then
            CHANNEL_FLAG="--channel alpha"
            echo "Generating appcast for alpha channel"
          fi

-          ./sparkle/bin/generate_appcast \
+          $SPARKLE_BIN/generate_appcast \
            --ed-key-file sparkle_ed25519.key \
            --download-url-prefix "$DOWNLOAD_PREFIX" \
            $CHANNEL_FLAG \
            .

-      - name: Upload Sparkle assets to S3
-        if: env.SPARKLE_S3_BUCKET != ''
+      # ============================================================
+      # Upload artifacts
+      # ============================================================
+
+      - name: Upload DMG
+        uses: actions/upload-artifact@v4
+        with:
+          name: EXO-dmg-${{ env.RELEASE_VERSION }}
+          path: output/EXO-${{ env.RELEASE_VERSION }}.dmg
+
+      - name: Upload to S3
+        if: env.SPARKLE_S3_BUCKET != '' && github.ref_type == 'tag'
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_REGION: ${{ env.AWS_REGION }}
          SPARKLE_S3_BUCKET: ${{ env.SPARKLE_S3_BUCKET }}
          SPARKLE_S3_PREFIX: ${{ env.SPARKLE_S3_PREFIX }}
+          IS_ALPHA: ${{ env.IS_ALPHA }}
        run: |
          set -euo pipefail
          cd output
@@ -276,24 +292,7 @@ jobs:
          fi
          DMG_NAME="EXO-${RELEASE_VERSION}.dmg"
          aws s3 cp "$DMG_NAME" "s3://${SPARKLE_S3_BUCKET}/${PREFIX}${DMG_NAME}"
-          aws s3 cp "$DMG_NAME" "s3://${SPARKLE_S3_BUCKET}/${PREFIX}EXO-latest.dmg"
+          if [[ "$IS_ALPHA" != "true" ]]; then
+            aws s3 cp "$DMG_NAME" "s3://${SPARKLE_S3_BUCKET}/${PREFIX}EXO-latest.dmg"
+          fi
          aws s3 cp appcast.xml "s3://${SPARKLE_S3_BUCKET}/${PREFIX}appcast.xml" --content-type application/xml --cache-control no-cache
-
-      - name: Cleanup keychain
-        if: always()
-        run: |
-          KEYCHAIN_PATH="$HOME/Library/Keychains/build.keychain-db"
-          security default-keychain -s login.keychain || true
-          security delete-keychain "$KEYCHAIN_PATH" 2>/dev/null || true
-
-      - name: Upload app bundle
-        uses: actions/upload-artifact@v4
-        with:
-          name: EXO-app-${{ env.RELEASE_VERSION }}
-          path: output/EXO.app
-
-      - name: Upload DMG
-        uses: actions/upload-artifact@v4
-        with:
-          name: EXO-dmg-${{ env.RELEASE_VERSION }}
-          path: output/EXO-${{ env.RELEASE_VERSION }}.dmg
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -5,10 +5,21 @@ Thank you for your interest in contributing to EXO!
 ## Getting Started

 To run EXO from source:
+
+**Prerequisites:**
+- [uv](https://github.com/astral-sh/uv) (for Python dependency management)
+  ```bash
+  brew install uv
+  ```
+- [macmon](https://github.com/vladkens/macmon) (for hardware monitoring on Apple Silicon)
+  ```bash
+  brew install macmon
+  ```
+
 ```bash
 git clone https://github.com/exo-explore/exo.git
 cd exo/dashboard
-npm install && npm run build
+npm install && npm run build && cd ..
 uv run exo
 ```

--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
 <div align="center">

 <picture>
-  <source media="(prefers-color-scheme: light)" srcset="/docs/exo-logo-black-bg.jpg">
-  <img alt="exo logo" src="/docs/exo-logo-transparent.png" width="50%" height="50%">
+  <source media="(prefers-color-scheme: light)" srcset="/docs/imgs/exo-logo-black-bg.jpg">
+  <img alt="exo logo" src="/docs/imgs/exo-logo-transparent.png" width="50%" height="50%">
 </picture>

 exo: Run your own AI cluster at home with everyday devices. Maintained by [exo labs](https://x.com/exolabs).
@@ -63,6 +63,26 @@ There are two ways to run exo:

 ### Run from Source (Mac & Linux)

+**Prerequisites:**
+- [brew](https://github.com/Homebrew/brew) (for simple package management on MacOS)
+  
+  ```bash
+  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+  ```
+- [uv](https://github.com/astral-sh/uv) (for Python dependency management)
+- [macmon](https://github.com/vladkens/macmon) (for hardware monitoring on Apple Silicon)
+- [node](https://github.com/nodejs/node) (for building the dashboard)
+  
+  ```bash
+  brew install uv macmon node
+  ```
+- [rust](https://github.com/rust-lang/rustup) (to build Rust bindings, nightly for now)
+
+  ```bash
+  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+  rustup toolchain install nightly
+  ```
+
 Clone the repo, build the dashboard, and run exo:

 ```bash
@@ -82,7 +102,7 @@ This starts the exo dashboard and API at http://localhost:52415/

 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="35%" />
+<img src="docs/imgs/macos-app-one-macbook.png" alt="exo macOS App - running on a MacBook" width="35%" />

 The macOS app requires macOS Tahoe 26.2 or later.

--- a/app/EXO/EXO/ContentView.swift
+++ b/app/EXO/EXO/ContentView.swift
@@ -212,7 +212,7 @@ struct ContentView: View {

    private var dashboardButton: some View {
        Button {
-            guard let url = URL(string: "http://localhost:8000/") else { return }
+            guard let url = URL(string: "http://localhost:52415/") else { return }
            NSWorkspace.shared.open(url)
        } label: {
            HStack {
--- a/app/EXO/EXO/Services/BugReportService.swift
+++ b/app/EXO/EXO/Services/BugReportService.swift
@@ -35,7 +35,7 @@ struct BugReportService {
    }

    func sendReport(
-        baseURL: URL = URL(string: "http://127.0.0.1:8000")!,
+        baseURL: URL = URL(string: "http://127.0.0.1:52415")!,
        now: Date = Date(),
        isManual: Bool = false
    ) async throws -> BugReportOutcome {
--- a/app/EXO/EXO/Services/ClusterStateService.swift
+++ b/app/EXO/EXO/Services/ClusterStateService.swift
@@ -15,7 +15,7 @@ final class ClusterStateService: ObservableObject {
    private let endpoint: URL

    init(
-        baseURL: URL = URL(string: "http://127.0.0.1:8000")!,
+        baseURL: URL = URL(string: "http://127.0.0.1:52415")!,
        session: URLSession = .shared
    ) {
        self.baseURL = baseURL
--- a/dashboard/package-lock.json
+++ b/dashboard/package-lock.json
@@ -861,6 +861,7 @@
 			"integrity": "sha512-oH8tXw7EZnie8FdOWYrF7Yn4IKrqTFHhXvl8YxXxbKwTMcD/5NNCryUSEXRk2ZR4ojnub0P8rNrsVGHXWqIDtA==",
 			"dev": true,
 			"license": "MIT",
+			"peer": true,
 			"dependencies": {
 				"@standard-schema/spec": "^1.0.0",
 				"@sveltejs/acorn-typescript": "^1.0.5",
@@ -900,6 +901,7 @@
 			"integrity": "sha512-Y1Cs7hhTc+a5E9Va/xwKlAJoariQyHY+5zBgCZg4PFWNYQ1nMN9sjK1zhw1gK69DuqVP++sht/1GZg1aRwmAXQ==",
 			"dev": true,
 			"license": "MIT",
+			"peer": true,
 			"dependencies": {
 				"@sveltejs/vite-plugin-svelte-inspector": "^4.0.1",
 				"debug": "^4.4.1",
@@ -1516,6 +1518,7 @@
 			"integrity": "sha512-LCCV0HdSZZZb34qifBsyWlUmok6W7ouER+oQIGBScS8EsZsQbrtFTUrDX4hOl+CS6p7cnNC4td+qrSVGSCTUfQ==",
 			"dev": true,
 			"license": "MIT",
+			"peer": true,
 			"dependencies": {
 				"undici-types": "~6.21.0"
 			}
@@ -1525,6 +1528,7 @@
 			"resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz",
 			"integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
 			"license": "MIT",
+			"peer": true,
 			"bin": {
 				"acorn": "bin/acorn"
 			},
@@ -1937,6 +1941,7 @@
 			"integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==",
 			"dev": true,
 			"license": "ISC",
+			"peer": true,
 			"engines": {
 				"node": ">=12"
 			}
@@ -2607,6 +2612,7 @@
 			"integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
 			"dev": true,
 			"license": "MIT",
+			"peer": true,
 			"engines": {
 				"node": ">=12"
 			},
@@ -2794,6 +2800,7 @@
 			"resolved": "https://registry.npmjs.org/svelte/-/svelte-5.45.3.tgz",
 			"integrity": "sha512-ngKXNhNvwPzF43QqEhDOue7TQTrG09em1sd4HBxVF0Wr2gopAmdEWan+rgbdgK4fhBtSOTJO8bYU4chUG7VXZQ==",
 			"license": "MIT",
+			"peer": true,
 			"dependencies": {
 				"@jridgewell/remapping": "^2.3.4",
 				"@jridgewell/sourcemap-codec": "^1.5.0",
@@ -2938,6 +2945,7 @@
 			"integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
 			"dev": true,
 			"license": "Apache-2.0",
+			"peer": true,
 			"bin": {
 				"tsc": "bin/tsc",
 				"tsserver": "bin/tsserver"
@@ -2959,6 +2967,7 @@
 			"integrity": "sha512-+Oxm7q9hDoLMyJOYfUYBuHQo+dkAloi33apOPP56pzj+vsdJDzr+j1NISE5pyaAuKL4A3UD34qd0lx5+kfKp2g==",
 			"dev": true,
 			"license": "MIT",
+			"peer": true,
 			"dependencies": {
 				"esbuild": "^0.25.0",
 				"fdir": "^6.4.4",
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -0,0 +1,64 @@
+# EXO Architecture overview
+
+EXO uses an _Event Sourcing_ architecture, and Erlang-style _message passing_. To facilitate this, we've written a channel library extending anyio channels with inspiration from tokio::sync::mpsc. 
+
+Each logical module - designed to be functional independently of the others - communicates with the rest of the system by sending messages on topics.
+
+## Systems
+
+There are currently 5 major systems:
+
+- Master
+    
+    Executes placement and orders events through a single writer
+
+- Worker
+    
+    Schedules work on a node, gathers system information, etc.#
+
+- Runner
+    
+    Executes inference jobs (for now) in an isolated process from the worker for fault-tolerance.
+
+- API
+    
+    Runs a python webserver for exposing state and commands to client applications
+
+- Election
+    
+    Implements a distributed algorithm for master election in unstable networking conditions
+
+## Topics
+
+There are currently 5 topics:
+
+- Commands
+
+    The API and Worker instruct the master when the event log isn't sufficient. Namely placement and catchup requests go through Commands atm.
+
+- Local Events
+
+    All nodes write events here, the master reads those events and orders them
+
+- Global Events
+
+    The master writes events here, all nodes read from this topic and fold the produced events into their `State`
+
+- Election Messages
+
+    Before establishing a cluster, nodes communicate here to negotiate a master node.
+
+- Connection Messages
+
+    The networking system write mdns-discovered hardware connections here.
+
+
+## Event Sourcing
+
+Lots has been written about event sourcing, but it lets us centralize faulty connections and message ACKing with the following model.
+
+Whenever a device produces side effects, it captures those side effects in an `Event`. `Event`s are then "applied" to their model of `State`, which is globally distributed across the cluster. Whenever a command is received, it is combined with state to produce side effects, captured in yet more events. The rule of thumb is "`Event`s are past tense, `Command`s are imperative". Telling a node to perform some action like "place this model" or "Give me a copy of the event log" is represented by a command (The worker's `Task`s are also commands), while "this node is using 300GB of ram" is an event. Notably, `Event`s SHOULD never cause side effects on their own. There are a few exceptions to this, we're working out the specifics of generalizing the distributed event sourcing model to make it better suit our needs
+
+## Purity
+
+A significant goal of the current design is to make data flow explicit. Classes should either represent simple data (`CamelCaseModel`s typically, and `TaggedModel`s for unions) or active `System`s (Erlang `Actor`s), with all transformations of that data being "referentially transparent" - destructure and construct new data, don't mutate in place. We have had varying degrees of success with this, and are still exploring where purity makes sense.
--- a/docs/imgs/exo-logo-black-bg.jpg
+++ b/docs/imgs/exo-logo-black-bg.jpg
--- a/docs/imgs/exo-logo-transparent-black-text.png
+++ b/docs/imgs/exo-logo-transparent-black-text.png
--- a/docs/imgs/exo-logo-transparent.png
+++ b/docs/imgs/exo-logo-transparent.png
--- a/docs/imgs/exo-rounded.png
+++ b/docs/imgs/exo-rounded.png
--- a/docs/imgs/exo-screenshot.jpg
+++ b/docs/imgs/exo-screenshot.jpg
--- a/docs/imgs/four-mac-studio-topology.png
+++ b/docs/imgs/four-mac-studio-topology.png
--- a/docs/imgs/macos-app-one-macbook.png
+++ b/docs/imgs/macos-app-one-macbook.png
--- a/packaging/pyinstaller/exo.spec
+++ b/packaging/pyinstaller/exo.spec
@@ -0,0 +1,118 @@
+# -*- mode: python ; coding: utf-8 -*-
+
+import importlib.util
+import shutil
+from pathlib import Path
+
+from PyInstaller.utils.hooks import collect_submodules
+
+PROJECT_ROOT = Path.cwd()
+SOURCE_ROOT = PROJECT_ROOT / "src"
+ENTRYPOINT = SOURCE_ROOT / "exo" / "__main__.py"
+DASHBOARD_DIR = PROJECT_ROOT / "dashboard" / "build"
+EXO_SHARED_MODELS_DIR = SOURCE_ROOT / "exo" / "shared" / "models"
+
+if not ENTRYPOINT.is_file():
+    raise SystemExit(f"Unable to locate Exo entrypoint: {ENTRYPOINT}")
+
+if not DASHBOARD_DIR.is_dir():
+    raise SystemExit(f"Dashboard assets are missing: {DASHBOARD_DIR}")
+
+if not EXO_SHARED_MODELS_DIR.is_dir():
+    raise SystemExit(f"Shared model assets are missing: {EXO_SHARED_MODELS_DIR}")
+
+block_cipher = None
+
+
+def _module_directory(module_name: str) -> Path:
+    spec = importlib.util.find_spec(module_name)
+    if spec is None:
+        raise SystemExit(f"Module '{module_name}' is not available in the current environment.")
+    if spec.submodule_search_locations:
+        return Path(next(iter(spec.submodule_search_locations))).resolve()
+    if spec.origin:
+        return Path(spec.origin).resolve().parent
+    raise SystemExit(f"Unable to determine installation directory for '{module_name}'.")
+
+
+MLX_PACKAGE_DIR = _module_directory("mlx")
+MLX_LIB_DIR = MLX_PACKAGE_DIR / "lib"
+if not MLX_LIB_DIR.is_dir():
+    raise SystemExit(f"mlx Metal libraries are missing: {MLX_LIB_DIR}")
+
+
+def _safe_collect(package_name: str) -> list[str]:
+    try:
+        return collect_submodules(package_name)
+    except ImportError:
+        return []
+
+
+HIDDEN_IMPORTS = sorted(
+    set(
+        collect_submodules("mlx")
+        + _safe_collect("mlx_lm")
+        + _safe_collect("transformers")
+    )
+)
+
+DATAS: list[tuple[str, str]] = [
+    (str(DASHBOARD_DIR), "dashboard"),
+    (str(MLX_LIB_DIR), "mlx/lib"),
+    (str(EXO_SHARED_MODELS_DIR), "exo/shared/models"),
+]
+
+MACMON_PATH = shutil.which("macmon")
+if MACMON_PATH is None:
+    raise SystemExit(
+        "macmon binary not found in PATH. "
+        "Install it via: brew install macmon"
+    )
+
+BINARIES: list[tuple[str, str]] = [
+    (MACMON_PATH, "."),
+]
+
+a = Analysis(
+    [str(ENTRYPOINT)],
+    pathex=[str(SOURCE_ROOT)],
+    binaries=BINARIES,
+    datas=DATAS,
+    hiddenimports=HIDDEN_IMPORTS,
+    hookspath=[],
+    hooksconfig={},
+    runtime_hooks=[],
+    excludes=[],
+    win_no_prefer_redirects=False,
+    win_private_assemblies=False,
+    noarchive=False,
+)
+pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)
+exe = EXE(
+    pyz,
+    a.scripts,
+    [],
+    exclude_binaries=True,
+    name="exo",
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=False,
+    upx=False,
+    console=True,
+    disable_windowed_traceback=False,
+    argv_emulation=False,
+    target_arch=None,
+    codesign_identity=None,
+    entitlements_file=None,
+)
+coll = COLLECT(
+    exe,
+    a.binaries,
+    a.zipfiles,
+    a.datas,
+    strip=False,
+    upx=False,
+    upx_exclude=[],
+    name="exo",
+)
+
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -16,7 +16,6 @@ dependencies = [
    "filelock>=3.18.0",
    "aiosqlite>=0.21.0",
    "networkx>=3.5",
-    "pathlib>=1.0.1",
    "protobuf>=6.32.0",
    "rich>=14.1.0",
    "rustworkx>=0.17.1",
@@ -44,6 +43,7 @@ exo = "exo.main:main"
 # dependencies only required for development
 [dependency-groups]
 dev = [
+    "pyinstaller>=6.17.0",
    "pytest>=8.4.0",
    "pytest-asyncio>=1.0.0",
    "pytest-env",
--- a/src/exo/main.py
+++ b/src/exo/main.py
@@ -1,4 +1,39 @@
+from __future__ import annotations
+
+import sys
+from collections.abc import Sequence
+from multiprocessing import freeze_support
+from typing import Final
+
 from exo.main import main

+INLINE_CODE_FLAG: Final[str] = "-c"
+
+
+def _maybe_run_inline_code(argv: Sequence[str]) -> bool:
+    """
+    Reproduce the bare minimum of Python's `-c` flag so multiprocessing
+    helper processes (for example the resource tracker) can execute.
+    """
+
+    try:
+        flag_index = argv.index(INLINE_CODE_FLAG)
+    except ValueError:
+        return False
+
+    code_index = flag_index + 1
+    if code_index >= len(argv):
+        return False
+
+    inline_code = argv[code_index]
+    sys.argv = ["-c", *argv[code_index + 1 :]]
+    namespace: dict[str, object] = {"__name__": "__main__"}
+    exec(inline_code, namespace, namespace)
+    return True
+
+
 if __name__ == "__main__":
+    if _maybe_run_inline_code(sys.argv):
+        sys.exit(0)
+    freeze_support()
    main()
--- a/src/exo/shared/constants.py
+++ b/src/exo/shared/constants.py
@@ -1,35 +1,46 @@
 import os
+import sys
 from pathlib import Path

-EXO_HOME_RELATIVE_PATH = os.environ.get("EXO_HOME", ".exo")
-EXO_HOME = Path.home() / EXO_HOME_RELATIVE_PATH
+_EXO_HOME_ENV = os.environ.get("EXO_HOME", None)

-EXO_MODELS_DIR_ENV = os.environ.get("EXO_MODELS_DIR")
-EXO_MODELS_DIR = Path(EXO_MODELS_DIR_ENV) if EXO_MODELS_DIR_ENV else EXO_HOME / "models"

-EXO_GLOBAL_EVENT_DB = EXO_HOME / "global_events.db"
-EXO_WORKER_EVENT_DB = EXO_HOME / "worker_events.db"
-EXO_MASTER_STATE = EXO_HOME / "master_state.json"
-EXO_WORKER_STATE = EXO_HOME / "worker_state.json"
-EXO_MASTER_LOG = EXO_HOME / "master.log"
-EXO_WORKER_LOG = EXO_HOME / "worker.log"
-EXO_LOG = EXO_HOME / "exo.log"
-EXO_TEST_LOG = EXO_HOME / "exo_test.log"
+def _get_xdg_dir(env_var: str, fallback: str) -> Path:
+    """Get XDG directory, prioritising EXO_HOME environment variable if its set. On non-Linux platforms, default to ~/.exo."""

-EXO_NODE_ID_KEYPAIR = EXO_HOME / "node_id.keypair"
+    if _EXO_HOME_ENV is not None:
+        return Path.home() / _EXO_HOME_ENV

-EXO_WORKER_KEYRING_FILE = EXO_HOME / "worker_keyring"
-EXO_MASTER_KEYRING_FILE = EXO_HOME / "master_keyring"
+    if sys.platform != "linux":
+        return Path.home() / ".exo"

-EXO_IPC_DIR = EXO_HOME / "ipc"
+    xdg_value = os.environ.get(env_var, None)
+    if xdg_value is not None:
+        return Path(xdg_value) / "exo"
+    return Path.home() / fallback / "exo"
+
+
+EXO_CONFIG_HOME = _get_xdg_dir("XDG_CONFIG_HOME", ".config")
+EXO_DATA_HOME = _get_xdg_dir("XDG_DATA_HOME", ".local/share")
+EXO_CACHE_HOME = _get_xdg_dir("XDG_CACHE_HOME", ".cache")
+
+# Models directory (data)
+_EXO_MODELS_DIR_ENV = os.environ.get("EXO_MODELS_DIR", None)
+EXO_MODELS_DIR = (
+    EXO_DATA_HOME / "models"
+    if _EXO_MODELS_DIR_ENV is None
+    else Path.home() / _EXO_MODELS_DIR_ENV
+)
+
+# Log files (data/logs or cache)
+EXO_LOG = EXO_CACHE_HOME / "exo.log"
+EXO_TEST_LOG = EXO_CACHE_HOME / "exo_test.log"
+
+# Identity (config)
+EXO_NODE_ID_KEYPAIR = EXO_CONFIG_HOME / "node_id.keypair"

 # libp2p topics for event forwarding
 LIBP2P_LOCAL_EVENTS_TOPIC = "worker_events"
 LIBP2P_GLOBAL_EVENTS_TOPIC = "global_events"
 LIBP2P_ELECTION_MESSAGES_TOPIC = "election_message"
 LIBP2P_COMMANDS_TOPIC = "commands"
-
-# lower bounds define timeouts for flops and memory bandwidth - these are the values for the M1 chip.
-LB_TFLOPS = 2.3
-LB_MEMBW_GBPS = 68
-LB_DISK_GBPS = 1.5
--- a/src/exo/shared/tests/test_xdg_paths.py
+++ b/src/exo/shared/tests/test_xdg_paths.py
@@ -0,0 +1,118 @@
+"""Tests for XDG Base Directory Specification compliance."""
+
+import os
+import sys
+from pathlib import Path
+from unittest import mock
+
+
+def test_xdg_paths_on_linux():
+    """Test that XDG paths are used on Linux when XDG env vars are set."""
+    with (
+        mock.patch.dict(
+            os.environ,
+            {
+                "XDG_CONFIG_HOME": "/tmp/test-config",
+                "XDG_DATA_HOME": "/tmp/test-data",
+                "XDG_CACHE_HOME": "/tmp/test-cache",
+            },
+            clear=False,
+        ),
+        mock.patch.object(sys, "platform", "linux"),
+    ):
+        # Re-import to pick up mocked values
+        import importlib
+
+        import exo.shared.constants as constants
+
+        importlib.reload(constants)
+
+        assert Path("/tmp/test-config/exo") == constants.EXO_CONFIG_HOME
+        assert Path("/tmp/test-data/exo") == constants.EXO_DATA_HOME
+        assert Path("/tmp/test-cache/exo") == constants.EXO_CACHE_HOME
+
+
+def test_xdg_default_paths_on_linux():
+    """Test that XDG default paths are used on Linux when env vars are not set."""
+    # Remove XDG env vars and EXO_HOME
+    env = {
+        k: v
+        for k, v in os.environ.items()
+        if not k.startswith("XDG_") and k != "EXO_HOME"
+    }
+    with (
+        mock.patch.dict(os.environ, env, clear=True),
+        mock.patch.object(sys, "platform", "linux"),
+    ):
+        import importlib
+
+        import exo.shared.constants as constants
+
+        importlib.reload(constants)
+
+        home = Path.home()
+        assert home / ".config" / "exo" == constants.EXO_CONFIG_HOME
+        assert home / ".local/share" / "exo" == constants.EXO_DATA_HOME
+        assert home / ".cache" / "exo" == constants.EXO_CACHE_HOME
+
+
+def test_legacy_exo_home_takes_precedence():
+    """Test that EXO_HOME environment variable takes precedence for backward compatibility."""
+    with mock.patch.dict(
+        os.environ,
+        {
+            "EXO_HOME": ".custom-exo",
+            "XDG_CONFIG_HOME": "/tmp/test-config",
+        },
+        clear=False,
+    ):
+        import importlib
+
+        import exo.shared.constants as constants
+
+        importlib.reload(constants)
+
+        home = Path.home()
+        assert home / ".custom-exo" == constants.EXO_CONFIG_HOME
+        assert home / ".custom-exo" == constants.EXO_DATA_HOME
+
+
+def test_macos_uses_traditional_paths():
+    """Test that macOS uses traditional ~/.exo directory."""
+    # Remove EXO_HOME to ensure we test the default behavior
+    env = {k: v for k, v in os.environ.items() if k != "EXO_HOME"}
+    with (
+        mock.patch.dict(os.environ, env, clear=True),
+        mock.patch.object(sys, "platform", "darwin"),
+    ):
+        import importlib
+
+        import exo.shared.constants as constants
+
+        importlib.reload(constants)
+
+        home = Path.home()
+        assert home / ".exo" == constants.EXO_CONFIG_HOME
+        assert home / ".exo" == constants.EXO_DATA_HOME
+        assert home / ".exo" == constants.EXO_CACHE_HOME
+
+
+def test_node_id_in_config_dir():
+    """Test that node ID keypair is in the config directory."""
+    import exo.shared.constants as constants
+
+    assert constants.EXO_NODE_ID_KEYPAIR.parent == constants.EXO_CONFIG_HOME
+
+
+def test_models_in_data_dir():
+    """Test that models directory is in the data directory."""
+    # Clear EXO_MODELS_DIR to test default behavior
+    env = {k: v for k, v in os.environ.items() if k != "EXO_MODELS_DIR"}
+    with mock.patch.dict(os.environ, env, clear=True):
+        import importlib
+
+        import exo.shared.constants as constants
+
+        importlib.reload(constants)
+
+        assert constants.EXO_MODELS_DIR.parent == constants.EXO_DATA_HOME
--- a/src/exo/worker/download/download_utils.py
+++ b/src/exo/worker/download/download_utils.py
@@ -24,7 +24,7 @@ from pydantic import (
    TypeAdapter,
 )

-from exo.shared.constants import EXO_HOME, EXO_MODELS_DIR
+from exo.shared.constants import EXO_MODELS_DIR
 from exo.shared.types.memory import Memory
 from exo.shared.types.worker.downloads import DownloadProgressData
 from exo.shared.types.worker.shards import ShardMetadata
@@ -132,25 +132,6 @@ async def resolve_model_path_for_repo(repo_id: str) -> Path:
    return (await ensure_models_dir()) / repo_id.replace("/", "--")


-async def ensure_exo_home() -> Path:
-    await aios.makedirs(EXO_HOME, exist_ok=True)
-    return EXO_HOME
-
-
-async def has_exo_home_read_access() -> bool:
-    try:
-        return await aios.access(EXO_HOME, os.R_OK)
-    except OSError:
-        return False
-
-
-async def has_exo_home_write_access() -> bool:
-    try:
-        return await aios.access(EXO_HOME, os.W_OK)
-    except OSError:
-        return False
-
-
 async def ensure_models_dir() -> Path:
    await aios.makedirs(EXO_MODELS_DIR, exist_ok=True)
    return EXO_MODELS_DIR
--- a/uv.lock
+++ b/uv.lock
@@ -120,6 +120,15 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/f5/10/6c25ed6de94c49f88a91fa5018cb4c0f3625f31d5be9f771ebe5cc7cd506/aiosqlite-0.21.0-py3-none-any.whl", hash = "sha256:2549cf4057f95f53dcba16f2b64e8e2791d7e1adedb13197dd8ed77bb226d7d0", size = 15792, upload-time = "2025-02-03T07:30:13.6Z" },
 ]

+[[package]]
+name = "altgraph"
+version = "0.17.5"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/7e/f8/97fdf103f38fed6792a1601dbc16cc8aac56e7459a9fff08c812d8ae177a/altgraph-0.17.5.tar.gz", hash = "sha256:c87b395dd12fabde9c99573a9749d67da8d29ef9de0125c7f536699b4a9bc9e7", size = 48428, upload-time = "2025-11-21T20:35:50.583Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a9/ba/000a1996d4308bc65120167c21241a3b205464a2e0b58deda26ae8ac21d1/altgraph-0.17.5-py2.py3-none-any.whl", hash = "sha256:f3a22400bce1b0c701683820ac4f3b159cd301acab067c51c653e06961600597", size = 21228, upload-time = "2025-11-21T20:35:49.444Z" },
+]
+
 [[package]]
 name = "annotated-doc"
 version = "0.0.3"
@@ -327,7 +336,6 @@ dependencies = [
    { name = "mlx", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
    { name = "mlx-lm", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
    { name = "networkx", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
-    { name = "pathlib", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
    { name = "protobuf", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
    { name = "psutil", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
    { name = "pydantic", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
@@ -343,6 +351,7 @@ dependencies = [

 [package.dev-dependencies]
 dev = [
+    { name = "pyinstaller", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
    { name = "pytest", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
    { name = "pytest-asyncio", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
    { name = "pytest-env", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
@@ -368,7 +377,6 @@ requires-dist = [
    { name = "mlx", specifier = ">=0.29.3" },
    { name = "mlx-lm", specifier = ">=0.28.3" },
    { name = "networkx", specifier = ">=3.5" },
-    { name = "pathlib", specifier = ">=1.0.1" },
    { name = "protobuf", specifier = ">=6.32.0" },
    { name = "psutil", specifier = ">=7.0.0" },
    { name = "pydantic", specifier = ">=2.11.7" },
@@ -384,6 +392,7 @@ requires-dist = [

 [package.metadata.requires-dev]
 dev = [
+    { name = "pyinstaller", specifier = ">=6.17.0" },
    { name = "pytest", specifier = ">=8.4.0" },
    { name = "pytest-asyncio", specifier = ">=1.0.0" },
    { name = "pytest-env" },
@@ -682,6 +691,18 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/0c/29/0348de65b8cc732daa3e33e67806420b2ae89bdce2b04af740289c5c6c8c/loguru-0.7.3-py3-none-any.whl", hash = "sha256:31a33c10c8e1e10422bfd431aeb5d351c7cf7fa671e3c4df004162264b28220c", size = 61595, upload-time = "2024-12-06T11:20:54.538Z" },
 ]

+[[package]]
+name = "macholib"
+version = "1.16.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "altgraph", marker = "sys_platform == 'darwin'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/10/2f/97589876ea967487978071c9042518d28b958d87b17dceb7cdc1d881f963/macholib-1.16.4.tar.gz", hash = "sha256:f408c93ab2e995cd2c46e34fe328b130404be143469e41bc366c807448979362", size = 59427, upload-time = "2025-11-22T08:28:38.373Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c7/d1/a9f36f8ecdf0fb7c9b1e78c8d7af12b8c8754e74851ac7b94a8305540fc7/macholib-1.16.4-py2.py3-none-any.whl", hash = "sha256:da1a3fa8266e30f0ce7e97c6a54eefaae8edd1e5f86f3eb8b95457cae90265ea", size = 38117, upload-time = "2025-11-22T08:28:36.939Z" },
+]
+
 [[package]]
 name = "markdown-it-py"
 version = "4.0.0"
@@ -928,15 +949,6 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/20/12/38679034af332785aac8774540895e234f4d07f7545804097de4b666afd8/packaging-25.0-py3-none-any.whl", hash = "sha256:29572ef2b1f17581046b3a2227d5c611fb25ec70ca1ba8554b24b0e69331a484", size = 66469, upload-time = "2025-04-19T11:48:57.875Z" },
 ]

-[[package]]
-name = "pathlib"
-version = "1.0.1"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/ac/aa/9b065a76b9af472437a0059f77e8f962fe350438b927cb80184c32f075eb/pathlib-1.0.1.tar.gz", hash = "sha256:6940718dfc3eff4258203ad5021090933e5c04707d5ca8cc9e73c94a7894ea9f", size = 49298, upload-time = "2014-09-03T15:41:57.18Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/78/f9/690a8600b93c332de3ab4a344a4ac34f00c8f104917061f779db6a918ed6/pathlib-1.0.1-py3-none-any.whl", hash = "sha256:f35f95ab8b0f59e6d354090350b44a80a80635d22efdedfa84c7ad1cf0a74147", size = 14363, upload-time = "2022-05-04T13:37:20.585Z" },
-]
-
 [[package]]
 name = "platformdirs"
 version = "4.5.0"
@@ -1126,6 +1138,42 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/c7/21/705964c7812476f378728bdf590ca4b771ec72385c533964653c68e86bdc/pygments-2.19.2-py3-none-any.whl", hash = "sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", size = 1225217, upload-time = "2025-06-21T13:39:07.939Z" },
 ]

+[[package]]
+name = "pyinstaller"
+version = "6.17.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "altgraph", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
+    { name = "macholib", marker = "sys_platform == 'darwin'" },
+    { name = "packaging", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
+    { name = "pyinstaller-hooks-contrib", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
+    { name = "setuptools", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/01/80/9e0dad9c69a7cfd4b5aaede8c6225d762bab7247a2a6b7651e1995522001/pyinstaller-6.17.0.tar.gz", hash = "sha256:be372bd911392b88277e510940ac32a5c2a6ce4b8d00a311c78fa443f4f27313", size = 4014147, upload-time = "2025-11-24T19:43:32.109Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/35/f5/37e419d84d5284ecab11ef8b61306a3b978fe6f0fd69a9541e16bfd72e65/pyinstaller-6.17.0-py3-none-macosx_10_13_universal2.whl", hash = "sha256:4e446b8030c6e5a2f712e3f82011ecf6c7ead86008357b0d23a0ec4bcde31dac", size = 1031880, upload-time = "2025-11-24T19:42:30.862Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/b6/2e184879ab9cf90a1d2867fdd34d507c4d246b3cc52ca05aad00bfc70ee7/pyinstaller-6.17.0-py3-none-manylinux2014_aarch64.whl", hash = "sha256:aa9fd87aaa28239c6f0d0210114029bd03f8cac316a90bab071a5092d7c85ad7", size = 731968, upload-time = "2025-11-24T19:42:35.421Z" },
+    { url = "https://files.pythonhosted.org/packages/40/76/f529de98f7e5cce7904c19b224990003fc2267eda2ee5fdd8452acb420a9/pyinstaller-6.17.0-py3-none-manylinux2014_i686.whl", hash = "sha256:060b122e43e7c0b23e759a4153be34bd70914135ab955bb18a67181e0dca85a2", size = 743217, upload-time = "2025-11-24T19:42:39.286Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/10/c02bfbb050cafc4c353cf69baf95407e211e1372bd286ab5ce5cbc13a30a/pyinstaller-6.17.0-py3-none-manylinux2014_ppc64le.whl", hash = "sha256:cd213d1a545c97dfe4a3c40e8213ff7c5127fc115c49229f27a3fa541503444b", size = 741119, upload-time = "2025-11-24T19:42:43.12Z" },
+    { url = "https://files.pythonhosted.org/packages/11/9d/69fdacfd9335695f5900a376cfe3e4aed28f0720ffc15fee81fdb9d920bc/pyinstaller-6.17.0-py3-none-manylinux2014_s390x.whl", hash = "sha256:89c0d18ba8b62c6607abd8cf2299ae5ffa5c36d8c47f39608ce8c3f357f6099f", size = 738111, upload-time = "2025-11-24T19:42:46.97Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/1e/e8e36e1568f6865ac706c6e1f875c1a346ddaa9f9a8f923d66545d2240ed/pyinstaller-6.17.0-py3-none-manylinux2014_x86_64.whl", hash = "sha256:2a147b83cdebb07855bd5a663600891550062373a2ca375c58eacead33741a27", size = 737795, upload-time = "2025-11-24T19:42:50.675Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/15/9dc0f81ccb746c27bfa6ee53164422fe47ee079c7a717d9c4791aba78797/pyinstaller-6.17.0-py3-none-musllinux_1_1_aarch64.whl", hash = "sha256:f8cfbbfa6708e54fb936df6dd6eafaf133e84efb0d2fe25b91cfeefa793c4ca4", size = 736891, upload-time = "2025-11-24T19:42:54.458Z" },
+    { url = "https://files.pythonhosted.org/packages/97/e6/bed54821c1ebe1275c559661d3e7bfa23c406673b515252dfbf89db56c65/pyinstaller-6.17.0-py3-none-musllinux_1_1_x86_64.whl", hash = "sha256:97f4c1942f7b4cd73f9e38b49cc8f5f8a6fbb44922cb60dd3073a189b77ee1ae", size = 736752, upload-time = "2025-11-24T19:42:58.144Z" },
+]
+
+[[package]]
+name = "pyinstaller-hooks-contrib"
+version = "2025.10"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "packaging", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
+    { name = "setuptools", marker = "sys_platform == 'darwin' or sys_platform == 'linux'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/26/4f/e33132acdb8f732978e577b8a0130a412cbfe7a3414605e3fd380a975522/pyinstaller_hooks_contrib-2025.10.tar.gz", hash = "sha256:a1a737e5c0dccf1cf6f19a25e2efd109b9fec9ddd625f97f553dac16ee884881", size = 168155, upload-time = "2025-11-22T09:34:36.138Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/86/de/a7688eed49a1d3df337cdaa4c0d64e231309a52f269850a72051975e3c4a/pyinstaller_hooks_contrib-2025.10-py3-none-any.whl", hash = "sha256:aa7a378518772846221f63a84d6306d9827299323243db890851474dfd1231a9", size = 447760, upload-time = "2025-11-22T09:34:34.753Z" },
+]
+
 [[package]]
 name = "pytest"
 version = "8.4.2"
@@ -1337,6 +1385,15 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/ad/fe/cad1d9762868c7c5dc70c8620074df28ebb1a8e4c17d4c0cb031889c457e/safetensors-0.6.2-cp38-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:d944cea65fad0ead848b6ec2c37cc0b197194bec228f8020054742190e9312ac", size = 655957, upload-time = "2025-08-08T13:13:57.029Z" },
 ]

+[[package]]
+name = "setuptools"
+version = "80.9.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/18/5d/3bf57dcd21979b887f014ea83c24ae194cfcd12b9e0fda66b957c69d1fca/setuptools-80.9.0.tar.gz", hash = "sha256:f36b47402ecde768dbfafc46e8e4207b4360c654f1f3bb84475f0a28628fb19c", size = 1319958, upload-time = "2025-05-27T00:56:51.443Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a3/dc/17031897dae0efacfea57dfd3a82fdd2a2aeb58e0ff71b77b87e44edc772/setuptools-80.9.0-py3-none-any.whl", hash = "sha256:062d34222ad13e0cc312a4c02d73f059e86a4acbfbdea8f8f76b28c99f306922", size = 1201486, upload-time = "2025-05-27T00:56:49.664Z" },
+]
+
 [[package]]
 name = "sniffio"
 version = "1.3.1"
Author	SHA1	Message	Date
Jake Hillion	9afc1043ef	exo: handle -c flag for multiprocessing helpers in frozen apps When Python's multiprocessing spawns child processes on macOS (using the "spawn" method), it also spawns helper processes like the resource tracker by executing: ./frozen_app -c "from multiprocessing.resource_tracker import main; main()" A frozen PyInstaller app doesn't understand `-c` natively - it just runs main(). This causes the resource tracker to fail silently. This adds a minimal `-c` handler that intercepts the flag, extracts the inline code, and exec()s it before main() runs. This is required for the Process() spawn in runner_supervisor.py to work correctly in the DMG. Note that the pyinstaller docs say `freeze_support` is supposed to make this work, but it doesn't. Test plan: Hardware setup: 3x Mac Studio M3 Ultra connected all-to-all with TB5 - Built a DMG[0]. - Installed on the Macs. - Started an instance. Got an error this time in ~/.exo/exo.log. The last DMG from main doesn't show anything when an instance starts, this now shows the errors. [0] https://github.com/exo-explore/exo/actions/runs/20464409279/job/58804485197	2025-12-23 17:08:50 +00:00
Evan Quiney	70c423f5e0	feat: conform to XDG Base Directory Specification on Linux (#988 ) This is an extension of #964 with some cleanup. --------- Co-authored-by: majiayu000 <1835304752@qq.com>	2025-12-23 17:02:55 +00:00
Jake Hillion	a24bdf7680	exo: enable multiprocessing support in PyInstaller bundles Model loading fails silently when running from the DMG-packaged app, despite working correctly with `uv run exo`. The bundled app spawns child processes for model inference via multiprocessing, but these processes fail to start in a frozen (PyInstaller) environment. Add `freeze_support()` which is required for multiprocessing to work in frozen applications. Test plan: Hardware setup: 3x Mac Studio M3 Ultra connected all-to-all with TB5 - Built a DMG using a modified .github/workflows/build-app.yml[0] to avoid publishing it. - Installed on all 3 Macs, replacing the existing Exo. - Downloaded Llama 3.3 70B (FP16). - Downloaded Qwen3 Coder 235B A22B (8-bit). Things that work now but didn't on the previous app: - Topology looks good, previously there was no discovery. What didn't work: - Started an instance with Pipeline + MLX Ring + 3 Nodes. Failed. - Started an instance with Tensor + MLX RDMA + 2 Nodes. Failed. Will continue debugging the instance starting issues separately. [0] https://github.com/exo-explore/exo/actions/runs/20461320368	2025-12-23 14:34:21 +00:00
Jake Hillion	e8855959c1	build-app: add branch trigger from named branch As I've been working on the .dmg, it's become clear we need a way to test changes to the app. It's too hard to reproduce the full DMG locally to be reasonable and much more convenient to test if it's signed. Add a feature to the build-app workflow where if you push specifically to the `test-app` branch it'll perform a build. The version is stubbed to `0.0.0-alpha.0`, which is about as low as it gets in semver so you'll always update away from it automatically with Sparkle. The resulting DMG won't be pushed to S3 but will be uploaded as a GitHub Actions artifact. I've been using similar commits to this for a while for testing. It's worked well and not interfered with auto updating at all. Test plan: - Pushed this change to `test-app`. - Generated action at https://github.com/exo-explore/exo/actions/runs/20447213358/job/58752909332 - Installed the DMG on a Mac. It worked as intended.	2025-12-23 12:53:30 +00:00
Jake Hillion	0a7fe5d943	ci: migrate build-app to github hosted runners	2025-12-22 19:51:48 +00:00
rltakashige	51a5191ff3	format readme (#978 ) ## Motivation README looks weird after last update. <!-- 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: --> <!-- - --> I actually checked the file on GitHub this time. ### Automated Testing <!-- Describe changes to automated tests, or how existing tests cover this change --> <!-- - -->	2025-12-22 18:06:27 +00:00
Evan Quiney	1efbd26388	add architecture.md, move images to docs/imgs (#968 ) ## Motivation Documentation will make contribution easier and communicate our development philosophy and decision process. Closes #967 ## Changes Added `architecture.md` to docs/ and moved the images out of docs and into their own docs/imgs/ folder	2025-12-22 17:57:43 +00:00
Jake Hillion	02c915a88d	pyproject: drop pathlib dependency	2025-12-22 17:52:44 +00:00
rltakashige	fc41bfa1f1	Add all prerequisites to README (#975 ) ## Motivation Addresses #974 ``` INFO: pip is looking at multiple versions of exo to determine which version is compatible with other requirements. This could take a while. ERROR: Could not find a version that satisfies the requirement exo-pyo3-bindings (from exo) (from versions: none) ERROR: No matching distribution found for exo-pyo3-bindings ``` ## Changes Describes Rust dependency for building from source ## 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: --> <!-- - --> Tested locally and runs after this setup without exo-pyo3-bindings error ### Automated Testing <!-- Describe changes to automated tests, or how existing tests cover this change --> <!-- - -->	2025-12-22 17:38:51 +00:00
Jake Hillion	dd0638b74d	pyproject: add pyinstaller to dev-dependencies	2025-12-22 15:49:27 +00:00
majiayu000	e06830ce0b	fix: update macOS app to use correct API port (52415) Fixes #960 The macOS app was incorrectly using port 8000 instead of the default exo API port 52415. This caused confusion as the README correctly documents port 52415 but the app was connecting to a different port.	2025-12-22 13:24:09 +00:00
Jake Hillion	1df5079b98	ci: avoid pushing alpha build as latest	2025-12-22 13:00:49 +00:00
Nightguarder	1e75aeb2c2	Add Prerequisites to Readme (#936 ) ## Motivation Users need to know what prerequisites they need in order to run exo. Simple addition to docs prevents future raised issues. ## Changes Updated ``README.md``: - to include installation instructions for [uv](https://github.com/astral-sh/uv) and [macmon](https://github.com/vladkens/macmon). Updated ``CONTRIBUTING.md``: - to verify these prerequisites are met before starting development. - Standardized on brew installation instructions for macOS users to keep the guide simple. ## Why It Works By listing these prerequisites upfront, users will set up their environment correctly before attempting to run exo. ## Test Plan ### Manual Testing MacBook Pro M4 - Verified that ``uv`` and ``macmon`` were missing initially, causing failures - after installing them via brew (as documented), uv run exo starts successfully. ### Automated Testing <!-- Describe changes to automated tests, or how existing tests cover this change --> <!-- - --> --------- Co-authored-by: Evan Quiney <evanev7@gmail.com>	2025-12-22 02:28:08 +00:00