This guide provides the workflow for setting up the Bitfocus Buttons USB-Relay on a macOS machine. We will use the Global LaunchAgent method, which ensures the relay starts for any user who logs in and has the necessary permissions to access physical Stream Deck hardware.
Phase 1: Enable Automatic Login# Since a LaunchAgent requires an active user session to access USB hardware, your Mac must bypass the login screen after a reboot.
Open System Settings > Users & Groups . Locate "Automatically log in as" and select your primary account. Troubleshooting: If the option is greyed out:Go to Privacy & Security > FileVault and turn it OFF . Automatic login is incompatible with FileVault. Ensure the account uses a "Local Password" rather than just an iCloud login. Phase 2: Create the Global LaunchAgent# This configuration tells macOS to run the relay as a background service for any active user.
Open Terminal (Applications > Utilities).
Create the configuration file:
Copysudo nano /Library/LaunchAgents/com.bitfocus.usb-relay.plist
Paste this exact XML: T o run USB relay in server mode it will announce it self with mdns
Copy<? 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.bitfocus.usb-relay</ string >
< key >ProgramArguments</ key >
< array >
< string >/usr/local/bin/bitfocus-buttons-usb-relay-headless</ string >
</ array >
< key >RunAtLoad</ key >
< true />
< key >KeepAlive</ key >
< true />
< key >StandardErrorPath</ key >
< string >/tmp/bitfocus-usb.err</ string >
< key >StandardOutPath</ key >
< string >/tmp/bitfocus-usb.out</ string >
</ dict >
</ plist > Save and Exit: Press Ctrl+O, Enter, then Ctrl+X.
Or use this XML: if you want to run the USB relay as a client you need to point it to your Buttons server (edit the ip and port in the XML)
Copy<? 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.bitfocus.usb-relay</ string >
< key >ProgramArguments</ key >
< array >
< string >/usr/local/bin/bitfocus-buttons-usb-relay-headless</ string >
< string >-buttonsAddress</ string >
< string >'your buttons server ip':'your server port'</ string >
</ array >
< key >RunAtLoad</ key >
< true />
< key >KeepAlive</ key >
< true />
< key >StandardErrorPath</ key >
< string >/tmp/bitfocus-usb.err</ string >
< key >StandardOutPath</ key >
< string >/tmp/bitfocus-usb.out</ string >
</ dict >
</ plist >
Phase 3: Permissions & Security# Global services require specific ownership to be trusted by macOS.
Set System Ownership
Copysudo chown root:wheel/lLbrary/LaunchAgents/com.bitfocus.usb-relay.plist Copysudo chmod 644 /Library/LaunchAgents/com.bitfocus.usb-relay.plist Grant Hardware Access (Crucial):
Go to System Settings > Privacy & Security > Input Monitoring .
Click the + button.
Press Cmd + Shift + G, type /usr/local/bin/, and hit Enter .
Select bitfocus-buttons-usb-relay-headless and click Open .
Ensure the toggle is ON.
Phase 4: Activation# Start the service in your current session.
Load the relay:
Copylaunchctl bootstrap gui/ $( id -u ) /Library/LaunchAgents/com.bitfocus.usb-relay.plist
Phase 5: The Maintenance Toolkit# Use these commands to monitor and troubleshoot your relay station.
1. The Health Check# Verify the process is alive. A number in the first column is the PID (Process ID), which confirms it is running:
Copylaunchctl list | grep bitfocus
2. Live Log Monitoring# Watch the relay's internal messages. This will show you when Stream Decks are connected or if there is a network error:
Copytail -f /tmp/bitfocus-usb.out
3. The "Hardware Kick"# If the relay stops responding to button presses or you've plugged in a new device, force a restart without rebooting the Mac:
Copylaunchctl kickstart -k gui/ $( id -u ) /com.bitfocus.usb-relay
4. Verify Privacy Status# If the logs show "Permission Denied" but the program is running, run this to see if macOS is "quarantining" the binary:
Copyxattr -d com.apple.quarantine /usr/local/bin/bitfocus-buttons-usb-relay-headless
5. Full Service Removal# To completely remove the autostart configuration:
Copysudo launchctl bootout gui/ $( id -u ) /Library/LaunchAgents/com.bitfocus.usb-relay.plist Copysudo rm /Library/LaunchAgents/com.bitfocus.usb-relay.plist
Pro Tip: If you are running this on a headless Mac Mini, it is highly recommended to use a "HDMI Dummy Plug" or "Ghost Adapter." This forces macOS to fully initialize the WindowServer and Graphics drivers, which leads to much more stable USB performance for Stream Decks.