Skip to content
PolyKybd

What is PolyKybdHost?

PolyKybdHost is the Python application that runs on your computer and controls the PolyKybd’s per-key displays.

Without PolyKybdHost, the keyboard works as a standard QMK keyboard — all keys function normally, but the displays show only the static labels from the firmware. With PolyKybdHost running, the displays update dynamically based on context.

What it does

Section titled “What it does”
  • Tracks the active window on your computer and switches key overlays automatically when you change apps
  • Pushes keymap and display updates to the keyboard over USB HID
  • Manages language/unicode mode and display brightness
  • Provides a keymap editor for remapping keys without recompiling firmware
  • Flashes new firmware to the keyboard over HID
  • Supports multi-machine setups — one keyboard, multiple computers

Daemon and client model

Section titled “Daemon and client model”

PolyKybdHost runs in two parts. A background daemon owns the keyboard connection and tracks the active window. The tray app attaches to it as a client, and starts it if it is not running. You can quit and reopen the tray app without losing the keyboard connection. The polyctl command-line tool talks to the same daemon, so you can script the keyboard without the tray app. See Daemon & Client Model.

Operating modes

Section titled “Operating modes”

Normal mode (default): PolyKybdHost runs on the machine the keyboard is physically plugged into. It owns the HID device, tracks the active window, and pushes overlay, icon, and keymap updates directly to the keyboard.

Forwarder mode: PolyKybdHost runs on a second computer with no keyboard attached and sends that computer’s active window over TCP to the instance the keyboard is plugged into. One keyboard then serves several computers. See Multi-Machine.

See Multi-Machine Setup for details.

System requirements

Section titled “System requirements”
OS Status
Windows 10/11 Supported
macOS Supported
Linux (GNOME/X11) Supported
Linux (KDE Plasma) Supported (D-Bus integration)

Repositories

Section titled “Repositories”