Skip to main content

Miner Agent Overview

This document describes the positioning, capabilities, and core concepts of miner-agent.

Positioning​

miner-agent is the node-side control-plane agent for decentralized miner deployments.

It is intended to run beside the model runtime and dcgm-exporter. In the Compose topology generated by miner-cli, the agent is configured through the miner_client block.

What It Does​

On startup, miner-agent:

  1. Loads ${MINER_HOME}/config.json
  2. Generates a new node identity and wallet identity when no config exists
  3. Starts a FastAPI diagnostics server
  4. Calls the miner registration endpoint
  5. Sends an initial heartbeat
  6. Repeats heartbeat on a fixed interval
  7. Pulls and answers challenges when registration or heartbeat responses require it

Heartbeat Collection​

On every heartbeat, it collects:

  • Host CPU and memory snapshot
  • GPU inventory from nvidia-smi, with DCGM fallback
  • Runtime /health
  • Runtime /v1/models
  • Optional runtime /load
  • GPU metrics from DCGM /metrics

What It Does Not Do​

Important Boundaries

miner-agent does NOT:

  • Start, stop, or supervise the model runtime (handled by miner-cli via Docker Compose)
  • Scheduling, billing, revenue settlement, or model routing
  • Only reports local node state and answers control-plane verification challenges

Identity Model​

Identity persistence path: ${MINER_HOME}/config.json

Persisted fields:

  • node_id
  • node_key_type
  • node_public_key
  • node_private_key
  • wallet_key_type
  • wallet_public_key
  • wallet_private_key
  • wallet_address
  • created_at

Identity Details​

ItemDescription
node_idDerived from Ed25519 public key, uses libp2p-style Peer ID
SigningChallenge and control-plane payloads use Ed25519 node private key
wallet_addressDerived from secp256k1 keypair, uses EVM-style address
Directory permissionsBest-effort 0700
File permissionsBest-effort 0600
Identity Persistence

Docker deployments must persist ${MINER_HOME}. Losing this file creates a new node identity.

Background Loop​

After identity initialization, the agent starts one background loop. Each iteration:

  1. Waits for MINER_HEARTBEAT_INTERVAL_SECONDS
  2. Registers again if not registered
  3. Sends heartbeat
  4. Handles challenge if required by control plane

HTTP failures are recorded in memory state and exposed through the local status API.