Installation

Most users should install a prebuilt package; no Rust toolchain required. Source builds are for contributors and platform porters.

Not sure which path fits? Read Choose your install first.

For a Linux server or NAS controlling WLED and other network lights, use the Docker setup. The image bundles the web UI and HTML effects, with persistent storage and optional GPU access. Native installs provide the host capture and hardware integration that the supplied container setup does not expose.

#Linux: prebuilt installer

The fastest path on any Linux distribution. The script downloads a release tarball from GitHub, verifies its SHA256 checksum, installs the release under ~/.local/share/hypercolor/releases, links hypercolor, hypercolor-daemon, hypercolor-app, hypercolor-tui, and hypercolor-open into ~/.local/bin, and sets up a systemd user service. How Linux release installs are managed covers the full layout. It never asks for sudo, so it does not apply the udev rules or the i2c-dev setup that USB and SMBus device access need; see udev rules below.

curl -fsSL https://raw.githubusercontent.com/hyperb1iss/hypercolor/main/scripts/install-release.sh | bash

The installer is idempotent: re-running it upgrades an existing install. Pin any tagged release with --version (replace vX.Y.Z with the tag):

curl -fsSL https://raw.githubusercontent.com/hyperb1iss/hypercolor/main/scripts/install-release.sh | bash -s -- --version vX.Y.Z

On Linux the command prefix is fixed. HYPERCOLOR_INSTALL_PREFIX must be $HOME/.local and HYPERCOLOR_INSTALL_DIR must be $HOME/.local/bin; the script aborts on any other value, before downloading anything. Releases follow XDG_DATA_HOME and update state follows XDG_STATE_HOME when the first install records them. On macOS both variables are free to point somewhere else.

#Debian and Ubuntu (.deb)

Each release ships .deb packages for amd64 and arm64. They install the daemon, CLI, systemd user service, udev rules, and shell completions through apt:

# x86_64
version=X.Y.Z
sudo apt install "./hypercolor_${version}_amd64.deb"

# arm64
sudo apt install "./hypercolor_${version}_arm64.deb"

Remove it later with sudo apt remove hypercolor.

#Arch Linux (AUR)

The hypercolor-bin AUR package updates automatically on every tagged release:

yay -S hypercolor-bin

The PKGBUILD installs binaries, the systemd user service, shell completions, and udev rules automatically as part of the package install hooks.

#Linux: udev rules (USB and input device access)

USB and input device access on Linux requires udev rules. The .deb and AUR packages place them for you. If you used the prebuilt one-liner, install the copies retained in the active release, which ~/.local/bin/hypercolor links into:

release="$(dirname "$(dirname "$(readlink -f "$HOME/.local/bin/hypercolor")")")"
sudo install -Dm644 \
  "$release/lib/udev/rules.d/99-hypercolor.rules" \
  /etc/udev/rules.d/99-hypercolor.rules
sudo install -Dm644 \
  "$release/lib/udev/rules.d/70-hypercolor-input.rules" \
  /etc/udev/rules.d/70-hypercolor-input.rules
sudo install -Dm644 \
  "$release/etc/modules-load.d/i2c-dev.conf" \
  /etc/modules-load.d/i2c-dev.conf
sudo modprobe i2c-dev
sudo udevadm control --reload-rules
sudo udevadm trigger

Source installs apply the USB and hidraw rule, persist i2c-dev, and load the module by default. Run just udev-install from the checkout to install both udev rules, including input capture, and retrigger connected devices. Re-plug USB devices or log out and back in for session access changes to take effect.

#Windows

Download the NSIS installer (Hypercolor_<version>_x64-setup.exe) from the download page. The install is per-machine and asks for administrator elevation (UAC). In that one elevated pass the installer:

• Bundles hypercolor-daemon.exe and the hypercolor-app desktop shell
• Registers the app for autostart at login
• Runs hardware setup: installs the bundled PawnIO SMBus modules and registers the HypercolorSmBus broker service (motherboard and DRAM RGB)
• Adds Windows Firewall rules so mDNS discovery works without a first-run prompt
• Creates Start menu and Desktop shortcuts

Run the installer and launch Hypercolor from the Start menu. The app supervises the daemon automatically, so there is no separate daemon window to manage.

If hardware setup did not complete during install (the installer notes this in its details log), USB and network lighting still work. Re-run the SMBus setup later from Settings → Device Discovery → Hardware Support.

#macOS

Hypercolor for macOS requires Apple silicon and macOS 15.2 or newer; Intel Macs are not supported. Download the signed DMG from the download page. Open the DMG, drag Hypercolor to Applications, and launch it. The app registers a LaunchAgent for autostart and supervises the daemon; no terminal setup is required.

Homebrew users can install the desktop app as a cask (brew install --cask hyperb1iss/tap/hypercolor-app) or the daemon and CLI as a formula (brew install hyperb1iss/tap/hypercolor, with brew services support).

#macOS screen capture support

Screen capture is off until an explicit authorization or source-selection action. Keyboard capture uses Input Monitoring. Passive pointer capture does not use a TCC service. ScreenCaptureKit uses Screen Recording. The settings page links directly to the matching System Settings privacy pane when manual remediation is needed.

The CLI exposes the same explicit actions when the active process topology can perform them:

hypercolor access authorize-input-monitoring
hypercolor access authorize-screen-recording
hypercolor access choose-screen-source
hypercolor status --watch

Picker presentation can require Hypercolor.app. A headless installation returns a typed app-UI remedy instead of attempting private presentation APIs.

#The desktop app and autostart

On all platforms, Hypercolor ships a unified desktop app (hypercolor-app) built on Tauri. When you launch it:

1. The app checks if a daemon is already running on 127.0.0.1:9420. If so, it connects to it.
2. On Linux, it checks for an enabled systemd user service (hypercolor.service) and defers to it.
3. If no daemon is found, the app spawns one as a supervised child process with a watchdog that restarts it on crash. That daemon follows your [network] access mode, so it stays loopback-only unless you open it to the LAN. The one exception is a HYPERCOLOR_URL that points the app at a host other than 127.0.0.1, ::1, or localhost: the app then binds its daemon to exactly that address, whatever [network] says, and the daemon refuses a non-loopback address unless an API key or keyless network access is configured.
4. The tray icon appears, and the main window opens (or the app starts minimized if launched with --minimized).

Autostart is managed by the app’s autostart plugin. On Linux it creates a ~/.config/autostart/ entry; on macOS it registers a LaunchAgent; on Windows it writes a Run key in the current user’s registry. Toggle it from the tray menu or from within the app’s Settings page.

The app window is 1200×800 by default, with a minimum of 800×500. Close clicks hide the window rather than quit; Hypercolor stays in the tray. To fully quit, use the tray menu.

#Linux: systemd user service

The prebuilt installer and just install both install a systemd user service. Manage it with the CLI:

hypercolor service enable     # enable autostart on login
hypercolor service start      # start the daemon now
hypercolor service stop       # stop it
hypercolor service restart    # restart
hypercolor service status     # check current state
hypercolor service logs       # last 50 lines
hypercolor service logs --follow   # live tail

On Linux this wraps systemctl --user: it is a user service, not a system service. Never use sudo systemctl to manage it.

The unit file lives at ~/.config/systemd/user/hypercolor.service and uses %h/.local/bin/hypercolor-daemon as the executable path.

#macOS: LaunchAgent

The macOS app install registers a LaunchAgent (tech.hyperbliss.hypercolor) in ~/Library/LaunchAgents. The same hypercolor service subcommands work on macOS, wrapping launchctl.

#Choose the macOS daemon owner

Hypercolor supports four local daemon topologies:

• App sidecar: the desktop app supervises its bundled daemon. This is the default for the DMG and cask.
• Direct launchd: Hypercolor’s per-user LaunchAgent supervises the daemon.
• Homebrew service: brew services supervises the formula daemon.
• Standalone: a daemon started directly from a terminal. This topology can be observed and stopped, but it is not selected for autostart.

Only one topology can hold the per-user daemon guard. Select a persistent owner with one of these local commands:

hypercolor service choose-owner app-sidecar
hypercolor service choose-owner direct-launchd
hypercolor service choose-owner homebrew

Owner changes are journaled across stop, guard handoff, autostart changes, and startup. A failed handoff rolls back to the prior owner. If a standalone daemon owns the guard, the command reports its process ID and asks you to stop it before repeating the selection.

When a selected external owner is offline, use the remedy named by Settings or status output:

# Direct launchd owner
hypercolor service start

# Homebrew owner
brew services start hypercolor

Open Hypercolor.app to restore the app-sidecar owner. An ownership conflict is not a daemon crash; the losing managed contender exits without entering a restart loop.

#Verify the daemon is running

Regardless of install method, confirm the daemon is up:

curl http://localhost:9420/health

A 200 OK response means the daemon is healthy and accepting connections. The web UI is available at http://localhost:9420 in your browser.

#Developer install: build from source

This section is for contributors and platform porters. Ordinary users do not need to build from source.

#Prerequisites

• Rust 1.95+ (Edition 2024). Install via rustup.
• just, the task runner. cargo install just or your distro’s package manager.
• Bun, required for the web UI and TypeScript SDK. curl -fsSL https://bun.sh/install | bash.
• Platform libraries: see the distribution-specific lists below.

#Bootstrap (recommended)

git clone https://github.com/hyperb1iss/hypercolor.git
cd hypercolor
just setup

just setup installs system packages, the Rust toolchain, the WASM target, cargo tools (trunk, cargo-deny, sccache), and frontend dependencies. It is idempotent: re-running only installs what is missing.

Setup flags:

just setup -- -y              # non-interactive (no sudo prompts)
just setup -- --minimal       # Rust + wasm target only
just setup -- --no-system     # skip system package install
just setup -- --with-servo    # include Servo HTML renderer build deps

On Windows the same recipe dispatches to scripts/setup.ps1. Use PowerShell-style flags: -Yes, -Minimal, -NoSystem, -WithServo.

#System libraries

Debian / Ubuntu:

sudo apt install build-essential pkg-config cmake nasm \
  libudev-dev libusb-1.0-0-dev libhidapi-dev \
  libasound2-dev libpulse-dev libpipewire-0.3-dev \
  libxdo-dev libgtk-3-dev libwebkit2gtk-4.1-dev \
  libayatana-appindicator3-dev librsvg2-dev libssl-dev \
  clang lld

Fedora:

sudo dnf install gcc gcc-c++ pkg-config cmake nasm \
  systemd-devel libusb1-devel hidapi-devel \
  alsa-lib-devel pulseaudio-libs-devel pipewire-devel \
  libxdo-devel gtk3-devel webkit2gtk4.1-devel \
  libappindicator-gtk3-devel librsvg2-devel openssl-devel \
  clang lld

Arch Linux:

sudo pacman -S base-devel pkgconf cmake nasm \
  libusb hidapi alsa-lib libpulse pipewire \
  xdotool gtk3 webkit2gtk-4.1 \
  libappindicator-gtk3 librsvg openssl \
  clang lld

macOS:

xcode-select --install
brew install hidapi pkg-config cmake nasm

Windows: Install Visual Studio 2022 Build Tools with the “Desktop development with C++” workload.

#WASM target

Required for the web UI:

rustup target add wasm32-unknown-unknown
# or use the shortcut:
just setup-wasm

#Additional dev tools

cargo install --locked trunk cargo-deny    # required
cargo install --locked sccache             # optional; speeds rebuilds

#Frontend dependencies

cd crates/hypercolor-ui && bun install --frozen-lockfile   # Tailwind v4
cd ../../sdk && bun install --frozen-lockfile               # TypeScript SDK

#Build

just build           # debug build
just build-preview   # preview profile (optimized, fast compile)
just release         # full release bundle in dist/
just check           # type-check only, no artifact
just verify          # fmt + lint + test; run this before committing

#Install from source

After building, install the daemon and CLI to ~/.local/bin, the web UI assets, the systemd user service, and, by default, udev rules plus i2c-dev setup:

just install

Pass --skip-system-hooks if you want to skip the sudo-backed udev and SMBus setup:

just install -- --skip-system-hooks

#Run the desktop app from source

just app

This builds the daemon and the Tauri app at the preview profile and launches hypercolor-app. The app supervisor handles starting the daemon.

To run the daemon directly without the app shell:

just daemon

The daemon starts on 127.0.0.1:9420 by default with debug logging enabled.

#What’s next

With Hypercolor running, head to First launch to walk through the welcome wizard and connect your first device, or jump straight to the Quick start if you already know your way around.