You can stand up a self-hosted, single-pane-of-glass view of your entire home mining fleet in one evening: run Prometheus, Grafana, and a miner exporter on a Raspberry Pi or mini-PC, scrape each miner’s metrics over your LAN, and get alerted the moment a board drops hashrate, a fan stalls, a temperature ceiling is breached, or a pool connection dies. This is the hands-on build guide — not a tool roundup.
If you’ve ever woken up to find a rig had been offline for six hours, you already know why monitoring matters. Manufacturer web UIs are fine for one machine, but the second you run two or three miners, refreshing browser tabs stops scaling. What you want is one dashboard that shows every miner at a glance, with history, and a notification that reaches your phone before a problem costs you a day of hashrate.
The good news: the open-source observability stack the rest of the infrastructure world uses works beautifully for ASICs too. We stand on the shoulders of the people who built it — Prometheus (a CNCF project) for collecting and storing time-series metrics, and Grafana (from Grafana Labs) for turning those numbers into graphs and alerts. Neither was built for Bitcoin mining; both happen to be perfect for it.
First, the honest part: what talks to what
Before you copy any config, you need a clear mental model, because this is where most home setups go sideways.
Almost every ASIC firmware — stock, BraiinsOS+, VNish, LuxOS, and DCENT_OS — exposes the cgminer API on port 4028. That API is the work of Con Kolivas and the cgminer project, and it has become the lingua franca of mining: every firmware implements at least a subset of it. But there’s a catch that trips up newcomers constantly:
Port 4028 is a raw TCP socket that speaks JSON — it is not HTTP, and it is not a REST endpoint. You send a command like
{"command":"summary"}over a TCP connection and get JSON back. You cannot point a browser orcurlat it, and Prometheus cannot scrape it directly.
For the full command vocabulary — summary, stats, devs, pools, and friends — see our miner API reference, which documents the cgminer/BOSminer protocol on port 4028 in detail. That page is the companion to this one: it tells you what the miner can say, and this guide shows you how to collect and graph it.
So how does Prometheus, which only knows how to fetch an HTTP /metrics page, read a raw TCP JSON socket? Two paths:
- Native
/metricsendpoint. A couple of firmwares expose a real Prometheus-format HTTP endpoint out of the box. Per the D-Central firmware feature matrix, BraiinsOS+ ships a/metricsendpoint built for Grafana, and DCENT_OS does as well. Stock firmware, VNish, and LuxOS do not expose native Prometheus metrics. If you’re on one of those, you go to path two. - An exporter. An exporter is a small program that connects to the cgminer API over TCP, translates the JSON into Prometheus format, and serves it as a normal
/metricsHTTP page that Prometheus can scrape. The practical, fleet-friendly way to do this is with pyasic (an open-source library from UpstreamData) or a community cgminer-exporter. pyasic speaks the CGMiner API subset every firmware implements, so a single exporter can cover a mixed fleet of stock, BraiinsOS+, VNish, LuxOS, and DCENT_OS machines.
Brand-new to flashing custom firmware? Start with mining firmware for beginners, then the BraiinsOS+ setup guide (native /metrics), the LuxOS firmware guide, or the general Antminer firmware update guide. To compare firmware options before you commit, our Bitcoin mining software comparison lays out the tradeoffs.
One more distinction: the miner vs. the host
You’ll see node_exporter in every Prometheus tutorial, and it’s worth keeping straight. node_exporter (maintained by the Prometheus community) watches the host machine — the Raspberry Pi or mini-PC running your stack — reporting its CPU, RAM, disk, and network. It tells you nothing about your miners. The miner exporter is a separate thing that watches the ASICs. You want both: node_exporter so you know your monitoring box itself is healthy, and the miner exporter for the rigs.
The hardware: a Pi is plenty
This entire stack runs comfortably on a Raspberry Pi 4 or 5, or any cheap mini-PC, as long as it sits on the same LAN as your miners. There’s no GPU, no horsepower required — Prometheus and Grafana are lightweight, and a home fleet of a handful of miners barely registers. Give it a wired connection if you can; you want your monitoring box to be the last thing that flakes out.
The stack: one docker-compose file
Everything runs as containers, so the whole thing is one file you can version, back up, and move. Create a folder, drop in this docker-compose.yml, and you have Prometheus, Grafana, node_exporter, and a miner exporter ready to go:
services:
prometheus:
image: prom/prometheus:latest
volumes:
- ./prometheus.yml:/etc/prometheus/prometheus.yml
- prom_data:/prometheus
ports:
- "9090:9090"
restart: unless-stopped
grafana:
image: grafana/grafana:latest
volumes:
- grafana_data:/var/lib/grafana
ports:
- "3000:3000"
restart: unless-stopped
node_exporter:
image: prom/node-exporter:latest
ports:
- "9100:9100"
restart: unless-stopped
miner_exporter:
# community cgminer/pyasic exporter image of your choice
image: your-cgminer-exporter:latest
ports:
- "9876:9876"
restart: unless-stopped
volumes:
prom_data:
grafana_data:Then tell Prometheus what to scrape. This minimal prometheus.yml covers the host, the miner exporter, and — if you run BraiinsOS+ or DCENT_OS — a miner’s native /metrics endpoint directly:
global:
scrape_interval: 30s
scrape_configs:
- job_name: 'host'
static_configs:
- targets: ['node_exporter:9100']
- job_name: 'miners_via_exporter'
static_configs:
- targets: ['miner_exporter:9876']
# Only for firmware with a NATIVE /metrics endpoint
# (BraiinsOS+, DCENT_OS). Stock/VNish/LuxOS go through the exporter above.
- job_name: 'miners_native'
static_configs:
- targets: ['192.168.1.50:8080', '192.168.1.51:8080']Run docker compose up -d, open http://<your-pi-ip>:9090 to confirm Prometheus sees its targets as “up,” then http://<your-pi-ip>:3000 for Grafana (default login admin / admin, which you should change immediately). Add Prometheus as a data source in Grafana, pointing at http://prometheus:9090, and you’re collecting.
The dashboard: what to actually put on screen
A good home-fleet dashboard isn’t a wall of 40 gauges — it’s the four or five things that tell you whether you’re earning. Build panels for:
- Per-board hashrate. Each hashboard reports its own rate. Watching them individually (not just the machine total) is how you catch a single failing board before it drags the whole rig down. If you want to sanity-check “expected” hashrate, remember the chip counts differ by model — an S19 has 76 chips per board, while an S19 Pro has 114 — so don’t compare boards across models.
- Per-board temperature. Temperature on an ASIC is sensed per board, not per chip. Dedicated I2C sensor ICs on each hashboard (parts like the LM75A, TMP1075, or NCT218) report board temperature, which the controller reads over I2C. Graph the per-board readings; a board that runs hotter than its siblings is your early warning.
- Fan RPM. Miners run a closed-loop fan control with tachometer feedback. A fan reading 0 RPM is an emergency — when a fan stalls or a temp sensor fails, firmware’s thermal protection will throttle or shut the machine down to protect the silicon. You want to see that coming, not discover it after the rig has been idling.
- Pool accepted shares. A flat or zero accepted-share line means you’re hashing into the void — usually a pool disconnect or bad config. This is the panel that catches “the miner looks fine but is earning nothing.”
You don’t have to build all of this by hand. Export your finished layout as a dashboard JSON file (Grafana → Dashboard settings → JSON Model) so you can re-import it on any rebuild, and keep that JSON in the same folder as your compose file. Treat the whole directory as your backup.
The alerts that actually save sats
Graphs are for when you’re looking. Alerts are for when you’re not. Add Alertmanager (or use Grafana’s built-in alerting) and wire up exactly four rules — these are the failures that quietly cost real money:
- Hashrate drop — a miner’s total or per-board hashrate falls meaningfully below its expected TH/s for more than a few minutes.
- Fan stall — any fan tachometer reads 0 RPM. This precedes a thermal trip; treat it as urgent.
- Temperature ceiling — any per-board sensor crosses your safe threshold.
- Pool disconnect — accepted shares flatline, or the
summarydata shows no active pool.
Point the notifications wherever you’ll actually see them — a phone push, a Telegram bot, an email. The goal is simple: turn “I found out the next morning” into “I got a ping in four minutes.”
The SNMP option (and when to skip it)
If you’re running a larger setup alongside other gear that speaks SNMP, some stock firmware offers SNMP, and DCENT_OS treats it as an optional add-on for enterprise monitoring compatibility. For a home fleet, SNMP is usually overkill — the cgminer API plus an exporter covers everything you need. Reach for SNMP only if you already have an SNMP-based monitoring system you want the miners to plug into.
Prefer a smart-home dashboard instead?
The Prometheus + Grafana stack is the right answer if you want deep history, flexible alerting, and a purpose-built ops dashboard. But if you already run Home Assistant and would rather see your miners next to your thermostats and lights, that’s a perfectly good alternative — we have a full walkthrough for the Home Assistant Bitcoin mining integration, which also reads the cgminer API on port 4028. Same data, different pane of glass.
Where DCENT_OS fits
We mention DCENT_OS here for the same reason we mention BraiinsOS+: it exposes a native Prometheus /metrics endpoint, so it drops straight into this stack with no exporter in between. DCENT_OS and the DCENT_Toolbox are source-available under GPL-3.0 and currently in beta — one more open option in an ecosystem that already has good ones. Whatever firmware you run, the stack above works; that’s the whole point of an open standard like the cgminer API.
When a panel goes red
Monitoring tells you that something’s wrong; fixing it is the next step. When a board drops out, a fan reads zero, or temps climb, keep our ASIC troubleshooting cheat sheet open in the next tab. Between a dashboard that shows you the problem and a cheat sheet that tells you what to do about it, you’ve got the two halves of running a home fleet like you mean it.
Build it once, and you’ll never refresh a miner’s web UI in a panic again.
Bitaxe Heatsink — High-Performance Aluminum Cooler for Bitaxe & Nerdaxe Gamma / Supra / Ultra — Silent Operation & Stable Overclocking" width="80" height="80" loading="lazy" style="width:80px;height:80px;object-fit:contain;border-radius:6px;background:#1A1A1A;flex-shrink:0;">
Shop Heatsinks
