Radio software that just works.

Airwaves OS is a radio-focused operating system based on Armbian that runs on embedded computers, mini PCs, and servers. It provides a fully pre-configured environment for receiving and decoding radio signals, with all services running as Docker containers.

Website: airwavesos.com

• Getting Started — download, verify, flash, first boot, first app
• Troubleshooting — discovery, web UI, SDR, app, and update issues
• Deployment — VMs, disk sizing, UEFI boot
• Updates — update channels and the system updater

Note: Raspberry Pi 5 uses the same image as the Pi 4B. Armbian's rpi4b board target covers all 64-bit Raspberry Pi models (3 through 5), so there is no separate Pi 5 image — flash the rpi4b image.

Out-of-the-box udev rules and driver support for:

• RTL-SDR (Blog V3/V4, generic RTL2832U)
• Airspy Mini / R2 / HF+
• HackRF One
• SDRplay RSP series
• FlightAware Pro Stick / Pro Stick Plus
• Funcube Dongle Pro / Pro+

Host OS (Armbian minimal)
├── Kernel + systemd + Docker
├── systemd-networkd + avahi (mDNS)
├── SDR udev rules + driver packages
└── Docker containers
    ├── airwaves-gateway (nginx reverse proxy, port 80)
    ├── airwaves-manager (system management API, future)
    └── [decoder/feeder apps installed via app store]

All user-facing services run as Docker containers. The host OS is minimal (BUILD_MINIMAL=yes) with only the kernel, systemd, Docker, networking, and hardware drivers.

airwaves-os/
├── armbian/
│   ├── build.sh                    # Build entry point (clones armbian/build at pinned tag)
│   └── userpatches/                # Armbian customization layer
│       ├── extensions/
│       │   ├── airwaves-base.sh    # Identity, users, MOTD, config
│       │   ├── airwaves-docker.sh  # Docker CE + container infrastructure
│       │   ├── airwaves-networking.sh  # systemd-networkd, avahi, mDNS
│       │   ├── airwaves-hardware.sh    # SDR udev rules, driver packages
│       │   └── airwaves-os/        # Extension data (config files, scripts, templates)
│       ├── common-airwaves.conf    # Core build configuration
│       ├── config-airwaves.conf    # Board-specific overrides
│       └── targets.yaml            # Build matrix definition
├── containers/
│   └── airwaves-gateway/           # Nginx reverse proxy container
├── catalog/                        # App catalog definitions
└── releases/                       # Release manifests

• Linux system (Ubuntu 24.04 recommended) or Docker
• 8GB+ RAM, 50GB+ free disk space
• Root/sudo access

# Build for a specific board
./armbian/build.sh airwaves BOARD=rock-5b BRANCH=current RELEASE=bookworm

# Build for Raspberry Pi 4B
./armbian/build.sh airwaves BOARD=rpi4b BRANCH=current RELEASE=noble

# Build for x86 (mini PC / server)
./armbian/build.sh airwaves BOARD=uefi-x86 BRANCH=current RELEASE=bookworm

The build script clones armbian/build at a pinned tag and applies our userpatches automatically.

cd containers/airwaves-gateway
docker buildx build --platform linux/amd64,linux/arm64 -t airwaves-gateway .

1. Flash the image to an SD card or USB drive
2. Boot the device
3. The system automatically:
   • Generates a unique hostname (airwaves-XXXXXX from MAC address)
   • Loads pre-baked container images from disk
   • Starts the gateway container on port 80
   • Advertises itself via mDNS
4. Access the web interface at http://airwaves-XXXXXX.local

Default credentials: airwaves / airwaves — change them immediately after first login. See docs/GETTING_STARTED.md for the full walkthrough (downloading, checksum verification, flashing, first boot).

This project uses the Armbian build framework's userpatches system for OS customization and Docker for all application services.

Key docs:

• Armbian Build Documentation
• Armbian Extensions

See LICENSE for details.