---
sidebar_position: 2
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lium.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Node Quickstart

## Get started in 5 min

Three commands and a portal click bring a GPU machine online as a Lium node.

### Requirements

- **OS**: Ubuntu 24.04 LTS, or Ubuntu 22.04 LTS with the HWE kernel. Both give a 6.8 kernel. See [Supported operating systems](#supported-operating-systems) for what else works.
- **GPU**: NVIDIA driver installed (`nvidia-smi` works)
- **HGX H100/H200 hosts** (SXM modules behind an NVSwitch): NVIDIA Fabric Manager running and the fabric in `State : Completed` (`nvidia-smi -q | grep -A4 -i fabric`) before you add the node — until then `nvidia-smi` works but CUDA cannot start, and the GPU probe fails every cycle with `GPU_VERIFY_FAILED`. See [Troubleshooting → CUDA cannot start](../troubleshooting.md#gpu-verify-failed-cuda-not-ready).
- **Docker**: installed and running
- **Network**: **100 Mbps download** as the validator measures it (an EMA of its own VerifyX probe, see [Troubleshooting → VerifyX](../troubleshooting.md#2-run-the-verifyx-benchmark-to-reproduce-validator-checks)), public IP, ports open (default `8080` HTTP and `2200` SSH)
- **Hardware**: ≥ 8 GB RAM, ≥ 150 GB of disk: the node images take about 40 GB and the node needs 100 GB free after them. To earn the idle (unrented) incentive the node also needs **total disk of at least 1.5× its total GPU VRAM** — an 8× H100 80GB node reports 637.2 GB of VRAM, so it needs 955.8 GB of disk, not 100 GB. See [Subnet emission → Unrented pool](../rewards/emission.mdx#unrented-pool)
- **8× H200, B200 or B300 nodes**: to earn idle pay, the node must offer one of three things: [GPU splitting](./gpu-splitting.md) with a minimum GPU count per rental below 8, [GPU profiling](./gpu-profiling.md), or an attested [confidential VM](./cvm.md). Without one of these the node is rentable and earns rental income, but it earns nothing while it waits for a rental. The check reason is `flagship_without_ncu_or_split`. The Add Node form shows this checklist when you pick one of these models with a count of 8.
- **A provider account** — see [Provider Quickstart](../quickstart). With an e-mail or Google account (Path A, [not open yet](../quickstart#path-a--create-an-account-nothing-to-buy-first)) nothing is registered: the portal's **Overview** page shows the install command with the `-k` value already filled in (Lium's listing key; the node becomes yours when you add it in the portal). With your own registered hotkey (Path B) the `-k` value is that hotkey's SS58 address.

### Supported operating systems {#supported-operating-systems}

The node runs in a container, so the host OS matters mostly for the kernel it provides. The validator reads the host kernel (`uname -r`) on every check and stores it in the node's specs as `specs.kernel`. The rows below group kernels by family, the first two numbers of the version (`6.8.0-138-generic` is family 6.8).

| Host OS | Kernel family | Status | Notes |
|---|---|---|---|
| Ubuntu 24.04 LTS with its default kernel | 6.8 | Recommended | The setup most nodes run. 431 active nodes had a 6.8 kernel on 13 Sep 2026. |
| Ubuntu 22.04 LTS with the HWE kernel | 6.8 | Recommended | HWE (Hardware Enablement) is Ubuntu's newer kernel for an LTS release. The default 22.04 kernel is 5.15. [Sysbox](./sysbox.md), the container runtime the node needs, requires 5.19 or newer. On 5.15 the installer stops and prints the command that installs `linux-generic-hwe-22.04`. |
| Ubuntu 24.04 HWE, Ubuntu 25.10, Ubuntu 26.04 | 6.14 to 7.0 | Works. We measure it. | 36 active nodes ran a 7.0 kernel on 13 Sep 2026. We compared them with 6.8 nodes of the same GPU model and found no slowdown (see below). Fewer nodes run these kernels, so we have less data on them. |
| Cloud and VM kernels (`-azure`, `-nvidia`, `-intel`, `-dstack`) | 6.8 to 6.17 | Works. We measure it. | The family rule applies to the version, not to the suffix. A 6.8 cloud kernel is in the recommended family. A 6.11 or 6.17 cloud kernel gets the same note as the row above. |
| Ubuntu 20.04 or older, other Linux distributions | any | Unsupported | Ubuntu 20.04 stops at kernel 5.15, below the Sysbox minimum. The installer targets Ubuntu. Other distributions are not tested. |

A kernel in a "Works" row is not a problem. The installer and the validator do not warn about it, score it or change idle pay for it.

What we measured on 13 Sep 2026, kernel 7.0 nodes against 6.8 nodes of the same GPU model. On RTX 5090 (24 nodes on 6.8, 11 on 7.0) the validator's GPU check took 12.4 s on 7.0 and 15.2 s on 6.8. Those are per-node medians over 72 hours. Over 14 days, 7.0 nodes ended 3.0 % of 636 rentals in an error (node offline, node broken, start failed). 6.8 nodes ended 12.1 % of 5,221 rentals that way. The Ubuntu 26.04 kernel regression reported in public is an AMDGPU driver loop in 7.0.0-28. It affects AMD GPUs only, and Lium nodes run NVIDIA GPUs. If you already run a 7.0 kernel, keep it. If you set up a new node, pick a recommended row. That is where we have the most data.

### Optional (strongly recommended)

- **[Docker Storage Setup](./docker-storage.md)** — provision XFS-backed Docker storage with project quotas so each rented pod is capped at the disk size advertised in the portal.

  :::danger Why this matters
  Without XFS + `pquota`, a renter can write across the **entire host disk**, past the slice they paid for. The validator detects this as a misbehaving node and your **score drops to 0**, which means **no emission and no rentals** until you reprovision storage.
  :::

### Step 1 — Install Sysbox (required)

[Sysbox](./sysbox.md) is **required**. Validators reject any node missing the `sysbox-runc` runtime — without it the node earns no emission and cannot be rented. Install it before anything else. The `lium-io` repo ships an installer that also handles the NVIDIA Container Toolkit:

```bash
curl -fsSL https://raw.githubusercontent.com/Datura-ai/lium-io/main/neurons/executor/nvidia_docker_sysbox_setup.sh | sudo bash
```

The installer checks the host before it installs anything and prints one `PASS`, `FIX` or `SKIP` line per requirement — kernel, Docker, NVIDIA driver, the iptables modules the validators' probe needs, disk for the idle incentive, ports — with the command that fixes each `FIX`; `SKIP` is a check that could not run. To run only the checks, add `-s -- --check` after `sudo bash`; see [Sysbox → Check the host first](./sysbox.md#check-the-host-first).

Verify with the same command our validator uses:

```bash
docker run --rm --runtime=sysbox-runc --gpus all daturaai/compute-subnet-executor:latest nvidia-smi
```

If `nvidia-smi` output appears — you're good. Hitting `no such file or directory` on `/proc/driver/nvidia`? Sysbox is running without ID-mapped mounts, usually an old kernel — see [Kernel 5.19+ is mandatory for GPUs](./sysbox.md#kernel-519-is-mandatory-for-gpus). Running Docker 29.x, or hitting `permission denied` or `namespace {"time" ""} does not exist`? See [Docker 29](./sysbox.md#docker-29-two-required-settings).

### Step 2 — Run the node in one script

**Shortest path:** open [provider.lium.io](https://provider.lium.io) → **Add Node** → **Run one command on the host** first. It shows a single line, `curl -fsSL https://lium.io/mine.sh | bash -s -- --register <token>`, that installs the node *and* registers it in your portal, so you can skip Step 3. Use the `-k` command below only if you want to start the node before signing in.

```bash
curl -fsSL https://lium.io/mine.sh | bash -s -- -k <your_provider_hotkey_ss58>
```

This installs the [`lium`](https://github.com/Datura-ai/lium) CLI, then runs `lium mine`, which:

| Step | Action |
|------|--------|
| 1 | Clone or update the `lium-io` repo into `./compute-subnet` |
| 2 | Run `scripts/install_executor_on_ubuntu.sh` — apt base packages, Docker Engine + compose plugin if missing, `docker info` check |
| 3 | Prerequisite check — fails fast if `nvidia-smi`, `nvidia-container-cli` or `docker` is missing |
| 4 | Render `neurons/executor/.env` from the template (ports + hotkey) |
| 5 | `docker compose up -d` and wait for the container to report `healthy` |
| 6 | Run the validator's own check via `daturaai/lium-validator:latest` |

`lium mine --verbose` prints this plan before it starts.

You'll be prompted for ports interactively. Defaults work for most providers:

- **Service port** — node HTTP API (default `8080`)
- **Node SSH port** — used by validators to SSH into the container (default `2200`)
- **Public SSH port** — only if behind NAT and forwarding a different port
- **Renting port range** — optional, e.g. `2000-2005`

To skip prompts and accept all defaults, append `--auto`:

```bash
curl -fsSL https://lium.io/mine.sh | bash -s -- -k <your_provider_hotkey_ss58> --auto
```

When the script finishes, note the printed **GPU type, IP address, port, and GPU count** — you'll paste them into the portal next.

### Step 3 — Register the node in the Provider Portal

1. Sign in at [provider.lium.io](https://provider.lium.io) — an e-mail or Google account (Path A, not open yet) signs in at `/login`; a hotkey account follows [Provider Quickstart → Path B, Step 2](../quickstart#step-2--sign-in-to-the-provider-portal).
2. In the sidebar, click **Add Node**.
3. Fill the form with the values printed at the end of Step 2:
   - **GPU Type** (e.g. `RTX 4090`)
   - **GPU Count**
   - **IP Address**
   - **Port** (default `8080`)
   - **Price per GPU (USD/hr)**
4. Click **Add Node** to submit.

After submitting, the node appears in your portal as **VALIDATION PENDING** and turns **AVAILABLE** once a validator has verified it and published the result. Over the 175 nodes added in the 30 days to 6 Sep 2026 that took **21 minutes at the median and 64 minutes at the 90th percentile**, never under 8 — the validator runs every 15 minutes and publishes only after it has finished every provider in that cycle. It never happens if the account is not connected to a coordinator (the Central Provider opt-in in [Provider Quickstart → Step 2](../quickstart#step-2--sign-in-to-the-provider-portal); an e-mail or Google account is connected automatically), and it costs one extra cycle when the first network probe measures under 100 Mbps. What each badge means and what to do about it: [Monitoring → What each status means](../portal/monitoring.md#what-each-status-means). Detailed walk-through: [Managing Nodes → Adding New Nodes](../portal/managing-nodes#adding-new-nodes).

## What's next

1. [Docker Storage Setup](./docker-storage.md) — provision XFS-backed Docker storage for stable rentals.
2. [GPU splitting](./gpu-splitting.md) — let multiple customers rent partial GPUs from one node.
3. [CVM (Confidential VM)](./cvm.md) — TDX-isolated nodes for sensitive workloads.
4. [Manage prices and notice periods](../portal/managing-nodes.md) in the Provider Portal.

## Other useful `lium` commands

```bash
lium gpu-splitting check    # inspect host before enabling GPU splitting
lium gpu-splitting setup    # provision XFS-backed Docker storage non-interactively
lium gpu-splitting verify   # confirm the host meets the splitting requirements
```

See [GPU Splitting](./gpu-splitting.md) for the full workflow.