Hub OS

A ready-to-flash Raspberry Pi image that runs Alby Hub (self-custodial Lightning) with zero manual install — flash, boot, open http://albyhub.local. Built with CustomPiOS.

Why

Manually installing Alby Hub on a Pi means SSH + curl | bash + a signature prompt + systemd setup. This image bakes all of that in, so onboarding is just:

1. Flash the image with Raspberry Pi Imager 2.0+ (“Use custom”) and set a user + password in the customization dialog (required — Raspberry Pi OS won't finish first boot without one). Setting WiFi there is optional — you can also configure it on first boot (step 2). Leave the hostname at its default so albyhub.local works.
2. Insert the card, power on, wait ~2 min. If the Pi has no internet yet, it raises an open WiFi network albyhub-setup — join it from your phone, pick your home WiFi, and enter the password. (Powered by balena wifi-connect.)
3. Open http://albyhub.local, set a password, save your seed, open a channel.

No terminal, no computer needed for WiFi. Tested target: Raspberry Pi Zero 2 W (512 MB) and up.

What's baked in (src/modules/albyhub)

• Alby Hub aarch64 binary + runtime libraries in /opt/albyhub, GPG-verified at build time against a pinned release (ALBYHUB_VERSION). Alby Hub supports multiple Lightning backends — you choose one during first-boot setup.
• albyhub.service (systemd, runs as dedicated albyhub user, port 80, with a low-resource default configuration).
• Port-80 binding via systemd AmbientCapabilities; ld.so.conf.d entry for the bundled libraries.
• gpu_mem=16 (frees ~48 MB) and vm.swappiness=10 + 1 GB swap.
• avahi-daemon for albyhub.local; default hostname albyhub (Imager's hostname customization can still override it — leave it default).
• WiFi onboarding via wifi-connect (pinned release, checksum-verified): wifi-connect.service raises the albyhub-setup portal on first boot only if the device is offline, then exits so the hub takes :80. NetworkManager + dnsmasq-base back it; a WiFi regulatory domain (ALBYHUB_WIFI_COUNTRY) is baked in because AP mode needs one.

What Imager handles at flash time (not baked)

SSH enable/key, user/password (required), locale/timezone, hostname — applied on first boot. WiFi is optional here: set it in Imager to skip the portal, or leave it blank and use the albyhub-setup portal on first boot. Use Raspberry Pi Imager 2.0 or newer — older versions don't reliably apply customization to current Raspberry Pi OS (cloud-init), which silently drops the SSH/WiFi settings.

Build

git submodule update --init --recursive   # pulls src/CustomPiOS
sudo bash ./build.sh -d                    # -d downloads the base image; emits workspace/*.img

CI (.github/workflows/build.yml) builds on tag push and publishes HubOS-<ver>-arm64.img.xz + sha256 to a GitHub release.

Distribution

Download the latest HubOS-<ver>-arm64.img.xz from the latest GitHub release, then flash it with Raspberry Pi Imager ("Use custom") — or any flasher (Etcher, dd). Set your WiFi + hostname in Imager's customisation, write, boot, and open http://albyhub.local.

Configuration

Edit src/modules/albyhub/config — pinned version, swap size, user, hostname. Bump ALBYHUB_VERSION to ship a new image; users can also self-update in place via /opt/albyhub/update.sh.

Updates

The image keeps itself current with no SSH:

• OS security patches apply automatically (unattended-upgrades).
• Alby Hub is checked weekly and updated automatically (GPG + SHA256 verified, with rollback) — but only if auto-unlock is enabled, since an update restarts the hub and would otherwise leave the wallet locked. The updater asks the hub's own /api/info and skips the update when auto-unlock is off.

So for fully hands-off updates, enable auto-unlock in Alby Hub → Settings. Trade-off: the unlock secret is then stored on the device (your seed phrase remains your backup). With manual unlock, update when the hub shows "Update Available". Place a file at /opt/albyhub/disable-autoupdate to turn the app auto-updater off entirely.

Status

Builds green in CI and boots on a Raspberry Pi Zero 2 W. On first boot with no internet, the albyhub-setup WiFi portal comes up; once connected, the hub serves on :80 at albyhub.local. Flash with Raspberry Pi Imager 2.0+ so first-boot customization applies. Not yet tagged as a release.