Metadata-Version: 2.4
Name: nexus-worker
Version: 0.1.1
Summary: Provider daemon for NexusCompute: Monetize your GPU by serving AI inference.
Home-page: https://github.com/nexus-compute-ai/nexus-worker
Author-email: NexusCompute Network <providers@nexuscompute.ai>
License: MIT
Project-URL: Homepage, https://nexus-compute.pages.dev
Project-URL: Repository, https://github.com/nexus-compute-ai/nexus-worker
Project-URL: Documentation, https://github.com/nexus-compute-ai/nexus-worker#readme
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: websockets>=12.0
Requires-Dist: click>=8.1.7
Requires-Dist: rich>=13.7.0
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# ⚡ Become a Compute Provider with NexusWorker

[![PyPI](https://img.shields.io/pypi/v/nexus-worker.svg)](https://pypi.org/project/nexus-worker/)
[![License: MIT](https://img.shields.io/badge/License-MIT-emerald.svg)](LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![Provider Portal](https://img.shields.io/badge/Provider%20Portal-NexusCompute-teal.svg)](https://nexus-compute.pages.dev)

> **Monetize your idle GPU compute by serving open-source AI inference on the NexusCompute decentralized network.**

Whether you have a single gaming PC (NVIDIA RTX 3060/4090), an Apple Silicon Mac (M1/M2/M3/M4), or a dedicated mining rig / GPU cluster, **NexusWorker** enables you to earn revenue passively by serving inference requests for open models like **Llama 3**, **DeepSeek-R1**, and **Mistral**.

---

## 💡 Why Provide Compute on NexusCompute?

* 💰 **Passive Income**: Earn revenue for every prompt token and completion token your GPU processes.
* 🔒 **100% Secure & Outbound-Only**: Zero inbound open ports, no port forwarding, and no router configuration needed. The daemon connects outbound to Cloudflare Edge.
* 🛡️ **Completely Sandboxed**: Only communicates with your local inference backend (Ollama / vLLM) over `127.0.0.1`.
* ⚡ **1-Minute Setup**: Install in a single command with `pip install nexus-worker`.
* 🖥️ **Full Cross-Platform Support**: Runs seamlessly on Windows, Linux, and macOS.
* ⏸️ **You're in Control**: Start, pause, or stop whenever you need your GPU for gaming or work (`Ctrl + C`).

---

## 🚀 Provider Quickstart Guide (Under 3 Minutes)

### Step 1: Get Your Node Token
1. Open the [NexusCompute Provider Portal](https://nexus-compute.pages.dev).
2. Go to the **Provider Dashboard** and click **Become a Provider** or **Register Node**.
3. Copy your unique Node Token (e.g., `nx-node-0a0a3b29ed...`).

### Step 2: Ensure Your Local Engine is Running
We recommend **[Ollama](https://ollama.ai)** for the easiest 1-click setup:
1. Install Ollama and pull any model you want to serve:
   ```bash
   ollama pull llama3:8b
   ollama pull deepseek-r1:7b
   ```
2. Verify Ollama is running at `http://localhost:11434`.

*(Note: [vLLM](https://github.com/vllm-project/vllm) is also supported for high-throughput enterprise setups).*

### Step 3: Install & Start Serving
Open your terminal (PowerShell, Command Prompt, or Terminal on macOS/Linux) and run:

```bash
# 1. Install the official provider daemon from PyPI
pip install nexus-worker

# 2. (Optional) Check your detected GPU & available local models
nexus-worker info

# 3. Start earning!
nexus-worker start --token nx-node-YOUR_TOKEN_HERE
```

That's it! Your node will register with the network, begin long-polling for inference tasks, stream responses back to users, and track your earnings on your live dashboard.

---

## 🛠️ CLI Reference for Providers

### `nexus-worker start`
Connects your machine to the NexusCompute coordinator network and begins processing jobs.

| Flag | Default | Description |
| :--- | :--- | :--- |
| `--token` *(required)* | - | Your unique node token from the provider dashboard |
| `--coordinator` | `https://nexus-compute.pages.dev` | NexusCompute Coordinator edge endpoint |
| `--ollama-url` | `http://localhost:11434` | Endpoint for local Ollama instance |
| `--vllm-url` | `http://localhost:8000` | Endpoint for local vLLM instance |
| `--engine` | `auto` | Backend engine selection (`auto`, `ollama`, `vllm`, `emulate`) |
| `--poll-interval` | `1.0` | Polling heartbeat interval (seconds) |
| `--emulate` | `false` | Run in emulation / mock mode to test connection without GPU |

**Example:**
```bash
nexus-worker start --token nx-node-0a0a3b29ed4e323af354549a6681821a1b75157e
```

### `nexus-worker info`
Scans and displays your local system specs (GPU model, VRAM, and discovered models ready to serve):

```bash
nexus-worker info
```

---

## ❓ Frequently Asked Questions (FAQ) for Providers

<details>
<summary><b>Do I need to open any firewall ports or configure port-forwarding on my router?</b></summary>
<br>
<b>No.</b> NexusWorker uses outbound HTTP/2 long-polling to communicate with the coordinator edge. Because all network traffic is initiated outbound from your computer, it works behind any home router, NAT, corporate firewall, or VPN without any configuration.
</details>

<details>
<summary><b>What happens when I want to play games or use my GPU?</b></summary>
<br>
Simply press <code>Ctrl + C</code> in the terminal where <code>nexus-worker</code> is running. The daemon will gracefully disconnect and notify the coordinator. Whenever you are done with your GPU, run <code>nexus-worker start --token ...</code> to resume earning.
</details>

<details>
<summary><b>What hardware is required?</b></summary>
<br>
Any GPU with at least 6 GB VRAM (e.g. NVIDIA RTX 2060/3060/4060/4090, AMD Radeon 6000/7000 series, or Apple Silicon M1/M2/M3/M4 with unified memory). You can also run CPU inference or test using the <code>--emulate</code> flag.
</details>

<details>
<summary><b>How do I track my earnings and node uptime?</b></summary>
<br>
Visit your <a href="https://nexus-compute.pages.dev">Provider Dashboard</a> to view real-time metrics including tokens served, active hours, latency benchmarks, and accrued balance.
</details>

---

## 💻 Developer Installation (From Source)

If you wish to contribute to the open-source provider daemon codebase:

```bash
git clone https://github.com/nexus-compute-ai/nexus-worker.git
cd nexus-worker

# Setup virtual environment
python -m venv .venv
source .venv/bin/activate  # Or .\.venv\Scripts\activate on Windows

# Install in editable mode
pip install -e .
```

---

## 📄 License

Distributed under the **MIT License**. See [LICENSE](LICENSE) for more details.
