🚀 How to Install and Auto-Start Kanata on macOS 15.5

Kanata is a powerful keyboard remapping tool that pairs well with custom ergonomic or split keyboards. While it's primarily developed for Linux, it's fully functional on macOS—if you know how to set it up properly.

This guide walks you through installing Kanata on macOS 15.5, configuring it, and ensuring it runs automatically at startup.

✅ Step 1: Install the Karabiner Virtual HID Driver

Kanata depends on a virtual HID (Human Interface Device) driver to simulate keyboard inputs. Karabiner’s open-source driver is the best option.

1. Download the Driver

Download the latest release from:👉 Karabiner-DriverKit-VirtualHIDDevice

2. Install and Activate the Driver

After installing the .pkg file, activate the driver with this command:

/Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager activate

Then, go to System Settings > General > Login Items and enable the driver under “Allow in the Background.”

💻 Step 2: Install Kanata

Use Homebrew to install Kanata:

brew install kanata

🛠️ Step 3: Create Your Kanata Configuration

Create a folder for your configuration file:

mkdir -p ~/.config/kanata

Then create the file kanata.kbd:

touch ~/.config/kanata/kanata.kbd

Add your remapping configuration to this file. (Refer to Kanata's docs for syntax examples.)

To test your config immediately:

sudo kanata -c ~/.config/kanata/kanata.kbd

🔁 Step 4: Make Kanata Auto-Start at Boot

We'll create two launchd daemon plist files to ensure everything loads automatically.

1. Karabiner HID Daemon

Create org.pqrs.karabiner.virtualhiddevice.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>org.pqrs.karabiner.virtualhiddevice</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/Applications/Karabiner-VirtualHIDDevice-Daemon.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Daemon</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

Copy it to the system daemon folder:

sudo cp ./org.pqrs.karabiner.virtualhiddevice.plist /Library/LaunchDaemons/

2. Kanata Launch Daemon

Create com.example.kanata.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.example.kanata</string>

    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/kanata</string>
        <string>-c</string>
        <string>/Users/YOUR_USERNAME/.config/kanata/kanata.kbd</string>
    </array>

    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>

    <key>StandardOutPath</key>
    <string>/Library/Logs/Kanata/kanata.out.log</string>
    <key>StandardErrorPath</key>
    <string>/Library/Logs/Kanata/kanata.err.log</string>
</dict>
</plist>

Then copy it over:

sudo cp ./com.example.kanata.plist /Library/LaunchDaemons/

🚀 Step 5: Load the Services

Finally, load both services using launchctl:

sudo launchctl load /Library/LaunchDaemons/org.pqrs.karabiner.virtualhiddevice.plist
sudo launchctl load /Library/LaunchDaemons/com.example.kanata.plist

🎉 Done!

From now on, Kanata will run automatically at system boot, complete with your custom configuration. To edit mappings later, just update your kanata.kbd file and restart the daemon:

sudo launchctl stop com.example.kanata
sudo launchctl start com.example.kanata

🧠 Troubleshooting Tips

• Make sure paths in your .plist files are absolute and correct.

• If Kanata fails to start, check /Library/Logs/Kanata/kanata.err.log for errors.

• On macOS 15+, ensure System Extensions and DriverKit permissions are granted in System Settings > Privacy & Security.