Gittensor

Appearance

Validators ​

  • Authenticate users via miner provided github PAT
  • Retrieve github PR data
  • Verify successful and meaningful merged PRs
  • Calculate miner score based on incentive mechanism

INFO

MINIMUM REQUIREMENTS: Docker, 4 CPUs, 8GB RAM, one publicly accessible TCP port

TIP

Running a validator requires deployment on a server with reliable, continuous availability. Validators continuously query miners to verify their GitHub PATs and evaluate their contributions.

WARNING

Validators must expose their axon port (default 8099) to the public internet. Miners broadcast their GitHub PATs to your validator via this port — if it is not reachable, your validator will not receive miner PATs and will be unable to score the issue bounties competition. Open the port in your firewall and any cloud security group, and forward it to the host running the validator container.

You can run a validator following the Docker Setup (Recommended) or Manual Setup

1. Ensure that you have an accessible coldkey and hotkey. ​

Please refer to the official Bittensor documentation for creating or importing a Bittensor wallet.

2. Register to the subnet ​

  • To register a validator:
bash
# testnet
btcli subnet register --netuid 422 \
--wallet-name WALLET_NAME \
--hotkey WALLET_HOTKEY \
--network test

# mainnet
btcli subnet register --netuid 74 \
--wallet-name WALLET_NAME \
--hotkey WALLET_HOTKEY

3. Create a Github Classic PAT ​

WARNING

This step is new for validators as of 3/6/26. Please ensure you have configured a GITTENSOR_VALIDATOR_PAT following these steps for your validator!

Your validator needs a classic GitHub PAT to fetch PR data and verify issue solutions. The GITTENSOR_VALIDATOR_PAT is used in the issue bounties competition. It is not used in OSS contributions validation.

  • In Github go to your settings, find developer settings

  • In developer settings, go to Personal access tokens, then Tokens (classic)

  • Then click Generate new token (classic)

  • token name gittensor-validator

  • Expiration No Expiration

TIP

Some Github organizations forbid access via PAT if the token's lifetime is indefinite. Be aware if you are part of any organizations on Github and plan accordingly if that happens to be the case (either by creating a PAT with an expiration or leaving the organization).

  • Select Scopes public_repo, ensure this checkbox is the only one activated

  • Hit Generate token

  • Copy generated token for next step

INFO

You should now have a classic token that only allows public repository scope (public_repo), this allows a much higher threshold for fetching public github data

4. Now setup your validator ​

Get it running by either using the Docker Setup (Recommended) or the Manual Setup.

Docker Setup ​

TIP

For information on installing Docker refer to the official documentation

A. Clone the repository ​

  • Clone the gittensor repo
bash
git clone [email protected]:entrius/gittensor.git
  • Step into your freshly cloned gittensor folder
bash
cd gittensor

B. Setup environment ​

  • Create a .env file in the root of the project using .env.example as a guide, then fill with your own env variables
bash
cp .env.example .env

TIP

Make sure to set GITTENSOR_VALIDATOR_PAT from the previous step

  • Update your copied .env file with the subnet netuid, network, github pat, etc
bash
nano .env

WARNING

The PORT value in your .env (default 8099) must be open to the public internet so miners can broadcast their PATs to your validator. The Docker Compose file publishes this port on the host ("${PORT}:${PORT}") — make sure your firewall and any cloud security group allow inbound TCP traffic on it.

C. Run in Docker container ​

bash
docker compose -f docker-compose.vali.yml up -d

Done! You are now running a gittensor validator with automatic updates

Manual Setup ​

WARNING

ensure you are on main branch using git branch or git checkout main

A. Setup environment ​

  • Create venv + install dependencies
bash
# make sure you're at the root of the project
python -m venv venv
source venv/bin/activate

pip install -e .
  • Log into wandb
bash
export WANDB_API_KEY=<your_wandb_key>

wandb login $WANDB_API_KEY
  • Create a .env file in the root of the project using .env.example as a guide, then fill with your own env variables
bash
cp .env.example .env
  • Update your copied .env file with your subnet netuid, network, and wallet details:
bash
nano .env
  • source environment variables
bash
source .env

B. Run the validator (manually) ​

TIP

You may want to run the validator in some background process that ensures it is consistently live to validate miners

WARNING

The --axon.port value (default 8099) must be open to the public internet so miners can broadcast their PATs to your validator. Make sure your firewall and any cloud security group allow inbound TCP traffic on it.

bash
# testnet
python neurons/validator.py --wallet.name <test-wallet-name> --wallet.hotkey <test-hotkey-name> --netuid 422 --axon.port 8099 --subtensor.network test --logging.debug

# mainnet
python neurons/validator.py --wallet.name <wallet> --wallet.hotkey <hotkey> --netuid 74 --axon.port 8099 --subtensor.network finney --logging.debug