github docs

2025-12-23 22:27:50 -05:00 · 2025-12-18 13:49:07 +00:00
parent f64d17fac0
commit 2c16e00be9
5 changed files with 171 additions and 5 deletions
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,43 @@
+---
+name: Bug Report
+about: Create a report to help us improve
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Describe the bug
+
+A clear and concise description of what the bug is.
+
+## To Reproduce
+
+Steps to reproduce the behavior:
+1.
+2.
+3.
+
+## Expected behavior
+
+A clear and concise description of what you expected to happen.
+
+## Actual behavior
+
+A clear and concise description of what actually happened.
+
+## Environment
+
+- macOS Version:
+- EXO Version:
+- Hardware:
+  - Device 1: (e.g., MacBook Pro M1 Max, 32GB RAM)
+  - Device 2: (e.g., Mac Mini M2, 16GB RAM)
+  - Additional devices:
+- Interconnection:
+  - (e.g., Thunderbolt 4 cable between Device 1 and 2)
+  - (e.g., WiFi 6 for Device 3)
+  - (e.g., 10GbE Ethernet between all devices)
+
+## Additional context
+
+Add any other context about the problem here.
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,11 @@
+---
+name: Feature Request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+<!-- Please use a clear, descriptive title above -->
+
+Describe what you'd like to see added to EXO.
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -0,0 +1,23 @@
+## 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 -->
+<!-- - -->
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,54 @@
+# Contributing to EXO
+
+Thank you for your interest in contributing to EXO!
+
+## Getting Started
+
+To run EXO from source:
+```bash
+git clone https://github.com/exo-explore/exo.git
+cd exo
+uv run exo
+```
+
+## Development
+
+EXO is built with a mix of Rust, Python, and TypeScript (Svelte for the dashboard), and the codebase is actively evolving. Before starting work:
+
+- Pull the latest source to ensure you're working with the most recent code
+- Keep your changes focused - implement one feature or fix per pull request
+- Avoid combining unrelated changes, even if they seem small
+
+This makes reviews faster and helps us maintain code quality as the project evolves.
+
+## Code Style
+
+Write pure functions where possible. When adding new code, prefer Rust unless there's a good reason otherwise. Leverage the type systems available to you - Rust's type system, Python type hints, and TypeScript types. Comments should explain why you're doing something, not what the code does - especially for non-obvious decisions.
+
+Run `nix fmt` to auto-format your code before submitting.
+
+## Testing
+
+EXO relies heavily on manual testing at this point in the project, but this is evolving. Before submitting a change, test both before and after to demonstrate how your change improves behavior. Do the best you can with the hardware you have available - if you need help testing, ask and we'll do our best to assist. Add automated tests where possible - we're actively working to substantially improve our automated testing story.
+
+## Submitting Changes
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/your-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin feature/your-feature`)
+5. Open a Pull Request and follow the PR template
+
+## Reporting Issues
+
+If you find a bug or have a feature request, please open an issue on GitHub with:
+- A clear description of the problem or feature
+- Steps to reproduce (for bugs)
+- Expected vs actual behavior
+- Your environment (macOS version, hardware, etc.)
+
+## Questions?
+
+Join our community:
+- [Discord](https://discord.gg/EUnjGpsmWw)
+- [X](https://x.com/exolabs)
--- a/README.md
+++ b/README.md
@@ -10,12 +10,12 @@ exo: Run your own AI cluster at home with everyday devices. Maintained by [exo l

 <h3>

-[Discord](https://discord.gg/EUnjGpsmWw) | [Telegram](https://t.me/+Kh-KqHTzFYg3MGNk) | [X](https://x.com/exolabs)
+[Discord](https://discord.gg/EUnjGpsmWw) | [X](https://x.com/exolabs)

 </h3>

 [![GitHub Repo stars](https://img.shields.io/github/stars/exo-explore/exo)](https://github.com/exo-explore/exo/stargazers)
-[![License: GPL v3](https://img.shields.io/badge/License-Apache2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0.html)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0.html)

 <a href="https://trendshift.io/repositories/11849" target="_blank"><img src="https://trendshift.io/api/badge/repositories/11849" alt="exo-explore%2Fexo | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>

@@ -23,8 +23,43 @@ exo: Run your own AI cluster at home with everyday devices. Maintained by [exo l

 ---

-> **EXO**
->
-> Coming soon. For legacy exo, see this repo's history or [exo-explore/ex-exo](https://github.com/exo-explore/ex-exo) for a snapshot.
+EXO lets you run your own AI cluster at home with everyday devices. We take advantage of Apple's M-series hardware and unified memory to run large language models, building a cluster to enable even more memory.
+
+EXO underwent a full rewrite for v1. For legacy exo, see this repo's history or [exo-explore/ex-exo](https://github.com/exo-explore/ex-exo) for a snapshot.

 ---
+
+## Features
+
+- **Automatic discovery**: Devices running EXO automatically find each other on your local network - no manual configuration.
+- **RDMA over Thunderbolt**: Ultra-low latency communication between macOS devices using RDMA over Thunderbolt.
+- **Super-linear scaling**: Get up to 3.2x performance running large models across 4 machines with Tensor parallelism and RDMA.
+
+---
+
+## Quick Start
+
+You need at least one Mac device running macOS Tahoe 26.2 (released December 12th 2025).
+
+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!
+
+To run from source, clone the repo and run `uv run exo`.
+
+After starting with either of these methods go to `http://localhost:8000` in your browser, and you'll have EXO.
+
+---
+
+## Requirements
+
+- 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
+
+We intend to add support for other hardware platforms like the DGX Spark 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.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to EXO.