---
sidebar_position: 5
---

> ## 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.

# Self-Hosted Provider Setup

This page covers installing and operating the **self-hosted provider** — the lightweight CPU coordinator that connects your GPU nodes to the Lium network. Skip this entire page if you opted into the [Lium.io Central Provider Server](./provider-configuration.md), which runs the coordinator for you.

For the conceptual picture of how the coordinator, nodes, validators, and Provider Portal fit together, see [Architecture](./architecture.md).

:::warning Coldkey safety
Never place your coldkey on a provider server. Coldkeys belong on a secure, offline machine. Provider infrastructure only needs the registered hotkey.
:::

## Prerequisites

Before installing the self-hosted provider, you should have:

- A registered Bittensor wallet (coldkey + hotkey) — see the [Bittensor wallet docs](https://docs.bittensor.com/getting-started/wallets) if you haven't created one.
- Your hotkey already registered on subnet 51 (`btcli subnet register --netuid 51 ...`) — see [Quickstart Step 1](./quickstart.md#step-1--register-your-provider-on-subnet-51).
- Basic Linux administration and Docker familiarity.

## System Requirements

The self-hosted provider is a lightweight CPU coordinator — it does **not** need a GPU.

| Component | Minimum | Recommended |
|-----------|---------|-------------|
| CPU       | 4 cores | 8 cores     |
| RAM       | 8 GB    | 16 GB       |
| Storage   | 50 GB   | 100 GB SSD  |
| Network   | 100 Mbps | 1 Gbps     |
| OS        | Ubuntu 20.04+ | Ubuntu 22.04 |

GPU nodes have their own separate requirements — see [Node Quickstart → Requirements](./nodes/quickstart.md#requirements).

## Installation

### Step 1 — Clone the repo

```bash
git clone https://github.com/Datura-ai/lium-io.git
cd lium-io
```

### Step 2 — Run the installer

```bash
chmod +x scripts/install_miner_on_ubuntu.sh
./scripts/install_miner_on_ubuntu.sh
```

Verify the tools are present:

```bash
btcli --version
docker --version
```

If either is missing, install them directly:

- **Bittensor**: [official installation guide](https://github.com/opentensor/bittensor/blob/master/README.md#install-bittensor-sdk)
- **Docker**: [Docker's documentation](https://docs.docker.com/engine/install/)

### Step 3 — Configure the `.env`

Create the config from the template:

```bash
cp neurons/miners/.env.template neurons/miners/.env
```

Set these values:

```bash
# Your Bittensor wallet name (check with: btcli wallet list)
BITTENSOR_WALLET_NAME=your_wallet_name

# Your hotkey name (must already be registered on subnet 51)
BITTENSOR_WALLET_HOTKEY_NAME=your_hotkey_name

# Public IP of this provider host
EXTERNAL_IP_ADDRESS=your.server.ip.address

# Path to the Bittensor wallet directory
HOST_WALLET_DIR=/home/your_user/.bittensor/wallets

# Network ports (EXTERNAL_PORT must be open in the firewall)
INTERNAL_PORT=8000
EXTERNAL_PORT=8000
```

:::caution Network configuration
`EXTERNAL_PORT` must be:

- open in your firewall / cloud security group
- not blocked by your ISP
- forwarded correctly if the host is behind NAT
:::

### Step 4 — Start the provider

```bash
cd neurons/miners
docker compose up -d
```

Verify it's running:

```bash
docker compose ps
docker compose logs -f
```

## Adding GPU nodes

Once the self-hosted provider is up, you have two ways to attach GPU nodes:

1. **Via the Provider Portal** (recommended) — register each node from the [portal UI](./portal/managing-nodes.md#adding-new-nodes); the portal pushes config to the self-hosted provider automatically.
2. **Via the provider CLI** — run `add-executor` directly inside the provider container (described below). Useful for scripted / batch operations.

### Add a node from the CLI

```bash
docker exec <provider_container> pdm run src/cli.py add-executor \
  --address <node_ip> \
  --port <node_port> \
  --validator <validator_hotkey>
```

| Argument | Meaning |
|----------|---------|
| `<provider_container>` | Container ID/name (find with `docker ps`) |
| `<node_ip>` | Public IP of the node host |
| `<node_port>` | Node's listening port (default `8001`) |
| `<validator_hotkey>` | Validator SS58 to associate this node with. **Optional** — see note below. |

:::tip Picking a validator
Today there is exactly **one active validator sending jobs** on Subnet 51: `5F7X5UpKSr26KU3jKfpLmT8kuKtBNyHhEnfS8xtxPCqCb13p`. You can pass that hotkey explicitly, but the argument is fully optional — if you omit it, the provider falls back to the main Lium validator automatically. There is no benefit to spreading or rotating across multiple validators on this subnet at the moment.
:::

### Remove a node

```bash
docker exec <provider_container> pdm run src/cli.py remove-executor \
  --address <node_ip> \
  --port <node_port>
```

### Switch a node's validator

```bash
docker exec -it <provider_container> pdm run src/cli.py switch-validator \
  --address <node_ip> \
  --port <node_port> \
  --validator <validator_hotkey>
```

### List attached nodes

```bash
docker exec <provider_container> pdm run src/cli.py list-executors
```

## Logs and basic monitoring

```bash
# Recent logs
docker compose logs --tail=100

# Follow logs
docker compose logs -f

# List currently attached nodes
docker exec <provider_container> pdm run src/cli.py list-executors
```

For node-level performance and validator scoring, use the [Provider Portal monitoring view](./portal/monitoring.md) or [TaoMarketCap Subnet 51](https://taomarketcap.com/subnets/51/miners).

To check your wallet status from the host:

```bash
btcli wallet overview --netuid 51
```

## Operational security

The self-hosted provider is exposed to the internet and signs with your hotkey. Treat the host accordingly.

1. **Key management**
   - Coldkeys stay offline. Never copy them to a provider host.
   - Only the registered hotkey is needed on the provider.
   - Rotate hotkeys promptly if a host is compromised.

2. **Network**
   - Restrict `EXTERNAL_PORT` and SSH to known sources where possible.
   - Use SSH key authentication, disable password login.
   - Keep the host patched.

3. **Operations**
   - Watch for node disconnections — they translate directly into lost emission.
   - Back up `neurons/miners/.env` and the wallet directory.

## Troubleshooting

| Symptom | Likely cause |
|---------|--------------|
| Node not connecting | Firewall / NAT blocking `EXTERNAL_PORT`, wrong `<node_ip>`, or node host down |
| Provider container crashes on start | Wallet path missing or unreadable; check `HOST_WALLET_DIR` mount |
| Low or zero rewards | Node not scored yet (wait one validator cycle ~15 min), validator assignment issue, or node failing rental checks — see [Monitoring](./portal/monitoring.md) |
| Registration command failed | Insufficient TAO balance for the dynamic registration fee |

Pre-support checklist:

- [ ] Hotkey registered on subnet 51 (`btcli wallet overview --netuid 51`)
- [ ] Provider container running (`docker compose ps`)
- [ ] `EXTERNAL_PORT` reachable from the public internet
- [ ] Each node's `MINER_HOTKEY_SS58_ADDRESS` matches your registered hotkey
- [ ] Wallet directory mounted into the container correctly

## Next

- [Bring a GPU node online](./nodes/quickstart.md)
- [Provider Portal overview](./portal/overview.md) — manage nodes and pricing in the UI
- [Architecture](./architecture.md) — conceptual picture of the system