This guide reflects the current minotaur_subnet.miner.main CLI and submission routes. By the end you’ll have the agent loop running and your first solver submitted.

↳ BG · 00 Overview How mining works and the champion/challenger model. ↳ REF · 02 Configuration Full flag reference. ↳ API · 03 Solver API Interfaces your solver must implement. ↳ REF · 05 Network Reference Production endpoints + mainnet addresses.

Prerequisites

• Python 3.12+
• Git
• Docker — required for git-based submission screening; recommended for local testing
• Bittensor wallet with a hotkey registered on subnet 112 (required for submitting against mainnet)

Targets: local dev vs mainnet

The CLI flags are the same; only the --validator-url changes:

Target	URL	When to use
Local testnet	http://localhost:8080	After make testnet-up. Submissions auto-benchmark, fast iteration.
Production	<PRODUCTION_API_URL> (see project announcement channel)	Real subnet 112 mining; emissions, real benchmarks.

The rest of this guide uses $VALIDATOR_URL as a placeholder — set it to one of the above:

terminal SH COPY

export VALIDATOR_URL=http://localhost:8080            # local dev
# For production, fetch the current API URL from the project announcement
# channel (see project README) and export it:
# export VALIDATOR_URL=<PRODUCTION_API_URL>

See the Network Reference for where to find the active production endpoint.

Step 1 — Install

terminal SH COPY

git clone https://github.com/subnet112/minotaur_subnet.git
cd minotaur_subnet
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Step 2 — Register on subnet 112 MAINNET ONLY

Local testnet auto-registers a test miner. For mainnet, register your hotkey first:

terminal SH COPY

btcli subnet register --netuid 112 --subtensor.network finney \
--wallet.name my-miner --wallet.hotkey my-miner-hotkey

Verify:

terminal SH COPY

btcli subnet metagraph --netuid 112 --subtensor.network finney

Your hotkey should appear in the metagraph. The --hotkey argument in CLI commands below refers to the hotkey name (e.g. my-miner-hotkey), not the wallet name.

Step 3 — Start the target API LOCAL TESTNET ONLY

For mainnet, skip — you submit against the production endpoint.

For local dev:

terminal SH COPY

make testnet-up
# or, lighter, just the API:
python -m minotaur_subnet.api.server --port 8080

Step 4 — Run the agent loop RECOMMENDED

Agent mode discovers active apps, generates strategies, tests them, and submits source code to /v1/submissions/source. This is the fastest way to iterate.

terminal SH COPY

python -m minotaur_subnet.miner.main agent \
--validator-url "$VALIDATOR_URL" \
--strategy-dir ./strategies \
--miner-id my-miner-001

+

Tip

The agent loop is the recommended flow for new miners — it handles discovery, generation, and submission automatically while you focus on improving strategies.

Step 5 — Submit a git-based solver

Once you’re ready to submit a vetted, signed solver, use the submit subcommand:

terminal SH COPY

python -m minotaur_subnet.miner.main submit \
--repo-url https://github.com/youruser/my-solver \
--commit-hash <commit> \
--hotkey my-miner-hotkey \
--epoch 0 \
--validator-url "$VALIDATOR_URL" \
--poll

i

Note

• --hotkey is the bittensor hotkey name (matches --wallet.hotkey in btcli), not the wallet name. The signed submission is verified against the metagraph by the API.
• --epoch is required in practice unless your target exposes GET /v1/status for auto-detection.
• --validator-url defaults to http://localhost:9100 if omitted, which is wrong for both local dev (use :8080) and mainnet — always set it explicitly.

Step 6 — Optional: direct source submission (local/dev)

You can submit inline solver code directly:

terminal SH COPY

curl -X POST http://localhost:8080/v1/submissions/source \
-H "Content-Type: application/json" \
-d '{
  "solver_source": "from minotaur_subnet.sdk.intent_solver import IntentSolver\nclass S(IntentSolver):\n    def initialize(self, config):\n        pass\n    def generate_plan(self, intent, state, snapshot=None):\n        raise NotImplementedError\n    def metadata(self):\n        from minotaur_subnet.sdk.intent_solver import SolverMetadata\n        return SolverMetadata(name=\"s\", version=\"0.1.0\", author=\"local\")\nSOLVER_CLASS = S",
  "hotkey": "local-miner",
  "epoch": 0,
  "solver_name": "local-dev"
}'

This route skips screening and queues directly into benchmarking.

Step 7 — Check submission status

terminal SH COPY

python -m minotaur_subnet.miner.main status \
--submission-id sub_xxx \
--validator-url "$VALIDATOR_URL"

Status values

Status	Meaning
queued	Submission accepted, waiting to start screening.
screening_stage_1	Static checks (imports, no banned syscalls, basic shape).
screening_stage_2	Docker build + import.
screening_stage_3	Smoke-test run on a benchmark scenario.
benchmarking	Full replay against the current scenario suite.
scored	Benchmark complete — ranked against current champion.
adopted	Promoted to champion; running in BlockLoop.
rejected	Failed screening or scored below threshold.

What happens after submission

Once submit returns, the API queues your solver for evaluation. The lifecycle on the validator/API side:

1. Screening (seconds–minutes)

   Three stages run in sequence. Most failures show up here — Docker build errors, missing SOLVER_CLASS, banned imports.

2. Benchmarking (minutes)

   The benchmark worker runs your solver against the active scenario suite for each live App. Each scenario produces a score; your final score is the aggregate.

3. Champion comparison

   If your aggregate exceeds the current champion by at least DETHRONE_MARGIN (currently 0.005 = 0.5%), you become the new champion.

4. Adoption

   Champion adoption requires N-of-M validator signatures via champion-certification consensus (separate from order consensus). This typically completes in seconds once the leader proposes the new champion.

5. Weight emission

   The active champion’s submitter gets 100% of the miner emission weight on the next subtensor epoch (~20 min in production with --epoch-seconds 1200). Champion-takes-all. At Alpha launch only 5% of miner emissions are enabled, ramping as the network proves out.

Wall-clock times depend on the live network’s queue depth. On a quiet network, screening + benchmarking takes 1–3 minutes. During a benchmark spike (multiple submissions queued), it can stretch to 10+ minutes.

Poll with status or watch the agent loop logs — both surface state transitions in real time.

Next steps

↳ REF · 02 Configuration Full CLI flags and environment variables. ↳ API · 03 Solver API IntentSolver and Strategy contracts. ↳ DEEP · 04 Custom Solver Implementation guidance and patterns. ↳ REF · 05 Network Reference Production endpoints + contract addresses.