# Install USB Relay on macOS

> Install the Bitfocus USB Relay desktop app on an Apple Silicon Mac, or run the headless command with a LaunchAgent.

USB Relay lets a Stream Deck plugged into a Mac show up in Buttons as a network surface, even though it isn't physically attached to the machine running Buttons. The installer offers two components, and both are selected by default. Desktop app installs Bitfocus USB Relay in Applications, with a menu bar icon. Headless command line installs bitfocus-buttons-usb-relay-headless in /usr/local/bin , which you then keep running with a LaunchAgent. Do not run both at once. Both use port 3040 . Uncheck the one you do not want. Before you begin An Apple Silicon Mac (the current build targets Apple Silicon only) with any Stream Deck hardware you want to relay plugged in. Administrator access, to install the package and grant hardware permissions. A Buttons license above the free tier: adopting a USB Relay surface requires at least an Individual-tier license. Install Download the signed, notarized .pkg installer and run it. On the customization step, leave Desktop app selected to install Bitfocus USB Relay in /Applications . Leave Headless command line selected only if you also want bitfocus-buttons-usb-relay-headless in /usr/local/bin . Follow the installer through to completion. Open Bitfocus USB Relay from Applications. How to use the window is covered in Use the USB Relay desktop app . The app does not need the LaunchAgent below. The headless command does not set itself to keep running. That is the next part, and it applies only if you installed Headless command line . Set up automatic login Skip this if someone will sign in to the Mac and open Bitfocus USB Relay , or turn on Start USB Relay when you log in in the app. A relay that has to come back after a reboot with nobody at the keyboard needs an active user session, so the Mac has to sign in automatically rather than sitting at the login screen. Open System Settings → Users & Groups . Set Automatically log in as to the account this relay should run under. If that option is greyed out, turn off FileVault (Privacy & Security → FileVault) since automatic login is incompatible with it, and make sure the account has a local password rather than only signing in via iCloud. Run the headless command with a LaunchAgent Skip this section if you are using the desktop app. Open Terminal and create the LaunchAgent file: sudo nano /Library/LaunchAgents/com.bitfocus.usb-relay.plist Paste in the following to run in server mode (listens and announces itself so Buttons can discover it automatically): <?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> To connect outbound to a specific Buttons address instead of waiting to be discovered, add -buttonsAddress and the address as extra <string> entries inside ProgramArguments . Save and exit ( Ctrl+O , Enter, then Ctrl+X ). Set correct ownership: sudo chown root:wheel /Library/LaunchAgents/com.bitfocus.usb-relay.plist sudo chmod 644 /Library/LaunchAgents/com.bitfocus.usb-relay.plist Grant hardware access: open System Settings → Privacy & Security → Input Monitoring , select + , press Cmd+Shift+G , type /usr/local/bin/ , select bitfocus-buttons-usb-relay-headless , and make sure its toggle is on. For the desktop app, allow Bitfocus USB Relay in the same list if a plugged-in Stream Deck does not appear. Load it for your current session: launchctl bootstrap gui/$(id -u) /Library/LaunchAgents/com.bitfocus.usb-relay.plist Discover and adopt it in Buttons Once running, open Buttons and follow the normal discovery flow: see Add and attach a surface . The relay itself appears in the discovered list labeled USB Relay ; adopting it also makes any Stream Deck attached to that Mac available to adopt. Maintain it Check it's alive: launchctl list | grep bitfocus ; a number in the first column is its process ID. Watch its logs live: tail -f /tmp/bitfocus-usb.out Restart it without rebooting: launchctl kickstart -k gui/$(id -u)/com.bitfocus.usb-relay ; useful if it stops responding, or after plugging in a new device. Check for a quarantine flag if logs show permission errors despite the process running: xattr -d com.apple.quarantine /usr/local/bin/bitfocus-buttons-usb-relay-headless Remove it sudo launchctl bootout gui/$(id -u) /Library/LaunchAgents/com.bitfocus.usb-relay.plist sudo rm /Library/LaunchAgents/com.bitfocus.usb-relay.plist Then uninstall the package itself the same way you would any other installed software. If Buttons' certificate changes If you replace Buttons' own HTTPS certificate (see Replace the HTTPS certificate ) while a relay is already connected outbound to it, the relay refuses to reconnect until it's told to trust the new one. In the desktop app, select Forget under Server certificate , then let it connect again. For the headless command, add -accept-cert-change as an extra argument in the plist once, then remove it again afterward. If you get stuck What you see What to try The relay stops as soon as you log out. Confirm automatic login is set up: a LaunchAgent needs an active session to reach USB hardware, so it won't survive at the login screen. Logs show "Permission Denied" even though the process is running. Check whether macOS quarantined the binary ( xattr -d com.apple.quarantine ... ), and confirm Input Monitoring access is actually granted, not just requested. The relay doesn't appear in Buttons' discovered surfaces. Confirm it's actually running (`launchctl list \ grep bitfocus`) and that both machines are on a network that supports discovery. Its logs ( tail -f /tmp/bitfocus-usb.out ) show an error about being unable to multicast. The relay can't broadcast itself on the network, usually due to a VPN or a corporate network that blocks discovery traffic. Skip discovery entirely by connecting it outbound instead: see the -buttonsAddress step under Run the headless command with a LaunchAgent above. The relay refuses to reconnect after you replaced Buttons' HTTPS certificate. In the desktop app, select Forget under Server certificate . For the headless command, add -accept-cert-change to the plist's arguments once, reload it, then remove the flag again. USB performance is inconsistent on a headless Mac Mini. An HDMI dummy plug (sometimes sold as a "ghost adapter") can help: it forces macOS to fully initialize its graphics stack, which some setups need for stable USB behavior. Where to go next Use the USB Relay desktop app Add and attach a surface Manage your Buttons license
