# Install USB Relay on Linux

> Install the USB Relay .deb package as a systemd service so a Stream Deck plugged into a Linux machine appears in Buttons as a network surface.

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 Install USB Relay on a Raspberry Pi Add and attach a surface Manage your Buttons license