USB Relay lets a Stream Deck plugged into a Windows PC show up in Buttons as a network surface, even though it isn't physically attached to the machine running Buttons. Once running, Buttons discovers it and any Stream Deck attached to it, and you adopt them the same way as any other surface.
The installer offers two ways to run it.
Desktop app is selected by default: that is
Bitfocus USB Relay, with a system tray icon.
Headless Windows service runs it in the background instead. Do not run both at once. Both use port
3040.
Before you begin#
- The Windows PC has any Stream Deck hardware you want to relay plugged in.
- Network connectivity between this PC and your Buttons installation.
- A Buttons license above the free tier: adopting a USB Relay surface requires at least an Individual-tier license.
Install#
- Download the Windows installer and run it. The installer needs administrator rights.
- Accept the license agreement.
- On the components page, leave Desktop app selected. Its description is "The Bitfocus USB Relay app, with a system tray icon".
- Select Headless Windows service only when you want a background service instead of the app. Its description says not to run both at once.
- Leave Add Firewall Rules selected.
- Select Install. When only the desktop app was installed, the finish page can Start Bitfocus USB Relay.
Note
Upgrading a PC that already has the Windows service keeps Headless Windows service selected, and leaves Desktop app unselected unless the app was already installed.
Run the Windows service#
If you selected Headless Windows service, it is already running. No further action needed.
By default the service runs in server mode: it listens on port 3040 and announces itself on the network so Buttons can find it automatically. No further configuration is needed for this.
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 PC available to adopt, either from the relay's own settings or back in the main Surfaces list.
Manage the service#
- Check or change startup behavior: open
services.msc (press Win+R, type services.msc), find Bitfocus Buttons USB-Relay, and use its Properties to change the startup type or start/stop it manually. - Reinstall or remove just the service registration:
bitfocus-buttons-usb-relay-headless.exe accepts install-service, uninstall-service, start-service, stop-service, and status-service. These manage the Windows service without reinstalling the whole application. Reinstalling the service this way is safe to repeat; it replaces any existing registration rather than failing. The desktop app does not take these commands. - Fully remove USB Relay: use Windows' own Add or remove programs.
For the Windows service, add -buttonsAddress <ip>:<port> by reinstalling the service with that flag included.
Note
There's no separate flag to change the relay's own listening port; it only changes via an environment variable (USB_RELAY2_PORT) if you genuinely need something other than the default.
If you replace Buttons' own HTTPS certificate (see
Replace the HTTPS certificate) while a relay is already connected outbound to it, the relay notices the certificate no longer matches what it trusted before and refuses to reconnect, to protect against a silently swapped server. In the desktop app, select
Forget under
Server certificate, then let it connect again. For the Windows service, add
-accept-cert-change once so it trusts and remembers the new certificate.
If you get stuck#
What you see | What to try |
|---|
The relay doesn't appear in Buttons' discovered surfaces. | For the desktop app, confirm the banner says Listening. For the service, check services.msc. Both machines need a network that supports discovery. |
The relay reports that it cannot multicast. | The relay can't broadcast itself on the network, usually due to a Public network profile, VPN, or a corporate network that blocks discovery traffic. Skip discovery and connect outbound: see Connect outbound to a specific Buttons address above. |
You need it to connect outbound instead of waiting to be discovered. | In the desktop app, choose Client and save the Buttons address. For the service, reinstall it with -buttonsAddress <ip>:<port>. |
The relay refuses to reconnect after you replaced Buttons' HTTPS certificate. | In the desktop app, select Forget under Server certificate. For the service, run it once with -accept-cert-change if the change was intentional. |
You want to change which port the relay listens on. | Set the USB_RELAY2_PORT environment variable: there's no command-line flag for this. |
Where to go next#
