Skip to content

Latest commit

 

History

History
326 lines (236 loc) · 9.24 KB

04-running-your-first-miner.md

File metadata and controls

326 lines (236 loc) · 9.24 KB

Tutorial 04 — Running Your First Miner

Ready to see rewards flow? This tutorial keeps things upbeat while you launch a reference miner, validate the environment, and keep logs tidy. We’ll highlight friendly tips, defensive warnings, diagrams, and verification commands so your first run feels smooth.

miner launch flow placeholder

Table of Contents

🎯 Learning goals

  • Select an appropriate subnet and confirm registration.
  • Configure miner dependencies (CUDA, ports, Python modules).
  • Launch a reference miner and keep it alive with screen or systemd.
  • Interpret miner logs and key performance metrics.

🧠 Prerequisites

  • Tutorials 01–03 complete.
  • A registered hotkey with sufficient TAO for burn fees.
  • Optional: NVIDIA GPU + drivers if targeting GPU-heavy subnets.

💡 Tip: Keep /opt/tensorium/logs/miner-notes.md handy. Jot down subnets you try, miner scripts used, and any special parameters.

1. Pick a subnet

Use btcli subnet list to find a subnet that matches your hardware:

Subnet Hardware Notes
1 (nakamoto) CPU Classic PoW, good for testing
3 (vision) GPU Requires CUDA 12+, >12 GB VRAM
7 (language) GPU/CPU Balanced workloads

Once selected, confirm your hotkey is registered:

btcli subnet inspect --netuid 1 --wallet-name tensorium --wallet-hotkey miner-main

subnet decision placeholder

2. Environment validation

Run the helper scripts:

./scripts/detect_gpu.sh
./scripts/install_bittensor.sh --validate-only

Ensure ports 8091/8092 are free:

sudo lsof -i -P -n | grep 8091

For GPU miners, confirm CUDA libraries:

nvcc --version
nvidia-smi

⚠️ Warning: If ports are already in use, don’t blindly kill processes—confirm whether another miner or critical service depends on them before reassigning ports.

3. (Optional) GPU tuning quickstart

If you plan to mine on GPU-heavy subnets, align drivers and power targets:

sudo ubuntu-drivers autoinstall
sudo reboot

# After reboot validate with:
nvidia-smi
sudo nvidia-smi -pm 1
sudo nvidia-smi -pl 320

Log GPU metadata alongside your miner configs:

scripts/detect_gpu.sh >> /opt/tensorium/logs/gpu-inventory.log
echo "netuid=1 hotkey=miner-main -> RTX 4090" >> /opt/tensorium/logs/gpu-inventory.log

gpu tuning placeholder

4. Configure miner settings

Most reference miners use YAML or CLI flags. Example for the text miner:

Create configs/miner-netuid-1.yaml:

wallet:
  name: tensorium
  hotkey: miner-main
  hotkey_password: ${BT_HOTKEY_PASSWORD}
netuid: 1
axon:
  ip: "auto"
  port: 8091
miner:
  blacklist:
    default: false
system:
  log_dir: /opt/tensorium/logs/miner-netuid-1

Export environment variables:

export BT_HOTKEY_PASSWORD="$(pass show tensorium/hotkey)"

config diagram placeholder

5. Launch inside screen

cd /opt/tensorium/bittensor
source .venv/bin/activate
screen -S miner-1 -L -Logfile /opt/tensorium/logs/miner-1.log \
  python neurons/text/text_server.py --config configs/miner-netuid-1.yaml
  • Ctrl+A D detaches the session.
  • screen -r miner-1 reattaches it later.

6. Optional systemd service

Create /etc/systemd/system/tensorium-miner.service:

[Unit]
Description=Tensorium reference miner
After=network-online.target

[Service]
User=ubuntu
WorkingDirectory=/opt/tensorium/bittensor
EnvironmentFile=/opt/tensorium/.env
ExecStart=/opt/tensorium/bittensor/.venv/bin/python neurons/text/text_server.py \
  --config configs/miner-netuid-1.yaml
Restart=on-failure
RestartSec=15
StandardOutput=append:/opt/tensorium/logs/miner-1.log
StandardError=append:/opt/tensorium/logs/miner-1.log

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now tensorium-miner
sudo systemctl status tensorium-miner

7. Monitor performance

Key metrics:

  • Difficulty: Increases as the subnet fills; track via btcli subnet show.
  • Incentive: Indicates emission share; falling incentives may mean your miner underperforms.
  • Axon status: btcli axon info to verify connectivity.
  • Logs: Look for 🎯 or 🔥 markers in reference miner logs indicating success/failure.

Script snippet to tail logs:

tail -f /opt/tensorium/logs/miner-1.log | grep -E "hotkey|mining step|incentive"

Collect metrics with btcli miner stats (if available in your version) or third-party dashboards.

8. Verification checklist

After launch, run these to confirm health:

btcli subnet show --netuid 1 | head -n 20
btcli axon info --netuid 1 --wallet-name tensorium --wallet-hotkey miner-main
tail -n 20 /opt/tensorium/logs/miner-1.log
systemctl status tensorium-miner --no-pager

Log outcomes:

echo "$(date -u) netuid=1 miner online incentive=$(grep 'incentive' /opt/tensorium/logs/miner-1.log | tail -n1)" \
  >> /opt/tensorium/logs/miner-health.log

9. Common errors & fixes

Error Meaning Fix
Port already in use Another process uses 8091 Change axon port in config or stop conflicting service
RegistrationRequired Hotkey not registered Run btcli subnet register
Hotkey password incorrect Bad env var Update /opt/tensorium/.env and restart
CUDA initialization failed Driver mismatch Reinstall drivers, reboot, verify nvidia-smi

Keep /opt/tensorium/logs/miner-1.log under versioned backups so you can trace regressions.

10. Tensorium helper tools

Run the CLI directly

# One-off usage without symlink
cd /opt/tensorium/bittensor
source .venv/bin/activate
python tools/tensorium_cli.py list-subnets --max-rows 5

# If symlinked to /usr/local/bin/tensorium (Tutorial 06)
tensorium start-miner --netuid 1 --config configs/miner-netuid-1.yaml

Use tensorium logs --netuid 1 --lines 50 to grab the latest miner output when debugging.

Run the guided installer

cd /opt/tensorium/bittensor/tools/miner-installer
source ../../.venv/bin/activate
python miner.py --netuid 1 --wallet-name tensorium --wallet-hotkey miner-main

Refresh dependencies quickly

cd /opt/tensorium/bittensor/scripts
sudo ./install_bittensor.sh --validate-only

📘 Example Output

(.venv) $ screen -r miner-1
[2025-11-17 09:32:11] ✅ Hotkey miner-main unlocked
[2025-11-17 09:32:12] 🌐 Axon listening on 0.0.0.0:8091
[2025-11-17 09:32:25] 🔁 Step 42 — difficulty 23.8 — loss 0.42 — incentive 17.91%
[2025-11-17 09:32:51] 🎯 Submitted work — block 15,842,344 — reward pending

$ sudo systemctl status tensorium-miner --no-pager
● tensorium-miner.service - Tensorium reference miner
     Loaded: loaded (/etc/systemd/system/tensorium-miner.service; enabled)
     Active: active (running) since Mon 2025-11-17 09:30:02 UTC; 4min ago
   Main PID: 2964 (python)
      Tasks: 16 (limit: 4573)
     Memory: 2.1G
        CPU: 1min 20.4s
     CGroup: /system.slice/tensorium-miner.service
             └─2964 /opt/tensorium/bittensor/.venv/bin/python neurons/text/text_server.py ...

✅ Summary

  • Pick subnets that match your hardware profile, and document configs/env vars beside each run log.
  • Validate the environment (ports, GPU, installer health) before attaching screen or systemd.
  • Use Tensorium helper tools (tensorium start-miner, miner-installer/miner.py) to reduce manual errors.
  • Capture verification commands and log outputs so debugging future incidents takes minutes, not hours.

📝 Review questions

  1. Why is it important to verify port availability before starting a miner?
  2. How can you keep a miner running after you disconnect from SSH?
  3. What does the Restart=on-failure directive accomplish in a systemd unit?
  4. Which log indicators suggest your miner successfully submitted work?
  5. Why should you periodically review btcli subnet show while mining?

Answers

  1. Miners run axons on fixed ports; conflicts prevent peers from connecting, leading to zero rewards.
  2. Use screen (detach/reattach) or run the miner as a systemd service.
  3. It automatically restarts the process if it exits abnormally, improving uptime.
  4. Log lines showing block numbers, incentives, or success emojis (🎯) indicate submissions.
  5. Subnet incentives, difficulty, and tempo shift over time; monitoring ensures you mine where profitability and requirements align with your hardware.