A lightweight Linux tray app and per-key editor for laptop keyboard lighting, with a focus on TongFang-based laptops using ITE controllers.

LLM note: For a concise, LLM-optimized summary of supported hardware, backends, and repo-discovery hints, see AGENTS.md.

Uses a priority-based backend system plus a backend-stability policy to select the most appropriate eligible backend for detected hardware.

1. Kernel Driver (Preferred): Uses safe, native Linux kernel interfaces (/sys/class/leds).

   • Clevo / Tuxedo: Full RGB support via tuxedo-drivers or clevo-xsm-wmi.
   • System76: Full RGB support via standard ACPI drivers.
   • Broad: Brightness control on many laptops that expose a keyboard backlight LED via /sys/class/leds.

2. USB / HID Direct: Uses an implemented userspace backend such as ite8291r3 or ite8910.

   • TongFang: Supports per-key RGB on devices without kernel drivers (XMG, Wootbook, Eluktronics, older Tuxedo models) if the hardware supports it.

3. ASUS Aura: Uses the asusctl-aura backend when the ASUS userspace stack is available.

   • ASUS: Best for laptops that already expose lighting control through asusctl / rog-control-center.

Current backend plan:

• sysfs-leds, ite8291r3, and asusctl-aura: validated
• ite8910: experimental (0x048d:0x8910, Linux hidraw feature-report path)
• ite8297: dormant

Note: direct ITE backends only enable known-good, whitelisted IDs. Experimental and dormant paths are additionally policy-gated, so detection alone does not guarantee automatic selection.

The installer (install.sh) can optionally help you install the necessary kernel modules for Clevo/Tuxedo laptops, and installs the matching KeyRGB udev rules for supported USB / hidraw access paths.

• Beta: versioning follows 0.x.y. Currently stable but has limited backend support.
• Current release: v0.17.2.
• Installer support is primarily developed on Fedora/Nobara; other distro families are supported on a staged, best-effort basis.
• Support depends entirely on your specific keyboard controller and firmware. See Troubleshooting and Hardware support and contributing below.

Tray Menu (Effects)	Power Management
Per-Key Editor	Settings
Tray Menu (Brightness)	RAM / CPU Usage

More screenshots

Tray Menu (Software Effects)	Tray Menu (Keyboard / Profiles)
Uniform Color UI	Per-Key Calibrator
Keymap Calibration	Reactive Typing

KeyRGB's automated installer strategy is a contained AppImage:

• Downloads the self-contained AppImage release asset
• Installs it as ~/.local/bin/keyrgb (plus desktop launcher + autostart)
• Best-effort permissions/integration (udev rules + optional polkit helper)

The AppImage bundles runtime dependencies (Python, tkinter, tray libraries) so the installer does not install Python/Tk/GUI runtime packages via your distro package manager.

Standard install (default):

curl -fsSL https://raw.githubusercontent.com/Rainexn0b/keyRGB/main/install.sh -o install.sh && bash install.sh

No system package changes (skip kernel drivers / TCC app / polkit installs):

curl -fsSL https://raw.githubusercontent.com/Rainexn0b/keyRGB/main/install.sh -o install.sh && bash install.sh --no-system-deps

Full install (non-interactive example: kernel drivers + Reactive Typing permissions + TCC integration):

curl -fsSL https://raw.githubusercontent.com/Rainexn0b/keyRGB/main/install.sh -o install.sh && \
  KEYRGB_INSTALL_KERNEL_DRIVERS=y \
  KEYRGB_INSTALL_INPUT_UDEV=y \
  KEYRGB_INSTALL_TUXEDO=y \
  KEYRGB_INSTALL_TCC_APP=y \
  bash install.sh

Notes:

• Some integration steps may prompt for sudo (installing udev rules / polkit rules).
• --no-system-deps only skips system package changes; it does not affect AppImage downloads.
• The installer reports a distro support profile at startup: Fedora / Red Hat (tested), Debian / Ubuntu / Linux Mint (experimental), Arch / EndeavourOS / Manjaro (experimental), and openSUSE / Other Linux (best-effort).
• On Debian/Ubuntu/Linux Mint, the AppImage path is usually enough for a first install. Optional kernel-driver package installs are best-effort and may require TUXEDO package sources; the installer does not add third-party apt repos automatically.
• Experimental ite8910 support (0x048d:0x8910) uses Linux hidraw. The bundled KeyRGB udev rules also grant uaccess on matching hidraw nodes so the app can talk to that controller without detaching the kernel keyboard driver.
• To pin installs to a known release tag (instead of main), use both --ref <tag> and --version <tag> (for example v0.17.2).

Replaces ~/.local/bin/keyrgb with the newest matching release. Reuses your last saved release channel (stable vs prerelease).

curl -fsSL https://raw.githubusercontent.com/Rainexn0b/keyRGB/main/install.sh -o install.sh && bash install.sh --update-appimage

For development or local modifications. Installs system dependencies + installs KeyRGB in editable mode.

./install.sh --dev

Notes:

• Fedora / Nobara is the primary supported target.
• Other distros are best-effort via common package managers (dnf/apt/pacman/zypper/apk).
• System dependencies are only needed for development installs; the AppImage bundles everything.

Docs:

• Quickstart & install instructions: see the Quickstart section above.
• Commands / entrypoints / environment variables: see Run and Environment variables sections above.
• Architecture / TongFang support roadmap: docs/architecture/tongfang/00-index.md

Downloads and runs the latest uninstaller script:

curl -fsSL https://raw.githubusercontent.com/Rainexn0b/keyRGB/main/uninstall.sh -o uninstall.sh && bash uninstall.sh

Non-interactive uninstall (AppImage + desktop entries):

curl -fsSL https://raw.githubusercontent.com/Rainexn0b/keyRGB/main/uninstall.sh -o uninstall.sh && bash uninstall.sh --yes --remove-appimage

# Interactive removal
./uninstall.sh

# Non-interactive (scripted)
./uninstall.sh --yes --remove-appimage

If you installed via the installer, run KeyRGB from your app menu or start it from a terminal:

These are the effect names stored in ~/.config/keyrgb/config.json under the effect key.

• Hardware (firmware) effects: rainbow, breathing, wave, ripple, marquee, raindrop, aurora, fireworks
• Software effects: rainbow_wave, rainbow_swirl, spectrum_cycle, color_cycle, chase, twinkle, strobe
• Reactive typing: reactive_fade, reactive_ripple
• Per-key static map: perkey

Access Settings via the tray menu to configure:

• Power Management: toggle LEDs on Suspend/Resume or Lid Close/Open.
• Screen Dim Sync: optionally sync keyboard brightness with desktop-driven screen dimming/brightness changes (e.g. KDE brightness slider).
• Autostart: enable “Start KeyRGB on login”.
• Backend policy: opt in to experimental backends. Current plan: ite8910 is experimental and ite8297 remains dormant.

Profiles are stored in:

~/.config/keyrgb/profiles/

Each profile contains the keymap (calibration), global overlay tweaks, and per-key color data. Manage these via the Per-Key Editor.

Most supported controllers use a fixed LED matrix (e.g., 6×21). To map this to your physical layout:

1. Open keyrgb-perkey.
2. Click Run Keymap Calibrator.
3. Click the corresponding key on-screen as each physical LED lights up.
4. Save the keymap.

Environment variables: see the Environment variables section above.

If KeyRGB detects your device but behaves oddly, or if you have a new laptop model (TongFang/Clevo/etc.), please help us support it.

1. Run diagnostics:

keyrgb-diagnostics

2. Open an issue:

• https://github.com/Rainexn0b/keyRGB/issues/new/choose

Select Hardware support / diagnostics and paste the JSON output from step 1.

3. Include details:

• Laptop model (e.g., XMG Core 15, Tuxedo InfinityBook)
• USB ID (run lsusb | grep -i "048d:")
• Description of what works vs. what fails

keyrgb-diagnostics attempts to sanitize output, but please review the JSON before posting to ensure no personal paths/names are included.

GPL-2.0-or-later.