Validator setup

Validator setup: run the evaluator and the weight setter in one process. No owner-side components are required for validators.

Workflow

Tasks (first frame + prompt + miner outputs) are created and stored in Hippius S3. As a validator you run one process (leoma serve) that (1) evaluator: polls the API for the latest task, downloads task data from S3, runs GPT-4o evaluation, and POSTs pass/fail results to the Leoma API; (2) weight setter: each epoch, calls GET /weights and sets on-chain weights from the current rank output. The subnet uses Text-Image to Video (TI2V); miners receive first frame + text.

---

Validator setup

Prerequisites

• Bittensor wallet (coldkey + hotkey) registered as a validator on the Leoma subnet.

• Leoma API URL — the deployed owner API.

• Hippius S3 access: read-only to the samples bucket (evaluator downloads task data from S3; it never uploads—evaluation results are submitted to the Leoma API with hotkey signature). Use access keys from the Hippius console.

• OpenAI API key (for GPT-4o evaluation in the evaluator).

• Validator registration in API DB: An admin must add your validator hotkey (and UID, stake) so the API includes you in stake-weighted scoring. Example: leoma db add-validator --uid <uid> --hotkey <ss58>.

Environment variables

Set these (e.g. in .env) where you run the validator:

Variable	Description
API_URL	Leoma API base URL (e.g. https://api.leoma.ai)
NETUID	Subnet ID (e.g. 99)
NETWORK	Bittensor network (finney for mainnet)
WALLET_NAME	Bittensor wallet name (e.g. default)
HOTKEY_NAME	Bittensor hotkey name (e.g. default)
OPENAI_API_KEY	OpenAI API key for GPT-4o (evaluator)
EPOCH_LEN	Blocks per epoch for weight-setting (default 180).
HIPPIUS_ENDPOINT	e.g. s3.hippius.com
HIPPIUS_REGION	e.g. decentralized
HIPPIUS_SAMPLES_BUCKET	Samples bucket (e.g. samples)
HIPPIUS_SAMPLES_READ_ACCESS_KEY / HIPPIUS_SAMPLES_READ_SECRET_KEY	Read access to samples bucket (evaluator downloads tasks only; no write needed)

Running the validator

Recommended: one process (evaluator + weight setter together):

leoma serve

Advanced: split processes (e.g. two terminals):

1. Evaluator — polls GET /tasks/latest, downloads task from S3, runs GPT-4o, POSTs evaluation results to the API.

   leoma servers evaluator

2. Validator (weight setter) — every epoch, fetches GET /weights and sets on-chain weights from the current rank result.

   leoma servers validator

Ensure your wallet has sufficient TAO for transaction fees when setting weights.

---

Docker (recommended)

We recommend running the validator in Docker using the Leoma subnet repository and its docker-compose.yml. One container runs both evaluator and weight setter (leoma serve). Optional Watchtower can auto-update the container when a new image is pushed.

1. Clone and configure

git clone https://github.com/RendixNetwork/leoma.git
cd leoma
cp env.example .env

Edit .env with:

• API_URL, NETUID, NETWORK, WALLET_NAME, HOTKEY_NAME

• OPENAI_API_KEY

• HIPPIUS_SAMPLES_READ_ACCESS_KEY, HIPPIUS_SAMPLES_READ_SECRET_KEY (and optionally HIPPIUS_ENDPOINT, HIPPIUS_REGION, HIPPIUS_SAMPLES_BUCKET)

2. Run with Docker Compose

docker compose up -d

This starts:

• leoma-validator — evaluator + weight setter in one container (leoma serve). Mounts ~/.bittensor/wallets read-only for signing weight-setting transactions.

• leoma-watchtower — polls the registry every 30s and restarts leoma-validator when a new image is available (image: rendixnetwork/leoma:latest).

3. Pre-built image vs build

The compose file uses the image rendixnetwork/leoma:latest. When you run docker compose up -d, Docker will pull that image from Docker Hub if it is not already built or present locally. To build from source instead (e.g. after cloning the repo), run:

docker compose build
docker compose up -d

Logs

docker logs -f leoma-validator

Compose file reference

The repo’s docker-compose.yml (validator only) looks like this:

services:
  validator:
    build: .
    image: rendixnetwork/leoma:latest
    container_name: leoma-validator
    restart: unless-stopped
    command: leoma serve
    env_file: .env
    environment:
      API_URL: ${API_URL}
      NETWORK: ${NETWORK:-finney}
      NETUID: ${NETUID:-99}
      EPOCH_LEN: ${EPOCH_LEN:-180}
      WALLET_NAME: ${WALLET_NAME:-default}
      HOTKEY_NAME: ${HOTKEY_NAME:-default}
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      HIPPIUS_ENDPOINT: ${HIPPIUS_ENDPOINT:-s3.hippius.com}
      HIPPIUS_REGION: ${HIPPIUS_REGION:-decentralized}
      HIPPIUS_SAMPLES_BUCKET: ${HIPPIUS_SAMPLES_BUCKET:-samples}
      HIPPIUS_SAMPLES_READ_ACCESS_KEY: ${HIPPIUS_SAMPLES_READ_ACCESS_KEY}
      HIPPIUS_SAMPLES_READ_SECRET_KEY: ${HIPPIUS_SAMPLES_READ_SECRET_KEY}
    volumes:
      - ~/.bittensor/wallets:/root/.bittensor/wallets:ro

  watchtower:
    image: nickfedor/watchtower
    container_name: leoma-watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --interval 30 leoma-validator

Adjust the wallet path if your wallets live elsewhere (e.g. $HOME/.bittensor/wallets on Linux).

Authentication (API)

Endpoints that require validator identity (e.g. POST /samples/batch, GET /miners/valid) use signature auth. Send headers: X-Validator-Hotkey, X-Signature, X-Timestamp. Message to sign: SHA256(request_body):timestamp (UTF-8), with your validator keypair. See API reference.

---

Summary

1. Set env (API_URL, Hippius samples read only, OpenAI, wallet, NETUID, NETWORK).

2. Ensure your validator is registered in the API DB.

3. Run the validator: Docker — docker compose up -d in leoma (one container + Watchtower); or native — leoma serve (or split: leoma servers evaluator and leoma servers validator).

4. Monitor the Network page and API for samples and weights.

Next

• Miner setup — miner Hugging Face naming and commit

• Storage (Hippius S3) — buckets and credentials

• API reference — endpoints and auth