Discover, Audit & Diagnose Your Miners (Read-Only)

The safe order is discover → identify → diagnose & audit, and every step is read-only. Run dcent scan to find what is actually on your LAN (neighbour-first: it reads your machine's ARP/neighbour cache and can listen for UDP IP-report broadcasts before it probes anything), then run dcent doctor <ip> — the canonical first command for any single unit. Nothing in this pass writes to a miner. What you get out of it is an evidence profile — exact model, control board, incumbent firmware, reachability, security findings — not permission to flash.

What does “read-only” actually mean here?

Discovery and diagnosis are observation, not authorization. Every command on this page reads — it probes ports, reads your own ARP cache, listens for broadcasts, fingerprints firmware over HTTP/SSH, and runs diagnostic reads — and none of them mutate the miner.

The toolbox is built on a proof ladder, and the rungs are not interchangeable:

• “Detected” is not “safe to configure.”
• “A command exists” is not “that operation is validated on this miner.”
• “The firmware package parsed cleanly” is not “safe to install.”

Before any mutating operation is even offered, it must resolve to an exact model, control board, incumbent firmware, evidence level, and recovery route. A marketing model name never silently selects a control board, and a MAC address is a hint, never an identity. That discipline is precisely why the read-only pass exists: it removes the ambiguity first, and none of it can brick a unit.

The read-only workflow, in order

1. Discover — find what is on the operator LAN (neighbour-first, then bounded probing).
2. Identify — fingerprint firmware and control board on the responders only.
3. Diagnose & audit — build the evidence profile with dcent doctor, dcent diagnose, and dcent audit.

You come out the other side with a report, not a changed device.

What do I need before I start?

DCENT_Toolbox is version 2.5.0 — 491 Python modules, 87 CLI command modules (roughly 75 user-facing top-level commands), 4,500+ offline tests passing. It runs on Windows, macOS, and Linux, but launching it requires Python 3.9+ and a source checkout: there is no PyPI package and no prebuilt installer or binary download. Install once from the public GPL-3.0 repository:

git clone https://github.com/DCentralTech/DCENT_Toolbox.git
cd DCENT_Toolbox
python -m pip install -e .

The keygen-style terminal UI (dcent tui) is the flagship interactive surface and needs the optional [tui] extra from the same checkout (python -m pip install -e ".[tui]"). The Tauri desktop GUI in the tree is a scaffold that does not yet install — use the CLI or the TUI.

It is 0% dev fee, no cloud account, no license server, no telemetry, GPL-3.0 — the same bench D-Central Technologies has been building on since 2016, released from Québec so every operator can own and understand their own hardware.

Step 1 — How do I discover miners without knowing the subnet?

Discovery is neighbour-first. DCENT_Toolbox reads your machine's fresh ARP / neighbour cache (a cache read, not a sweep) and can listen for the UDP IP-report broadcast a control board sends. Only if that comes back empty or stale does it fall back to a cheap TCP-80 presence probe over your local /24, and then it identifies only the hosts that responded — rather than firing a multi-port scan at a whole CIDR first.

# Neighbour-first: no subnet required (reads ARP/neighbour cache)
dcent scan

# Neighbour/UDP hints only, no CIDR at all
dcent scan --neighbors

# Plan only — print the discovery plan, contact nothing
dcent scan --dry-run

# Explicit range when you want a specific subnet
dcent scan --range 192.168.1.0/24

# Also listen for a miner's physical IP-report button (UDP)
dcent scan --listen 30

The default range is this machine's local /24, not a hardcoded 192.168.1.0/24, so a bare dcent scan already stays on the network you are actually on. The scan itself is a read-only probe of the mining-relevant port trio — 22, 80, 4028 — optionally fingerprinting firmware over HTTP. Results reflect the moment of probe: hosts come and go, so a re-scan may find or miss different miners.

Discovery flags worth knowing

A MAC or a model string is a hint, never an identity

The ARP vendor hint comes from a small set of held prefixes. It will not tell an S19k Pro apart from an S21, and it does not select a control board. dcent scan --capabilities attaches a capability profile that is fail-closed by design for exactly this reason: a marketing model name is never treated as a unique control board, so a scan row carries the same honest capability envelope the rest of the toolbox uses.

Fastest way to find one freshly-racked miner

If you just plugged a unit in and do not know its address, skip the scan entirely: dcent ipreport listens for the UDP broadcast a control board sends when its physical IP Report button is pressed, and prints the unit's IP (and MAC when present). It is listen-only — it never sends a packet to a miner — and because the datagram's source address is the miner's IP, the result is authoritative.

# Press the miner's IP Report button, then:
dcent ipreport

Step 2 — How do I identify each responder?

Discovery gives you addresses; identity comes from fingerprinting the responders. dcent detect reads the firmware type over HTTP/SSH, and dcent fingerprint maps the control-board family, boot source, and an applicable-exploit feasibility table. Both are read-only, and both are honest about their limits: detected firmware reflects the fingerprint at the moment of read (it can change after an install, unlock, or revert), and the listed exploits are reference data, not proof that any exploit will succeed on this unit.

dcent detect <ip>          # firmware type (read-only fingerprint)
dcent fingerprint <ip>     # control board + boot source + exploit feasibility

DCENT_Toolbox drives four real vendor backends — Bitmain (stock / BraiinsOS+ / LuxOS / VNish / DCENT_OS), MicroBT WhatsMiner, Canaan/Avalon (cgminer + ascset), and BitAxe (AxeOS) — covering six firmware ecosystems (Bitmain stock, BraiinsOS+, LuxOS, VNish, DCENT_OS on Antminer, DCENT_OS/ESP on DCENT_axe) across seven control-board families: am1-XIL, am2-XIL, am3-BB, am3-AML, cv1835, bcb100, esp32-s3. Unknown gear routes to a read-only generic cgminer backend — never a silent Bitmain mis-route.

Step 3 — dcent doctor, the canonical first diagnostic

Once you have an IP, dcent doctor <ip> is the single first step for every persona. It is a read-only orchestrator that runs the individual read checks in parallel — preflight, firmware detect, fingerprint, verify-mining, audit, credential checks, vendor (VNish/ESP) probes, and artifact state — and emits one unified report with a suggested-next-commands footer. Two hard guarantees: it never mutates the target, and a failed sub-check degrades to an error row rather than aborting the run, so a partial report is always emitted.

# Full read-only triage of one unit
dcent doctor <MINER_IP>

# Faster pass
dcent doctor <MINER_IP> --quick

# Machine-readable report for automation or a support bundle
dcent doctor <MINER_IP> --json > doctor.json
dcent doctor <MINER_IP> --markdown > report.md

Targets can be a single IP, a CIDR, an IP range such as 192.168.1.100-120, or a path to a text/CSV file — so doctor scales from one bench unit to a room. Output is Rich (default), Markdown, or JSON.

Step 4 — Diagnose and audit: build the evidence profile

dcent diagnose — hardware reads over SSH

dcent diagnose runs read-only hardware probes over SSH — kernel, uptime, memory, NAND (/proc/mtd), mounts, miner processes, i2c devices, temps, fans, listening ports, and dmesg errors — and reports per-check pass/fail with a per-target proof scope (all-passed, diagnostics-with-failures, no-diagnostics, unreachable, or not-contacted under --dry-run). Transient readings can change between runs.

dcent diagnose <ip>             # per-check hardware pass/fail
dcent diagnose <ip> --dry-run   # plan only, no target contact

dcent audit — the read-only firmware security pass

dcent audit <ip> checks a live miner over SSH/HTTP/cgminer-API against a catalog of documented indicators — the DCENT-2026 series (hidden SSH backdoors, phone-home, unauth RCE) — read-only, no mutation. Each target gets an explicit proof scope: target_observed_clean, target_observed_findings_present, target_unreachable, or not_target_contacted under --dry-run. It can also statically inspect an extracted firmware image with no live miner contact, or turn the lens on the toolbox itself.

# Live read-only audit of one unit
dcent audit <MINER_IP>

# Plan only — no miner contact
dcent audit <MINER_IP> --dry-run

# Static audit of a firmware artifact (no live miner contact)
dcent audit firmware <path-to-image>

# Audit the toolbox's own shipping-safety posture
dcent audit self

“Clean” means no detected findings — it is not a guarantee that the miner is secure. Only the documented detection rules ran; absence of findings is not absence of issues.

The rest of the read-only surface

Whatever you run, record the toolbox version, the adapter/backend in play, the exact command, the miner and control board, the incumbent firmware, and the raw output. Never generalise one successful adapter/command combination to a whole platform family. And redact your payout address and pool credentials before sharing raw mining logs with anyone — they are in there.

Does this scale from a home rig to a large operation?

Yes — the same read-only primitives cover a handful of bench units and a full hashcenter; only the gear changes. For a few miners, neighbour-first dcent scan plus a per-unit dcent doctor is the whole loop. For a room, dcent doctor accepts a CIDR, an IP range, or a target file and triages hosts in parallel, and dcent fleet status gives a bulk live view — also neighbour-first, with an optional CIDR presence-probe fallback.

# Home bench: find, then triage one unit
dcent scan
dcent doctor <MINER_IP>

# Larger op: triage a subnet in parallel into a daily report
dcent scan --range 10.0.1.0/24
dcent doctor 10.0.1.0/24 --quick --markdown > daily-report.md
dcent fleet status --range 10.0.1.0/24

Evidence, not permission to flash

This is the load-bearing rule of the whole pass. A clean audit, a confident fingerprint, and a firmware package that parsed cleanly still do not make a miner flashable. Where the toolbox does describe a capability, it labels the confidence honestly — Production, Beta, Experimental, Recovery-only, or Detected-but-unsupported — and “detected-but-unsupported” is a real, common answer.

DCENT_OS first-install reality varies sharply by board. Only the Antminer S9 (am1-XIL) has a public network-write / SD-trial route today. Every current-generation Antminer (S17 / S19 / S19j Pro / S19k Pro / S21) stock first-install is lab-gated, evidence-gap, or no-customer-write — it is not one-click and it is not available to end users yet. BitAxe / ESP devices have real OTA/USB routes. Read the install lane through the per-board matrix, never as a blanket “any board can be flashed.”

Discovery earns you the facts. The install page is where you check whether a write path exists at all.

Where next

• Getting started — install and your first commands.
• Command reference — the full read-only and write-path surface.
• Compatibility — miners, firmwares, control boards, and what is validated.
• Installing DCENT_OS — where a write path actually exists, after your evidence pass.
• Toolbox FAQ — common questions.
• DCENT_OS docs and the web flasher — the companion firmware side.