Installation

The validator uses the same repository as the miner. If you've already set up a miner on this machine, skip to step 3.

1. Clone the Repository

git clone https://github.com/Connito-AI/Connito
cd Connito

2. Create a Virtual Environment

Create and activate a virtual environment before installing any dependencies:

python -m venv .venv
source .venv/bin/activate  # Linux/Mac

3. Install Dependencies

Install build tools and project dependencies:

sudo apt-get update
sudo apt-get install -y build-essential python3-dev
pip install -r requirements.txt
pip install -e .

This installs all required packages (including Bittensor, PyTorch, FastAPI, and uvicorn). There is no need to install Bittensor or the base model separately.

4. Register on the Subnet

btcli subnets register \
  --netuid 102 \
  --wallet-name <MY_COLDKEY_NAME> \
  --hotkey <MY_HOTKEY_NAME>

5. Add Stake to Obtain a Validator Permit

Validators need a validator permit to set weights on the chain. This requires staking TAO to your hotkey:

btcli stake add \
  --netuid 102 \
  --wallet-name <MY_COLDKEY_NAME> \
  --hotkey <MY_HOTKEY_NAME> \
  --partial

Check the current permit threshold with btcli subnet show --netuid 102. Once the stake threshold is met, the permit activates within one tempo (~45 blocks).

6. Generate a Config File

Create a template config file for your validator:

python connito/shared/config.py \
  create_config \
  --coldkey_name <your coldkey name> \
  --hotkey_name <your hotkey name> \
  --role validator \
  --run_name <your naming to specify this run>

Edit the generated YAML config to adjust any specifics.

Verify Everything

# Check GPU
python -c "import torch; print(f'CUDA: {torch.cuda.is_available()}, VRAM: {torch.cuda.get_device_properties(0).total_mem / 1e9:.1f}GB')"

# Check bittensor
python -c "import bittensor; print(bittensor.__version__)"

Proceed to Running Your Validator when all checks pass.

7. (Optional) To Run Validator with Docker

Instead of installing dependencies directly on the host, you can run the validator as a Docker container with automatic updates via Watchtower. This is the recommended approach for production validators.

Prerequisites

• Linux host with an NVIDIA GPU (Docker GPU passthrough is Linux-only).

• NVIDIA driver ≥ 550 on the host.

• Docker Engine ≥ 23.0 with the Compose plugin:

  curl -fsSL https://get.docker.com | sudo sh
  sudo usermod -aG docker $USER
  newgrp docker

  If you get permission denied ... /var/run/docker.sock in a new terminal after this, run newgrp docker in that terminal or log out and back in.

• 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
  
  # Some distros (for example ubuntu24.04 at times) may not have a
  # distro-specific URL yet. Fall back to ubuntu22.04 if needed.
  repo_path="$distribution"
  if ! curl -fsI "https://nvidia.github.io/libnvidia-container/$repo_path/libnvidia-container.list" >/dev/null; then
    repo_path="ubuntu22.04"
  fi
  
  curl -fsSL "https://nvidia.github.io/libnvidia-container/$repo_path/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-get update
  sudo apt-get 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.4.1-base-ubuntu22.04 nvidia-smi

  If this verify command fails with Docker socket permission errors, run it with sudo or complete the Docker group step in a fresh login shell.

Docker Setup

Generate the compose .env:

python connito/shared/config.py create_docker_env \
  --path checkpoints/validator/<coldkey_name>/<hotkey_name>/<run_name>/config.yaml

Then add your Hugging Face token (from the Hugging Face Setup prerequisite) to connito/validator/docker/.env:

HF_TOKEN=hf_your_token_here

Use the raw token value (no extra quotes). If you change .env values, recreate the validator container so the new env is applied:

cd connito/validator/docker
docker compose up -d --no-deps --force-recreate validator

Proceed to Running Your Validator for the Docker startup commands.