On Windows and macOS, USB Relay can run as the Bitfocus USB Relay app instead of a background service. The app has a menu bar icon on macOS and a system tray icon on Windows. Closing the window hides it. The relay keeps running until you choose Quit.
Server is the usual choice. The app waits for Buttons and announces itself on the network, so Buttons can discover it. The banner says Listening, and Connection says Listening for Buttons. The address under that line is this computer's name, on port 3040, with the path /ws.
The name in that picture stands in for this computer's own name.
Client is for a network that does not allow discovery. The app connects out to a Buttons machine you name. Choose Client, type the address, and select Save. The field accepts a host name, host:port, or a full wss:// address. The placeholder reads hostname, host:port, or wss://…. The app turns what you type into the relay address, which ends in /usb-relay.
Server certificate says Accepted on the first connection until a connection succeeds. After that it says Remembered certificate, or System-trusted certificate when the system already trusts it. Forget drops a remembered certificate so the next connection can accept a new one. Forget stays unavailable while the app is connected.
The address in that picture is an example, which is why the banner still says Connecting. When Buttons answers, the banner says Connected. Under Connection, server mode then says Buttons connected, and client mode says Connected to Buttons.
USB devices lists the Stream Decks plugged into this computer. With none plugged in it says No USB devices connected. Each device shows its product name, and under that the manufacturer, serial number, and USB ids.
Buttons still has to adopt the relay and the surfaces. See Add and attach a surface. The relay appears in the discovered list as USB Relay.
Under Startup, turn on Start USB Relay when you log in. That starts the app after you sign in to this account. It does not run while the computer is sitting at the login screen. On a Mac that should come back with nobody signing in, set automatic login as described in Install USB Relay on macOS.
The bottom of the window shows Relay ID, and the button beside it copies that id. Buttons uses it to tell one relay from another. The copied text starts with relay:.
Check the address under Server address, select Save again, and confirm Buttons is reachable on that host and port.
The app stays on Connecting.
Buttons is not answering at that address. Confirm the host, the port, and that no firewall is blocking it.
A Stream Deck is plugged in, but the list says No USB devices connected.
On macOS, allow Bitfocus USB Relay under System Settings → Privacy & Security → Input Monitoring.
Buttons replaced its HTTPS certificate and the app will not reconnect.
Under Server certificate, select Forget, then let it connect again. The next connection accepts the new certificate.
Buttons cannot discover the relay.
Leave the app in Server with the banner on Listening, and confirm both machines are on a network that allows discovery. If they are not, switch to Client and enter the Buttons address.
The relay and a headless install fight over the port.
Quit one of them. The desktop app and the headless relay both use port 3040.
