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.
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.
- Accept the prompts and the license agreement.
- Leave Install and start as a Windows service checked (this is the default) if you want USB Relay to always run in the background and start automatically. Uncheck it if you'd rather start it manually yourself.
- Select Install, then Close once it finishes.
The installer also adds a firewall rule for the relay's network port.
Run it#
If you installed it as a service, it's already running: no further action needed. If you left the service option unchecked, launch the application yourself (a shortcut is created for this); a command-line window opens and stays open while it runs. Closing that window, or pressing Ctrl+C inside it, stops the relay.
By default, USB Relay runs in server mode: it listens for a connection 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: the installed application also accepts service-management commands directly; running it with
install-service, uninstall-service, start-service, stop-service, or status-service manages 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. - Fully remove USB Relay: use Windows' own Add or remove programs.
If your network doesn't support automatic discovery, point the relay at your Buttons installation directly instead of waiting to be discovered. Add -buttonsAddress <ip>:<port> when running it manually, or bake the flag into the service registration 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. If you changed the certificate intentionally, add
-accept-cert-change once to have the relay trust and remember the new one.
If you get stuck#
What you see | What to try |
|---|
The relay doesn't appear in Buttons' discovered surfaces. | Confirm it's actually running (check services.msc, or that its command-line window is still open), and that both machines are on a network that supports discovery. |
The relay's command-line window shows an error about being unable to 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 entirely by connecting it outbound: see Connect outbound to a specific Buttons address above. |
You need it to connect outbound instead of waiting to be discovered. | Add -buttonsAddress <ip>:<port> when running manually, or reinstall the service with that flag included. |
The relay refuses to reconnect after you replaced Buttons' HTTPS certificate. | This is expected protection against an unexpected certificate change: 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#
