Validator Guide

Nepher Robotics · Bittensor Subnet 49

This guide walks through deploying a Bittensor Subnet 49 validator using Docker. A single GPU machine runs the complete validator lifecycle: agent evaluation, on-chain weight setting, and burn.

How it works: the validator is a lightweight orchestrator. It downloads miner agents, sets weights on-chain, and spawns a GPU sandbox container (Isaac Sim 5.1 + Isaac Lab 2.3.2 + eval-nav) on demand to evaluate untrusted agent code in isolation. The sandbox is built once but never runs as a long-lived service — the validator launches it via the host Docker socket. That's why the machine needs a GPU + the NVIDIA Container Toolkit even though the orchestrator itself is light.

What it does each cycle:

Evaluates unevaluated agents for every active tournament — on public scenes during public evaluation, on hidden EnvHub benchmarks during private evaluation — and submits signed scores to the tournament API.
Sets weights every 30 minutes as one combined vector: 1% to each running tournament's preliminary leader, the remainder to the approved podium of the tournament in its reward period, and anything unresolved burned on UID 0. See Incentive Mechanism.

No GPU? You can run a CPU-only validator that sets weights but does not evaluate — see the Appendix.

1. Requirements

Spec	Minimum	Recommended
GPU	NVIDIA RTX-class, 24 GB VRAM (e.g. RTX 4090, RTX A5000)	RTX A6000 (48 GB) / A100 (40 GB+)
RAM	64 GB	128 GB
Disk	100 GB SSD	200 GB+ NVMe
OS	Ubuntu 22.04 LTS	Ubuntu 22.04 LTS
NVIDIA Driver / CUDA	535+ / 12.1+	Latest stable / 12.1+

Software: Docker + Compose, Git. Most GPU cloud providers ship drivers and Docker pre-installed — skip to Step 3 if so.

2. Server Setup (if needed)

bash

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl wget build-essential
nvidia-smi  # If this fails, install drivers below

Install NVIDIA drivers

bash

sudo apt install -y nvidia-driver-535 && sudo reboot

Install Docker + NVIDIA Container Toolkit

bash

# Docker
curl -fsSL https://get.docker.com -o get-docker.sh && sudo sh get-docker.sh
sudo usermod -aG docker $USER && newgrp docker
sudo apt install -y docker-compose-plugin

# NVIDIA Container Toolkit
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt update && sudo apt install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker && sudo systemctl restart docker

# Verify
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

3. Bittensor Wallet

Install the Bittensor CLI (btcli), then register and stake on Subnet 49:

bash

btcli subnet register --wallet.name validator --wallet.hotkey default --netuid 49
btcli stake add       --wallet.name validator --wallet.hotkey default --amount <AMOUNT>

Wallet files live at ~/.bittensor/wallets/validator/.

4. Nepher Account, Validator Role & API Key

The tournament API only accepts evaluation results from accounts that are authorized as validators:

Create an account at nepher.ai/account/signup and choose the validator role (or switch to it later under Profile settings). Switching from miner to validator deactivates the account until an admin activates it.
Link your hotkey — contact the team on Discord with your account email and validator hotkey (SS58). An admin links the hotkey to your account; evaluation submissions are signed with it and rejected if the hotkey does not match.
Create an API key at nepher.ai/account/api-keys → copy it. An unrestricted key (no platform restriction) is simplest; the validator uses the same key for the Tournament API and EnvHub downloads.

The key is shown only once — store it safely.

5. Configure & Run (Docker)

bash

git clone https://github.com/nepher-ai/nepher-subnet.git && cd nepher-subnet

cp config/docker.env.example .env
cp config/validator_config.example.yaml config/validator_config.yaml

Edit .env (Docker Compose reads these — the wallet directory defaults to ~/.bittensor):

bash

NEPHER_API_KEY=nepher_your_actual_api_key_here
# Optional override (default shown):
# BITTENSOR_WALLET_PATH=~/.bittensor

Edit config/validator_config.yaml (read by the validator process — keep it in sync with .env):

yaml

tournament:
  api_key: "nepher_your_actual_api_key_here"
wallet:
  name: "validator"
  hotkey: "default"

Shared settings live in config/common_config.yaml (ships with repo) and are merged automatically — network finney, netuid 49, Tournament API https://api.nepher.ai/tournament, Isaac Lab 2.3.2 / Isaac Sim 5.1. You normally don't need to change them. Replace the your_api_key_here placeholder in validator_config.yaml — it is used as-is if left unchanged.

Build the images, then start the validator. The first build is heavy because it builds the GPU sandbox image (Isaac Sim ~20 GB); the validator won't start until it completes:

bash

docker compose build                    # Builds validator + sandbox — 30–60 min first time
docker compose up -d validator          # Starts the orchestrator (spawns sandbox on demand)
docker compose logs -f validator

# Manage
docker compose down                     # Stop
docker compose restart validator        # Restart
docker compose up -d --build validator  # Rebuild after updates
docker compose exec validator bash      # Shell into container

Check status — docker compose ps shows healthy once the container is up. The health check only confirms the process started, so use the logs to confirm the validator is fetching tournaments, evaluating agents, and setting weights:

bash

docker compose ps
docker compose logs -f validator

Common errors in the logs:

Message	Fix
`No active validator hotkey linked to your account`	Ask an admin to link your hotkey (Step 4)
`Hotkey mismatch`	The wallet hotkey in `validator_config.yaml` differs from the one linked to your account
`User account is not active`	Your validator role is awaiting admin activation (Step 4)
`User must have validator role`	Switch your account role to validator (Step 4)
`Invalid or expired API key`	Check `tournament.api_key` in `config/validator_config.yaml` and `NEPHER_API_KEY` in `.env`

Appendix: CPU-Only Validator (weights only)

The validator-cpu service is a stripped-down validator that only sets weights and burns — it does not evaluate agents. Use it if you want to run a valid validator without a GPU. (The full GPU validator from Section 5 already does everything, including weight setting; the CPU service is not a companion to it.)

It runs on a cheap CPU VPS — 2 vCPU · 4 GB RAM · 20 GB disk · Ubuntu 22.04 — with no GPU, no Isaac Sim, and a lightweight image (~200 MB). It uses the same wallet, account, API key, config, and .env setup as the GPU validator (Steps 3–5), and sets the same combined weight vector every 30 minutes.

bash

docker compose build validator-cpu && docker compose up -d validator-cpu
docker compose logs -f validator-cpu

Need Help?

Docs: https://docs.nepher.ai
Discord: https://discord.gg/qZUc3vdjVq
Issues: https://github.com/nepher-ai/nepher-subnet/issues

Validator Guide ​

1. Requirements ​

2. Server Setup (if needed) ​

3. Bittensor Wallet ​

4. Nepher Account, Validator Role & API Key ​

5. Configure & Run (Docker) ​

Appendix: CPU-Only Validator (weights only) ​

Need Help? ​

Validator Guide

1. Requirements

2. Server Setup (if needed)

3. Bittensor Wallet

4. Nepher Account, Validator Role & API Key

5. Configure & Run (Docker)

Appendix: CPU-Only Validator (weights only)

Need Help?