lium.io

<p align="center">
  <img src="https://github.com/user-attachments/assets/69550b83-91a9-492a-bd7a-09d35c6106d3" alt="Lium" width="120" height="120" />
</p>

<h1 align="center">Lium</h1>

<p align="center"><strong>The decentralized GPU cloud on Bittensor Subnet 51.</strong></p>

<p align="center">
  <a href="https://github.com/Datura-ai/lium-io/actions/workflows/test.yml"><img src="https://github.com/Datura-ai/lium-io/actions/workflows/test.yml/badge.svg" alt="Tests" /></a>
  <a href="https://taomarketcap.com/subnets/51"><img src="https://img.shields.io/badge/Bittensor-Subnet%2051-000000" alt="Bittensor Subnet 51" /></a>
  <a href="https://pypi.org/project/lium.io/"><img src="https://img.shields.io/pypi/v/lium.io?label=lium.io%20CLI" alt="lium.io on PyPI" /></a>
  <a href="https://discord.gg/lium"><img src="https://img.shields.io/discord/1350984082733142026?label=Discord&logo=discord&logoColor=white" alt="Discord" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/Datura-ai/lium-io" alt="MIT License" /></a>
</p>

Lium is a GPU rental marketplace. Providers around the world list their NVIDIA GPUs, and renters (people, teams and AI agents) rent them by the hour at [lium.io](https://lium.io), from the web, the `lium` CLI, the Python SDK or the API. Every node is checked by the Subnet 51 validator every 15 minutes: hardware, GPU, network, ports and a Sysbox-isolated container runtime. Only nodes that pass are listed. Providers earn twice: a share of what renters pay, and Bittensor emission for their nodes, including idle pay for eligible GPUs that are not rented. This repository holds the code that runs on providers' machines (the node agent and the miner) and the validator that scores them.

## Quick links

| | |
|---|---|
| Rent a GPU | [lium.io](https://lium.io) |
| Documentation | [docs.lium.io](https://docs.lium.io) ([providers](https://docs.lium.io/providers), [validators](https://docs.lium.io/validators), [renters](https://docs.lium.io/pod-users), [developers](https://docs.lium.io/developers)) |
| Provider Portal | [provider.lium.io](https://provider.lium.io) (add nodes, set prices, see earnings) |
| Rewards calculator | [provider.lium.io/rewards-calculator](https://provider.lium.io/rewards-calculator) |
| CLI and Python SDK | [Datura-ai/lium](https://github.com/Datura-ai/lium): `pip install lium.io` ([CLI docs](https://docs.lium.io/developers/cli/overview), [SDK docs](https://docs.lium.io/developers/sdk)) |
| Community and support | [Discord](https://discord.gg/lium), and for account help, a private ticket in [`#tickets`](https://discord.com/channels/1350984082733142026/1547193098969284650) |

## For renters

Sign up at [lium.io](https://lium.io), pick a GPU, and SSH into your pod. From a terminal:

```bash
pip install lium.io
lium init   # saves your API key
lium ls     # GPUs available now, with prices
```

Next steps: the [renter quickstart](https://docs.lium.io/pod-users/quickstart), the [CLI quickstart](https://docs.lium.io/developers/cli/quickstart), or [AI agents](https://docs.lium.io/developers/agents) for the fully headless path.

## For providers

Docs and the Provider Portal call a miner a **provider** and an executor a **node**.

**Why list your GPUs on Lium**

- **Two income streams.** You list each node at your own price per GPU-hour and get a share of what renters pay. On top of that, your hotkey earns Subnet 51 emission for rented nodes. See [How providers earn](https://docs.lium.io/providers/rewards).
- **Idle pay.** An eligible GPU that is not rented still earns from the unrented pool (see [How incentives work](#how-incentives-work)).
- **One-command setup.** `lium mine` installs, configures and checks a node.

### Requirements

Per GPU host (the full list is in the [Node Quickstart](https://docs.lium.io/providers/nodes/quickstart#requirements)):

- **OS:** Ubuntu 24.04 or 26.04, or Ubuntu 22.04 with the HWE kernel. Sysbox needs kernel 5.19 or newer. On 26.04 the Sysbox setup script adds an AppArmor rule so Sysbox can mount its file systems.
- **GPU:** an NVIDIA model on the [supported list](https://docs.lium.io/providers/architecture#supported-gpus) (the validator's source of truth is `GPU_MODEL_RATES` in [`neurons/validators/src/services/const.py`](neurons/validators/src/services/const.py)), with the driver installed (`nvidia-smi` works).
- **Docker Engine**, installed and running.
- **Network:** a public IP and at least **100 Mbps download**, as measured by the validator.
- **Hardware:** at least 8 GB RAM and 140 GB free disk before the first install (100 GB once the node's images are pulled). For idle pay, total disk must be at least **1.5× total GPU VRAM**. The node removes the volumes of ended rentals by itself, and below 100 GB free or above 90% used also the images no container uses. An idle node may keep a background workload's model checkpoint; it is listed as free disk and removed when a rental's ordered disk does not fit beside it.
- **A registered hotkey** on Subnet 51 (below). Keep your coldkey off the server.

### Ports

| Port | Default | Who connects | Set in `neurons/executor/.env` |
|---|---|---|---|
| Node service (HTTP) | `8080` with `lium mine` (`8001` in the template) | The provider coordinator (yours or the Central Provider Server) | `EXTERNAL_PORT` / `INTERNAL_PORT` |
| Node SSH | `2200` | The validator | `SSH_PORT`, plus `SSH_PUBLIC_PORT` when NAT forwards a different public port |
| Renting ports | All ports | Renters' pods | `RENTING_PORT_RANGE` (like `40000-40100`) or, behind NAT, `RENTING_PORT_MAPPINGS`. Set one, never both. **At least 3 must be reachable from the internet.** |

A self-hosted coordinator also needs its own `EXTERNAL_PORT` (default `8000`) open to the validator; see [`neurons/miners/README.md`](neurons/miners/README.md).

### Install

1. **Register a hotkey** on Subnet 51, from your own machine and not the GPU host. The fee is dynamic ([check it here](https://taomarketcap.com/subnets/51/registratio