alkane-toolkit
The CI badge shows the last completed attempt for this branch while newer runs are queued. Badge SVGs are stored in a private, machine-maintained branch.
A cross-platform desktop toolkit for discovering, monitoring, and re-flashing ASIC miners. It scans a fleet over the network, shows live health and hashrate in a sortable table. The install path is under development for stock and alkaneOS firmware on boards running stock, VNish/AnthillOS, Braiins OS+, LuxOS, ePIC, HiveOn, BixBit, WardenOS).
The core and UI are pure Rust; the native window is wxWidgets driven through a vendored, patched wx-rs bridge, so there is no Electron, no web view, and a single self-contained binary per platform.
What it does
- Discover a fleet by CIDR or IP range and identify each miner's make, model, control board, and firmware (via a vendored asic-rs).
- Monitor hashrate vs. expected, per-board health, chip temperatures, fans, PSU state, and pool workers, with an Excel-style filter and drag-reorderable columns.
- Operate miners from a right-click menu: flash the locate light, pause / resume, restart, set a power or hashrate target, select a firmware profile (LuxOS/VNish presets), configure pools, set the timezone, and change the password -- each action offered only when every selected miner supports it.
- Install firmware: push stock or aftermarket images, or revert an aftermarket miner to stock, behind a typed confirmation.
Discovery and telemetry are read-only and safe to run against any fleet; every mutating action is capability-gated and, where destructive, confirmed.
Build and run (Debian/Ubuntu)
scripts/build-wx-linux.sh # once: builds the vendored wxWidgets 3.3.3 into ~/.cache
scripts/build-gui-linux.sh # cargo build --release -p alkane-gui
~/.cache/alkane-tk-target/release/alkane-toolkit
Runtime needs GTK 3: sudo apt install libgtk-3-0. To explore the UI with no
hardware, run the offline demo fleet:
ALKANE_FAKE_SCAN=1 alkane-toolkit
Windows and macOS share all GUI code; only the C++ bridge and wx build differ
(scripts/build-gui-windows.sh needs an msys2 toolchain, -macos.sh needs a
Mac).
Command-line probe
miner_probe is a headless companion for hardware checks that should not go
through the window event loop -- discovery, telemetry, and each write action:
miner_probe scan 10.0.0.0/24 # discover + telemetry (TSV)
miner_probe presets 10.0.0.5 # list a firmware's selectable profiles
miner_probe setpreset 10.0.0.5 540MHz
Run miner_probe with no arguments for the full verb list.
Development
export WX_RS_WXCONFIG="$HOME/.cache/wx-3.3.3-linux/bin/wx-config"
export CARGO_TARGET_DIR="$HOME/.cache/alkane-tk-target" # keep the target tree off the source share
cargo test -p alkane-gui # unit tests
cargo test -p alkane-gui --release -- --ignored bench_ # microbenchmarks
cargo clippy -p alkane-gui --no-deps --bins -- -D warnings # lint gate
xvfb-run -a env ALKANE_SELFTEST=1 \
"$CARGO_TARGET_DIR/release/alkane-toolkit" # headless UI self-test
ci/coverage.sh --summary-only # coverage (tests + self-test)
CI mirrors these: verify.yml runs lint, tests, benchmarks, the self-test, and
a dependency audit on development branches. release.yml runs the full gate
on every main push and cuts an X.Y.Z release when the change warrants it.
next.yml builds release candidates with little testing and publishes -rc
releases. Dependencies are vendored under vendor/, so builds never touch the
network.
Architecture
crates/alkane-gui-- the application: scan engine, data model, wxWidgets UI, and theminer_probeCLI (the othercrates/alkane-*are early scaffolding).vendor/asic-rs-- the miner-discovery and control library, vendored and extended through numbered patches underthirdparty/asic-rs/patches.thirdparty/wx-rs-- the patched wxWidgets bridge (seedocs/adr/0002,0003).
See docs/IMPLEMENTATION-PLAN.md for the roadmap
and docs/aftermarket-parity-roadmap.md
for the firmware config/scan parity work.
Firmware safety rules
Encoded in code, from alkane-sdk docs/install-methods.md:
- Never write the bootloader or secure region.
- Verify on a channel the installer does not control.
- Reboot is root-only; a dropped SSH connection can still be success.
- A packer is per board; never reuse one across boards.
- Boot-switch handling is an explicit, verified step.
License
Licensed under the MIT license.