Skip to main content

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, which runs the coordinator for you.

For the conceptual picture of how the coordinator, nodes, validators, and Provider Portal fit together, see Architecture.

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 if you haven't created one.
  • Your hotkey already registered on subnet 51 (btcli subnet register --netuid 51 ...) — see Quickstart Step 1.
  • Basic Linux administration and Docker familiarity.

System Requirements​

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

ComponentMinimumRecommended
CPU4 cores8 cores
RAM8 GB16 GB
Storage50 GB100 GB SSD
Network100 Mbps1 Gbps
OSUbuntu 20.04+Ubuntu 22.04

GPU nodes have their own separate requirements — see Node Quickstart → Requirements.

Installation​

Step 1 — Clone the repo​

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

Step 2 — Run the installer​

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

Verify the tools are present:

btcli --version
docker --version

If either is missing, install them directly:

Step 3 — Configure the .env​

Create the config from the template:

cp neurons/miners/.env.template neurons/miners/.env

Set these values:

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

cd neurons/miners
docker compose up -d

Verify it's running:

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; 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​

docker exec <provider_container> pdm run src/cli.py add-executor \
  --address <node_ip> \
  --port <node_port> \
  --validator <validator_hotkey>
ArgumentMeaning
<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.
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​

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

Switch a node's validator​

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

List attached nodes​

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

Logs and basic monitoring​

# 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 or TaoMarketCap Subnet 51.

To check your wallet status from the host:

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​

SymptomLikely cause
Node not connectingFirewall / NAT blocking EXTERNAL_PORT, wrong <node_ip>, or node host down
Provider container crashes on startWallet path missing or unreadable; check HOST_WALLET_DIR mount
Low or zero rewardsNode not scored yet (wait one validator cycle ~15 min), validator assignment issue, or node failing rental checks — see Monitoring
Registration command failedInsufficient 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​