Files
alkane-toolkit/README.md
T
noahandClaude Opus 4.8 c1aa6db834 license: unify under MIT
Collapse the dual MIT OR Apache-2.0 licensing to MIT only (operator's choice):
set the workspace `license` field to "MIT" (all crates inherit it), replace
LICENSE-MIT + LICENSE-APACHE with a single LICENSE file, and update the README
license section and the license badge. deny.toml keeps its permissive allow-list
(that governs dependency licenses, which remain a mix of MIT/Apache-2.0/BSD/etc.);
only its project-license comment changed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Djv3oncM4LxTS5tb61Ako6
2026-09-23 08:05:11 -06:00

4.7 KiB

alkane-toolkit

CI tests coverage bench lines of code clippy dependencies license

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, and installs stock or alkaneOS firmware onto a control board whatever it currently runs (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 mirrors these: verify.yml runs the lint, tests, benchmarks, self-test, and a best-effort dependency audit on every pull request and branch push; release.yml repeats them on main and cuts an X.Y.Z release with the built binary attached when the change warrants it. 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.