Cortex: A Rust control plane for Bittensor's multi-challenge subnet

What Cortex actually does

Cortex is not a mining framework or a validator client. It is the control plane for a Bittensor subnet that hosts multiple AI research challenges. The README is explicit: validators fetch weights, they do not execute challenges. Miners submit work over HTTP to a gateway, the gateway signs score leaves and seals an epoch weight bundle, and validators pull that bundle via GET /v1/weights/latest. The two live challenges are Design, which takes a ZIP harness with agent.py and pyproject.toml, and Prism, which uses an AutoModel pin plus patch and an operator-owned GPU recipe eval. This separation of duties is the core design: the gateway is the sole public edge, and validators have a narrow, read-only interface. If you are a miner, you never touch the control plane; you only hit challenge-specific endpoints. If you are a validator, you only read weights. That is a clean boundary, and it is the first thing to understand about this project.

The sealed bundle as the trust anchor

The trust model rests on an EpochBundleV1 that the gateway seals. The README describes a burn vector: unsealed or decode-error latest weights result in uid 0 getting 100% of the weight, with sealed: false, rather than a 404. That is a deliberate failure mode, not an oversight. It means a misconfigured or compromised gateway does not silently drop weights; it forces a visible, drastic outcome that any observer can detect. Trust roots come from owner-signed local files, config/challenges.toml and config/measurements.toml, which are never fetched from the gateway. This is a strong stance: the subnet owner's local configuration is the root of trust, not the network. The trade-off is that the master host, where the gateway runs, becomes a single point of failure. If that host is compromised, the burn vector is the only safety net, and it is blunt.

How miners and validators interact

Miners submit over HTTP only. The README points to docs/external-miner/ and gives the endpoint patterns: https://<gateway>/challenge/design/... and https://<gateway>/challenge/prism/.... Public miner docs live in separate repositories, design-challenge and prism, and contain examples only, no control-plane code. The README warns never to put mnemonics or challenge signing keys in miner clients. Validators have a single command: curl -fsS "$GATEWAY/v1/weights/latest", then set_weights or CRV4 timelock with the validator wallet. This is a deliberately thin validator path. The architecture diagram shows the gateway proxying to design-challenge or prism-challenge services, then sealing the bundle. The gateway is the only component that runs on the subnet-owner host, via docker compose --profile master. Everything else, postgres, validator, updater, socket-proxy, runs without that profile. The asymmetry is intentional: miners and validators never need to know about each other's internals.

Getting it running

Deployment uses Docker Compose with environment materialization. The README gives the operator sequence: ./deploy/scripts/materialize-env.sh, then docker compose up -d for the base services, and docker compose --profile master up -d on the subnet-owner host to add the gateway. Images come from GHCR, digest-pinned, with suffixes like validator, gateway, updater, prism-challenge, design-challenge, and design-egress-proxy. The README is firm: never use :latest in measured compose. For local testing, there is a smoke path: ./deploy/scripts/local-e2e.sh --help and --smoke, targeting testnet 541 with an optional tunnel. The toolchain is pinned to Rust 1.96.0 via rust-toolchain.toml, and the workspace is crates/*, bins/*, and xtask. The core gate is cargo test --workspace, and CI also runs fmt, clippy -D warnings, cargo deny, and several xtask checks: loc-cap, consensus-lint, spec-check, design-check, and external-docs-check. The setup is not trivial; it assumes you have a Bittensor subnet identity and a master host.

The naming mess is a real cost

The README admits that some env vars, host paths, GHCR package names, and crypto domain tags still spell BASE_* or base, and that this is intentional. docs/NAMING.md explains the mapping. The registry path is still ghcr.io/baseintelligence/base/<suffix>, a historical package name. This is a maintenance trap. Anyone who forks or deploys this will have to remember that base in a config file does not mean the old project, it means Cortex. The README says the naming is deliberate, but it is also a source of confusion for new operators. If you are evaluating this for production, budget time to trace every BASE_* reference and confirm which one is live. The upside is that the documentation is upfront about it; the downside is that the confusion is baked into the codebase.

What was removed and why it matters

The README states there is no miner Phala/CVM path on this branch. The agent-v1 and Harbor pack executors were removed. That is a significant limitation. Earlier versions of Bittensor subnets often used confidential VMs for miner execution; this branch has dropped that entirely. Miners now submit HTTP only, and the challenges themselves run on operator-owned infrastructure. For the Prism challenge, that means an operator-owned GPU recipe eval. This shifts the trust burden: the operator must provide the compute, and miners must trust that the eval is fair. If you were hoping to run miners inside a TEE or confidential container, this is the wrong branch. The removal is a design choice, but it narrows the deployment options considerably. The threat model doc, docs/THREAT_MODEL.md, presumably covers the implications, but the README alone makes clear that the execution model is centralized on the operator side.

Alternatives and the weight-only validator path

The obvious alternative is a traditional Bittensor subnet where validators run the challenges themselves, or a subnet that uses a different control plane language, such as Python, which is common in the Bittensor ecosystem. The difference here is that validators do not execute challenges; they only fetch and submit weights. This is a meaningful architectural divergence. In many subnets, validators are the ones scoring miner work, which requires them to run the evaluation logic. Cortex moves that evaluation into the gateway and challenge services, leaving validators with a single HTTP GET. The trade-off is that validators lose the ability to independently verify scores; they must trust the gateway's sealed bundle. The burn vector is a crude backstop, but it is not a verification mechanism. If you need validators to audit the scoring process, this design will not give you that.

Maintenance, license, and upgrade cost

The project is Apache-2.0, which is permissive and allows commercial use with attribution. The repository has active releases, with v3.3.5 pushed in August 2026, so there is a steady cadence. The CI gates are strict: clippy -D warnings, cargo deny, and multiple xtask checks. That is a sign of disciplined maintenance, but it also means contributing requires passing all those gates. The docs list frozen specs, docs/BUNDLE_SPEC.md and docs/DESIGN_CHALLENGE.md, which means changes to those areas are intentional and likely slow. Upgrade cost is moderate: you must track Rust 1.96.0, digest-pinned images, and the naming inconsistencies. The README warns against :latest, so you will need to update pinned digests on each release. The presence of a runbooks directory and a local-e2e script suggests the maintainers expect operators to test upgrades before applying them. The main cost is not code changes; it is operational vigilance around the master host and the sealed bundle.

Editorial conclusion

Adopt Cortex if you run a Bittensor subnet with multiple challenge types and want a Rust-based control plane that keeps validators on a weight-only path. Do not adopt it if you need a miner-side Phala/CVM execution path, since that was removed on this branch. Before deploying, verify the naming inconsistencies: some env vars and GHCR paths still use BASE_* and base, and the trust roots are owner-signed local files, so you must control the master host. Check the frozen specs for bundle and design challenge, and confirm your Rust toolchain matches 1.96.0.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes