KeyRGB

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.

Supported Backends & Devices

Uses a priority-based backend system to select the most appropriate implemented 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 Direct: Uses the ite8291r3 or any other implemented backend userspace driver.

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

Note: the USB ITE backends only enable known-good, whitelisted USB IDs. If you want to confirm whether your hardware is supported, check src/core/backends/ite8291r3/backend.py (and other src/core/backends/*/backend.py backends). You can add additional IDs or new backends at your own risk.

The installer (install.sh) can optionally help you install the necessary kernel modules for Clevo/Tuxedo laptops.

Status

• Beta: versioning follows 0.x.y. Currently stable but has limited backend support.
• Installer support is best-effort on other distros via common package managers (dnf/apt/pacman/zypper/apk) but is primarily developed on Fedora.
• Support depends entirely on your specific keyboard controller and firmware. See Troubleshooting and Hardware support and contributing below.

Screenshots

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

Quickstart

Install

Standalone AppImage (recommended for most users)

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.
• To pin installs to a known release tag (instead of main), use both --ref <tag> and --version <tag>.

Update existing AppImage (non-interactive)

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

Development install (local checkout)

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

Uninstall

One-line uninstall (no clone)

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

Uninstall from a local checkout

# Interactive removal
./uninstall.sh

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

Run

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

Command	Description
keyrgb	Start the tray app (background).
./keyrgb	Run attached to terminal (dev mode).
keyrgb-perkey	Open the per-key editor.
keyrgb-uniform	Open the uniform-color GUI.
keyrgb-reactive-color	Open the reactive typing color GUI.
keyrgb-calibrate	Open the keymap calibrator UI.
keyrgb-settings	Open the settings GUI.
keyrgb-tcc-profiles	Open the TCC power profiles GUI (if tccd is available).
keyrgb-diagnostics	Print hardware diagnostics JSON.

Environment variables

Variable	Usage
KEYRGB_BACKEND	Force backend: auto (default), ite8291r3, or sysfs-leds.
KEYRGB_DEBUG=1	Enable verbose debug logging.
KEYRGB_TK_SCALING	Float override for UI scaling (High-DPI / fractional scaling).
KEYRGB_TCCD_BIN	Override the tccd helper path for TCC integration.
KEYRGB_DEBUG_BRIGHTNESS	When set to 1, emits detailed logs for brightness actions and sysfs writes (useful when investigating flashes when restoring from dim). Example: KEYRGB_DEBUG_BRIGHTNESS=1 ./keyrgb dev state

Tray effects (names)

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

Configuration

Settings and autostart

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”.

Profiles

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.

Per-key calibration

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.

Troubleshooting

Issue	Solution
No tray icon	Run keyrgb from a terminal to see errors. Check if the system tray extension is enabled (GNOME).
Permission denied	Ensure udev rules are installed. Try replugging the device or rebooting.
Flickering effects	Ensure other tools (OpenRGB, TCC) are not running. KeyRGB needs exclusive access.
Per-key not working	You likely need to run the Keymap Calibrator first.
Brightness works but color does not (Kernel Driver / kbd_backlight)	Your sysfs LED node is likely brightness-only (no multi_intensity, color, or rgb attribute under /sys/class/leds/*kbd_backlight*). KeyRGB can only change color when the kernel exposes RGB attributes (common on Clevo/Tuxedo/System76). On ASUS ROG laptops, use asusctl / rog-control-center for Aura/RGB control.
Per-key editor not available on your laptop	The per-key editor requires a backend that can address individual LEDs (typically the USB ITE/TongFang path). Many kernel drivers expose only uniform brightness (and sometimes uniform RGB), not per-key RGB.

Advanced usage

Installer arguments

Argument	Meaning
--appimage	Download AppImage (default).
--dev	Developer install (editable pip install mode).
--pip	Legacy alias for dev editable install.
--clone	Clone repo and install via editable pip (dev/source).
--clone-dir <path>	Clone target directory (dev mode).
--version <tag>	Install specific tag (e.g. v0.9.3).
--asset <name>	Override AppImage filename (default: keyrgb-x86_64.AppImage).
--prerelease	Allow picking prereleases when auto-resolving latest AppImage.
--no-system-deps	Skip system package changes (kernel drivers / TCC app / polkit).
--update-appimage	Non-interactive: update an existing AppImage install (downloads latest and replaces ~/.local/bin/keyrgb).
--ref <git-ref>	For curl installs: download installer modules from a specific git ref (default: main).

Environment variables: see the Environment variables section above.

Hardware support and contributing

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

Privacy note

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

License

GPL-2.0-or-later.