Bitfocus AS
logo
logo
Bitfocus AS
logo
logo

Loading...

Bitfocus

Subscribe to our newsletter

The latest news, articles, and resources, sent to your inbox.

FacebookInstagramGitHubYouTubeLinkedIn

Products

  • Buttons
  • Companion

Integrations

  • Supported Devices
  • Developer Community
  • Connection Development

Support

  • Support Overview
  • Documentation
  • Video Tutorials
  • Community Forum

Sales

  • Resellers & Integrators
  • Buttons Pricing

Updates

  • Case Studies
  • Events & Trade Shows
  • Press Releases
  • Product Updates
  • Webinars

Legal

  • Legal Overview
  • Privacy Policy
  • Buttons EULA
  • Terms & Cookie Policy

Company

  • About us
  • Press kit
  • Careers
Co-funded by the European Union

Our Bitfocus Workflow 2.0 project is co-funded by the European Union’s Creative Europe programme. About the project

© 2026 Bitfocus AS. All rights reserved.

Desktop app
Docs for
Overview
Getting started
What is Bitfocus Buttons?
Install Buttons and get started
Manage your Buttons license
Activate Buttons offline
Find your way around Buttons
Create your first backup
Add an ATEM connection
Choose a control method
Choose an installation path
Install Buttons on Debian or Ubuntu
Understand HA clustering
High Availability
Upgrade Buttons
Remove Buttons
Positions
Understand positions
Create a position
Add controls and sections to a position
Create your first button
Use a connection's presets
Build more capable button actions
Encoders
Add more feedback to a button
Organize controls in a section
Shift Section
Organize controls with a Folder Section
Add a Popover Section
Build and reuse a Shared Section
Show different controls by role
Choose a routing panel
Build a Router Section
Understand Custom Routers
Custom Router panel
Surfaces
Surface compatibility
Add and attach a surface
Device orientation
Connections
Update a connection's module safely
Monitor and troubleshoot a connection
Port forwarding (HA)
Router integrations
VideoHub and AJA KUMO
Utah Scientific BPS
Generic SW-P-08
Nevion VideoIPath
Arkona BLADE//runner
Evertz Quartz
Imagine LRC
Riedel MediorNet
Nevion MRP
Ross Video NK router
TAG Video Systems MCS
Routing
Physical routing
Configure ports and labels
Take a physical route
Understand route status
Topology graph
Routing Presets
Get started with virtual routing
Configure Nested Shapes
Reverse routing
Tielines
Routing Projects
Routing settings
Troubleshoot a route
NMOS
Understand NMOS in Buttons
Connect Buttons to an NMOS Registry
Built-in Registry Server
Configure NMOS connections
Discover and adopt
Browse the NMOS inventory
Manage NMOS multicast addresses
Diagnose NMOS problems
Understand Cuelists
Build a Cuelist
Read and advance a running Cuelist
Control a Cuelist from a Position
Workflows
Understand workflows
Build your first workflow
Encoders
Reuse a group of workflow nodes safely
Port forwarding (HA)
Troubleshoot a workflow
Recipes
Sequence a timed automation
Call an HTTP endpoint from a workflow
REST endpoint
Use variables
Understand variable scope
Understand nested variables
Update expressions for v1.8
Plan and use Tags
Access
Create and manage users
Create roles and assign permissions
Grant access to specific resources
Set up PIN and NFC sign-in
SSO
Get started with SSO
Connect a generic OIDC provider
Connect LDAP or Active Directory
Map identity claims to roles
Secure a Buttons deployment
Integrations
External control
Connect to Bitfocus Listener
USB Relay
Install USB Relay on Windows
Install USB Relay on macOS
Desktop app
Install USB Relay on Linux
Install USB Relay on a Raspberry Pi
Get started with the Control API
Secure and monitor the Control API
Control API reference
API reference
Administration
Enable and manage installable features
Services and health
Configure and monitor scheduled backups
Restore a backup and verify it
Export or import Buttons configuration
Store and rotate connection secrets
Replace the HTTPS certificate
HA backup and recovery
Settings
Collect support information
Reference
Glossary
Button Inspector reference
Network ports reference
Expressions
Internal actions reference
Custom Router button types
Startup configuration reference
Workflow nodes
Connection workflow nodes
Workflow variable and action nodes
Internal workflow nodes
Position workflow nodes
API workflow nodes
Utility workflow nodes

Loading...

Previous
← Install USB Relay on macOS
Next
Install USB Relay on Linux →
Contact support →
Buttons/Integrations/USB Relay/Desktop app

Desktop app

View as Markdown
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.
Linux and a Raspberry Pi do not have this app. Install the service instead: Install USB Relay on Linux.
Do not run the desktop app and the headless relay at the same time. Both listen on port 3040, and only one of them can.

Choose server or client#

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.

See the Stream Decks#

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.

Start when you log in#

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.

Relay ID#

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

If you get stuck#

What you see
What to try
The banner says Connection error in client mode.
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.

Where to go next#

  • Install USB Relay on Windows
  • Install USB Relay on macOS
  • Add and attach a surface

Was this helpful?

Was this helpful?

0 of 0 users found this page helpful