kanata

Installs kanata on macOS together with the Karabiner-DriverKit-VirtualHIDDevice driver, and starts both at boot via two root LaunchDaemons:

• local.karabiner-vhidd runs the VirtualHIDDevice daemon (the standalone driver package does not start its own).
• local.kanata runs kanata --cfg <config>. KeepAlive is SuccessfulExit=false, so a crash restarts it but the lctl+spc+esc escape hatch (clean exit) stays dead.

Requirements

• macOS, with privilege escalation (-K) for installer, /Library/LaunchDaemons and launchctl.
• A kanata config at kanata_config (default ~/Library/Application Support/kanata/kanata.kbd). The role does not manage it.
• Karabiner-Elements must not be installed; it ships a conflicting daemon.
• Collection community.general (only when kanata_install_via_brew is true).

Role Variables

See defaults/main.yml. The main ones:

Variable	Default	Purpose
kanata_install_via_brew	true	brew install kanata; set false if the brew role does it
kanata_driver_version	6.2.0	Driver release to install if none is present
kanata_driver_pkg_checksum	""	Optional sha256:<hex> for the pkg
kanata_bin	/opt/homebrew/bin/kanata	Symlink that survives brew upgrade
kanata_config	~/Library/Application Support/kanata/kanata.kbd	kanata config

Example Playbook

- hosts: anubis
  roles:
    - role: kanata

Notes

• Tagged kanata.
• Use driver v6.x with kanata 1.10-1.12. v7/v8 use a different IPC protocol and fail without a useful error. An existing driver is never upgraded automatically; upgrade driver and kanata together.
• Manual step on first install: approve the system extension in System Settings > General > Login Items & Extensions > Driver Extensions, then reboot. The role prints a warning while it is not [activated enabled].
• After brew upgrade kanata: Input Monitoring and Accessibility grants are tied to the resolved binary (readlink -f (which kanata)); re-add it in System Settings > Privacy & Security, then restart the job: sudo launchctl bootout system/local.kanata; sudo launchctl bootstrap system /Library/LaunchDaemons/local.kanata.plist.
• kanata 1.12.0 spams virtual_hid_keyboard_ready true into the log (jtroo/kanata#2109); consider rotating /var/log/kanata.log.