ha-virtualhere-server

A Home Assistant add-on that runs the VirtualHere USB-over-IP server, letting another computer use a USB device plugged into your Home Assistant machine as if it were plugged in locally.

Built and tested moving a Logitech G935 wireless headset receiver onto a Home Assistant box and using it from a Windows gaming PC over wired Ethernet — audio, microphone and buttons all work.

Why you might want this

• Put a wireless dongle somewhere with a better RF path than behind your PC
• Keep a dongle powered and paired independently of your PC's power state
• Share one USB device between several machines
• Reach a USB device on a machine that lives in a rack or cupboard

Requirements

• Home Assistant OS with the Supervisor (this is a local add-on)
• amd64. For aarch64, change build.yaml to the matching base image and set VH_SERVER_BINARY=vhusbdarm64 in the Dockerfile
• A way to copy files to the host: the Samba or Advanced SSH & Web Terminal add-on, or HAOS debug SSH

The free VirtualHere server shares one device at a time with no time limit, which is all this needs. The client is free.

Install

Copy virtualhere-server/ into the host's local add-on directory (/addons via the Samba share, or /mnt/data/supervisor/apps/local/ over SSH), then in Home Assistant:

Settings → Add-ons → Store → ⋮ → Check for updates, and install VirtualHere USB Server under Local add-ons.

The Supervisor builds the image on the host; the first build pulls the Debian base and takes a few minutes.

deploy.ps1 automates the copy from Windows:

.\deploy.ps1 -HaHost homeassistant.local

Before starting the add-on, set ignored_devices. VirtualHere exposes every USB device on the host to any client on your network, and connecting one takes it away from Home Assistant. The shipped defaults are examples from one particular machine, not protection for yours. See virtualhere-server/README.md.

Client

Download the VirtualHere client from virtualhere.com. It finds the server by UDP broadcast on the same subnet; otherwise Add Server manually on port 7575. Right-click the device → Use.

For automatic reconnection after a reboot, set Auto-Use on the device and install the client as a service.

Notes from getting this working

• Debian base, not Alpine. The vhusbd binaries are glibc-linked. On musl they fail with a misleading not found.
• SYS_RAWIO is enough — no full_access needed — but apparmor: false is required, as the default profile blocks the usbfs ioctls VirtualHere uses to detach kernel drivers.
• run.sh must have LF line endings. CRLF gives /usr/bin/with-contenv^M: not found.
• EasyFind is off by default. VirtualHere silently enrolls new servers in its cloud relay, making them reachable from the public internet by ID and PIN. This add-on disables it and re-enforces that on every start, since VirtualHere re-adds the keys itself. Set enable_easyfind: true to opt in.
• HAOS has no sftp-server, so modern scp fails with Connection closed. deploy.ps1 passes -O for the legacy protocol.
• ha addons reload no longer reloads — addons is deprecated in favour of apps, and the command just lists. Use ha store reload.

USB audio over IP: expectations

USB audio is isochronous and timing-sensitive, unlike a keyboard or flash drive. It worked cleanly here with both machines on wired Ethernet. Over Wi-Fi, expect to tune Synchro Delay in the client (raise in ~5 ms steps until clicks stop), and accept that it may not be usable at all.

This moves the dongle, not the radio: it only improves wireless range if the Home Assistant machine has a better RF path to the device than your PC does. If it doesn't, an active USB extension cable or a USB-over-Cat5e extender solves the range problem directly, with no added latency.

Uninstall

Stop and uninstall the add-on in Home Assistant, then unplug the device. Nothing is modified outside the add-on directory.

License

MIT — see LICENSE. VirtualHere itself is proprietary and is downloaded from virtualhere.com at image build time; it is not redistributed here.