Skip to content

v0.1.0

Choose a tag to compare

View all tags
@blackcoffeexbt blackcoffeexbt released this 09 Feb 14:57
· 161 commits to main since this release
v0.1.0
ed322d3

LNbitsBox v0.1.0

Flash. Boot. Bitcoin.

LNbitsBox is a bootable NixOS SD card image that turns a Raspberry Pi 4 into a plug-and-play LNbits Lightning node powered by Spark L2.

Highlights

  • Zero-config hardware node - Flash the image to an SD card, insert it into a Raspberry Pi 4, and you're running LNbits with a Lightning
    wallet in minutes.
  • First-run setup wizard - A web-based configuration wizard guides you through Spark wallet seed generation (or import) and SSH password
    setup. No terminal required.
  • Lightspark Spark - Comes bundled with https://github.com/lnbits/spark_sidecar as the Lightning funding source, so you don't
    need to run a full Lightning node.
  • Tor hidden service - Automatically generates a .onion address on first boot for private remote access without port forwarding.
  • HTTPS by default - Caddy reverse proxy with automatic TLS certificates.
  • Admin dashboard - Built-in admin interface at /box for monitoring your node, viewing Spark balance, and finding your Tor address.

Hardware Requirements

  • Raspberry Pi 4 (any RAM variant)
  • MicroSD card (16GB+ recommended)
  • Ethernet connection
  • USB-C power supply (5V/3A)

Getting Started

  1. Download nixos-sd-image-*-aarch64-linux.img.zst from the release assets
  2. Flash to SD card using https://www.raspberrypi.com/software/ (handles .zst natively) or dd
  3. Boot the Pi and navigate to https:///
  4. Complete the setup wizard (generate seed, set SSH password)
  5. LNbits is ready at the same URL

Security

  • All backend services (LNbits, Spark, configurator) bind to 127.0.0.1 only - never directly exposed
  • Mnemonic stored with restricted file permissions (0640 root:spark-sidecar)
  • Configurator only runs once on first boot, then is disabled by systemd
  • Access logs disabled to prevent seed phrase leakage
  • Systemd service hardening (NoNewPrivileges, PrivateTmp, etc.)

Utilities

  • sudo lnbitspi-reset - Re-run the setup wizard without losing your LNbits data

Known Limitations

  • Raspberry Pi 4 only (Pi 3 and earlier are not supported)
  • Ethernet required (no WiFi out of the box)
Assets 2
Loading