How to use Kanata from Homebrew and LaunchCtl for macOS

[thomastthai]

The following installation and configuration steps are tested on macOS Sequoia 15.3.x.

Install Karabiner-DriverKit-VirtualHIDDevice

1. Download Karabiner-DriverKit-VirtualHIDDevice the latest (v5.0.0 as of August 2024) or specific version of the driver you need. When you click on the *.pkg file, GitHub may take you to another page with "View raw" link to download it.
2. Double-click on the file and follow the instructions to install it. Pay close attention to the step to use System Settings to grant the driver privileges.

Install Kanata

Execute the following command in your terminal:

brew install kanata

Manually test your kanata configuration to make sure it works before proceeding to configure kanata to launch at startup.

Edit startup files for LaunchCtl

Create and edit three files in /Library/LaunchDaemons/ using your favorite text editor:

❯ ls -l /Library/LaunchDaemons/ | grep example
-rw-r--r--@ 1 root  wheel  817 Nov 25 13:11 com.example.kanata.plist
-rw-r--r--@ 1 root  wheel  595 Nov 25 12:49 com.example.karabiner-vhiddaemon.plist
-rw-r--r--@ 1 root  wheel  522 Nov 25 12:48 com.example.karabiner-vhidmanager.plist

/Library/LaunchDaemons/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/thomas/.config/kanata/YOUR-KANATA-CONFIG.kbd</string>
        <string>--port</string>
        <string>10000</string>
        <string>--debug</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>

Customize the settings you need in the section below. These are the same switches or flags and values you would use with kanata in the terminal.

<array>
        <string>/opt/homebrew/bin/kanata</string>
        <string>-c</string>
        <string>/Users/thomas/.config/kanata/YOUR-KANATA-CONFIG.kbd</string>
        <string>--port</string>
        <string>10000</string>
        <string>--debug</string>
    </array>

/Library/LaunchDaemons/com.example.karabiner-vhiddaemon.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.karabiner-vhiddaemon</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>

/Library/LaunchDaemons/com.example.karabiner-vhidmanager.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.karabiner-vhidmanager</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager</string>
        <string>activate</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

Configure starting Kanata for LaunchCtl

Execute the following command in your terminal:

sudo launchctl bootstrap system /Library/LaunchDaemons/com.example.kanata.plist
sudo launchctl enable system/com.example.kanata.plist

Kanata will start on reboot with those commands. If you want to start kanata manually now:

sudo launchctl start com.example.kanata

Configure starting Karabiner-DriverKit-VirtualHIDDevice for LaunchCtl

Execute the following command in your terminal:

sudo launchctl bootstrap system /Library/LaunchDaemons/com.example.karabiner-vhiddaemon.plist
sudo launchctl enable system/com.example.karabiner-vhiddaemon.plist

sudo launchctl bootstrap system /Library/LaunchDaemons/com.example.karabiner-vhidmanager.plist
sudo launchctl enable system/com.example.karabiner-vhidmanager.plist

vhiddaemon and vhidmanager will start on reboot with those commands. If you want to start them now manually now:

sudo launchctl start com.example.karabiner-vhiddaemon
sudo launchctl start com.example.karabiner-vhidmanager

Set macOS to use the virtual keyboard

Navigate to your System Settings > Keyboard > Keyboard navigation > Keyboard Shortcuts:

In your keyboard Modifier Keys setting, select Karabiner DrivrKit VirtualHIDKeyboard x.x.x from the drop-down menu.

Set macOS to allow your terminal and kanata to monitor input from your keyboard

Navigate to your System Settings > Privacy & Security > Input Monitoring

If your terminal and kanata aren't listed, click on the + button to add them. Locate each application from the popup finder window and choose them. Since kanata was installed by Homebrew or if you installed kanata from source, you may need to type in the path to kanata manually using the keyboard shortcut Shift+Command+G while in the Finder file browser, e.g., /opt/homebrew/bin/kanata. On my system, /opt/homebrew/bin/kanata is a symbolic link to the actual location and macOS follows that link. If you choose kanata from the actual installed location, you may need to redo this step since each upgrade is placed in a separate version folder, e.g., 1.8.0, 1.8.1.

Set macOS Accessibility access to allow Kanata and your terminal to control your computer

Navigate to your System Settings > Privacy & Security > Accessibility:

Additional notes

• Some users reported conflicts when using Karabiner-Element and Kanata at the same time. Karabiner-Element hogs the virtual keyboard device and doesn't allow kanata to access it.

• If you want to test kanata from your CLI manually, you need to run it with sudo or else you'll get the IOHIDDeviceOpen error: (iokit/common) privilege violation error, e.g.,

  Error when running without sudo:

  ❯ kanata -d -c ~/.config/kanata/kanata.kbd
  20:45:17.3888 [INFO] kanata v1.8.0 starting
  ...
  20:45:19.4487 [INFO] entering the event loop
  20:45:19.4488 [INFO] Init: catching only releases and sending immediately
  IOHIDDeviceOpen error: (iokit/common) privilege violation
  20:45:19.5186 [ERROR] failed to open keyboard device(s): Couldn't register any device
  ...
  Error: failed to open keyboard device(s): Couldn't register any device
  libc++abi: terminating
  Abort trap: 6
  

  No error when running with sudo:

  ❯ sudo kanata -d -c ~/.config/kanata/kanata.kbd
  20:46:43.3365 [INFO] kanata v1.8.0 starting
  ...
  20:46:45.3812 [INFO] Init: catching only releases and sending immediately
  connected
  driver_activated 1
  driver_connected 0
  driver_version_mismatched 0
  20:46:46.0146 [INFO] Starting kanata proper
  20:46:46.0146 [INFO] You may forcefully exit kanata by pressing lctl+spc+esc at any time. These keys refer to defsrc input, meaning BEFORE kanata remaps keys.
  driver_connected 1
  

[LeonardoMor]

This worked fine.

For some reason after updating kanata, I had to remove and then re add and enable kanata on System Settings > Privacy & Security > Input Monitoring

But it worked after that.

[thomastthai]

@LeonardoMor, I'm glad it worked for you! The reason some people had to remove, re-add, and enable System Settings > Privacy & Security > Input Monitoring is likely because (from the write-up above):

If you choose kanata from the actual installed location, you may need to redo this step since each upgrade is placed in a separate version folder, e.g., 1.8.0, 1.8.1.

Choosing a symbolic link Kanata file that brew creates to the actual file for a particular version eliminates the need to re-enable. The only issue is that the added item doesn't have a nice icon.

[LeonardoMor]

Got it. Should have read in more detail.

How do I distinguish between the symlink and the the actual binary? I thought that I was adding the symlink already.

[thomastthai]

@LeonardoMor, there was a lot to read. That small part was easy to miss. I'll do a better job when I write the macOS docs for Kanata.

❯ which kanata
/opt/homebrew/bin/kanata

❯ ls -la /opt/homebrew/bin/kanata
lrwxr-xr-x@ 1 thomas  admin  33 Feb 15 01:21 /opt/homebrew/bin/kanata -> ../Cellar/kanata/1.8.0/bin/kanata

That line of output describes a symbolic link (symlink) on a Unix-like system (like macOS, which uses the @ symbol in permissions to indicate extended attributes). Let's break it down piece by piece:

• lrwxr-xr-x@: This represents the file permissions and type.

  • l: The very first character l indicates that this is a symbolic link. This is the most important part!
  • rwxr-xr-x: These are the standard Unix file permissions (read, write, execute) for the owner, group, and others. In this case:
    • rwx: The owner (thomas) has read, write, and execute permissions.
    • r-x: The group (admin) has read and execute permissions, but not write.
    • r-x: Others have read and execute permissions, but not write.
  • @: This symbol indicates that the file has extended attributes (like Access Control Lists or other metadata). This is common on macOS.

• 1: This is the number of hard links to the file. For a symbolic link, this is always 1.

• thomas: This is the owner of the symbolic link.

• admin: This is the group associated with the symbolic link.

• 33: This is the size of the symbolic link. Crucially, this is not the size of the file it points to. It's the length of the path string that the link contains (in this case, the string "../Cellar/kanata/1.8.0/bin/kanata").

• Feb 15 01:21: This is the last modification time of the symbolic link itself. If the target file changes, this timestamp will not update.

• /opt/homebrew/bin/kanata: This is the name of the symbolic link. This is what you would type on the command line to run the kanata program.

• -> ../Cellar/kanata/1.8.0/bin/kanata: This is the target of the symbolic link. It shows where the link points to. When you execute /opt/homebrew/bin/kanata, the system follows this link to the actual executable file. ../ means "go up one directory" relative to /opt/homebrew/bin.

[mFinnian]

Is it possible to use this same method when installing Kanata through cargo?

I've tried to do this but have so far been unsuccessful. I've changed the path to kanata in the com.example.kanata.plist file but I can see kanata only opens briefly (in activity monitor) and never applies the config I've written. (I've tested this config by running it with sudo kanata -c <path to config> and it runs without complaint).
In the sudo launchctl list, com.example.kanata has the status -6, when I ran launchctl  error -6 it returned a long number : null (4294967290: (null)) and I don't have permission to view the /Library/Logs/Kanata folder

I tried to install it with cargo so that I could install the cmd allowed version as I was unable to install that version with Homebrew (I wasn't able to find out if this is possible with Homebrew).

I would be grateful for any help, Thanks!!

[thomastthai]

@mFinnian, I compiled Kanata after 1.7.0 and before 1.8.0 from source and it worked using the instructions above. The good news is Kanata can start with sudo manually so that's a good place to start. Some of the following may apply to you.

Where did you place com.example.kanata.plist?

I don't have permission to view the /Library/Logs/Kanata folder

❯ sudo ls -la /Library/Logs/Kanata
total 885960
drwxr--r--   4 root  wheel        128 Feb 15 23:11 .
drwxr-xr-x  10 root  wheel        320 Feb 17 06:49 ..
-rw-r--r--   1 root  wheel     393801 Feb 17 22:37 kanata.err.log
-rw-r--r--   1 root  wheel  449767419 Feb 20 15:55 kanata.out.log

Would you copy and paste the terminal output for the following?

❯ ls -la /Library/LaunchDaemons/{*kanata*,*vhid*}
-rw-r--r--@ 1 root  wheel  802 Feb 17 20:40 /Library/LaunchDaemons/com.example.kanata.plist
-rw-r--r--@ 1 root  wheel  595 Nov 25 12:49 /Library/LaunchDaemons/com.example.karabiner-vhiddaemon.plist
-rw-r--r--@ 1 root  wheel  522 Nov 25 12:48 /Library/LaunchDaemons/com.example.karabiner-vhidmanager.plist

❯ cat /Library/LaunchDaemons/{*kanata*,*vhid*}

Unfortunately, "launchctl error -6" is a very generic error message and doesn't give a lot of specific information about what went wrong. It generally indicates a problem with loading or interacting with a launchd agent or daemon.

Here's a breakdown of common causes and troubleshooting steps:

❗ = possible cause
✅ = unlikely or you checked

Possible Causes:

• ❗Issues with the plist file:
  • Syntax errors: The plist file (which defines the launch agent or daemon) might have incorrect syntax. You can check for syntax errors using the plutil command in Terminal.
  • Incorrect paths: The paths to the executable or other files referenced in the plist might be incorrect. Make sure to use absolute paths.
  • Permissions problems: The plist file or the files it references might have incorrect permissions.
• ✅ Problems with the executable:
  • Not executable: The executable file might not have execute permissions. You can fix this using the chmod +x command in Terminal.
  • Dependencies: The executable might depend on other files or libraries that are missing or inaccessible.
• Launchd issues:
  • Conflicts: There might be conflicts with other launch agents or daemons.
  • Corrupted launchd database: The launchd database might be corrupted.

Troubleshooting Steps:

1. ❗Check the plist file:

   • Use plutil to check for syntax errors: plutil /path/to/your.plist
   • Carefully review all paths in the plist to ensure they are correct and absolute.
   • Verify the permissions of the plist file and any files it references.

2. ✅ Check the executable:

   • Ensure the executable has execute permissions: chmod +x /path/to/your/executable
   • Check if the executable has any dependencies and that they are all installed and accessible.

3. Examine launchd logs:

   • Launchd logs can provide more detailed information about errors. You can find them in /var/log/com.apple.xpc.launchd/launchd.log (on macOS 12 Monterey and later) or through the Console app.

4. Try unloading and reloading:

   • Sometimes, simply unloading and reloading the launch agent or daemon can resolve the issue:
     • launchctl unload /path/to/your.plist
     • launchctl load /path/to/your.plist

5. Restart your Mac:

   • A restart can sometimes resolve underlying issues with launchd.

[mFinnian]

Starting Point

com.example.kanata.plist (example was replaces with my username and was also changed in the file but I shall write here with example) is in the /Library/LaunchDaemon folder

(currently running homebrew installation of kanata with LaunchCtl set up and working as expected)
running ls -la /Library/LaunchDaemons/{*kanata*,*vhid*} results in :

-rw-r--r--@ 1 root  wheel  833 20 Feb 21:44 /Library/LaunchDaemons/com.example.kanata.plist
-rw-r--r--@ 1 root  wheel  599 18 Feb 00:07 /Library/LaunchDaemons/com.example.karabiner-vhiddaemon.plist
-rw-r--r--@ 1 root  wheel  526 18 Feb 00:06 /Library/LaunchDaemons/com.example.karabiner-vhidmanager.plist

newly formatted version of com.example.kanata.plist returns ok when running plutil
sudo launchctl list | grep example returns:

514	0	com.example.karabiner-vhiddaemon
-	0	com.example.karabiner-vhidmanager
517	0	com.example.kanata

TYPO IN FILE PATH

sudo launchctl unload /Library/LaunchDaemon/com.example.kanata.plist returns

Unload failed: 5: Input/output error
Try running `launchctl bootout` as root for richer errors.

trying: sudo launchctl disable system/com.example.kanata runs but when running sudo launchctl list | grep example it still returns:

514	0	com.example.karabiner-vhiddaemon
-	0	com.example.karabiner-vhidmanager
517	0	com.example.kanata

Unloading homebrew plist file

I realised the type so ran sudo launchctl unload /Library/LaunchDaemon/com.example.kanata.plist successfully and then ran sudo launchctl enable system/com.example.kanata to undo the disable
sudo launchctl list | grep example returns:

514	0	com.example.karabiner-vhiddaemon
-	0	com.example.karabiner-vhidmanager

Putting the Cargo plist File in Launch Daemons Folder

sudo rm /Library/LaunchDaemons/com.example.kanata.plist runs successfully
sudo cp com.example.kanata.plist /Library/LaunchDaemons/com.example.kanata.plist runs successfully

sudo launchctl bootstrap system /Library/LaunchDaemons/com.example.kanata.plist runs successfully

sudo launchctl list | grep finnian returns:

514	0	com.example.karabiner-vhiddaemon
-	0	com.example.karabiner-vhidmanager
-	-6	com.example.kanata

Running Scrips as Asked

ls -la /Library/LaunchDaemons/{*kanata*,*vhid*} reutrns:

-rw-r--r--@ 1 root  wheel  826 21 Feb 12:16 /Library/LaunchDaemons/com.example.kanata.plist
-rw-r--r--@ 1 root  wheel  599 18 Feb 00:07 /Library/LaunchDaemons/com.example.karabiner-vhiddaemon.plist
-rw-r--r--@ 1 root  wheel  526 18 Feb 00:06 /Library/LaunchDaemons/com.example.karabiner-vhidmanager.plist

cat /Library/LaunchDaemons/{*kanata*,*vhid*}

<?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>/Users/example/.cargo/bin/kanata</string>
        <string>-c</string>
        <string>/Users/example/.config/kanata/kanata.kbd</string>
        <string>--port</string>
        <string>10000</string>
        <string>--debug</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>
<?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.karabiner-vhiddaemon</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>
<?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.karabiner-vhidmanager</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager</string>
        <string>activate</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

Launchd.log

reading the launchd.log file I saw

(system/com.example.kanata) <Notice>: service state: spawning
(system/com.example.kanata) <Notice>: service state: spawning
(system/com.example.kanata) <Notice>: launching: inefficient
(system/com.example.kanata [2561]) <Notice>: xpcproxy spawned with pid 2561
(system/com.example.kanata [2561]) <Notice>: internal event: SPAWNED, code = 0
(system/com.example.kanata [2561]) <Notice>: service state: xpcproxy
(system/com.example.kanata [2561]) <Notice>: deferred event: domain spawn response: 0
(system/com.example.kanata [2561]) <Notice>: internal event: SOURCE_ATTACH, code = 0
(system/com.example.kanata [2561]) <Notice>: service state: running
(system/com.example.kanata [2561]) <Notice>: internal event: INIT, code = 0
(system/com.example.kanata [2561]) <Notice>: Successfully spawned kanata[2561] because inefficient
(pid/2561 [kanata]) <Notice>: uncorking exec source upfront
(pid/2561 [kanata]) <Notice>: created
(gui/501 [100018]) <Warning>: failed lookup: name = com.apple.chronoservices.chronodbridge, flags = 0x200, requestor = chronod[678], error = 3: No such process
<Notice>: Last log repeated 9 times
(system/com.example.kanata [2561]) <Notice>: exited due to SIGABRT | sent by kanata[2561], ran for 2106ms
(system/com.example.kanata [2561]) <Notice>: service has crashed 106 times in a row (last was not dirty)
(system/com.example.kanata [2561]) <Notice>: service state: exited
(system/com.example.kanata [2561]) <Notice>: internal event: EXITED, code = 0
(system) <Notice>: service inactive: com.example.kanata
(system/com.example.kanata [2561]) <Notice>: service state: not running
(system/com.example.kanata) <Notice>: Service only ran for 2 seconds. Pushing respawn out by 8 seconds.
(system/com.example.kanata) <Notice>: internal event: WILL_SPAWN, code = 0
(system/com.example.kanata) <Notice>: service state: spawn scheduled
(system/com.example.kanata) <Notice>: service throttled by 8 seconds
(system) <Warning>: failed lookup: name = com.apple.bird, requestor = ReportCrash[749], error = 3: No such process
<Notice>: Last log repeated 69 times
(pid/2561 [kanata]) <Notice>: shutting down
(pid/2561 [kanata]) <Notice>: cleaning up
(system) <Notice>: removing child: pid/2561
(gui/501 [100018]) <Warning>: failed lookup: name = com.apple.chronoservices.chronodbridge, flags = 0x200, requestor = chronod[678], error = 3: No such process
<Notice>: Last log repeated 39 times

on repeat

p.s. I have tried restarting and unloading and reloading the plist file a couple times, no dice

[thomastthai]

@mFinnian, thank you for sharing those details. Having kanata crash and not knowing why is frustrating.

If you use your username instead of example, feel free to keep that in the log if you are comfortable. Would you do the following:

1. Ensure the setup is in place and execute sudo launchctl start com.example.kanata to cause kanata to crash
2. sudo tail -n -100 /Library/Logs/Kanata/kanata.{err,out}.log | pbcopy to copy the last 100 lines of kanata's logs to the clipboard
3. Paste the clipboard into a reply here

Would you also share the commands and settings you used to compile kanata?

[mFinnian]

I'm stupid!

I forgot to add kanata to the Input Monitoring page in system settings!!! I added the binary in the .cargo/bin folder to the page in settings using the + button and now it is working.

Thank you @thomastthai for all your help!

if anyone after me is interested

I used Cargo to install kanata by running
cargo install kanata --features cmd
it installed into ~/.cargo/bin/kanata

Logs

sudo tail -n -100 /Library/Logs/Kanata/kanata.{err,out}.log | pbcopy

==> /Library/Logs/Kanata/kanata.err.log <==
Error: failed to open keyboard device(s): Couldn't register any device
libc++abi: terminating
IOHIDDeviceOpen error: (iokit/common) not permitted
19:44:57.9771 �[0m�[31m[ERROR] �[0mfailed to open keyboard device(s): Couldn't register any device


Press enter to exit
Error: failed to open keyboard device(s): Couldn't register any device
libc++abi: terminating
IOHIDDeviceOpen error: (iokit/common) not permitted
19:45:08.0900 �[0m�[31m[ERROR] �[0mfailed to open keyboard device(s): Couldn't register any device


Press enter to exit
Error: failed to open keyboard device(s): Couldn't register any device
libc++abi: terminating
IOHIDDeviceOpen error: (iokit/common) not permitted
19:45:18.2128 �[0m�[31m[ERROR] �[0mfailed to open keyboard device(s): Couldn't register any device


Press enter to exit
Error: failed to open keyboard device(s): Couldn't register any device
libc++abi: terminating
IOHIDDeviceOpen error: (iokit/common) not permitted
19:45:28.3258 �[0m�[31m[ERROR] �[0mfailed to open keyboard device(s): Couldn't register any device


Press enter to exit
Error: failed to open keyboard device(s): Couldn't register any device
libc++abi: terminating
IOHIDDeviceOpen error: (iokit/common) not permitted
19:45:38.4109 �[0m�[31m[ERROR] �[0mfailed to open keyboard device(s): Couldn't register any device


Press enter to exit
Error: failed to open keyboard device(s): Couldn't register any device
libc++abi: terminating
IOHIDDeviceOpen error: (iokit/common) not permitted
19:45:48.5324 �[0m�[31m[ERROR] �[0mfailed to open keyboard device(s): Couldn't register any device


Press enter to exit
Error: failed to open keyboard device(s): Couldn't register any device
libc++abi: terminating
IOHIDDeviceOpen error: (iokit/common) not permitted
19:45:58.6015 �[0m�[31m[ERROR] �[0mfailed to open keyboard device(s): Couldn't register any device


Press enter to exit
Error: failed to open keyboard device(s): Couldn't register any device
libc++abi: terminating
IOHIDDeviceOpen error: (iokit/common) not permitted
19:46:08.7201 �[0m�[31m[ERROR] �[0mfailed to open keyboard device(s): Couldn't register any device


Press enter to exit
Error: failed to open keyboard device(s): Couldn't register any device
libc++abi: terminating
IOHIDDeviceOpen error: (iokit/common) not permitted
19:46:18.8282 �[0m�[31m[ERROR] �[0mfailed to open keyboard device(s): Couldn't register any device


Press enter to exit
Error: failed to open keyboard device(s): Couldn't register any device
libc++abi: terminating
IOHIDDeviceOpen error: (iokit/common) not permitted
19:46:28.9551 �[0m�[31m[ERROR] �[0mfailed to open keyboard device(s): Couldn't register any device


Press enter to exit
Error: failed to open keyboard device(s): Couldn't register any device
libc++abi: terminating
IOHIDDeviceOpen error: (iokit/common) not permitted
19:46:39.0613 �[0m�[31m[ERROR] �[0mfailed to open keyboard device(s): Couldn't register any device


Press enter to exit
Error: failed to open keyboard device(s): Couldn't register any device
libc++abi: terminating
IOHIDDeviceOpen error: (iokit/common) not permitted
19:46:49.1638 �[0m�[31m[ERROR] �[0mfailed to open keyboard device(s): Couldn't register any device


Press enter to exit
Error: failed to open keyboard device(s): Couldn't register any device
libc++abi: terminating
IOHIDDeviceOpen error: (iokit/common) not permitted
19:46:59.2713 �[0m�[31m[ERROR] �[0mfailed to open keyboard device(s): Couldn't register any device


Press enter to exit
Error: failed to open keyboard device(s): Couldn't register any device
libc++abi: terminating
IOHIDDeviceOpen error: (iokit/common) not permitted
19:47:09.3901 �[0m�[31m[ERROR] �[0mfailed to open keyboard device(s): Couldn't register any device


Press enter to exit
Error: failed to open keyboard device(s): Couldn't register any device
libc++abi: terminating

==> /Library/Logs/Kanata/kanata.out.log <==
19:45:48.5149 �[0m�[34m[INFO] �[0mentering the processing loop
19:45:48.5151 �[0m�[34m[INFO] �[0mlistening for event notifications to relay to connected clients
19:45:48.5152 �[0m�[34m[INFO] �[0mentering the event loop
19:45:48.5153 �[0m�[34m[INFO] �[0mInit: catching only releases and sending immediately
19:45:56.5578 �[0m�[34m[INFO] �[0mkanata v1.8.0 starting
19:45:56.5586 �[0m�[34m[INFO] �[0mprocess unmapped keys: true
19:45:56.5588 �[0m�[36m[DEBUG] �[0m(1) kanata_parser::cfg::alloc: freeing allocations of length 0
19:45:56.5593 �[0m�[34m[INFO] �[0mconfig file is valid
19:45:56.5594 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd reset state
19:45:56.5594 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd soft reset state
19:45:56.5594 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd clear historical data
19:45:56.5594 �[0m�[34m[INFO] �[0mSleeping for 2s. Please release all keys and don't press additional ones. Run kanata with --help to see how understand more and how to disable this sleep.
19:45:58.5844 �[0m�[34m[INFO] �[0mentering the processing loop
19:45:58.5846 �[0m�[34m[INFO] �[0mlistening for event notifications to relay to connected clients
19:45:58.5846 �[0m�[34m[INFO] �[0mInit: catching only releases and sending immediately
19:45:58.5847 �[0m�[34m[INFO] �[0mentering the event loop
19:46:06.6332 �[0m�[34m[INFO] �[0mkanata v1.8.0 starting
19:46:06.6337 �[0m�[34m[INFO] �[0mprocess unmapped keys: true
19:46:06.6338 �[0m�[36m[DEBUG] �[0m(1) kanata_parser::cfg::alloc: freeing allocations of length 0
19:46:06.6343 �[0m�[34m[INFO] �[0mconfig file is valid
19:46:06.6344 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd reset state
19:46:06.6344 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd soft reset state
19:46:06.6344 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd clear historical data
19:46:06.6344 �[0m�[34m[INFO] �[0mSleeping for 2s. Please release all keys and don't press additional ones. Run kanata with --help to see how understand more and how to disable this sleep.
19:46:08.7044 �[0m�[34m[INFO] �[0mentering the processing loop
19:46:08.7046 �[0m�[34m[INFO] �[0mlistening for event notifications to relay to connected clients
19:46:08.7046 �[0m�[34m[INFO] �[0mInit: catching only releases and sending immediately
19:46:08.7047 �[0m�[34m[INFO] �[0mentering the event loop
19:46:16.7481 �[0m�[34m[INFO] �[0mkanata v1.8.0 starting
19:46:16.7488 �[0m�[34m[INFO] �[0mprocess unmapped keys: true
19:46:16.7489 �[0m�[36m[DEBUG] �[0m(1) kanata_parser::cfg::alloc: freeing allocations of length 0
19:46:16.7497 �[0m�[34m[INFO] �[0mconfig file is valid
19:46:16.7499 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd reset state
19:46:16.7499 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd soft reset state
19:46:16.7500 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd clear historical data
19:46:16.7500 �[0m�[34m[INFO] �[0mSleeping for 2s. Please release all keys and don't press additional ones. Run kanata with --help to see how understand more and how to disable this sleep.
19:46:18.8105 �[0m�[34m[INFO] �[0mentering the processing loop
19:46:18.8107 �[0m�[34m[INFO] �[0mlistening for event notifications to relay to connected clients
19:46:18.8108 �[0m�[34m[INFO] �[0mInit: catching only releases and sending immediately
19:46:18.8108 �[0m�[34m[INFO] �[0mentering the event loop
19:46:26.8599 �[0m�[34m[INFO] �[0mkanata v1.8.0 starting
19:46:26.8604 �[0m�[34m[INFO] �[0mprocess unmapped keys: true
19:46:26.8606 �[0m�[36m[DEBUG] �[0m(1) kanata_parser::cfg::alloc: freeing allocations of length 0
19:46:26.8611 �[0m�[34m[INFO] �[0mconfig file is valid
19:46:26.8611 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd reset state
19:46:26.8611 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd soft reset state
19:46:26.8611 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd clear historical data
19:46:26.8611 �[0m�[34m[INFO] �[0mSleeping for 2s. Please release all keys and don't press additional ones. Run kanata with --help to see how understand more and how to disable this sleep.
19:46:28.9362 �[0m�[34m[INFO] �[0mentering the processing loop
19:46:28.9365 �[0m�[34m[INFO] �[0mlistening for event notifications to relay to connected clients
19:46:28.9366 �[0m�[34m[INFO] �[0mInit: catching only releases and sending immediately
19:46:28.9367 �[0m�[34m[INFO] �[0mentering the event loop
19:46:36.9831 �[0m�[34m[INFO] �[0mkanata v1.8.0 starting
19:46:36.9837 �[0m�[34m[INFO] �[0mprocess unmapped keys: true
19:46:36.9838 �[0m�[36m[DEBUG] �[0m(1) kanata_parser::cfg::alloc: freeing allocations of length 0
19:46:36.9844 �[0m�[34m[INFO] �[0mconfig file is valid
19:46:36.9844 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd reset state
19:46:36.9844 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd soft reset state
19:46:36.9844 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd clear historical data
19:46:36.9845 �[0m�[34m[INFO] �[0mSleeping for 2s. Please release all keys and don't press additional ones. Run kanata with --help to see how understand more and how to disable this sleep.
19:46:39.0445 �[0m�[34m[INFO] �[0mentering the processing loop
19:46:39.0447 �[0m�[34m[INFO] �[0mlistening for event notifications to relay to connected clients
19:46:39.0448 �[0m�[34m[INFO] �[0mInit: catching only releases and sending immediately
19:46:39.0448 �[0m�[34m[INFO] �[0mentering the event loop
19:46:47.0882 �[0m�[34m[INFO] �[0mkanata v1.8.0 starting
19:46:47.0887 �[0m�[34m[INFO] �[0mprocess unmapped keys: true
19:46:47.0888 �[0m�[36m[DEBUG] �[0m(1) kanata_parser::cfg::alloc: freeing allocations of length 0
19:46:47.0893 �[0m�[34m[INFO] �[0mconfig file is valid
19:46:47.0894 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd reset state
19:46:47.0894 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd soft reset state
19:46:47.0894 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd clear historical data
19:46:47.0894 �[0m�[34m[INFO] �[0mSleeping for 2s. Please release all keys and don't press additional ones. Run kanata with --help to see how understand more and how to disable this sleep.
19:46:49.1446 �[0m�[34m[INFO] �[0mentering the processing loop
19:46:49.1449 �[0m�[34m[INFO] �[0mlistening for event notifications to relay to connected clients
19:46:49.1449 �[0m�[34m[INFO] �[0mInit: catching only releases and sending immediately
19:46:49.1450 �[0m�[34m[INFO] �[0mentering the event loop
19:46:57.2006 �[0m�[34m[INFO] �[0mkanata v1.8.0 starting
19:46:57.2011 �[0m�[34m[INFO] �[0mprocess unmapped keys: true
19:46:57.2012 �[0m�[36m[DEBUG] �[0m(1) kanata_parser::cfg::alloc: freeing allocations of length 0
19:46:57.2017 �[0m�[34m[INFO] �[0mconfig file is valid
19:46:57.2017 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd reset state
19:46:57.2017 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd soft reset state
19:46:57.2017 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd clear historical data
19:46:57.2017 �[0m�[34m[INFO] �[0mSleeping for 2s. Please release all keys and don't press additional ones. Run kanata with --help to see how understand more and how to disable this sleep.
19:46:59.2543 �[0m�[34m[INFO] �[0mentering the processing loop
19:46:59.2544 �[0m�[34m[INFO] �[0mlistening for event notifications to relay to connected clients
19:46:59.2545 �[0m�[34m[INFO] �[0mInit: catching only releases and sending immediately
19:46:59.2545 �[0m�[34m[INFO] �[0mentering the event loop
19:47:07.2955 �[0m�[34m[INFO] �[0mkanata v1.8.0 starting
19:47:07.2960 �[0m�[34m[INFO] �[0mprocess unmapped keys: true
19:47:07.2962 �[0m�[36m[DEBUG] �[0m(1) kanata_parser::cfg::alloc: freeing allocations of length 0
19:47:07.2967 �[0m�[34m[INFO] �[0mconfig file is valid
19:47:07.2967 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd reset state
19:47:07.2967 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd soft reset state
19:47:07.2968 �[0m�[36m[DEBUG] �[0m(1) kanata_state_machine::kanata::output_logic::zippychord: zchd clear historical data
19:47:07.2968 �[0m�[34m[INFO] �[0mSleeping for 2s. Please release all keys and don't press additional ones. Run kanata with --help to see how understand more and how to disable this sleep.
19:47:09.3715 �[0m�[34m[INFO] �[0mentering the processing loop
19:47:09.3717 �[0m�[34m[INFO] �[0mlistening for event notifications to relay to connected clients
19:47:09.3718 �[0m�[34m[INFO] �[0mInit: catching only releases and sending immediately
19:47:09.3718 �[0m�[34m[INFO] �[0mentering the event loop

[thomastthai]

My pleasure, @mFinnian! Congrats on getting your setup working. There are many steps to figure out. I'd say you are pretty smart for getting through all that!

[michaelrommel]

Hello Thomas,

how do you ensure that the karabiner plists run in order? First the "activate" of the manager then the background daemon and then the kanata process?

Thanks in advance!

Michael.

[michaelrommel]

After testing that a bit I found out the following:

• macos launchd does not support dependencies. Daemons are expected to coordinate dependencies with IPC messages. So because of that, I don't think it is feasible to create wrappers around the daemons.
• the manager activate is needed only once. Even after I rebooted my mac, just launching the HID daemon was enough to get it going.
• kanata already retries opening the HID device. So that means, if kanata starts before the HID daemon, it will retry until the daemon is also up.

Therefore my worries about launch daemon dependencies are not warranted in this situation. I will now try to configure this on my system.

[michaelrommel]

Another point that may be misleading is the section titled "Set macOS to use the virtual keyboard" in the guide. You cannot "set" the keyboard. On this page you can select a keyboard and then change the modifiers for that specific keyboard. I have no idea, what the virtual hid driver does under the hood, it probably captures the input of all keyboards and feeds it then into kanata. Will check that the next days with my laptop and several keyboards...

[michaelrommel]

And lastly now I can confirm, that the system setting of Privacy -> Input Monitoring is only needed for one program:

• if kanata is started via Launchdaemons, then kanata needs to be added to this list or
• if kanata is started in a terminal, then the terminal needs to be added

It is not needed to add both if you do not switch between starting methods.

[InSasquatchCountry]

Great stuff! This is the kind of info that needs to find its way to the official documentation!

[shaleh]

Thank you for putting this document together. It is a great start.

I ran into a snag though. Details for others who might run into this.

I have installed the Karabiner driver as per their page. I have seen the example run and take over the mouse and then emit "egggggg". So far so good.

I then made /Library/LaunchDaemons/com.example.karabiner-vhiddaemon.plist and copied in your plist data. When I try to run launchctl I get no luck:

$ sudo launchctl bootstrap system /Library/LaunchDaemons/com.example.karabiner-vhiddaemon.plist 
Bootstrap failed: 5: Input/output error

Which is about as helpful as that error 6 above. https://developer.apple.com/forums/thread/665661 had a bunch of spaghetti being thrown at the wall. Reading through them all I found someone talking about permissions. In the end, permissions on the file were the issue. Ensuring the plist files are owned by root and wheel made things happy. The examples show this in the ls -al output but do not explicitly state the permission is required. I made the files in my home directory as myself and then sudo mv them over to the final location so the permissions were still me and not root. After that I was able to run Kanata manually from my terminal to start exploring.

[kash-01]

Thank you for putting this document together. It is a great start.

I ran into a snag though. Details for others who might run into this.

I have installed the Karabiner driver as per their page. I have seen the example run and take over the mouse and then emit "egggggg". So far so good.

I then made /Library/LaunchDaemons/com.example.karabiner-vhiddaemon.plist and copied in your plist data. When I try to run launchctl I get no luck:

$ sudo launchctl bootstrap system /Library/LaunchDaemons/com.example.karabiner-vhiddaemon.plist 
Bootstrap failed: 5: Input/output error

Which is about as helpful as that error 6 above. https://developer.apple.com/forums/thread/665661 had a bunch of spaghetti being thrown at the wall. Reading through them all I found someone talking about permissions. In the end, permissions on the file were the issue. Ensuring the plist files are owned by root and wheel made things happy. The examples show this in the ls -al output but do not explicitly state the permission is required. I made the files in my home directory as myself and then sudo mv them over to the final location so the permissions were still me and not root. After that I was able to run Kanata manually from my terminal to start exploring.

I'm stuck on this. Can you please elaborate on this? I can't seem to get this to work

[xiexingwu]

I'm stuck on this. Can you please elaborate on this? I can't seem to get this to work

Here's what I did to deal with the I/O error, which appeared to be caused by ownership issues (not owned by root):

sudo chown root:wheel /Library/LaunchDaemons/com.example.kanata.plist /Library/LaunchDaemons/com.example.karabiner-vhiddaemon.plist /Library/LaunchDaemons/com.example.karabiner-vhidmanager.plist

[viviengarcia]

Applied the guide on MacOS Sequoia 15.5 with success. Had to create the .plist files in my home folder as told by @shaleh to make it work.

One thing, though: contrarly to what's written in the instructions, sudo launchctl start com.example.kanata doesn't launch kanata. No process in activity monitor, nothing. Is it only me or do other people get same results?

EDIT: correction, it doesn't was Karabiner-elements that prevented kanata to start with launchctl. I suppose it starts before karabiner when I boot, nullifying the issue.

[pmithunish]

For me the first time the setup was not working. I did all kinds of hacky stuff that I really don't understand properly. Nothing worked. Then I decided to install Karabiner Elements and leave Kanata. But then I noticed that the latest version of Karabiner Elements also installs the Karabiner-DriverKit-VirtualHIDDevice-5.0.0.pkg package instead of the Karabiner-DriverKit-VirtualHIDDevice-6.0.0.pkg at the time of posting this. I initially used v6 thinking that's the latest version available to me at this moment, so that would be the best thing to do. Then I uninstalled the Karabiner Elements again. Then installed the v5 of the Karabiner Driver Kit. Followed the setup guide once again. This time it worked. But at the modifier keys section of the guide I am not seeing the Karabiner in the list of devices. But it now works, I am happy with that. Thanks OP for the setup guide.

[kash-01]

I keep getting this error shown below.

sudo launchctl bootstrap system /Library/LaunchDaemons/com.example.kanata.plist
Bootstrap failed: 5: Input/output error

I'm using sudo to create the files in the LaunchDaemon folder. Does anyone know how to fix this?

Thanks in advance

[michaelrommel]

Some hints around this topic:

• make sure that the plists are owned by root:wheel
• if you have already bootstrapped a plist the second call will display that error as well
• if you want to bootstrap a plist and the service is deactivated, you get this error. you can then use sudo launchctl enable system/com.example.kanata and then bootstrap. Try it with and without the .plist extension. I am fairly certain, that you do not need the extension, but the guide at the beginning says you do, so maybe you try both.
• ensure that the label inside the plist matches the filename

[dhruvsingh510]

Hi, @thomastthai, @michaelrommel.

Firstly, thank you for this comprehensive guide for settings up kanata on macos. I am stuck in the final stage of the installation.

I suspect that some other application is using the HID which is causing the error. Also, I am unable to find the Kanata log file that should be generated from com.example.kanata.plist.

I have used your configs and made changes according to my user. I am trying to look for the file here: /Users/dhruvsingh/Logs/Kanata but the Kanata directory hasn't been created signalling that the program is not running as it is supposed to.

The console logs when running sudo kanata --cfg /Users/dhruvsingh/.config/kanata/kanata.kbd -t are given below

I have also paid a close attention to the System Settings and enabled Kanata and iTerm (where I'm running kanata) both in Accessibility and Input Monitoring under Privacy & Security. I have noticed that I didn't have the karabiner_grabber that is present in your settings but suspect that it's because you had installed Karabiner-Elements also, that I didn't have.

Finally, I'm running Kanata v1.19.0, Karabiner-DriverKit-VirtualHIDDevice-6.0.0.pkg or v1.8.0, on MacOS ProductVersion: 15.3.2.

Please help how I can debug this further.

[dhruvsingh510]

Found the problem. When I created the launchctl file and restarted the computer, launchctl automatically ran an instance of kanata. When I used to run kanata again manually in iterm, kanata threw an error saying that the HID device was already in use. Please make sure there is only one instance of Kanata running at one time

[plasmadice]

Because someone ran into a similar issue on MacOS, I published the Raycast scripts that I use to control Kanata. Also threw in a command to view the last 100 lines of the error log for debugging.

Stop, Start, and Restart kanata using Raycast.

Instructions inside:
The Raycast script requires a bit of setup. Because you need sudo to launch, you have to save credentials that can run kanata with elevated permissions. The instructions for that are in each script, but only need to be set up once.

[allreddv]

How did you get these to work with Raycast? I followed everything to the T, and the scripts work if I run them manually in the terminal. The password is correctly entered, and I even did another debugging script

#!/bin/bash

# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title Debug Kanata Sudo
# @raycast.mode fullOutput
# @raycast.icon 🐞

echo "--- Starting Sudo Debug Script ---"

# 1. Check current user
echo "Running as user: $(id -un)"

# 2. Check keychain access
echo "\n--- Attempting to access keychain ---"
pw_name="kanata_sudo"
pw_account="removed"

if ! cli_password=$(security find-generic-password -w -s "$pw_name" -a "$pw_account"); then
  echo "❌ CRITICAL ERROR: Could not get password from keychain."
  exit 1
fi
echo "✅ Successfully retrieved password from keychain."


# 3. Test sudo command
echo "\n--- Attempting to run sudo command ---"
if echo "$cli_password" | sudo -S -k whoami; then
    echo "✅ SUCCESS: Sudo command executed successfully."
else
    echo "❌ CRITICAL ERROR: Sudo command failed."
fi

echo "\n--- Debug Script Finished ---"

and this works via Raycast

But I get an error every time I try to run the scripts via Raycast to start or stop the services.

[allreddv]

Never mind, I figured out what was wrong. I tried to create a different raycast script today that was basically almost an exact replica of a different script I have and the new one failed. So then I knew it had something to do with new scripts added.

So either due to a Raycast update or Sequoia 15.6 which I just recently updated so I am assuming it is the cause, Raycast now needs absolute paths. So for me I need to use

cli_password=$(/usr/bin/security find-generic-password -w -s "$pw_name" -a "$pw_account" 2>/dev/null)

if [ -z "$cli_password" ]; then
  echo "❌ Could not get password from keychain."
  exit 1
fi

so i need to use /usr/bin/security , and this is for everything now. instead of cat, now /bin/cat

The interesting thing is my old scripts created before the update still work maybe due to caching or something. that is why I was so confused as to what was going on. Only once I had the issue using a simple script using "cat" failing that I found this.

So not sure if others are experiencing this or not, but for me that was the issue and now all are working. Thanks for the scripts.

[plasmadice]

Raycast now needs absolute paths.

That's not something I've experienced. I'm now on Tahoe 26.0.1 (25A362). I did not participate in the macOS beta and have been on Kanata 1.9.0.

After running into some issues and seeing @Jaycedam's comment below , I adopted the same approach with Raycast. May his pillow always be cool.

I dropped start because restart does the same thing. Still requires the approval of the Karabiner extension in settings and adding the Kanata bin file to Input Monitoring permissions.

• kanata-install.sh - Uses keychain for security
• kanata-restart.sh - Most used, need to find a way to run this each time a new keyboard is detected (Hazel or something?)
• kanata-stop.sh - Hopefully never need to use this, stopping and starting Kanata is problematic
• kanata-status.sh - Quick logs

[jaycem-dev]

I wrote a script to automate all of this: Kanata Gist

If you need more details:

• Installs Kanata if necessary
• Downloads and installs latest karabiner driver
• Write necessary plist then start services
• Open settings on the necessary tabs for permissions (you still need to manually add the kanata path, I can't find a way around that)

[InSasquatchCountry]

2025-10-19
macOS 26.0.1
worked great 👍

Had I looked closer at line 12:
KANATA_CONFIG="${HOME}/.config/kanata/config.kbd"
I wouldn't have had any issues, but it took me a second to realize my oversight 😆

[raymond-w-ko]

Has anyone tested this on macOS Tahoe 26.1 beta? I can navigate to the kanata executable, but can't add it for some reason. I've tried double clicking it and clicking on "Open"

[raymond-w-ko]

Okay, progress: I have to run kanata as root, which triggers initial keyboard setup, and then it appears in the keyboard modifiers list.

[hwamil]

Anyone having trouble with tahoe? can't add kanata to input monitoring.
In fact, can't add other executables to input monitoring.
Every time I try to bootstrap, I get I/O error.

[raymond-w-ko]

What I noticed is that the kanata executable is added, but it doesn't show up on the list. So if you add it and kanata is running as root, as well as all the Karabiner stuff is installed, and you selected the virtual keyboard, it works.

Make sure all three programs are running using ps auxww and that they are running as root. If not you may need a reboot or restart of the kanata program.

I can confirm kanata is working on the latest Tahoe beta in Ghostty, I use it everyday.

[xiexingwu]

As per these two comments, it's worth checking the plist files have the correct ownership:

ls -l /Library/LaunchDaemons/com.example.ka*
-rw-r--r--  1 root  wheel  807 16 Dec 11:20 /Library/LaunchDaemons/com.example.kanata.plist
-rw-r--r--@ 1 root  wheel  596  8 Apr  2025 /Library/LaunchDaemons/com.example.karabiner-vhiddaemon.plist
-rw-r--r--@ 1 root  wheel  523  8 Apr  2025 /Library/LaunchDaemons/com.example.karabiner-vhidmanager.plist

It's important you see root instead of your username. You can use sudo chown to change ownership to root.

[hwamil]

I did set correct ownership but just wouldn't work. I just resorted to running it manually in terminal :/

[xiexingwu]

If you're satisfied with the solution then it's all good.

I'll share how I resolved the issue in case anyone else is interested. I ended up changing my kanata.plist. Specifically, I deleted the following program arguments.

        <string>--port</string>
        <string>10000</string>
        <string>--debug</string>

---

I arrived to this by inspecting Kanata logs. To find out where the logs are:

sudo launchctl list com.example.kanata

{
        "StandardOutPath" = "/Library/Logs/Kanata/kanata.out.log";
        "LimitLoadToSessionType" = "System";
        "StandardErrorPath" = "/Library/Logs/Kanata/kanata.err.log";
...
}

Inspecting the logs:

sudo tail /Library/Logs/Kanata/kanata.err.log

...
thread 'main' (42334) panicked at src/tcp_server.rs:87:56:
TCP server starts: Os { code: 48, kind: AddrInUse, message: "Address already in use" }
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

So it looks like there's a clash with the port address somewhere. I don't think I need it so I simply removed the argument. But I suppose one could change the port address if they would like to use it.

[andre-guerreiro]

After a lot of debugging I got it to work on Tahoe. The key was to add the flag --nodelay. Here my entire daemon 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.jtroo.kanatadaemon</string>

    <key>ProgramArguments</key>
    <array>
    <string>/usr/local/bin/kanata_macos_cmd_allowed_arm64</string>
        <string>-c</string>
        <string>/path/to/.kanata_config.kbd</string>
        <string>--nodelay</string>
        <string>--no-wait</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>

    <key>ProcessType</key>
    <string>Interactive</string>
</dict>
</plist>

[allreddv]

Like others in this thread I was having a lot of issues getting Kanata to run the way I wanted with OSx Tahoe 26.2. I could get it to run fine with manual launch from terminal, but my issue was having it run in the background as a daemon (like I had for Sequoia). It seems like Tahoe will no longer grant background daemons permission to access input devices. If someone figured it out I would love to know what you did because I spent way too much time trying to get it to work. I tried a bunch of different options using LaunchAgents, but each one had its own annoying caveat I didn't like.

So I just created a small menubar app which allows me to run Kanata in Tahoe exactly how I want and it is actually better than what I had for Sequoia. I created a public repo in case anyone else wants to use it. KanataManager

[allreddv]

@andre-guerreiro I tried that in the beginning but still didn't work, but I believe why it works for you is that you are running off the binaries.
/usr/local/bin/kanata_macos_cmd_allowed_arm64

I run off Homebrew install.
/opt/homebrew/bin/kanata

I have it running exactly the way I want now which I prefer to how I had before even as now I have it in the menubar, but I spent way too much time on it, didn't even watch the Super Bowl. So until something breaks again I am going to stay exactly where I am. I waited to install Tahoe until 26.2 exactly because I hate OSx upgrades. I hardly ever use any of the new features and each year they make their permissions more of a pain and things always break because I use tons of things that interact with the APIs.

Thanks for responding.

[allreddv]

@jussapaavo That looks interesting, if i had not already built the app i just did I would have tried it for sure. Not sure if it works with homebrew install or not but from a very quick glance at the repo readme it is basically just what I built but also has versions for Linux and Windows. Mine only is for macOS and I only used it with Tahoe 26.2 so I can't even confirm if it works with other versions or not, and I am not planning on testing it. I created it for me and then when I was done I figured I would just throw it up as public repo.

[chianyungcode]

I tried recenlty installing kanata in /usr/local/bin and it's worked and i doesn't understand why. I'm running on macOS Tahoe 26.2. Before this happen i already try installed kanata with homebrew and kanata binary located in /opt/homebrew/bin and the second try is with cargo in /Users//.cargo/bin , both are doesn't work. Try to install it in /usr/local/bin

[allreddv]

@chianyungcode Not for nothing, but installing from the downloaded binaries into /usr/local/bin isn't an issue and has always worked that way easily, at least from my experience and knowledge, but that is not the same as from Homebrew. Hence the title of this entire thread "How to use Kanata from Homebrew and LaunchCtl for macOS".

When you install install /usr/local/bin you are in charge of managing the app, updates, etc. and is outside of homebrew. I like homebrew managing that for me, although going the /usr/local/bin works great for those that don't care if it is installed via homebrew or not.

But fixing the "how to run Kanata via homebrew" by installing to /usr/local/bin really isn't a solution to that problem at all. It is just a workaround and a way to run it without fighting apple TCC in order to have it run via homebrew install, but that option has always worked.

Apple TCC treats /usr/local/bin and /opt/homebrew/bin different, hence why you can run it easily from one and not the other. I have never tried installing with cargo, but i have heard that it can be done with Tahoe, just have not tried myself.

The ways to run it in Tahoe on login via homebrew that I have successfully tested.

1. LaunchAgent + Terminal login script - works but will have running terminal session open for it
2. Automator app wrapper - works but will have ongoing animated gear in menubar as keep alive script

in both 1 and 2, any attempts to hide or push to the background causes the permissions to be lost.

3. create small gui menubar app that acts as wrapper. This is the option that works best for me with how I want to run and manage Kanata.

If anyone does figure out how to get it running as background daemon via homebrew install I would love to hear how you did it, because I couldn't get it to work no matter how many different ways I tried to do it. But even with that option back on the table I think I am going to stick with the gui menubar app option. But just from a curiousity point I would love to know if someone gets it working so I can learn what option I couldn't think of to get it to go.

Moving focus back onto other tasks, most likely will be back to this thread again for next version of Tahoe, just like I was going from Sonoma to Sequoia. So see you all next year when Apple tightens everything again.

[jussapaavo]

I haven't tried installation through Homebrew and unfortunately don't have time to test it. But I'm running kanata succesfully from non-standard (on macOS) /Users/<username>/.local/bin path.

So from my previous experience with Homebrew, the usual gotchas are:

1. Homebrew dir is not included in PATH by default. Especially the background daemons don't have the same shell environment as your local terminal, so that might explain the difference between the two. This can be solved by adding PATH environment variable to the background daemon plist:

<key>EnvironmentVariables</key>
<dict>
  <key>PATH</key>
  <string>/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin:PATH/TO/HOMEBREW</string>
</dict>

2. Homebrew app isn't allowed to run. Permissions can be given by running shell command: xattr -r -d com.apple.quarantine PATH/TO/HOMEBREW/BIN

[benceferdinandy-signifyd]

Does (unicode < ) output work for you? For me that only works if I run it with sudo in a terminal.

[michaelrommel]

See here: #1546 (comment)

[benceferdinandy-signifyd]

Thanks! In the end I actually decided to go with chords. It's pretty cluncky, since it needs to basically know my default layout and obviously can only do what I can already type, but my understanding is, that the unicode input relies on the graphical environment and would not work at all in a tty for example, and it's a hit and miss on linux, so seemed safer that way.

[benceferdinandy-signifyd]

I will try it though, just to check.