alkane-toolkit

CI tests coverage bench bench coverage lines of code code quality dependencies license

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 the miner_probe CLI (the other crates/alkane-* are early scaffolding).
  • vendor/asic-rs -- the miner-discovery and control library, vendored and extended through numbered patches under thirdparty/asic-rs/patches.
  • thirdparty/wx-rs -- the patched wxWidgets bridge (see docs/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:

  1. Never write the bootloader or secure region.
  2. Verify on a channel the installer does not control.
  3. Reboot is root-only; a dropped SSH connection can still be success.
  4. A packer is per board; never reuse one across boards.
  5. Boot-switch handling is an explicit, verified step.

License

Licensed under the MIT license.

S
Description
Rust + wxWidgets cross-platform toolkit: install stock or alkaneOS on any ASIC miner
Readme MIT
92 MiB
v0.115.0
Latest
2026-11-17 00:03:11 -07:00
Languages
Rust 87.8%
Python 8.5%
Shell 3.5%
Dockerfile 0.2%