Daemon & Client Model

PolyKybdHost is built around a daemon + client split. Understanding it helps explain why the GUI can be closed and reopened without ever disturbing the keyboard.

The two parts

• The core (daemon). A Qt-free operational core owns the HID device, the reconnect logic, the active-window tracking, overlay/icon/keymap sends, adaptive brightness, and the recently-used overlay cache. It runs as a background process that keeps the keyboard connection alive on its own.
• The GUI (client). The system-tray application — menus, dialogs, the layout editor, the log viewer — attaches to the core as a client over a local control socket. It renders state the core publishes and forwards user actions back to it. It holds no device state of its own.

A plain python -m polyhost launch starts the GUI and, if no daemon is running, spawns one (detached) and connects to it. If the daemon cannot start, it falls back to running the core in-process.

Tip

Because the daemon keeps running after the GUI closes, you can quit the tray app and reopen it later without losing the device connection or losing reconnect state. Quitting a client closes only its own sockets — the daemon keeps running.

Why it exists

Running the core as a daemon means:

• The keyboard connection and its reconnect/debounce state survive GUI restarts.
• Multiple front-ends — the tray GUI and the polyctl CLI — talk to the same live core.
• A headless machine (a server, a CI rig) can run the core with no display at all.

The control socket

The GUI and polyctl reach the daemon over a local control socket:

• A Unix domain socket on Linux/macOS, or a named pipe on Windows.
• Authenticated with a key file stored with 0600 permissions in the platform’s user config directory.
• It also acts as the single-instance lock — only one core can own it at a time.

The wire protocol is plain JSON-RPC framed over that socket; the CLI uses the exact same transport the GUI does.

Startup modes

Mode	Flag	What runs
Daemon + GUI	(default)	Spawns/attaches the daemon, runs the tray GUI as its client
Client only	--connect[=ENDPOINT]	Tray GUI as a pure client of an already-running daemon
Headless	--headless	The core + control socket only, no Qt imported
In-process	--no-daemon	Legacy single-process startup (the core runs inside the GUI)

Note

--no-daemon is the one to use while developing PolyKybdHost: your code edits then run in the same process as the GUI, instead of in a separately-spawned daemon.

In headless mode the core auto-applies its own reconnect snapshots and is driven entirely through polyctl. The GUI can attach to a headless daemon at any time with --connect.

AI Assist · fix-debugpy-wmi

If you debug PolyKybdHost on Windows with Python 3.13, the fix-debugpy-wmi skill patches the known platform._wmi_query crash that stops the first debugpy launch, so stepping through the host works on the first try.

Logging

The daemon writes its own log to daemon_log.txt, which the Log Viewer shows under a Daemon Log tab. Start the daemon with --dev 1 for debug lines or --dev 2 for verbose ones, such as window-report receipts. It is the same --dev flag the GUI takes.