Files
alkane-toolkit/docs/windows.md
noahandClaude Opus 5.5 8275f893dd
source / check (pull_request) Skipped
verify / verify (pull_request) Successful in 7m55s
verify / verify-windows (pull_request) Successful in 5m8s
SSH login in the Credentials dialog; default range 192.168.1.1/24; legal publisher name
- Credentials dialog: new "SSH (restore)" row for the control-board SSH
  login used by the Braiins restore-to-stock. The username defaults to
  root; the password is masked and never re-displayed, and a blank
  password keeps the saved one. Reset to defaults also clears it.
  ssh-credentials.txt no longer has to be written by hand.
- Default scan range is now 192.168.1.1/24 (scans 192.168.1.0/24), and
  the range dialog's examples use that subnet.
- Windows version info, zip README, LICENSE and docs name the publisher
  as on the signing certificate: BlueFlare Energy Solutions Inc.
- Manual updated for all three.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 13:08:21 -06:00

5.7 KiB

Windows

The toolkit ships a Windows build alongside the Linux one in every release: alkane-toolkit-vX.Y.Z-windows-x86_64.zip, holding one self-contained alkane-toolkit.exe for Windows 10 and 11 (x86_64). There is no installer and no runtime to install. Design decisions are in ADR 0004.

Using it

  • Settings live in %APPDATA%\alkane-toolkit (Linux: ~/.config/alkane-toolkit), same file names and formats.
  • SSH actions use the OpenSSH client built into Windows (ssh.exe); HTTP actions use the built-in curl.exe. Both start without a console window.
  • The window follows the Windows light/dark app setting. Set ALKANE_APPEARANCE=light or dark to force one (any platform).
  • Headless modes (ALKANE_SELFTEST, ALKANE_ACCESS_PROBE, ALKANE_LOG_SCAN) print to the console they are started from.
  • Offline demo: set ALKANE_FAKE_SCAN=1 && alkane-toolkit.exe.

Building

The Windows build is cross-compiled on Linux with mingw-w64 (posix-threads variant), exactly as CI does it:

sudo apt install g++-mingw-w64-x86-64-posix wine xvfb   # once
scripts/build-wx-windows.sh       # once: static wxMSW 3.3.3 in ~/.cache/wx-3.3.3-mingw
scripts/build-gui-windows.sh      # release alkane-toolkit.exe

scripts/windows-cross-env.sh holds the toolchain environment (compilers, linker, WX_RS_WXCONFIG, the Wine test runner). Source it to run cargo by hand:

. scripts/windows-cross-env.sh
cargo test --offline --target "$ALKANE_WIN_TARGET" --workspace --exclude wx-rs   # runs under Wine
scripts/ui-selftest-windows.sh    # headless UI self-test of the .exe under Wine

alkane-toolkit.exe must import only Windows system DLLs; ci/windows-ci.sh build fails the build if a mingw runtime DLL slips in.

CI

ci/windows-ci.sh is the one definition of every Windows step; the workflows only call it.

Workflow Windows job Gate
verify.yml (PRs to main) verify-windows: clippy, release build, unit tests and UI self-test under Wine required
release.yml (main) windows: the same, then packages the zip; release waits for it and attaches it required
next.yml (next) windows: build and package the -rc zip required
windows-native.yml runs main's cross-built unit tests and UI self-test on real Windows 11 advisory

The CI image (ci/images/alkane-ci.Dockerfile, digest pinned in ci/runner-image.txt) adds mingw-w64, Wine with a ready prefix, the rustup target and a prebuilt wxMSW prefix to the Linux image. Rebuild it with ci/images/build-image.sh TAG from the workstation that holds the registry credential; the script pins the new digest everywhere.

Code signing

Release and -rc executables are Authenticode-signed with Azure Artifact Signing (formerly Trusted Signing), so Windows and SmartScreen show "BlueFlare Energy Solutions Inc." as the verified publisher instead of "Unknown publisher".

Piece Where
Signing account blueflaresigning (Basic), resource group rg-blueflare-signing, West US 2, endpoint https://wus2.codesigning.azure.net
CI identity service principal alkane-toolkit-ci-signer, role "Artifact Signing Certificate Profile Signer" on the certificate profile only; Gitea secrets AZURE_SIGNING_TENANT_ID, AZURE_SIGNING_CLIENT_ID, AZURE_SIGNING_CLIENT_SECRET (secret expires 2027-11-03)
Switch Gitea repository variable AZURE_SIGNING_PROFILE (certificate profile name); unset = builds stay unsigned
Signer ci/sign-windows.sh (jsign from the CI image, RFC 3161 timestamp from timestamp.acs.microsoft.com)
Check windows-native.yml requires Get-AuthenticodeSignature = Valid on real Windows once signing is on

Signing is on since 2026-11-03 (identity validation approved, certificate profile alkane-toolkit, PublicTrust). The zip's README.txt states whether its executable is signed. To set it up again, e.g. for a new profile, after an identity validation is approved (portal: signing account > Identity validations):

scripts/enable-windows-signing.sh <identity-validation-id>

It creates the PublicTrust certificate profile, narrows the CI identity to it, and sets AZURE_SIGNING_PROFILE. From then on a signing failure fails the release. Rotate the CI secret before it expires with az ad sp credential reset --id <appId> --years 1 and update the Gitea secret.

Sign by hand (any machine with Java, az login and the Signer role):

AZURE_SIGNING_PROFILE=alkane-toolkit ALKANE_JSIGN_JAR=jsign.jar \
AZURE_SIGNING_TOKEN=$(az account get-access-token --resource https://codesigning.azure.net --query accessToken -o tsv) \
  ci/sign-windows.sh alkane-toolkit.exe

Native Windows runner

windows-native.yml runs on the self-hosted runner win11-test-vm (label alkane-windows, host mode) inside a Windows 11 test VM. It downloads the alkane-toolkit-windows-tests artifact of the triggering main run, runs every test executable and the UI self-test natively, and never blocks a release: while the VM is off, the job waits for the runner.

In the VM, gitea-runner v3.5.0 lives in C:\gitea-runner and starts at boot as the scheduled task gitea-runner, running as LOCAL SERVICE (log: C:\gitea-runner\runner.log).

Differences from Linux worth knowing

  • wxMSW's wxDataViewCtrl is wx's generic implementation (GTK uses the native GtkTreeView), so drag-select and per-cell tooltips are implemented in the bridge for it.
  • Selected rows use the Windows 10/11 list-view highlight: a light tint under normal text, not a solid colour with white text.
  • The app is per-monitor DPI aware: the bridge converts every size it gets from Rust from DIPs to physical pixels for the window it applies to.