diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..04abb3e1 --- /dev/null +++ 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. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 00000000..9a030e4b --- /dev/null +++ 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: '' +--- + + + +Describe what you'd like to see added to EXO. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..0a924f88 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,23 @@ +## Motivation + + + + +## Changes + + + +## Why It Works + + + +## Test Plan + +### Manual Testing + + + + +### Automated Testing + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..0df6a5b0 --- /dev/null +++ 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) diff --git a/README.md b/README.md index ef097f9b..03a7fc13 100644 --- 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

-[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)

[![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) exo-explore%2Fexo | Trendshift @@ -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.