Setting Up Your First Miner

To run a Bittensor miner, prepare the subnet’s required software, create wallet keys, fund registration, and start its miner implementation. Verify the hotkey on the subnet and monitor queries, scores, and emissions after launch.

On this page

Prerequisites
Step-by-Step Setup
Monitoring Your Miner
Troubleshooting

Prerequisites

Before you start, confirm you have the following ready: a machine meeting the hardware requirements for your chosen subnet (covered in the previous step), a stable internet connection with low latency to the Finney mainnet, and a small amount of TAO to pay the registration fee. You should also have read the subnet’s documentation and confirmed that your hardware meets its minimum specifications.

Start on testnet first

Bittensor has a test network (finney testnet) where registration fees are free or minimal and the consequences of misconfiguration are zero. Running through the full setup on testnet first — creating wallets, registering, and starting the miner — lets you identify any configuration issues before spending real TAO on mainnet registration. Use --subtensor.network test in your btcli commands to work on testnet.

Step-by-Step Setup

Follow these steps in order to go from a fresh machine to a running miner:

Match commands to the SDK version required by your subnet. The official Bittensor CLI reference documents current options; the SDK migration reference maps commands from earlier versions.

Install system dependencies
On Ubuntu 22.04, install Python 3.10+, pip, git, and build essentials. Install NVIDIA drivers and CUDA if using a GPU. Verify your GPU is visible with nvidia-smi before proceeding.
Install the Bittensor SDK
Create a Python virtual environment and install the SDK: pip install bittensor. Verify the installation with btcli --version. Install any subnet-specific dependencies from the subnet repository README.
Create a coldkey and hotkey
Run btcli wallet new_coldkey --wallet.name miner to create your coldkey (the account that holds TAO). Then run btcli wallet new_hotkey --wallet.name miner --wallet.hotkey default to create your hotkey (the identity your miner uses on-chain). Back up both key files securely — they live in ~/.bittensor/wallets/.
Fund your coldkey
You need TAO to pay the subnet registration fee (typically 0.1–1 TAO depending on current registration cost). Transfer TAO to your coldkey address. You can view your coldkey address with btcli wallet overview --wallet.name miner.
Register your hotkey on the subnet
Run btcli subnets register --wallet.name miner --wallet.hotkey default --netuid <SUBNET_UID>. This burns a small amount of TAO as a registration fee and assigns your hotkey a UID on the subnet. Check the current registration cost first with btcli subnets list.
Configure and start the miner
Clone the subnet repository and follow its README to configure the miner. Most subnets provide a start script: python neurons/miner.py --wallet.name miner --wallet.hotkey default --netuid <SUBNET_UID> --subtensor.network finney. The miner process will begin receiving queries from validators within the next epoch.
Verify your registration
Run btcli wallet overview --wallet.name miner to confirm your hotkey is registered and check your initial trust and stake values. Your UID should appear in the subnet metagraph within a few blocks of registration.

Monitoring Your Miner

Once your miner is running, track three things: trust (your accumulated validator score, visible in btcli wallet overview), rank (your position among all miners on the subnet, lower number is better), and emission (how much TAO your miner received last epoch). These numbers update each epoch and give you an immediate signal on whether your miner is performing competitively.

Monitor GPU utilization and temperature with nvidia-smi -l 5 (updates every 5 seconds) to confirm the GPU is being used during query processing. A miner that receives queries but shows low GPU utilization may be returning cached or incorrect responses, which will hurt your trust score over time.

Troubleshooting

The most common setup issue is a firewall blocking the port your miner listens on. Validators connect to your miner via a public IP and port — confirm that your machine is reachable from outside your network on the port specified in your miner config (default varies by subnet). Run btcli subnets metagraph --netuid <SUBNET_UID> to see your miner’s registered IP and port, then verify connectivity from an external machine.

If your trust score is not rising after several epochs, check that your miner is receiving and responding to queries by reviewing the miner logs. A trust score stuck at zero usually means validators cannot reach your miner, your responses are being rejected as invalid, or your miner process crashed silently. Most subnet repositories include debug logging flags that can help identify the cause.

Loading Learn

Mining · GUIDE