Files
alkane-toolkit/docs/install.md
T
noahandClaude Opus 4.8 7cd26aff56
source / check (pull_request) Skipped
verify / verify (pull_request) Failing after 5m53s
verify / verify-windows (pull_request) Skipped
fix(gui): address code-review findings on the install/scan changes
- #1 Update must not rewrite the bootloader: start_install refuses a tier-3
  (bootloader-writing) .afw when the dialog is an in-place Update, enforcing the
  "BOOT.bin is never written" guarantee.
- #2 post-install verify could stick forever when auto-scan is off: tick() now
  re-probes awaiting boards on a fixed 10 s cadence until they answer as alkane
  or the give-up window expires.
- #3 board-health no longer greys a genuinely-mining miner whose backend omits
  per-board active/working_chips: (None,None) reads green when the miner is
  hashing, grey only when idle (the bare S17 case).
- #5 install docs/comments no longer describe the removed typed-FLASH step.
- #6 the flash-plan checklist verifies against the install target board, so a
  file for another board surfaces as an error instead of a misleading plan.
- #7 install board is taken from the selected row's board_family, not a fixed
  default (correct once more boards are supported).
- #4 (verify on the UI thread) accepted: .afw bundles are ~7 MB, so the manifest
  read is a sub-100 ms hash, not a user-visible freeze.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-13 11:22:00 -06:00

7.7 KiB

Installing and removing alkane-os

Two front-ends drive the same self-contained engine:

  • The CLI (alkane-cli afw ...), documented below, is the scriptable path.
  • The GUI (alkane-toolkit) can scan the fleet, then right-click a board to install alkane-os onto it from stock or restore it to stock. See "GUI (right-click install / uninstall)" at the end. (The GUI's older asic-rs firmware-upload path stays disabled; these two actions use the compiled-in network-only engine, the same one the CLI uses.)

Compatible miners

alkane-cli afw compat

Lists the control boards alkane-os can be installed on. For now that is the Antminer S17 (zynq-7010). The install/restore commands refuse any board whose .afw is not one of these.

Install

From a local bundle:

alkane-cli afw install path/to/alkane-os-<ver>-zynq-7010-armv7.afw \
    --host <miner-ip> --confirm FLASH

From the latest release (pulled from Gitea, not GitHub, which is retired):

alkane-cli afw install --latest --board zynq-7010 --host <miner-ip> --confirm FLASH
# or fetch only:
alkane-cli afw fetch-latest --board zynq-7010 --output ./downloads

A private release repo needs a token, read from ALKANE_RELEASE_TOKEN (else GITEA_TOKEN) at run time and passed to curl through a 0600 config file - never on the command line, never stored by the toolkit.

A board still on stock

Writing our first image onto a board that is still on genuine stock (past the stock gates and getting root) is done by the toolkit itself, over the network. The method is part of this binary; nothing else needs to be installed on your machine. On first use it fetches a small set of per-board assets from our Gitea (repo blueflare/alkane-stock-assets, release zynq-7010-v1) and caches them locally, verifying each against a known SHA-256. That repo is public, so no token is needed for the stock assets. The asset base URL can be overridden with ALKANE_STOCK_ASSETS_BASE.

Add --from-stock (the token below is only to resolve --latest from the private alkane-os release repo; a local .afw needs no token):

export ALKANE_RELEASE_TOKEN=<your-gitea-token>
alkane-cli afw install --latest --board zynq-7010 --host <miner-ip> \
      --from-stock --confirm FLASH

The toolkit acquires and verifies the .afw, gates on compatibility, fetches and verifies its assets, performs the network-only stock-side install, then you verify the board came up as alkane:

alkane-cli afw verify-live --host <miner-ip> --timeout 300

On Zynq (S17/S19 class) pass the .afw (or --board zynq-7010) and the board's alkane root credential; the check needs the web page to carry the image marker and SSH to report alkane with the installed kernel, and prints the running kernel command line (on a NAND boot it is the board's U-Boot env bootargs):

alkane-cli afw verify-live path/to/alkane-os-<ver>-zynq-7010-armv7.afw \
    --host <miner-ip> --password-file <alkane-root-pw> --timeout 300

For a bench image that is not signed, add --allow-unsigned.

Without --from-stock, install performs a tier-2 update of a board already on alkane, in place, over the network:

alkane-cli afw install path/to/alkane-os-<ver>-zynq-7010-armv7.afw \
    --host <miner-ip> --password-file <alkane-root-pw> --dry-run
alkane-cli afw install path/to/alkane-os-<ver>-zynq-7010-armv7.afw \
    --host <miner-ip> --password-file <alkane-root-pw> --confirm FLASH

On Zynq (S17/S19 class) the update refuses a board that is not running alkane. Alkane does not expose the NAND boot regions to Linux (only the small stock-cfg and alkane-cfg partitions), so the toolkit re-registers them first, the same way a restore does. It saves each boot slot to --backup-dir (default: the toolkit's backups directory) before any erase, then writes the rootfs (absolute NAND 0x2800000), dtb (0x1a00000) and kernel (0x2000000), with the kernel and rootfs wrapped as the legacy uImages the board's stock U-Boot boots, and reads each back (md5) before rebooting. Nothing below 0x1a00000 (BOOT.bin: FSBL, FPGA bitstream, U-Boot) is ever written. afw preflight runs the same checks read-only. --no-reboot skips the reboot.

Remove (back to stock)

alkane-cli afw restore-stock --host <miner-ip> \
      --stock-firmware <genuine-Bitmain-firmware> \
      --password-file <alkane-root-pw> --confirm FLASH

Returning an aftermarket board to genuine stock is done by the toolkit itself, over the network. It writes the genuine Bitmain stock kernel and rootfs - parsed from a vendor firmware file you supply with --stock-firmware (an OTA update .tar.gz or an SD recovery .zip for the board) - back to NAND, preserving BOOT.bin.

The one piece that is NOT in Bitmain's distributable firmware is the kernel device tree: it is factory-provisioned and preserved by every vendor update, so no OTA/SD package ships it. The toolkit supplies the correct per-board dtb itself (fetched + verified from the public assets repo, so no token is needed) and pairs it with the genuine kernel/rootfs. The board's alkane root credential is given with --password-file (or ALKANE_BOARD_PASSWORD/ALKANE_BOARD_PASSWORD_FILE).

After a restore the board returns to stock under its stock MAC and typically takes a new DHCP lease, so it may not reappear on the same address; verify independently that the board no longer answers as alkane and presents its stock OS.

GUI (right-click install / uninstall)

The GUI binary is alkane-toolkit. Launch it, let the scan list the fleet, then right-click one or more boards. The scan finds boards running Alkane OS too (Firmware column "Alkane"): they expose no cgminer socket or vendor web UI, so the toolkit identifies them itself from the board's public read-only GET /api/identity (alkane-os 0.1.2 and later; earlier images are found from /api/summary). Each action below is offered only when it applies to every selected board:

  • "Install alkane OS..." - for a supported board (one alkane-os has an image for; today the Zynq-7010 Antminer S17/S17 Pro/T17) that is not running Alkane OS yet. Scans the alkane-os releases on Gitea, lets you pick one (newest first; pre-releases are marked), optionally takes a board password and an "allow unsigned .afw (bench)" toggle, then - when you click Install - downloads and verifies the .afw and installs it onto each selected board over the network, via the same compiled-in engine the CLI uses.
  • "Update alkane OS..." - for a supported board already running Alkane OS: the same release picker and confirmation; the board is updated in place (BOOT.bin is never written).
  • "Uninstall alkane OS (restore to stock)..." - for a board running Alkane OS: takes the board's alkane root password and a genuine Bitmain firmware package, then - when you click Restore - restores each selected board to genuine stock over the network.

A stock board the scan identifies but cannot place on a supported control board (or a mixed stock/Alkane selection) gets neither Install nor Update.

Progress and per-board results appear on the status bar; verify board state independently afterwards (the GUI does not claim liveness on its own).

Release scanning reads the private alkane-os repo, so it needs a Gitea token. A read-only token can be baked into the GUI at build time (ALKANE_EMBEDDED_TOKEN=<token> when building), so the shipped binary scans releases with no setup; otherwise set ALKANE_RELEASE_TOKEN (or GITEA_TOKEN) in the environment before launching. The stock-asset fetch needs no token (that repo is public), so install-from-stock and restore-to-stock work without one - only the release picker needs it.

Runtime dependencies (Linux): the GUI links wxWidgets 3.2 (wxGTK) and GTK 3, so the target machine needs libwxgtk3.2-1 and libgtk-3-0 installed.