Settings Reference

Open Settings… in the tray menu. The dialog groups each setting under the first word of its key, so brightness_gamma appears as Brightness → Gamma. Hold the pointer over a setting to see a short description of it. From the command line, read or change a setting by its key:

polyctl settings get problem_scan_level
polyctl settings set ui_theme dark

The tables list the settings a user may want to change. The rest are developer and transport tuning settings; see the end of this page.

Appearance and language

Dialog	Key	Default	What it changes
Ui → Theme	ui_theme	auto	The tray menu and dialogs: Automatic follows the desktop’s light or dark setting, Light and Dark always use that theme. A desktop that does not report its setting gets the dark theme.
Ui → Language	ui_language	auto	The language of the menus and dialogs. Applies when the tray app restarts. See Interface language.

Brightness

Dialog	Key	Default	What it changes
Brightness → Set Daylight Dependent	brightness_set_daylight_dependent	on	Adaptive brightness: the host sets the keycap brightness from the sunlight at your location, every ten minutes.
Brightness → Allow Online Location Lookup	brightness_allow_online_location_lookup	on	Looks up your approximate location from your IP address (ip-api.com), once per run. Off, or with no answer, the brightness follows the hour of the day instead.
Brightness → Allow Online Irradiance Request	brightness_allow_online_irradiance_request	on	Asks open-meteo.com for the sunlight at that location this hour, which includes cloud cover. Off, the host computes a cloudless-sky value from the location and time.
Brightness → Gamma	brightness_gamma	1.0	Shapes the daylight curve between darkest and brightest. Above 1 the middle of the day gets dimmer; below 1 it gets brighter. The end points do not move.
Irradiance → Min / Max	irradiance_min / irradiance_max	1.8 / 5.2	The sunlight values that map to the dimmest and the brightest level. Lower Max to reach full brightness on a cloudy day.
Irradiance → Prescaler	irradiance_prescaler	0.75	Multiplies the sunlight value before Min and Max apply.

A change to any of these is applied immediately, without waiting for the next ten-minute refresh.

Overlays and shortcut icons

Dialog	Key	Default	What it changes
Generic → Overlays Enabled	generic_overlays_enabled	on	Icons for apps with no overlay: the app’s mark on Escape and an icon per shortcut.
Generic → Overlays Add Escape Mark	generic_overlays_fill_gaps	on	An app with its own overlay also gets its mark on Escape, when the overlay leaves Escape blank.
Generic → Overlays Add Shortcut Icons	generic_overlays_fill_shortcuts	on	Such an app is also read for its shortcuts, with icons on the keys its overlay leaves blank.
Shortcut → Icons Enabled	shortcut_icons_enabled	on	Whether the focused app is read for its shortcuts at all.
Shortcut → Icon Auto Fetch	shortcut_icon_auto_fetch	on	Whether missing icons may be downloaded.
Shortcut → Enable Accessibility	shortcut_enable_accessibility	on	Linux only: whether the host may turn on the desktop’s accessibility switch so Qt and KDE apps publish their shortcuts.
Browser → Url Detection	browser_url_detection	on	Matching an overlay to the focused tab’s website. Off, browser overlays match on the window title only. See Website-Aware Overlays.
Browser → Report Local Enabled	browser_report_local_enabled	on	The receiver the browser extension reports to. It listens on 127.0.0.1 only.
Browser → Report Port	browser_report_port	50164	The receiver’s port. It must match the extension’s Host port.
Browser → Report Token	browser_report_token	empty	A shared secret. When set, the extension must send the same token.

Keyboard and connection

Dialog	Key	Default	What it changes
Unicode → Send Composition Mode	unicode_send_composition_mode	on	Tells the keyboard how this computer takes Unicode input (for example WinCompose or the native method), on connect and whenever it changes. Off, the keyboard keeps the mode it has stored.
Fontpack → Auto Flash	fontpack_auto_flash	on	Flashes missing or outdated font-pack bundles when the keyboard connects. Off, you update them yourself from Updates → Keyboard fonts or with polyctl fontpack sync.
Fontpack → Path	fontpack_path	empty	A .plyf file to flash instead of the pack that ships with the app. Empty uses the shipped pack.
Daemon → Mode	daemon_mode	on	Runs the keyboard connection in a background daemon that the tray app attaches to. See Daemon & Client Model.
Window → Report Network Enabled	window_report_network_enabled	off	Accepts window reports from a forwarder on another computer. Applies after a restart. See Multi-Machine Setup.

Problem reports and usage data

Dialog	Key	Default	What it changes
Problem → Scan Keyboard Console	problem_scan_keyboard_console	on	Watches the keyboard’s console for known failure messages.
Problem → Scan Host Logs	problem_scan_host_logs	on	Watches this app’s own log.
Problem → Scan Level	problem_scan_level	errors	What counts as a problem: Errors, or Errors and warnings.
Telemetry → Enabled	telemetry_enabled	on	The anonymous daily usage report.
Telemetry → Endpoint	telemetry_endpoint	the project’s collector	Where that report goes. Empty sends nothing, like turning it off.
Telemetry → Install Id	telemetry_install_id	generated	The random ID of this installation. See the random ID.

When a scan finds a problem, the tray shows one dialog per session that offers Report a Problem. Nothing is sent unless you send it.

Not listed here

• Developer → Mode (developer_mode) shows the Developer submenu. The dev_* settings below it only matter with it on.
• Max → Hid Message Before Delay, Delay → Time After Max Hid Messages and Hid → Reconnect Retries tune the USB transport. Leave them at their defaults unless you are asked to change them while reporting a problem.

Note

A change made in the dialog and one made with polyctl settings set do not overwrite each other.

The file keeps only the settings you changed. Every other setting follows the default of the PolyKybdHost version you run, so an update that improves a default reaches you too.