> For the complete documentation index, see [llms.txt](https://docs.xynq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xynq.ai/run-a-node.md).

# Run a Node

Turn your idle GPU into part of the XYNQ network and earn $XYNQ for the compute you donate.

### What contributing means

When you run a node, your GPU joins the mesh. While your machine is idle, the scheduler enlists it to serve slices of inference for other people. The instant you start using your computer again, your node drains and steps aside automatically.

### How it works at a glance

1. **Install the XYNQ client** for your platform.
2. **Sign your node in** with a payout address for $XYNQ rewards.
3. **Set your idle policy** — when and how aggressively your GPU may be used.
4. **Leave it running.** The client handles enrollment, shard hosting, and draining for you.

```bash
# install
curl -fsSL https://get.xynq.ai | sh

# register this machine and start contributing
xynq node start \
  --payout 0xYOUR_ADDRESS \
  --max-vram 0.8 \          # donate up to 80% of VRAM when idle
  --idle-after 90s \        # only enlist after 90s of no local GPU use
  --models jaguar,qwen35-27b
```

The idle policy lives in a small config file the client reads on launch:

```toml
# ~/.xynq/node.toml
payout      = "0xYOUR_ADDRESS"
region      = "auto"

[limits]
max_vram_fraction = 0.80    # never use more than this share of VRAM
max_power_watts   = 320     # cap board power while contributing
pause_on_battery  = true

[idle]
enlist_after   = "90s"      # idle time before joining the pool
release_on_use = true       # leave instantly when you touch the GPU
gpu_util_floor = 0.05       # "idle" means < 5% local utilization
```

### Idle detection

The client watches GPU and system activity. It only enlists your card when it's genuinely idle (configurable thresholds), so contributing never gets in the way of your own work or gaming.

```python
async def idle_supervisor(cfg, node):
    while True:
        util = gpu.local_utilization()           # your own apps' GPU use
        if util < cfg.idle.gpu_util_floor:
            if node.idle_for() > cfg.idle.enlist_after and not node.enrolled:
                await node.enroll()              # join the mesh, start hosting shards
        else:
            if node.enrolled and cfg.idle.release_on_use:
                await node.drain()               # you're back — leave gracefully
        await asyncio.sleep(1.0)
```

### What your node actually does

* Holds one or more **model shards** in VRAM.
* Executes its assigned layers when routed a request.
* Reports telemetry (utilization, temp, VRAM, throughput) to the coordinator.
* Participates in verification spot-checks.

On the wire, a node simply receives activations, runs its layers, and forwards the result to the next hop:

```python
class StageWorker:
    def __init__(self, stage: Stage, device="cuda"):
        self.layers = load_layers(stage, device)   # only this slice lives in VRAM

    @torch.inference_mode()
    async def forward(self, msg: Activation) -> Activation:
        x = msg.tensor.to("cuda", non_blocking=True)
        for layer in self.layers:
            x = layer(x, kv_cache=msg.kv_cache)     # KV cache is per-request, transient
        return Activation(tensor=x, stage=self.stage.next, kv_cache=msg.kv_cache)

    async def serve(self):
        async for msg in self.inbound:              # from previous stage (or coordinator)
            out = await self.forward(msg)
            await self.route_to_next(out)           # to next stage (or back to user)
```

### Reclaiming your GPU

Reclamation is instant and lossless to the network. When you return:

* the client stops accepting new work,
* in-flight slices finish or fail over to replicas,
* your node leaves the active pool,

with zero disruption to any user's chat.

See **Hardware Requirements**, **Node Lifecycle**, and **Contributor Rewards** for specifics.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xynq.ai/run-a-node.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.