Install DCENT_OS With DCENT_Toolbox

DCENT_Toolbox is the local, open-source install companion for DCENT_OS — a GPL-3.0 command-line tool and keygen-style TUI that discovers your miner, identifies the exact control board, plans the install route, and (where a route is proven) writes D-Central's open-source mining firmware from your own machine. The honest boundary, stated up front: today only the Antminer S9 (am1-XIL) has a public network-write / SD-trial route. Every current-generation Antminer — S17 / S19 / S19j Pro / S19k Pro / S21 — stock first-install is lab-gated, evidence-gap, or no-customer-write. BitAxe / ESP devices have real OTA/USB routes.

How does DCENT_Toolbox fit with DCENT_OS?

DCENT_OS is the open-source mining firmware. DCENT_Toolbox is the operator-first, local-only bench that gets it onto — or off — your hardware safely. The Toolbox never writes blind: every mutating step must resolve to an exact model + control board + incumbent firmware + evidence level + recovery route before it will touch a miner. "Detected" is not "safe to configure." "The command exists" is not "the operation is validated on your miner." "The package parsed" is not "the package is safe to install."

DCENT_Toolbox is version 2.5.0: 491 Python modules, 87 CLI command modules (roughly 75 user-facing top-level commands), and a 4,500+ offline test suite passing. It runs on Windows, macOS, and Linux. 0% dev fee, no cloud, no license server, no telemetry, GPL-3.0 — built by the Mining Hackers at D-Central Technologies (Québec), doing Bitcoin mining technology since 2016. It is the bench D-Central uses, released so you can own, repair, and understand your own hardware.

The North Star flow: Get the source → Launch → Discover → Identify → Prepare → Install → Verify → Mine

That is the goal state — one path an operator can follow without knowing SSH, control-board families, or which signed artifact matches which SoC. Read it as the map, then read the model gating below, because the flow only completes end to end where the route is actually proven.

1. Get the source / Launch — clone the repository and get the Toolbox running.
2. Discover — a neighbour-first LAN pass finds responders.
3. Identify — resolve exact model + control board; a model name alone never silently picks a board.
4. Prepare — plan-only: the rail is ranked and the recommended archive is built in-process with a reported SHA-256, but nothing is uploaded and dcent unlock is not executed against a miner.
5. Install — dcent install is dry-run/plan by default; the live write step executes only on an explicit operator confirmation (--yes).
6. Verify → Mine — verify-mining classifies a real cold-boot mining proof, never a blanket "install-ready."

The last two rungs — Install and Verify — resolve differently for every board, because locked stock hardware presents a generational wall: post-July-2019 Antminers ship with SSH disabled and RSA-signed firmware whose signing chain cannot be forged. Each board generation either has a software foothold or it needs a physical rail (SD card, USB-OTG, console).

Step 1 — Get the source and launch the Toolbox (source checkout, Python 3.9+)

There is no package-index release and no published binary or installer download for DCENT_Toolbox. Do not go looking for a one-click installer or a Windows/macOS/Linux download link — they do not exist. Launch requires Python 3.9+ and a source checkout of the public GPL-3.0 repository:

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

The interactive flagship is the keygen-style TUI, dcent tui, installed from the same local checkout with the [tui] extra (textual + numpy). The Tauri desktop GUI is a scaffold that does not yet install anything — it is not an install surface. Use the TUI or the CLI.

python -m pip install -e ".[tui]"
dcent tui

Step 2 — Run the first command: dcent doctor

Point it at a miner and run dcent doctor <ip>. This is the canonical first step for every user: read-only, never destructive. It reports firmware, board family and health, and tells you what to do next.

dcent doctor <ip>

Discovery is neighbour-first — a fresh ARP/UDP pass over your LAN, then identification of the responders. A MAC prefix or a model string is a lead, not an identity.

dcent scan --range 192.168.1.0/24

Step 3 — Identify: the gate for everything downstream

Identity decides whether any write is even offered. A model name never silently selects a control board when more than one family fits — broad Zynq results additionally require an independently observed board family (am1 or am2) before a route is considered resolved. Start with dcent doctor / dcent fingerprint; when a fingerprint capsule needs replaying into the router, controlboard-route reads it back with --fingerprint-json.

dcent fingerprint <MINER_IP> --json > fingerprint.json
dcent controlboard-route --fingerprint-json fingerprint.json --json

What the Toolbox drives underneath

• 4 real vendor backends: Bitmain (stock / BraiinsOS+ / LuxOS / VNish / DCENT_OS), MicroBT WhatsMiner, Canaan/Avalon (cgminer + ascset), and BitAxe (AxeOS). Unknown gear routes to a read-only generic cgminer backend — never a silent Bitmain mis-route. An optional Rust device-abstraction extra (dcent scan --use-asic-rs) can widen the READ-ONLY device matrix beyond the four native backends.
• 6 firmware ecosystems detected and driven: Bitmain stock, BraiinsOS+, LuxOS, VNish, DCENT_OS (Antminer), and DCENT_OS/ESP (DCENT_axe).
• 7 control-board families: am1-XIL, am2-XIL, am3-BB, am3-AML, cv1835, bcb100, esp32-s3.

Confidence labels you will see throughout: Production, Beta, Experimental, Recovery-only, and Detected-but-unsupported.

Step 4 — Can I install DCENT_OS on any Antminer? The honest per-model gate

No. This is the part that matters most, so read your unit's row before assuming a write path exists. The Toolbox keeps unlock, route, artifact, and proof state separate, and tells you plainly where each rung holds. The taxonomy: Public-gated route (route-backed, public artifact plus a witnessed live capstone still required) · Lab route (requires exact backup/recovery/proof gates) · No customer write route (named, intentionally no write path) · Hardware/manual route (physical media or console) · Hardware-limited (hardware-fused; board swap or external flash).

Read this literally: "install DCENT_OS on any Antminer, software-only" is not true, and no S19 or S21 owner can one-click-install DCENT_OS today. dcent install is dry-run/plan by default; the live write step executes only on an explicit operator confirmation (--yes), on hardware you own.

The honest S9 path (high level)

For an evidenced legacy S9 on stock that you own, the shape of the flow is: fingerprint the board, let the Toolbox run the board-appropriate SSH-enable, plan the route against the hash-pinned S9 artifact as a dry run, inspect every persistent write, then execute only on your explicit go-ahead. Be precise about what that SSH-enable is: an authenticated CGI command injection using the web-admin password you already hold — not an authentication bypass — and it is never inferred from a model name alone.

dcent doctor <S9_IP>
dcent install <S9_IP> --dry-run --json

The S9 rail is public-gated, not production-released: a public artifact plus a witnessed live capstone are still required before D-Central will call it production. Treat it as public beta. This page is the wiring, not the step-by-step — for the actual procedure, hand off to the DCENT_OS docs:

• DCENT_OS: first run — powering up and confirming the install.
• DCENT_OS: S9 SD-card trial — the non-destructive SD route to try DCENT_OS on an S9 before committing.
• DCENT_OS docs hub — the full firmware documentation silo.

Step 5 — Verify: "the command ran" is never "it is mining"

The Toolbox reports exactly what it proved, and no more. Every action carries a proof-ladder state: an upload is accepted, not flashed; a reachable device is online, not mining. Prove the outcome against a real cold boot:

dcent verify-mining <MINER_IP>

verify-mining runs a cold-boot proof ladder and classifies the result PROVEN / PARTIAL / FAILED / UNVERIFIABLE. It cannot certify an ambiguous identity or a stock first-install evidence gap. D-Central's own five-platform native-mining proof (am1-s9, am2-s19pro, am3-aml S21, am3-bb S19j Pro, am2-XIL S19j Pro) is live-validated on the lab bench — that is D-Central's internal proof, not a customer-available install route for those current-gen boards.

Bitaxe / ESP: the one lane with real OTA and USB today

Unlike the Antminer lanes, DCENT_OS for ESP on Bitaxe-class hardware has genuine customer install routes: a running AxeOS / DCENT_axe device updates over HTTP OTA, and a first flash uses USB serial. Model-specific route rows are published for Bitaxe Max, Ultra, Supra, Gamma, Hex Ultra, and Hex Supra, so package names and the manifest boardTarget stay model-specific.

# Running device: install autoroutes to OTA
dcent install 192.168.1.42 -f <dcentaxe-update.bin> --dry-run

# First flash over USB serial
dcent flash --list-ports

Do not hard-code that build name: pin the exact build name from the repository release notes — the placeholder above is not a real published filename. The manifest validates boardTarget, deviceModel, payload SHA-256, the factory flash map, and slot fit before any upload or image write. Upload acceptance is still not boot proof, thermal proof, or mining proof.

If you would rather not touch a terminal for an ESP device, the browser route is the D-Central web flasher.

How do I revert to stock?

The per-vendor revert lane covers all four incumbent firmwares — BraiinsOS recovery-mode NAND rewrite, VNish dashd firmware/remove, and DCENT_OS / LuxOS uninstall.sh. Be precise about status: the DCENT_OS and LuxOS uninstall.sh path is the proven revert lane (Yes — uninstall.sh), while the BraiinsOS and VNish paths are code-complete, operator-gated — live proof pending. "Remove accepted" is not "stock observed."

dcent install --revert-to-stock <MINER_IP> --dry-run

For the DCENT_OS-side procedure, see the DCENT_OS uninstall guide.

What you cannot do yet — read this before you plan a fleet

• You cannot one-click-install DCENT_OS on an S17, S19, S19 Pro, S19j Pro, S19k Pro, or S21 from stock as an end user. Those lanes are lab-gated, evidence-gap, or no-customer-write.
• You cannot install the Toolbox from a package index, and there is no signed installer to download — launch requires Python 3.9+ and a source checkout.
• The desktop GUI does not install anything; use the TUI or the CLI.
• Stratum V2 support (dcent stratum v2-client / v2-proxy) is experimental, clean-room, plaintext / test-pool only — a host-side proxy/tap, not a miner-side firmware protocol upgrade. It runs without an encrypted Noise handshake and refuses a non-localhost upstream unless you pass an explicit lab opt-in.
• Amlogic Sept-2025-and-later stock and CVitek's signed FIP have no software path at all — physical rail or board swap only.

Evidence before every mutation

1. Identify the exact unit and control board — a model name alone is never enough.
2. Capture the incumbent firmware and version, plus hardware health.
3. Run a dry run and inspect every persistent write it plans.
4. Back up and prove the recovery route (NAND backup where it applies).
5. Open the exact firmware/model release record before authorizing a write.
6. Stop if the route is lab-gated, unproven, or absent for your board.

Where next

• Getting started — set up the source checkout and run your first commands
• Discovery — how neighbour-first scanning and identity gating work
• Compatibility — vendor backends, firmware ecosystems, and control-board families
• Commands — the ~75-command top-level reference
• Toolbox FAQ — scope and safety questions
• DCENT_OS docs hub · First run · S9 SD trial · Uninstall · DCENT_OS FAQ
• Web flasher for Bitaxe / ESP devices · Fund the sovereign stack