System requirements

macOS 13+, Windows 10+, or a mainstream Linux desktop (GNOME, KDE, XFCE). On Linux you also need GTK 3, WebKitGTK 4.1, and libudev; the AppImage bundles X11 capture deps (libxcb, libxrandr, libpipewire, libdbus).
At least one supported hardware target, otherwise the app runs but nothing lights up:
- A Philips Hue Bridge (gen 2 or newer) with one or more Entertainment Areas configured in the Hue app, or
- A WS2812B / SK6812 RGBW LED strip driven by a supported USB-serial controller (CH340, CH341, FT232, PL2303, or CP2104) running LumaSync v1 firmware or the opt-in Adalight profile, or
- An ESP32 / ESP8266 board running WLED firmware on the same LAN as the host machine — see the WLED bridge page.
See Hardware checklist for a parts list if you’re starting from scratch.

macOS

Download the universal .dmg from the Download page or the latest GitHub release. Apple Silicon and Intel Macs are covered by the same installer.

Open the .dmg and drag LumaSync.app into Applications.
On first launch, macOS asks for Screen Recording permission so the ambilight pipeline can sample your display. Grant it — without it the ambient mode has nothing to read from.
LumaSync starts hidden to the tray; click the menu-bar icon to open the main window. Cmd+Q from anywhere shuts the app down cleanly via the watchdog-bounded shutdown path; closing the window only hides it to the tray.

Windows

Download the signed .msi installer from the Download page. It runs a typical “Next, Next, Finish” dialog and installs to C:\Program Files\LumaSync\. From v1.5.1 every release ships the MSI alongside the macOS DMG and Linux packages — no more platform gaps between releases.

Linux

Three packages ship every release: .AppImage (distro-agnostic), .deb (Debian / Ubuntu), and .rpm (Fedora / openSUSE). Pick whichever your distro prefers.

# AppImage
chmod +x LumaSync_{LATEST_VERSION_BARE}_amd64.AppImage
./LumaSync_{LATEST_VERSION_BARE}_amd64.AppImage

# Debian / Ubuntu
sudo apt install ./lumasync_{LATEST_VERSION_BARE}_amd64.deb

# Fedora / openSUSE
sudo rpm -i lumasync-{LATEST_VERSION_BARE}.x86_64.rpm

Screen capture uses xcap for native X11 sampling — Wayland sessions need the X11 fallback (XWayland) for now. Tray behaviour varies by desktop environment: GNOME requires a third-party extension like AppIndicator Support to show the LumaSync tray icon; KDE Plasma and XFCE work out of the box. A Flathub package is in progress and will be the recommended path once it lands.

Verification

Every release asset is signed with minisign. The public key is embedded in the app and the updater verifies every binary before replacing anything on disk. To verify a download manually:

minisign -Vm LumaSync_{LATEST_VERSION_BARE}_universal.dmg -P "$(cat minisign.pub)"

minisign.pub is committed to the app repo. See Auto-updater for how this works in-app.

Next steps

Once installed, continue to First setup to pair your Hue bridge or connect a USB controller, then pick your first mode.