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.

• Install and troubleshooting
• Hardware support issue chooser
• Contributing guide
• Support guide
• Architecture notes
• Changelog
• Security policy

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

For most users, use the AppImage installer. Only use a source checkout if you want to modify KeyRGB locally.

The installer downloads the AppImage, stores it as ~/.local/bin/keyrgb.AppImage, installs the ~/.local/bin/keyrgb launcher, and refreshes desktop integration. The AppImage bundles the runtime dependencies, so normal installs do not need Python/Tk GUI packages from your distro.

Standard install:

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

AppImage install without system package changes:

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

Update an existing AppImage install:

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

Notes:

• Some integration steps may prompt for sudo when installing udev or polkit rules.
• --update-appimage also refreshes desktop integration and removes stale legacy KeyRGB PNG icons from older installs when the current SVG icon is available.
• --no-system-deps only skips system package changes; it still downloads and installs the AppImage.
• On Arch/CachyOS, install fuse2 for native AppImage/FUSE launching: sudo pacman -S --needed fuse2. KeyRGB also installs a launcher wrapper that falls back to --appimage-extract-and-run when libfuse.so.2 is unavailable.
• On Debian/Ubuntu/Linux Mint, the AppImage path is usually enough for a first install. Optional kernel-driver installs are best-effort and may require TUXEDO package sources; KeyRGB does not add third-party apt repos automatically.
• The installer bootstraps sub-scripts from the pinned release tag by default. To override, pass --ref <git-ref> or set KEYRGB_BOOTSTRAP_REF=<git-ref>.

Interactive uninstall:

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

Non-interactive uninstall of the AppImage install and desktop entries:

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

git clone https://github.com/Rainexn0b/keyRGB.git
cd keyRGB
./install.sh --dev

./uninstall.sh
./uninstall.sh --yes --remove-appimage

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

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: backend-specific. Common legacy values include 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

When a hardware effect name collides with a software effect name, KeyRGB stores the hardware selection with an hw: prefix to preserve the user's choice. Example: hardware spectrum_cycle is stored as hw:spectrum_cycle.

• Beta: versioning follows 0.x.y. Currently stable but has limited backend support.
• Installer support is validated on Fedora/Nobara and Arch/CachyOS; 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.

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.
   • Known limitation: some ite8291r3 laptops briefly blank the keyboard on AC unplug/replug before KeyRGB can repaint it; see docs/usage/05-backend-limitations.md.

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.

Experimental backends also carry an evidence tag in diagnostics so maintainers can distinguish speculative implementations from research-backed ones based on public protocol notes or reverse-engineering work.

Current backend plan:

• sysfs-leds, ite8291r3, ite8910, and asusctl-aura: validated
• ite8297: experimental + reverse_engineered
  • 0x048d:0x8297 — 64-byte hidraw feature-report path, uniform color only
• ite8258: experimental + reverse_engineered
  • 0x048d:0xc195 — Lenovo Legion 5 / Pro 5 Gen 10 24-zone ITE 8258 hidraw keyboard path (4×6 logical zone matrix, static color, brightness, and firmware effects)
• ite8258-chassis: experimental + reverse_engineered
  • 0x048d:0xc197 — Lenovo Gen10 composite ITE 8258 path with keyboard-plus-chassis lighting; currently shipped as a keyboard-first experimental backend with ANSI matrix mapping, per-key/static keyboard color, brightness, and the confirmed Lenovo Gen10 firmware effects while neon/logo/vent surfaces remain deferred
• ite8295-zones: experimental + reverse_engineered
  • 0x048d:0xc963 — Lenovo 4-zone ITE 8295 hidraw keyboard path used by IdeaPad Gaming 3-class systems, with static color, 4-zone updates, brightness, and the confirmed default firmware effects (breathing, wave, spectrum_cycle)
  • 0x048d:0xc966 — companion ITE 8176 endpoint reported on the same laptops; still treated as a separate unsupported protocol family until direct RGB evidence exists
• sysfs-mouse: experimental + speculative
  • Auxiliary-only route for color-capable external mouse LEDs exposed through /sys/class/leds; surfaced through discovery and tray secondary-device contexts, but intentionally kept out of primary keyboard auto-selection
• ite8233: experimental + reverse_engineered
  • 0x048d:0x7001 — single-zone lightbar, static color / brightness / off
  • 0x048d:0x7000 — lightbar + hidden backend-level effects: breathing, wave, bounce/clash, catchup/catch_up
  • 0x048d:0x6010 — lightbar + hidden backend-level effects: breathing, flash (with optional direction), vendor DMI color-scaling quirk for specific SKUs
• ite8291: experimental + reverse_engineered
  • 0x048d:0x6004, 0x6008, 0x600b — full per-key 6×21 row protocol
  • 0x048d:0xce00 (bcdDevice ≠ 0x0002) — per-key path; bcdDevice 0x0002 is routed to ite8291-zones instead
• ite8291-zones: experimental + reverse_engineered
  • 0x048d:0xce00 bcdDevice 0x0002 — 4-zone uniform-color firmware split

Naming note: backend identifiers follow the controller or protocol family first, and only add a semantic qualifier when the same family splits into incompatible runtime shapes. Laptop and SKU names stay in the support notes instead of becoming the primary backend identifier.

When a compatible auxiliary device is present, the tray exposes a Software Targets submenu so looped software effects can stay on the keyboard or mirror their uniformized output to all compatible secondary devices.

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.

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. Currently ite8297, ite8233, ite8258, ite8291, ite8291-zones, and ite8295-zones are experimental; the UI labels experimental paths as speculative or research-backed.

The tray's Power Mode submenu exposes the lightweight CPU power controls. Use Power Mode Settings… there to adjust the Extreme Saver target and review what each mode does.

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.

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

For support routing, see SUPPORT.md. For contributor workflow details, see CONTRIBUTING.md.

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.

KeyRGB is an independent platform with its own backend abstraction, power-management engine, and udev system. Some backend implementations were informed by device-support research from the Linux RGB community, including OpenRGB. Where OpenRGB data informed an implementation, the backend was independently reimplemented in Python for KeyRGB's custom layer. KeyRGB does not vendor, wrap, or directly reuse OpenRGB source code.

GPL-2.0-or-later.