Miner Node Setup

Last updated: 2026-06-28

Use this guide to install and run a Cortensor miner from the packaged cortensord binary. The setup flow covers the installer, IPFS, Docker, key generation, registration, verification, service scripts, GPU flags, upgrades, and troubleshooting, using the binary-first command format:

cortensord ~/.cortensor/.env minerv4

Quick Path

1. Install Docker, IPFS, and cortensord with the current installer for your platform.
2. Generate the node key and fund the node wallet with gas for the target network.
3. Register and verify the node.
4. Configure ~/.cortensor/.env for minerv4, runtime mode, RPC, chain ID, and model settings.
5. Start the miner and watch logs/stats until it receives work.

What A Miner Does

Miner nodes provide compute to the Cortensor network. A miner connects to the configured chain and router/session infrastructure, receives assigned inference work, runs the configured model runtime, and submits task results back through the network flow.

flowchart LR
  Router["Router / session queue"] --> Miner["Miner node"]
  Miner --> Runtime["LLM runtime<br/>Docker, subprocess, GPU, or CPU"]
  Runtime --> Miner
  Miner --> Queue["Task result / commit"]
  Queue --> Validator["Validation / oracle flow"]

Before You Start

Requirement	Notes
Supported host	Linux Ubuntu 22.04/Debian 12, macOS ARM64, and Windows/Cygwin paths are supported. Linux is the clearest production path because Docker, systemd, logs, and service scripts are already part of the installer flow.
Node wallet	The miner needs a node keypair. Generate it with tool gen_key or the installer helper script.
Gas	The node wallet needs gas on the target network. Alpha/testnet deployments used Arbitrum Sepolia test ETH; production and later testnet values come from the active network matrix.
Allowlist or registration approval	Some deployments require the miner address to be approved before registration/verification succeeds.
Docker	Required for Docker-managed LLM runtime. The Linux installer installs Docker before cortensord.
IPFS	The installer includes IPFS. Keep it installed when storage/off-chain flows are enabled by the deployment.
Model runtime	Miners need either a Docker-managed LLM engine, subprocess model runtime, GPU runtime, or external LLM endpoint depending on .env.

Setup Flow

flowchart TB
  Download["Download or clone installer"] --> Install["Install Docker, IPFS, cortensord"]
  Install --> VerifyInstall["Verify binary, scripts, Docker, IPFS"]
  VerifyInstall --> Key["Generate node key"]
  Key --> Fund["Fund node wallet"]
  Fund --> Approval["Get allowlist / registration approval if required"]
  Approval --> Register["Register node"]
  Register --> Verify["Verify node"]
  Verify --> Runtime["Configure LLM runtime"]
  Runtime --> Start["Start minerv4"]
  Start --> Monitor["Monitor logs and stats"]

1. Get The Installer

Download the current installer archive:

curl -L https://github.com/cortensor/installer/archive/main.tar.gz -o cortensor-installer-latest.tar.gz
tar xzfv cortensor-installer-latest.tar.gz
cd installer

Or clone it with Git LFS:

sudo apt install git-lfs
git clone https://github.com/cortensor/installer
cd installer
git lfs install
git lfs fetch
git lfs pull
git pull

2. Install On Linux

Run installer commands as the setup/root user, then switch to the deploy user created by the installer.

cd installer

# Ubuntu 22.04
./install-docker-ubuntu.sh

# Debian 12
./install-docker-debian.sh

# Storage/runtime dependencies
./install-ipfs-linux.sh

# Cortensor binary and service scripts
./install-linux.sh

After installation, verify the expected files and services:

sudo su deploy
cd ~/
export PATH="$PATH:$HOME/.cortensor/bin"

ls -al /usr/local/bin/cortensord
ls -al "$HOME/.cortensor/bin/cortensord"
ls -al /etc/systemd/system/cortensor.service
ls -al "$HOME/.cortensor/bin/start-cortensor.sh"
ls -al "$HOME/.cortensor/bin/stop-cortensor.sh"
docker version
ipfs version

3. Generate, Register, And Verify

The installer includes helper scripts. Use these when they are available for the release:

sudo su deploy
cd ~/installer

./utils/gen-key.sh
./utils/register.sh
./utils/verify.sh

The same flow can be run directly through cortensord:

export PATH="$PATH:$HOME/.cortensor/bin"

cortensord ~/.cortensor/.env tool gen_key
cortensord ~/.cortensor/.env tool register
cortensord ~/.cortensor/.env tool verify

Registration can fail if the address is not approved for the target deployment, the wallet has no gas, the RPC is wrong, or contract addresses do not match the active network.

4. Configure The Miner Environment

The installer creates or updates ~/.cortensor/.env. Confirm these areas before starting the miner.

# Network
HOST=
CHAINID=
IS_L3=

# Node wallet
NODE_PUBLIC_KEY=
NODE_PRIVATE_KEY=

# Runtime
AGENT_ROLE=minerv4
AGENT_MINER_DOCKER_LLM=1
AGENT_MINER_DOCKER_LLM_START=1
DOCKER_LLM_MANAGER=1
LLM_HOST=127.0.0.1
LLM_PORT=8091

# Polling
MINER_PULLING_INTERVAL_SECONDS=5

Set HOST, CHAINID, IS_L3, and contract addresses from the active network matrix for the target deployment. Set NODE_PUBLIC_KEY and NODE_PRIVATE_KEY from the key generated during the registration step. Do not copy empty wallet or RPC values into a running miner.

5. Start The Miner

Start manually:

cd ~/.cortensor
cortensord ~/.cortensor/.env minerv4

Start with Docker-managed LLM runtime when the release supports the extra Docker mode arguments:

cd ~/.cortensor
cortensord ~/.cortensor/.env minerv4 1 docker

Use installed scripts when they are configured for your host:

~/.cortensor/bin/start-cortensor.sh
~/.cortensor/bin/stop-cortensor.sh

On Linux hosts with the packaged systemd unit:

sudo systemctl start cortensor
sudo systemctl stop cortensor
sudo systemctl status cortensor

6. Enable GPU Support

Update ~/.cortensor/.env:

LLM_OPTION_GPU=1
LLM_OPTION_GPU_THRESHOLD=-1

Then start the miner with the subprocess/runtime mode used by the current release:

cortensord ~/.cortensor/.env minerv4

For Docker GPU setups, also confirm container device visibility and release-specific variables such as LLM_GPU_CONTAINER, LLM_GPU_CONTAINER_DEVICE_IDS, and LLM_GPU_CONTAINER_MEMORY where they are present.

macOS Notes

The macOS ARM64 installer path installs IPFS and cortensord, then uses the same key/register/verify and start flow.

cd installer
./install-ipfs-osx.sh
./install-osx.sh

export PATH="$PATH:$HOME/.cortensor/bin"
cortensord ~/.cortensor/.env tool gen_key
cortensord ~/.cortensor/.env tool register
cortensord ~/.cortensor/.env tool verify
cortensord ~/.cortensor/.env minerv4

Windows Notes

The Windows path uses Git for Windows or Cygwin plus installer scripts/BAT files. The operator flow is the same:

1. Install Git for Windows.
2. Install IPFS and cortensord from the Windows installer scripts.
3. Generate the node key.
4. Register and verify.
5. Start minerv4.

Prefer the platform-specific scripts packaged with the installer for Windows service/start behavior.

Upgrade

Linux:

sudo su deploy
cd ~/installer
git pull
./upgrade-linux.sh

macOS:

cd ~/installer
git pull
./upgrade-osx.sh

Windows/Cygwin:

cd ~/installer
git pull
./upgrade-win-cygwin.sh

After an upgrade, check version and restart the miner:

cortensord ~/.cortensor/.env tool version
cortensord ~/.cortensor/.env minerv4

Operational Checks

Check	Command
Node identity	cortensord ~/.cortensor/.env tool id
Wallet balance	cortensord ~/.cortensor/.env tool balance
Registration state	cortensord ~/.cortensor/.env tool is-register
Verification state	cortensord ~/.cortensor/.env tool is-verify
Account status	cortensord ~/.cortensor/.env tool account-status
Node stats	cortensord ~/.cortensor/.env tool stats
Binary version	cortensord ~/.cortensor/.env tool version

Linux logs from the installer path:

ls -alh /var/log/cortensord.log
tail -f /var/log/cortensord.log

Troubleshooting

Symptom	First checks
cortensord not found	Confirm $HOME/.cortensor/bin is in PATH, or call $HOME/.cortensor/bin/cortensord directly.
Env file missing	Confirm ~/.cortensor/.env exists and is readable by the deploy/user account.
Registration fails	Check gas, RPC, chain ID, allowlist/approval state, and active contract addresses.
Verification fails	Confirm registration succeeded and the target deployment expects this node role.
Miner starts but receives no work	Check router/session availability, node registration, model runtime health, and polling interval.
Docker runtime fails	Check Docker daemon, image availability, container logs, exposed LLM port, and Docker socket access.
GPU is ignored	Confirm GPU drivers, container runtime support, LLM_OPTION_GPU=1, and release-specific GPU variables.
IPFS conflict	Stop stale IPFS processes with the installer utility or pkill ipfs when safe for the host.

Other Node Roles

Most operators start with the miner flow above. Other roles use the same binary shape, with deployment-specific authorization and environment values.

Role	Start command	Purpose
Router	cortensord ~/.cortensor/.env routerv1	API-facing coordinator for sessions and tasks.
Miner	cortensord ~/.cortensor/.env minerv4	Executes inference work and submits task results.
Oracle	cortensord ~/.cortensor/.env oraclev3	Coordinates task/session lifecycle transitions.
Validator v1	cortensord ~/.cortensor/.env validatorv1	Runs network task-level checking/regulation with cognitive-level and node-level validation.
Validator v2	cortensord ~/.cortensor/.env validatorv2	Runs post-result quantitative validation for network task results.
Validator v3	cortensord ~/.cortensor/.env validatorv3	Runs post-result qualitative validation for network task results.
Pool	cortensord ~/.cortensor/.env poolv1	Supports pool coordination.
Quality oracle	cortensord ~/.cortensor/.env qualityv1	Runs heartbeat-style user task quality sampling.
Tool	cortensord ~/.cortensor/.env tool <command>	Runs key, registration, verification, stats, and maintenance commands.