Install USB Relay on Linux

USB Relay lets a Stream Deck plugged into a Linux machine show up in Buttons as a network surface, even though it isn't physically attached to the machine running Buttons. The Linux package installs and manages it as a systemd service: this is also the shared foundation for running USB Relay on a Raspberry Pi.

Before you begin#

An amd64 or arm64 Linux machine (these are the only supported architectures) with any Stream Deck hardware you want to relay plugged in.
A Buttons license above the free tier: adopting a USB Relay surface requires at least an Individual-tier license.

Install#

Double-click the downloaded .deb file on a desktop system, or install it from a terminal:

sudo apt install ./bitfocus-buttons-usb-relay-headless_*.deb

The installer:

Installs the program files.
Creates a dedicated buttons system user.
Installs udev rules so USB devices are accessible without running as root.
Enables and starts the bitfocus-buttons-usb-relay systemd service.

By default it runs in server mode: it listens on port 3040 and announces itself on the network so Buttons can find and adopt it automatically. No further configuration is needed for this.

Check it's running#

systemctl status bitfocus-buttons-usb-relay
journalctl -u bitfocus-buttons-usb-relay -f

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 machine available to adopt.

Connect outbound to a specific Buttons address#

If you can't rely on automatic discovery, point the relay at your Buttons installation directly instead. Edit /etc/default/bitfocus-buttons-usb-relay:

EXTRA_ARGS="-buttonsAddress 192.168.1.10:3000"

Then restart the service:

sudo systemctl restart bitfocus-buttons-usb-relay

Note

There's no flag to change the relay's own listening port; set the USB_RELAY2_PORT environment variable instead if you genuinely need something other than the default 3040.

Manage the service#

sudo systemctl stop bitfocus-buttons-usb-relay
sudo systemctl start bitfocus-buttons-usb-relay
sudo systemctl disable bitfocus-buttons-usb-relay   # don't start automatically on boot
sudo systemctl enable bitfocus-buttons-usb-relay    # start automatically on boot

Uninstall#

sudo apt remove bitfocus-buttons-usb-relay-headless

To also remove the buttons system user and all service data:

sudo apt purge bitfocus-buttons-usb-relay-headless

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. Add -accept-cert-change to EXTRA_ARGS in /etc/default/bitfocus-buttons-usb-relay, restart the service once, then remove the flag again.

If you get stuck#

What you see	What to try
The relay doesn't appear in Buttons' discovered surfaces.	Confirm the service is active (`systemctl status bitfocus-buttons-usb-relay`) and that both machines are on a network that supports discovery.
`journalctl -u bitfocus-buttons-usb-relay` shows 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: see Connect outbound to a specific Buttons address above.
A Stream Deck plugged into this machine isn't detected.	Check `journalctl -u bitfocus-buttons-usb-relay -f` while plugging it in: udev rule installation issues usually show up here as a permission error.
You need it to connect outbound instead of waiting to be discovered.	Set `EXTRA_ARGS="-buttonsAddress <ip>:<port>"` in `/etc/default/bitfocus-buttons-usb-relay` and restart the service.
The relay refuses to reconnect after you replaced Buttons' HTTPS certificate.	Add `-accept-cert-change` to `EXTRA_ARGS` once, restart, then remove it again.

Where to go next#

Was this helpful?

0 of 0 users found this page helpful