Nepher

Appearance

Tournament Miner Guide — Nepher Subnet 49 ​

A complete end-to-end walkthrough for miners: from cloning the task, training a policy, submitting it to the tournament, to getting evaluated and earning rewards.

Table of Contents ​

1. Overview ​

Nepher Subnet 49 runs a winner-takes-all robotics tournament on the Bittensor network. Each tournament proceeds through five sequential phases:

┌─────────────┬─────────────┬─────────────┬─────────────┬─────────────┐
│   CONTEST   │   SUBMIT    │ EVALUATION  │   REVIEW    │   REWARD    │
│   PERIOD    │   WINDOW    │   PERIOD    │   STAGE     │   PERIOD    │
├─────────────┼─────────────┼─────────────┼─────────────┼─────────────┤
│ Miners      │ Eligibility │ Validators  │ Admin       │ Winner gets │
│ train &     │ snapshot    │ evaluate    │ reviews &   │ all weight  │
│ submit      │ locked      │ all agents  │ approves    │ (emissions) │
└─────────────┴─────────────┴─────────────┴─────────────┴─────────────┘
PhaseWhat happensYour role as a miner
Contest PeriodTournament is open for submissionsTrain your policy and submit your agent
Submit PeriodEligibility snapshot is taken from the metagraphEnsure you are registered on-chain and have submitted
Evaluation PeriodValidators download agents, run them in standardized Isaac Lab environments via eval-nav, and submit scoresNothing — sit back and wait
Review PeriodAdmin reviews aggregated scores and verifies the top submissionNothing — results are being finalized
Reward PeriodValidators set all on-chain weight to the tournament winner's UIDIf you won, you receive all emissions for the duration

Key rule: Only the single top-performing miner receives weight (and thus emissions) per tournament. This is a winner-takes-all incentive mechanism.

2. Prerequisites ​

Hardware ​

ComponentFor TrainingFor Submission Only
GPUNVIDIA RTX 4090 or equivalent (24 GB+ VRAM)Not required (CPU-only)
RAM32 GB+8 GB+
Disk100 GB SSD10 GB

Software ​

SoftwareVersionRequired For
Python3.10+Everything
Isaac Sim5.1Training & local evaluation
Isaac Lab2.3.0Training & local evaluation
Bittensor7.0+Wallet & registration
nepher (EnvHub)0.1+Environment management

Accounts ​

3. Wallet & Registration ​

Install Bittensor and create your wallet:

bash
pip install bittensor

# Create a new coldkey and hotkey
btcli wallet new_coldkey --wallet.name miner
btcli wallet new_hotkey  --wallet.name miner --wallet.hotkey default

# Register on Subnet 49
btcli subnet register --wallet.name miner --wallet.hotkey default --netuid 49

⚠️ Back up your coldkey mnemonic securely. If you lose it, you lose access to your funds.

Your wallet files will be at: ~/.bittensor/wallets/miner/

4. Clone the Task Repository ​

The task repository (e.g., task_example) contains the environment definition, training scripts, and the agent structure you need. Clone it as your starting point:

bash
git clone https://github.com/nepher-ai/task_example.git
cd task_example

The repository has the following structure:

task_example/
├── best_policy/
│   ├── best_policy.pt              # Pre-trained example policy
│   └── exported/
│       ├── policy.pt               # JIT-exported model
│       └── policy.onnx             # ONNX-exported model
├── scripts/
│   ├── list_envs.py                # List registered environments
│   ├── random_agent.py             # Test with random actions
│   ├── zero_agent.py               # Test with zero actions
│   └── rsl_rl/
│       ├── train.py                # ← Training script
│       ├── play.py                 # ← Inference / playback script
│       └── cli_args.py             # CLI argument definitions
└── source/
    └── leatherbacknav/             # ← Task module (Isaac Lab extension)
        ├── leatherbacknav/
        │   ├── __init__.py
        │   ├── robots/             # Robot definitions (Leatherback)
        │   └── tasks/
        │       └── manager_based/
        │           └── waypoint_nav/
        │               ├── waypoint_nav_env_cfg.py        # Base env config
        │               ├── waypoint_nav_env_cfg_envhub.py # EnvHub env config
        │               ├── agents/rsl_rl_ppo_cfg.py       # RL agent config
        │               └── mdp/                           # Observations, rewards, etc.
        ├── setup.py
        └── pyproject.toml

Install the task module ​

bash
# From the Isaac Lab Python environment:
${ISAACLAB_PATH}/isaaclab.sh -p -m pip install -e source/leatherbacknav

Verify installation ​

bash
${ISAACLAB_PATH}/isaaclab.sh -p scripts/list_envs.py

You should see registered environments including:

  • Nepher-Leatherback-WaypointNav-v0 (training)
  • Nepher-Leatherback-WaypointNav-Play-v0 (inference)
  • Nepher-Leatherback-WaypointNav-Envhub-v0 (training with EnvHub scenes)
  • Nepher-Leatherback-WaypointNav-Envhub-Play-v0 (evaluation with EnvHub scenes)

5. Install the Environment Platform (EnvHub) ​

Nepher (EnvHub) is the environment management platform that provides standardized simulation environments. Validators use these exact environments to evaluate your agent, so you should train and test against them.

bash
# Install the nepher CLI
pip install nepher

# Authenticate (you'll be prompted for your API key)
nepher login

# List available environments
nepher list --category navigation

# Download the benchmark environments used for evaluation
nepher download waypoint-benchmark-v1 --category navigation
nepher download waypoint-sample-v1 --category navigation

# Verify downloaded environments
nepher cache list

Once downloaded, use the EnvHub-integrated task variant for training:

bash
# Training with EnvHub scenes (recommended for competition)
${ISAACLAB_PATH}/isaaclab.sh -p scripts/rsl_rl/train.py \
    --task=Nepher-Leatherback-WaypointNav-Envhub-v0

6. Train Your Policy ​

bash
${ISAACLAB_PATH}/isaaclab.sh -p scripts/rsl_rl/train.py \
    --task=Nepher-Leatherback-WaypointNav-v0

Training with EnvHub Environments ​

This uses the same standardized environments that validators will use for evaluation:

bash
${ISAACLAB_PATH}/isaaclab.sh -p scripts/rsl_rl/train.py \
    --task=Nepher-Leatherback-WaypointNav-Envhub-v0

Common Training Options ​

bash
${ISAACLAB_PATH}/isaaclab.sh -p scripts/rsl_rl/train.py \
    --task=Nepher-Leatherback-WaypointNav-Envhub-v0 \
    --num_envs 4096 \              # Number of parallel environments
    --max_iterations 10000 \       # Training iterations
    --seed 42 \                    # Random seed
    --headless                     # No GUI (faster)

Training Output ​

Training logs and checkpoints are saved to:

logs/rsl_rl/<experiment_name>/<timestamp>/
├── params/
│   ├── env.yaml            # Environment configuration snapshot
│   └── agent.yaml          # Agent configuration snapshot
├── model_*.pt              # Periodic checkpoints
└── model_last.pt           # Latest checkpoint

7. Test & Play Your Policy Locally ​

After training, test your policy visually:

bash
# Play with a specific checkpoint
${ISAACLAB_PATH}/isaaclab.sh -p scripts/rsl_rl/play.py \
    --task=Nepher-Leatherback-WaypointNav-Play-v0 \
    --checkpoint=/path/to/logs/rsl_rl/.../model_last.pt

# Or using EnvHub scenes
${ISAACLAB_PATH}/isaaclab.sh -p scripts/rsl_rl/play.py \
    --task=Nepher-Leatherback-WaypointNav-Envhub-Play-v0 \
    --checkpoint=/path/to/logs/rsl_rl/.../model_last.pt

The play script also exports your policy in JIT and ONNX formats to exported/.

Prepare the Best Policy ​

Copy your best checkpoint to the required location:

bash
mkdir -p best_policy
cp /path/to/logs/rsl_rl/.../model_best.pt best_policy/best_policy.pt

8. Self-Evaluate with eval-nav ​

Before submitting, run the exact same evaluation pipeline that validators use. This gives you a realistic preview of your score.

Install eval-nav ​

bash
git clone https://github.com/nepher-ai/eval-nav.git ./eval-nav
${ISAACLAB_PATH}/isaaclab.sh -p -m pip install -e ./eval-nav

Create an Evaluation Config ​

Create eval_config.yaml:

yaml
task_name: "Nepher-Leatherback-WaypointNav-Envhub-Play-v0"
task_module: "leatherbacknav"

env_scenes:
  - env_id: "waypoint-benchmark-v1"
    scene: 0
  - env_id: "waypoint-sample-v1"
    scene: 0

seeds: [42]
num_episodes: 10
max_episode_steps: 900
num_envs: 10
scoring_version: "v1"

log_dir: "logs/self-eval"
enable_logging: true
policy_path: "./best_policy/best_policy.pt"

Run the Evaluation ​

bash
${ISAACLAB_PATH}/isaaclab.sh -p ./eval-nav/scripts/evaluate.py \
    --config eval_config.yaml \
    --headless

Review Results ​

Results are saved to:

logs/self-eval/eval_run_YYYYMMDD_HHMMSS/
├── results.json        # Machine-readable results (score, metrics)
├── summary.txt         # Human-readable summary
├── config.yaml         # Evaluation configuration used
└── data/               # Episode state logs (.npy)

An evaluation_result.json is also written to the current directory:

json
{
  "score": 0.85,
  "log_dir": "logs/self-eval/eval_run_20260213_143022",
  "metadata": { ... },
  "summary": "..."
}

Understanding the Score (V1 Scoring) ​

The V1 scoring system evaluates fundamental navigation capability:

ComponentWeightDescription
Success Rate70%Fraction of episodes where the robot reached all waypoints
Time-to-Completion30%How quickly successful episodes are completed (normalized)

Formula: score = 0.7 × success_rate + 0.3 × time_efficiency

Where time_efficiency = 1.0 - (mean_completion_steps / max_episode_steps)

Failures are heavily penalized — an agent that never reaches waypoints scores 0.

9. Prepare Your Agent for Submission ​

Your agent directory must follow this exact structure:

my-agent/
├── best_policy/
│   └── best_policy.pt              # REQUIRED — trained policy weights
├── scripts/                        # Recommended
│   ├── list_envs.py
│   └── rsl_rl/
│       └── play.py
└── source/
    └── <task_module>/              # REQUIRED — at least one, with __init__.py
        ├── __init__.py
        └── ...

Required Files ​

PathDescription
best_policy/best_policy.ptYour trained model weights
source/<task_module>/The Isaac Lab task module with __init__.py

Excluded from Upload ​

The following directories are automatically excluded from the submission archive:

  • logs/, outputs/, __pycache__/, .git/, .venv/, venv/

Validate Before Submitting ​

Run the built-in validator to check your agent structure:

bash
nepher-miner validate --path ./my-agent

If everything is correct, you'll see:

✅ Agent structure is valid

If there are issues, you'll see specific error messages like:

❌ Agent validation failed:
  - Required file missing: best_policy/best_policy.pt
  - Task module missing __init__.py: source/leatherbacknav/

10. Submit to the Tournament ​

Install the Nepher Subnet CLI ​

bash
git clone https://github.com/nepher-ai/nepher-subnet.git && cd nepher-subnet
pip install -e .

Configure ​

bash
cp config/miner_config.example.yaml config/miner_config.yaml

Edit config/miner_config.yaml:

yaml
tournament:
  api_key: "your_api_key_here"

wallet:
  name: "miner"
  hotkey: "default"

Submit ​

bash
nepher-miner submit --path ./my-agent --config config/miner_config.yaml

Or pass everything as CLI arguments:

bash
nepher-miner submit \
    --path ./my-agent \
    --wallet-name miner \
    --wallet-hotkey default \
    --api-key YOUR_API_KEY

What Happens During Submission ​

  1. Validation — Agent structure is checked (can be skipped with --skip-validation)
  2. Archiving — Agent is zipped (excluding logs/, outputs/, etc.)
  3. Signing — The archive hash + your hotkey + timestamp are signed with your Bittensor wallet
  4. Authorization — The signed payload is sent to the tournament backend for verification
  5. Upload — The ZIP archive is uploaded to the tournament backend (stored in Cloudflare R2)
  6. Confirmation — You receive an Agent ID and tournament confirmation
✅ Upload successful!

═══════════════════════════════════════════
  Agent ID:      a1b2c3d4-e5f6-...
  Tournament:    f7g8h9i0-j1k2-...
  Hotkey:        5GrwvaEF5zXb6Lgd...
  Content Hash:  a3f2b1c4d5e6f7...
  Uploaded At:   2026-02-13T14:30:22Z
═══════════════════════════════════════════

Docker Submission (Optional) ​

bash
docker compose build miner
docker compose run miner submit --path /app/agent --config /app/config/miner_config.yaml

Place your agent in ./agent/ or set AGENT_PATH. No GPU required.

💡 Tip: You can submit multiple times during the contest period. Only your latest submission per hotkey is evaluated.

11. What Happens After You Submit ​

Once the contest period ends and evaluation begins, validators run the following automated pipeline on your agent:

┌──────────────────────────────────────────────────────────────────┐
│                     VALIDATOR EVALUATION PIPELINE                │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. Download your agent ZIP from the tournament backend          │
│                                                                  │
│  2. Extract and install your task module:                        │
│     pip install -e ./agent/source/<task_module>                  │
│                                                                  │
│  3. Download required evaluation environments via nepher:        │
│     nepher download waypoint-benchmark-v1 waypoint-sample-v1     │
│                                                                  │
│  4. Run eval-nav with the tournament evaluation config:          │
│     evaluate.py --config eval_config.yaml --headless             │
│     • Loads your best_policy/best_policy.pt                      │
│     • Runs fixed episodes across multiple scenes + seeds         │
│     • Computes V1 score (success rate + time efficiency)         │
│                                                                  │
│  5. Submit score + metadata + logs to tournament backend         │
│                                                                  │
│  6. Backend aggregates scores from multiple validators           │
│     using stake-weighted averaging                               │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

Key details:

  • Evaluation runs in headless Isaac Sim with fixed seeds for reproducibility
  • Multiple validators independently evaluate your agent
  • Your score is the stake-weighted average across all validators
  • If no validators have stake, a simple average is used as fallback
  • Failed evaluations (e.g., your agent crashes) result in a score of 0 for that validator

12. Scoring & Rewards ​

Score Aggregation ​

  Validator A (stake: 1000)  →  Score: 0.85  →  ┐
  Validator B (stake: 500)   →  Score: 0.82  →  ├→  Weighted Avg = 0.84
  Validator C (stake: 200)   →  Score: 0.87  →  ┘

aggregated_score = Σ(score_i × stake_i) / Σ(stake_i)

Rankings ​

Agents are ranked by aggregated score (descending). Ties are broken by earliest submission time.

Winner-Takes-All Rewards ​

  • Only the #1 ranked miner receives weight (and thus TAO emissions) for the reward period
  • If no miner meets the performance threshold, or if the admin doesn't approve, all weight goes to UID 0 (burn)
  • Emissions are sparse and episodic — designed as prize capital, not recurring income
  • During non-reward periods (contest, evaluation, review), all weight goes to UID 0

Eligibility Requirements ​

To be eligible for rewards, you must:

  1. ✅ Be registered on-chain on Subnet 49 (present in the metagraph)
  2. ✅ Have submitted an agent during the contest/submit period
  3. ✅ Have your agent successfully evaluated by at least one validator

Note: If you are deregistered from the subnet after the eligibility snapshot but before rewards are distributed, you still receive your reward. The team will contact you to re-register.

13. Tips for Competitive Miners ​

Training ​

  • Focus on generalization — benchmark datasets are only revealed to validators during the evaluation period, so your agent will be tested on environments it has never seen before
  • Train on diverse scenes and terrain variations — the wider the variety your agent experiences during training, the better it will generalize to unseen benchmarks
  • Use multiple seeds during training to improve robustness across different initial conditions
  • Train for longer — more iterations generally yield better, more generalizable policies
  • Tune your reward function — experiment with reward shaping, auxiliary rewards, and penalty terms to guide your agent toward more robust behavior
  • Experiment with RSL-RL model architectures — try different MLP hidden layer sizes, depths, activation functions (ELU, ReLU, etc.), and init noise std within the RSL-RL actor-critic framework to improve learning efficiency and generalization
  • Fine-tune your training methodology — explore hyperparameter sweeps (learning rate, batch size, discount factor), curriculum learning, domain randomization, and data augmentation to push performance further
  • Monitor success rate — this accounts for 70% of your score
  • Optimize completion time — faster agents get a bonus (30% of score)

Pre-submission ​

  • Always self-evaluate with eval-nav before submitting — use the same config validators use
  • Run nepher-miner validate to catch structural issues early
  • Submit early in the contest period so you have time to iterate
  • Re-submit if you train a better policy — only your latest submission counts

Common Pitfalls ​

  • ❌ Forgetting best_policy/best_policy.pt
  • ❌ Missing __init__.py in your task module
  • ❌ Training only on a single environment — overfitting to one scene will hurt generalization on unseen benchmarks
  • ❌ Not testing with headless mode (agents sometimes behave differently)
  • ❌ Submitting after the contest/submit period closes

14. Troubleshooting ​

ProblemSolution
Validation failsRun nepher-miner validate --path ./my-agent -v and check error output
"No active tournament"Submissions are only accepted during the contest/submit period — check Discord for schedule
Connection errorVerify internet connectivity, API URL (https://tournament-api.nepher.ai), and firewall settings
Wallet not foundCheck ~/.bittensor/wallets/miner/ has coldkey, coldkeypub.txt, and hotkeys/default
Rejected (not registered)Register on Subnet 49: btcli subnet register --wallet.name miner --wallet.hotkey default --netuid 49
API key issuesVerify your key at https://account.nepher.ai → API Keys
eval-nav score = 0Your agent likely fails all episodes — check that best_policy.pt loads correctly and was trained on compatible environments
Isaac Lab import errorsEnsure ISAACLAB_PATH and ISAACSIM_PATH are exported in your shell
EnvHub download failsRun nepher login first, then nepher download <env_id>
Low score despite local successYour agent may be overfitting to a narrow set of scenes — train on diverse environments to improve generalization on unseen benchmarks

15. Resources & Links ​

ResourceLink
Nepher Websitehttps://nepher.ai
Documentationhttps://docs.nepher.ai
Tournament Dashboardhttps://tournament.nepher.ai
Account & API Keyshttps://account.nepher.ai
Discordhttps://discord.gg/nepher
nepher-subnet repohttps://github.com/nepher-ai/nepher-subnet
eval-nav repohttps://github.com/nepher-ai/eval-nav
EnvHub repohttps://github.com/nepher-ai/envhub
task_example repohttps://github.com/nepher-ai/task-leatherback-waypointnav
Isaac Lab Install Guidehttps://isaac-sim.github.io/IsaacLab/main/source/setup/installation/index.html

Quick Reference — Full Workflow Summary ​

bash
# 1. Wallet setup
pip install bittensor
btcli wallet new_coldkey --wallet.name miner
btcli wallet new_hotkey  --wallet.name miner --wallet.hotkey default
btcli subnet register --wallet.name miner --wallet.hotkey default --netuid 49

# 2. Clone the task
git clone https://github.com/nepher-ai/task-leatherback-waypointnav && cd task-leatherback-waypointnav
${ISAACLAB_PATH}/isaaclab.sh -p -m pip install -e source/leatherbacknav

# 3. Install environments
pip install nepher
nepher login
nepher download waypoint-benchmark-v1 waypoint-sample-v1

# 4. Train
${ISAACLAB_PATH}/isaaclab.sh -p scripts/rsl_rl/train.py \
    --task=Nepher-Leatherback-WaypointNav-Envhub-v0 --headless

# 5. Copy best checkpoint
cp logs/rsl_rl/.../model_best.pt best_policy/best_policy.pt

# 6. Self-evaluate
git clone https://github.com/nepher-ai/eval-nav.git ./eval-nav
${ISAACLAB_PATH}/isaaclab.sh -p -m pip install -e ./eval-nav
${ISAACLAB_PATH}/isaaclab.sh -p ./eval-nav/scripts/evaluate.py \
    --config eval_config.yaml --headless

# 7. Install nepher-subnet and submit
git clone https://github.com/nepher-ai/nepher-subnet.git
pip install -e ./nepher-subnet
nepher-miner submit --path . --wallet-name miner --api-key YOUR_KEY

Good luck, miner! 🏆

Released under the MIT License.

Copyright © 2019-present Evan You