Dotfiles Automated Setup for MacOS (with Homebrew & LaunchCtl)

[GabrielKGardner]

Dotfiles Automated Setup (with Homebrew & LaunchCtl)

After following @thomastthai's great MacOS setup guide. I ran into some hiccups and wanted to tie Kanata into my personal .dotfiles repository to sync up with other work stations automatically. This took quite a bit longer than I expected, so hopefully this is useful for anyone else running into issues.

Additional Notes

• Tested for MacOS Tahoe 26.3.x
• I did find some repositories doing some similar scripting, but I just wanted things a bit more lean and maintainable exclusively by .dotfiles.
• Don't know what a .dotfile repo is? I encourage you to look into it! Good Starter
• Karabiner-DriverKit-VirtualHIDDevice does not as of the time of writing this post support a homebrew install. I think it very much should and so do some other people. The KaraninerDriverKit.sh script below is good replacement in the mean time. If this goes through you can disregard this part.
• This differs a tiny bit from the MacOS setup guide
  • We are moving files into /Library/LaunchDaemons and granting root permission
  • I kept getting this error Bootstrap failed: 5: Input/output error when running sudo launchctl bootstrap system ... I had to move sudo launchctl enable before it.

File Structure

~/.dotfiles/
├── .config/
│   └── .kanata.kbd (symlinked to ~/.config/.kanata.kbd)
└── scripts/
    ├── kanata/
    │   └── LaunchDaemons/
    │       ├── com.example.kanata.plist
    │       ├── com.example.karabiner-vhiddaemon.plist
    │       └── com.example.karabiner-vhidmanager.plist
    ├── KaraninerDriverKit.sh
    └── SetupDaemons.sh

~/.dotfiles/.config/kanata.kbd (find a starter)

~/.dotfiles/scripts/kanata/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/example/.config/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>

~/.dotfiles/scripts/kanata/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>

~/.dotfiles/scripts/kanata/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>

~/.dotfiles/scripts/kanata/KaraninerDriverKit.sh

#!/bin/bash
set -e

case "$1" in
install)
  REPO="pqrs-org/Karabiner-DriverKit-VirtualHIDDevice"
  API_URL="https://api.github.com/repos/${REPO}/releases/latest"

  echo "Fetching latest Karabiner-DriverKit-VirtualHIDDevice release..."

  PKG_URL=$(curl --silent "$API_URL" |
    grep "browser_download_url" |
    grep "\.pkg" |
    cut -d '"' -f 4)

  if [ -z "$PKG_URL" ]; then
    echo "Error: Could not find .pkg download URL." >&2
    exit 1
  fi

  echo "Downloading from: $PKG_URL"
  curl -L "$PKG_URL" -o /tmp/Karabiner-DriverKit-VirtualHIDDevice.pkg

  echo "Installing..."
  sudo installer -pkg /tmp/Karabiner-DriverKit-VirtualHIDDevice.pkg -target /

  echo "Requesting driver permissions."
  /Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager activate

  rm /tmp/Karabiner-DriverKit-VirtualHIDDevice.pkg
  echo "Done."
  ;;

uninstall)
  echo "Uninstalling..."

  bash '/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/scripts/uninstall/deactivate_driver.sh'
  sudo bash '/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/scripts/uninstall/remove_files.sh'
  sudo killall Karabiner-VirtualHIDDevice-Daemon

  echo "Done."
  ;;

*)
  echo "Usage: $0 [install|uninstall]"
  exit 1
  ;;
esac

~/.dotfiles/scripts/kanata/SetupDaemons.sh

#!/bin/bash

DOTFILES_LAUNCH_DAEMONS="$HOME/.dotfiles/scripts/kanata/LaunchDaemons"
LAUNCH_DAEMONS="/Library/LaunchDaemons"

shopt -s nullglob
PLISTS=("$DOTFILES_LAUNCH_DAEMONS"/*.plist)

if [[ ${#PLISTS[@]} -eq 0 ]]; then
  echo "ERROR: No .plist files found in $DOTFILES_LAUNCH_DAEMONS"
  exit 1
fi

case "$1" in
install)
  for SRC in "${PLISTS[@]}"; do
    FILENAME=$(basename "$SRC")
    LABEL="${FILENAME%.plist}"
    DEST="$LAUNCH_DAEMONS/$FILENAME"

    sudo cp "$SRC" "$DEST" || {
      echo "ERROR: Failed to copy $FILENAME"
      exit 1
    }
    sudo chown root:wheel "$DEST"
    sudo launchctl enable "system/$LABEL" || echo "WARN: enable failed for $LABEL"
    sudo launchctl bootstrap system "$DEST" || echo "WARN: bootstrap failed for $LABEL"
    sudo launchctl start "$LABEL" || echo "WARN: start failed for $LABEL"
  done
  echo -e "\033[1;33m!! ADDITIONAL SETUP REQUIRED !!"
  echo 'Settings > Keyboard > Keyboard Shortcuts... > Modifier Keys, select keyboard "Karabiner DriverKit VirtualHIDKeyboard x.x.x"'
  echo 'Settings > Privacy & Security > Input Monitoring > click "+" > Press keys SHIFT + COMMAND + G > type "/opt/homebrew/bin/kanata" > Open'
  echo 'Settings > Privacy & Security > Accessibility > click "+" > Press keys SHIFT + COMMAND + G > type "/opt/homebrew/bin/kanata" > Open'
  ;;
uninstall)
  for SRC in "${PLISTS[@]}"; do
    FILENAME=$(basename "$SRC")
    LABEL="${FILENAME%.plist}"
    DEST="$LAUNCH_DAEMONS/$FILENAME"

    [[ ! -f "$DEST" ]] && echo "WARN: $DEST not found, skipping" && continue

    sudo launchctl stop "$LABEL"
    sudo launchctl disable "system/$LABEL" || echo "WARN: disable failed for $LABEL"
    sudo launchctl bootout system "$DEST" || echo "WARN: bootout failed for $LABEL"
    sudo rm "$DEST" || echo "ERROR: removal failed for $DEST"
  done
  ;;
*)
  echo "Usage: $0 [install|uninstall]"
  exit 1
  ;;
esac

Install

1. Copy these files into your own machine
2. Replace all instances of example inside the .plist files and the .plist file names with your username
3. Install Kanata
   brew install kanata
4. Install KaraninerDriverKit
   bash ./scripts/kanata/KaraninerDriverKit.sh install

Click "Open System Settings"


5. Move LaunchDaemons to correct directory
bash ./scripts/kanata/SetupDaemons.sh install

Follow the additional setup instructed in output

Uninstall

bash ./scripts/kanata/KaraninerDriverKit.sh uninstall
bash ./scripts/kanata/SetupDaemons.sh uninstall
brew uninstall kanata