NEXAPod: Distributed Compute Fabric for Scientific Problems

NEXAPod seamlessly unites diverse computing resources from consumer GPUs to high-end clusters to tackle large-scale scientific challenges.

1. Mission

NEXAPod is a distributed computing system designed to coordinate heterogeneous compute resources—ranging from consumer GPUs to high-performance clusters—to solve large-scale scientific problems. It is, in essence, Folding@home for the AI era.

2. Frequently Asked Questions (FAQ)

What is NexaPod?
NexaPod is a modern take on distributed scientific computing. It allows anyone to contribute their computer's idle processing power to help solve complex scientific problems, starting with molecular science and protein structure prediction.

What was the inspiration for NexaPod?
NexaPod is a synthesis of three ideas: 1. Decentralized Compute at Scale (e.g., Prime Intellect): Inspired by the vision of training large AI models on a decentralized network of nodes. 2. Mesh Networking (e.g., Meshtastic): Built on the concept of a resilient, decentralized network of peers. 3. Scientific Mission (e.g., Folding@home): Focused on applying this compute power to solve real-world scientific challenges.

Is this project affiliated with Prime Intellect?
No. NexaPod is an independent, open-source project. While inspired by the ambitious goals of projects like Prime Intellect, it is not formally associated with them. NexaPod's focus is on scientific computing and inference, not general-purpose LLM training.

How is NexaPod different from Folding@home?
NexaPod aims to be a modern successor. Key differences include: - AI-Native: Designed for modern machine learning inference tasks. - Heterogeneous Compute: Built from the ground up to support diverse hardware (CPU, GPU). - Job Agnostic: The architecture can be adapted to any scientific problem, not just a single one. - Modern Tooling: Uses containers, modern CI/CD, and robust orchestration for security and scalability.

3. Project Roadmap

Phase 1: Alpha (Launched)

• Goal: Ship a working proof-of-concept. Test the core system and validate that the distributed mesh works in the wild.
• Actions: Launched the first public alpha running a secondary structure prediction job. Onboarding technical users to gather feedback, observe bugs, and fix obvious blockers.

Phase 2: Beta (Next 2–4 Weeks)

• Goal: Iterate on user feedback, harden the system, and expand the network.
• Actions: Bugfixes and infrastructure upgrades (better logging, validation, robust VPS). Refine onboarding and documentation. Begin groundwork for ZK proofs, incentives, and improved scheduling.

Phase 3: Full Launch (Post-Beta, ~1–2 Months Out)

• Goal: A production-grade, incentivized scientific compute mesh ready to tackle a "grand challenge" problem.
• Actions: Implement ZK proofs for trustless validation. Roll out more robust job scheduling. Launch incentive mechanisms (token/reputation). Target a large-scale challenge like DreamMS (inference on 201 million molecular datapoints).

4. DevOps & Containers

This project uses a robust GitHub Actions workflow for continuous integration and delivery. The pipeline includes: - Test Stage: Runs automated tests for quality and reliability. - Build & Push Stage: Builds server and client Docker images and pushes them to GitHub Container Registry (GHCR). - Artifact Storage: Stores build artifacts for traceability.

Deployment to production/staging is currently manual, allowing for controlled and verified rollouts.

5. Getting Started

There are two main ways to run the project: using the installed package or running the script directly.

Method 1: Install and Use nexapod-cli (Recommended)

This method installs the project as a command-line tool, nexapod-cli, which you can run from anywhere.

1. Installation

Open a terminal in the project's root directory and run:

bash pip install -e .

2. Usage

After installation, you can use the nexapod-cli command with one of the available subcommands:

To set up the client:

bash nexapod-cli setup

To run a specific job:

bash nexapod-cli run <your-job-id>

Example:

bash nexapod-cli run job-12345

To start the client worker:

bash nexapod-cli start

Method 2: Run the Script Directly (For Development)

This method is useful for development as it runs the CLI without installation.

For Bash users (Linux, macOS, Git Bash on Windows):

1. Make the script executable (only needs to be done once): bash chmod +x scripts/NexaPod.sh
2. Run the script from the project root: bash ./scripts/NexaPod.sh setup ./scripts/NexaPod.sh run my-job-123

For PowerShell users (Windows):

1. Open a PowerShell terminal. You may need to allow script execution for the current session: powershell Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
2. Run the script from the project root: powershell .\scripts\NexaPod.ps1 setup .\scripts\NexaPod.ps1 run my-job-123

For Developers (Running Locally with Docker Compose)

To run the entire stack (server, client, monitoring) locally using the pre-built images from the registry: 1. Prerequisites: Docker and Docker Compose. 2. Log in to GHCR (first time only): bash # Use a Personal Access Token (classic) with read:packages scope. echo "YOUR_PAT_TOKEN" | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin 3. Pull the latest images: bash docker-compose pull 4. Launch Services: bash docker-compose up -d This will start the server, a local client, Prometheus, and Grafana. To stop the services, run docker-compose down.

Monitoring Dashboard (Local)

Once the services are running, you can access the monitoring stack: - Prometheus: http://localhost:9090 (View metrics and service discovery) - Grafana: http://localhost:3000 (Create dashboards; default user/pass: admin/admin)

6. Project Structure

nexapod/ ├── NexaPod_CLI/ # The user-facing CLI tool ├── client/ # Worker node agent code ├── Infrastructure/ # Dockerfiles and Kubernetes manifests ├── docs/ # Architecture, API, and Onboarding documentation ├── scripts/ # Utility scripts ├── tests/ # Unit and integration tests ├── .github/ # CI/CD workflows └── docker-compose.yaml # Local development setup

7. Core Components & Tech Stack

| Layer | Component | Tech / Libs | |----------------------|--------------------------|-------------------------------------------------------| | Comms | HTTP API | FastAPI (server) + requests (client) | | Profiling | Hardware detection | psutil, nvidia-ml-py, subprocess (nvidia-smi) | | Execution | Container runtime | Docker (nexapod CLI) | | Scheduling | Job queue & matching | In-memory queue (Alpha) | | Data storage | Metadata & logs | SQLite (Alpha) → Postgres | | Security | Cryptographic signatures | cryptography (Ed25519) | | Orchestration | Single-node MVP | Python scripts + Docker | | | Multi-node (v2) | Kubernetes (k8s) manifests | | Monitoring | Metrics & logs | Prometheus / Grafana | | Testing | Unit & integration tests | pytest |

8. Contributing

PRs and issues are welcome! See Docs/CONTRIBUTING.md for detailed guidelines.