Installation

This page covers getting the reference miner client, aetron-miner, onto a machine and through its first run. It is the mechanical side of mining: requirements, install, configuration, and a first health check. For what mining is and how rewards work, read Mining in AETRON, and for choosing a Neuronet and joining it, read How to Start Mining.

What the Client Is

aetron-miner ships as two cooperating processes:

• The daemon. A Rust background process that holds your identity and keystore, talks to the chain, listens for jobs, and orchestrates everything else. The CLI and the desktop GUI are both thin front ends over the same daemon, talking to it over a local socket.
• The runner. The compute component that loads the model, executes inference and training steps, and produces the validation artifacts that Proof of Intelligence compares. In a release build it is a compiled native binary rather than a Python source tree, and the daemon verifies its signature before launching it.

The runner ships slim: it contains AETRON's own code, not the ML stack. PyTorch and the rest of the stack live in a separate environment that the client provisions itself:

aetron-miner env install

That command picks a profile from your hardware (CUDA version, Apple Silicon, or CPU), downloads a pinned set of wheels, builds the environment next to any existing one, runs a self-test, and only then switches over. aetron-miner env rollback puts the previous one back. You never invoke pip or python yourself, and the versions are not yours to choose: the runner has the pins compiled into it and refuses to start against an environment that does not match, because a different PyTorch build produces different numbers and different numbers fail verification.

The split keeps the download small and lets the same runner cover hardware that a single frozen bundle could not, Blackwell being the case that forced it.

The Reference Client Is Not the Only Path

aetron-miner is a reference implementation, not a mandatory one. The protocol is open, and a client written independently against the public protocol documentation is a full participant. Verification does not care which software produced a result. It checks the result itself against the task's canonical execution spec, so a custom client that produces correct, reproducible artifacts earns exactly like the reference one.

What the reference client gives you is convenience: identity handling, job orchestration, the Pulse implementation, model cache management, and the verification duties wired up. Writing your own means reimplementing those against the protocol surface, which is a reasonable trade if you have specific infrastructure to fit.

Hardware

Mining is not tied to one GPU vendor. The verification design supports mixed hardware, with comparison done either bit-exactly inside one hardware class or within a calibrated tolerance across classes. See Heterogeneous Mining for how that works. In practice the reference runner has been exercised on NVIDIA CUDA GPUs, Apple Silicon via MPS, and plain CPU.

Memory is what determines your Pulse tier. The runner detects available memory at startup and every cycle, and assigns a tier automatically. You do not pick it:

Tier	Detected memory	Pulse memory table
Phone	2 GB and up	256 MB
Low	4 GB and up	1 GB
Standard	8 GB and up	4 GB
High	16 GB and up	8 GB
Datacenter	32 GB and up	16 GB

Below 2 GB the runner refuses to start. A higher tier builds a larger memory table and claims more samples per Pulse window, which is what makes the proof memory hard rather than something a small specialized device can fake.

Tier is a floor, not a guarantee of earnings. The binding requirement is still the Neuronet you join: your machine has to run that task's canonical model at its declared precision, which for a large model means far more VRAM than the tier minimum.

Plan disk around model weights and datasets rather than the client itself. The install wizard suggests a cache soft cap of half the free space on whichever volume you point it at, and the cache can live on a separate drive.

Platforms

Release packaging exists for Linux x86_64 (tarball plus an install script) and macOS, including Apple Silicon (a .pkg with a graphical setup step). Windows is not covered by the current packaging, and some client features (free space detection for the cache limit, for one) are unimplemented there.

Builds are not published for download yet. The macOS package still needs a Developer ID signature and notarisation before it can be handed out, and there is no public release page. Until then, running a miner means building from source.

On Linux, building the daemon from source needs a normal toolchain: build-essential and cmake. It does not need OpenSSL or protobuf development packages. The optional desktop GUI additionally needs libwebkit2gtk-4.1-dev, libsoup-3.0-dev, libayatana-appindicator3-dev, and librsvg2-dev. On macOS the webview is native, so the GUI needs nothing extra.

First Run

Put both binaries somewhere on your PATH, then run the setup wizard:

aetron-miner init

init is interactive. It asks a short list of questions and writes the answers to ~/.aetron-miner/config.toml. If a config already exists it asks before overwriting, and declining leaves the file untouched. The questions, in order:

1. Wallet path. A location for key material. The wizard offers to create the file if it is missing.
2. Neuronet ID. The on-chain id of the Neuronet you intend to mine in.
3. Model path. Where the weights live. The path is accepted if the file exists or if its parent directory does, so you can point at a location you have not populated yet.
4. GPU limit. A percentage from 0 to 100. Leaving it empty means no limit.
5. Cache directory. Where models and datasets are stored. Defaults to ~/.aetron-miner/cache/, and can be on another volume such as an external SSD.
6. Cache size cap. A soft limit in gigabytes, pre-filled with half the free space on that volume. Entering 0 means no limit. Exceeding it produces a warning on download rather than a hard block.
7. Network. One of mainnet, testnet, or local. The default is testnet, which resolves to the public entrypoint wss://entrypoint-test.aetron.ai.

Choosing local adds two more questions: the Substrate node WebSocket URL, defaulting to ws://127.0.0.1:9944, and a task id, defaulting to 0 for the Neuronet's first task.

The wizard is deliberately quiet. It does not create the cache directory or download anything, it only writes the config file. It also covers only the common fields. Everything else, including the advanced settings it never asks about, is documented in Configuration.

Once the config exists, bring the client up:

aetron-miner start

That starts the background daemon and then starts the engine event loop. aetron-miner stop reverses both. Running aetron-miner with no arguments in a terminal opens an interactive TUI instead; in a pipe or CI it prints help and exits. The full command set is in the CLI Reference.

Where Things Live

Everything the client owns sits under ~/.aetron-miner/:

Path	Contents
config.toml	The configuration the wizard wrote
keystore/	Encrypted hotkey.json plus a meta.json holding the public SS58 address for display before unlock
cache/	Downloaded models and datasets, unless you moved it elsewhere
state.db	Local persistence, including which witness challenges you already voted on, so a restart does not redo work
enc_secret	The X25519 secret used to open sealed job inputs, mode 0600, stable across restarts
daemon.log	Daemon log, streamed by aetron-miner logs
daemon.sock, daemon.pid	Local RPC socket and pidfile

Your coldkey is not in there. It stays in your own wallet software, and the config records only its SS58 address for on-chain queries and display. See Wallets and Keys.

Checking It Came Up

aetron-miner status

status first reports whether the config file was found, then queries the running daemon over its local socket. When the daemon is up you get its PID and uptime, the configured network, the chain backend actually in use, the mining state, jobs completed, detected GPU and memory, the Pulse tier that was auto-detected, the inference backend, and cache contents. If the daemon is not running, status says so instead of failing.

Read the network line and the chain backend line as two separate facts. Network is what your config asked for. Chain backend is what the daemon actually built, and it is labelled honestly, including when it is simulated or fell back with a reason. A tier line that reads lower than your hardware, or an inference backend of CPU on a GPU box, is the usual sign that the runner did not get at the accelerator.

If you plan to receive jobs over the peer-to-peer mesh rather than only from chain state, the mesh listener is off by default and has to be enabled in the config. See Peer to Peer.