Skip to main content
Sign in

Bitfocus Buttons USB-Relay Mac

Per Røine
  • Updated

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.

  1. Open System Settings > Users & Groups.

  2. Locate "Automatically log in as" and select your primary account.

  3. 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.

  1. Open Terminal (Applications > Utilities).

  2. Create the configuration file:

     
    sudo nano /Library/LaunchAgents/com.bitfocus.usb-relay.plist

  3. Paste this exact XML:  To run USB relay in server mode it will announce it self with mdns

    <?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>

  4. Save and Exit: Press Ctrl+O, Enter, then Ctrl+X.

     

  5. 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) 

    <?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.

  1. Set System Ownership

     
    sudo chown root:wheel /Library/LaunchAgents/com.bitfocus.usb-relay.plist
     
    sudo chmod 644 /Library/LaunchAgents/com.bitfocus.usb-relay.plist

  2. 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.

  1. Load the relay:

    launchctl 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:

launchctl 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:

tail -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:

launchctl 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:

xattr -d com.apple.quarantine /usr/local/bin/bitfocus-buttons-usb-relay-headless

5. Full Service Removal

To completely remove the autostart configuration:

sudo launchctl bootout gui/$(id -u) /Library/LaunchAgents/com.bitfocus.usb-relay.plist

 

sudo 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.

Related to

Related articles

ß