Skip to content

FAQ.md

Latest commit

 

History

History
262 lines (196 loc) · 11.8 KB

FAQ.md

File metadata and controls

262 lines (196 loc) · 11.8 KB
Raw

DCENT_Toolbox — Frequently Asked Questions

Quick answers to the questions people ask most. For the full feature reference see CAPABILITIES.md; for the quickstart and the honest per-board install reality see README.md; for what is and isn't allowed, see ../SECURITY.md.

Getting started

What is DCENT_Toolbox?

DCENT_Toolbox is an open-source command-line tool (plus a keygen-style terminal UI) for managing, recovering, auditing, and re-flashing Bitcoin miners — entirely from your own computer. One tool scans your LAN, identifies each miner's vendor and firmware, reads its status, and — on hardware you own — can unlock locked units, audit firmware for hidden backdoors, build and write SD cards, install alternative firmware, and prove that a miner is actually hashing afterward. It is built by D-Central Technologies and released under the GPL-3.0.

How do I install it?

cd DCENT_Toolbox
pip install -e .

Until the full public source export, PyPI package, and prebuilt binaries are published, install from a complete source checkout/export. The core install includes SSH support. There's nothing else to register or license.

Does it need Python?

For the current source install, yes — Python 3.9 or newer. Prebuilt single-file executables are a release artifact, not a live install path yet.

Does it run on Windows, macOS, and Linux?

Yes, all three. DCENT_Toolbox is local-first and cross-platform. On Windows, SSH to miners (including miners that require legacy SSH crypto) works out of the box because the SSH library is part of the core install.

What's the first command I should run?

Point it at any miner and run:

dcent doctor 192.168.1.50

dcent doctor is the canonical first step for everyone. It is read-only and never destructive — it triages the unit in a few seconds, tells you the firmware, board family, and health, and suggests what to do next. To discover every miner on your network first:

dcent scan --range 192.168.1.0/24

Then explore the help topics with dcent help getting-started or open the terminal dashboard with dcent tui.

Cost, trust & licensing

Is there a dev fee?

No — 0%. DCENT_Toolbox never inserts a developer fee, never adds a pool-fee skim, and never redirects any portion of your hashrate. In fact, one of its features detects and removes a hidden dev-fee redirect found in certain closed-source third-party firmware (see the firmware-audit section below).

Does it phone home or need a cloud account?

No. There is no cloud tether, no remote account, no license server, and no telemetry. The tool runs 100% locally on your machine and talks only to the miners you point it at on your own network. When it needs to pull public Bitcoin network stats for the dashboard, that's an optional feed you can turn off.

Is it really open source?

Yes. DCENT_Toolbox is licensed GPL-3.0-only. The full source is public so anyone — owners and security researchers alike — can audit exactly what the tool does. See ../CONTRIBUTING.md if you'd like to help.

Capability

Which miners and vendors does it support?

Four vendor ecosystems, through four real backends:

  • Bitmain / Antminer — full read surface plus route-scoped write paths where the board/firmware/proof gates support them.
  • MicroBT WhatsMiner — including the authenticated write-API, which enables WhatsMiner OTA.
  • Canaan / Avalon — cgminer JSON-RPC plus privileged ascset writes.
  • BitAxe — the full AxeOS surface, including USB flashing and OTA.

Unknown gear is routed to a read-only generic cgminer backend, never a silent write path — so an unrecognized miner is never accidentally treated as a Bitmain unit. See PLATFORMS.md for the full matrix.

Which firmwares can it detect and drive?

Six firmware ecosystems are detected and driven with one CLI: Bitmain stock, BraiinsOS+, LuxOS, VNish, DCENT_OS, and DCENT_OS for ESP / DCENT_axe. It understands seven hardware/control-board families including ESP32-S3, so it can tell, for example, a Zynq-based S9 from an Amlogic-based S19j Pro or a Bitaxe Gamma and plan accordingly.

Can it unlock a locked Antminer?

On hardware you own — for many boards, yes; for some, no, and the tool is honest about which is which. Locked stock Antminers ship with SSH disabled and signed firmware, and getting a root foothold hits a hardware wall that varies by board generation. Both Zynq generations are software-unlockable, BeagleBone-based boards have a wired privilege-escalation path, and one Amlogic window has an assisted USB-OTG downgrade. The newest Amlogic boards and the eFuse-locked CVitek boards have no software path at all — those need a physical reflash or a board swap. The per-board reality table in README.md and PLATFORMS.md shows exactly where each path holds.

Can it install alternative firmware?

Yes, but only through route-backed lanes. dcent install drives DCENT_OS planning and install where a supported route exists; dcent install --auto-unlock can run the board-appropriate unlock step before planning the install. S9 has a route-backed install rail but remains public-artifact/live-capstone gated. AM2 S19 Pro/S19j Pro DCENT_OS-source self-updates are lab-gated, while vendor-source first install is an explicit evidence gap until its authenticated runtime/migration capsule exists. Other S17/plain S19/BB/Amlogic/CVitek lanes remain evidence-gated, physical-rail gated, or blocked according to dcent support --flash-readiness. Every write path is dry-run by default, requires explicit confirmation, and reports its progress honestly (see the proof-ladder answer below). Read the install lane through the per-board matrix; it is route-specific, not a blanket "any board."

Does it work on WhatsMiner, Avalon, and BitAxe?

Yes. WhatsMiner is driven through its authenticated write-API (which unlocks OTA), Avalon through cgminer plus ascset, and Bitaxe-class ESP32-S3 miners through AxeOS/DCENT_axe-compatible settings, tuning, statistics, USB flashing, and OTA. Reading status works across all of them; the available write actions depend on the vendor and route.

Which Bitaxe-class miners can install DCENT_OS for ESP?

DCENT_Toolbox exposes exact OTA/USB route rows for Bitaxe Max (bitaxe-max), Ultra (bitaxe-ultra), Supra (bitaxe-supra), Gamma (bitaxe-gamma), Hex Ultra (bitaxe-hex-ultra), and Hex Supra (bitaxe-hex-supra). Running devices use HTTP OTA update packages; first flash uses USB serial factory packages. Both routes require the companion signed manifest and DCENT_OTA_PUBLIC_KEY_HEX. Upload acceptance is not boot, rollback, thermal, or mining proof.

Safety & legality

Is it legal to use?

DCENT_Toolbox is for authorized use only — hardware you own or are explicitly authorized in writing to administer. Using its unlock/enabler, credential, or flashing features against miners you don't control is illegal in most jurisdictions. The techniques it implements are based on publicly documented research, published CVEs, and independently reverse-engineered protocols, and publishing them lets owners audit and repair their own equipment. Read ../SECURITY.md before you use the unlock or flash features — by using the tool you accept its responsible-use terms.

Will it brick my miner?

The tool is designed so it's hard to. dcent doctor and most recon commands are strictly read-only. Every destructive action is gated behind an explicit confirmation (a --yes flag, or a typed confirmation in the UI) and is dry-run by default — and the safety gates fail closed, meaning if the tool can't verify a unit is safe to write, it refuses rather than proceeding. There are also baked-in protections: a voltage clamp and a home-use fan cap, EEPROM write protection, atomic NAND environment writes (never raw block writes to fragile flash), and a rule that cuts hash power rather than blasting fans on a fault. No tool can make a guarantee, but bricking a unit that had a safe path available is exactly the kind of bug we treat as a security issue.

What do "operator-gated" and "proof-ladder" mean?

These are two parts of the tool's honesty model:

  • Operator-gated means a feature is built and tested, but the live, real-world write or execute step deliberately stops and waits for you to authorize it on real hardware. The tool plans and constructs the exact commands, but it won't touch a live miner on its own.
  • Proof-ladder means the tool reports exactly what it actually proved — no more. Uploading firmware is not the same claim as "flashed," and "flashed" is not the same claim as "verified mining." Each command tells you which rung it reached, so a timeout is reported as unknown, never as success. When dcent verify-mining says a unit is hashing, it's because it watched real shares — not because an upload returned HTTP 200.

Where do I share logs safely?

Use dcent diag bundle --redact <ip>. Raw mining logs contain your full Bitcoin payout address and pool credentials — treat those like a credit-card number. The redacted bundle masks wallets, credentials, public IPs, and MAC addresses automatically, so it's safe to attach to a bug report.

The firmware audit

Can it find or remove hidden backdoors or dev-fee redirection in closed-source firmware?

Yes — on hardware you own. DCENT_Toolbox can audit certain closed-source, third-party miner firmware for hidden SSH backdoors, phone-home telemetry, remote-access vulnerabilities, and silent dev-fee redirection, and remove them from your own miner. dcent audit reports what it finds against a catalog of known indicators; dcent clean removes a known backdoor SSH key, kills the phone-home process, clears the device blacklist, and blocks the embedded dev-fee redirect on affected images.

These are defensive capabilities — they help an owner understand and clean firmware running on their own hardware. The tool describes what it detects and removes; it does not publish abuse walk-throughs against any named vendor.

Troubleshooting & support

SSH isn't working on Windows — what do I do?

It should just work: the SSH library (paramiko) is part of the core install, not an optional extra, and the tool also falls back to native SSH helpers for miners that need legacy crypto. If you still hit trouble, run dcent doctor 192.168.1.50 for a read-only diagnosis, confirm the miner is reachable on your LAN, and check that you're using the right credentials for that firmware. Note that on first contact the tool pins the miner's SSH host key; if a unit was deliberately reimaged and its key changed, you'll need to remove that miner's saved entry and reconnect.

A command says it "can't" do something on my board. Is that a bug?

Usually not — it's the tool being honest. Some boards are hardware-fused with no software path, and some write paths are route-specific. Run dcent support --flash-readiness and dcent install --list-routes to see what's actually available for your unit, and check the per-board matrix in PLATFORMS.md. A command existing is not the same as a proven route for your specific hardware.

How do I get help or report a bug?