Home Assistant on Proxmox: Zigbee and Thread USB Passthrough

Quick Summary (TL;DR):
Running Home Assistant OS as a Proxmox VM works very well with Zigbee, Thread and Z-Wave USB radios, but the radio must be passed from the Proxmox host into the HAOS virtual machine. The cleanest setup is to identify the adapter on the Proxmox host with lsusb, add it to the Home Assistant VM under Hardware → Add → USB Device, and bind it either by vendor/product ID or by a specific physical USB port. Vendor/product mapping is convenient when the device is unique; physical-port mapping is safer when you have two identical adapters with the same USB IDs. Inside Home Assistant, verify the radio under hardware before configuring ZHA or the OpenThread Border Router App. For Zigbee and Thread, use separate radios: Home Assistant Connect ZBT-2 can run Zigbee or Thread, but not both simultaneously. Use a short USB extension cable to move 2.4GHz radios away from USB 3.x noise and the mini-PC chassis. If you plan to migrate Home Assistant VMs between Proxmox nodes, a network-connected Zigbee/Thread adapter is often cleaner than host USB passthrough because a physical USB radio remains tied to one node.

What USB Passthrough Actually Does

When Home Assistant OS runs directly on a mini PC, the operating system can see a Zigbee, Thread or Z-Wave USB adapter as soon as you plug it into the machine. With Proxmox, the hardware path is different.

USB radio
    ↓
Proxmox VE host
    ↓
USB passthrough
    ↓
Home Assistant OS VM
    ↓
ZHA / OpenThread Border Router / Z-Wave

The Proxmox host sees the physical USB device first. You then assign that device to the Home Assistant VM so HAOS can use it.

What You Need Before Starting

• A working Proxmox VE host.
• A Home Assistant OS VM using the official KVM/Proxmox image.
• A supported Zigbee, Thread or Z-Wave USB radio.
• A spare physical USB port.
• A short USB extension cable for 2.4GHz Zigbee/Thread adapters.
• Administrator access to the Proxmox web interface or shell.
• A current Home Assistant backup before changing an existing radio setup.

If you have not yet decided whether Proxmox is appropriate, read Home Assistant OS vs Docker vs Proxmox first. A dedicated Home Assistant mini PC is simpler with HAOS installed directly on the hardware.

Use Separate Radios for Zigbee and Thread

Home Assistant Connect ZBT-2 supports either Zigbee or Thread. Home Assistant explicitly recommends dedicating one adapter to each protocol rather than attempting simultaneous multiprotocol operation on the same radio.

USB adapter 1 → Zigbee coordinator
USB adapter 2 → Thread radio / OpenThread Border Router

You may not need a Home Assistant Thread radio if your home already has suitable Apple, Google or other Thread border routers. But if you want Home Assistant to provide its own OpenThread border router, use a dedicated Thread-capable adapter.

Our existing guide covers the official adapter in more detail: Home Assistant Connect ZBT-2: Zigbee.

Identify the USB Radio on the Proxmox Host

Plug the coordinator into the Proxmox machine, open the node shell or connect over SSH, and run:

lsusb

A typical result might look like:

Bus 001 Device 005: ID 10c4:ea60 Silicon Labs CP210x UART Bridge

The hexadecimal pair after ID is the USB vendor/product pair. Your values will be different, so do not copy the example blindly.

Add the Radio in the Proxmox Web Interface

1. Open the Proxmox web interface.
2. Select the Home Assistant VM.
3. Open Hardware.
4. Select Add.
5. Select USB Device.
6. Choose the USB radio.
7. Confirm the assignment.
8. If it does not appear cleanly inside HAOS, shut down and start the VM again.

After the VM boots, Home Assistant should see the USB serial device as if it were connected directly to HAOS.

Configure USB Passthrough from the CLI

Proxmox’s qm tool can assign a host USB device to a QEMU VM. Using a vendor/product pair:

qm set <VMID> --usb0 host=<vendor_id>:<product_id>

Example:

qm set 104 --usb0 host=10c4:ea60

A second radio can be added as usb1:

qm set 104 --usb1 host=<vendor_id>:<product_id>

Vendor/Product Mapping vs Physical-Port Mapping

Mapping method	Example	Best use	Weakness
Vendor/product ID	10c4:ea60	One unique adapter of that type	Two identical devices may share the same IDs
Host bus/port	1-2.3	Multiple identical USB devices	Radio becomes tied to that physical port/node

Proxmox documents host USB passthrough using either vendor/product ID or the physical host bus/port path. If two radios report the same vendor/product IDs, physical-port mapping can be clearer.

qm set 104 --usb0 host=1-2.3

The actual path depends on your mini PC’s USB topology. Treat the value above as syntax only.

Do Not Rely on the Changing USB Device Number

lsusb may show a temporary value such as Bus 001 Device 005. The device number can change after unplugging the adapter or rebooting the host.

For persistent configuration, use the Proxmox USB assignment, vendor/product mapping or the physical host port path rather than treating the temporary device number as a permanent identity.

Verify the Adapter Inside Home Assistant OS

1. Open Home Assistant.
2. Go to Settings → System → Hardware.
3. Open the full hardware list.
4. Look for the USB serial adapter.

Depending on the adapter, HAOS may expose paths such as /dev/ttyUSB0, /dev/ttyACM0 or a persistent entry under /dev/serial/by-id/.

When an integration or App lets you select a persistent device path, a unique /dev/serial/by-id/ path is preferable to assuming that ttyUSB0 will always refer to the same radio.

Set Up Zigbee with ZHA

Home Assistant’s ZHA integration supports Connect ZBT-2 and several tested third-party coordinators.

1. Pass the Zigbee adapter through to the HAOS VM.
2. Confirm HAOS sees the device.
3. Go to Settings → Devices & services.
4. Add or configure Zigbee Home Automation (ZHA).
5. Select the passed-through coordinator.
6. Complete the radio setup.

If you are replacing an existing coordinator, use the migration procedure supported by your Zigbee software rather than deleting the integration and rebuilding the mesh unless that is genuinely necessary.

Use a USB Extension Cable for Zigbee

Do not plug a 2.4GHz Zigbee coordinator directly against the mini-PC chassis if you can avoid it. USB 3.x electronics, SSDs and the metal chassis can create local interference. A short extension cable moves the antenna away from the computer and usually improves placement.

Set Up a Thread Radio in HAOS on Proxmox

Thread normally uses the radio through the OpenThread Border Router App.

1. Make sure the adapter is running Thread/OpenThread firmware rather than Zigbee firmware.
2. Pass the USB device through to the HAOS VM.
3. Verify the adapter appears in Home Assistant hardware.
4. Go to Settings → Apps.
5. Install OpenThread Border Router.
6. Open the App configuration.
7. Select the passed-through radio under Device.
8. Set the baud rate required by the adapter.
9. Start or restart the App and check its logs.
10. Open the Thread integration and verify that the border router/network appears.

Home Assistant’s current Thread guidance says that if the manufacturer’s baud rate is unknown, 460800 is the default starting point for compatible third-party adapters. Follow the adapter manufacturer’s instructions where available.

Connect ZBT-2: Zigbee or Thread, Not Both

Home Assistant Connect ZBT-2 can run Zigbee or Thread, but Home Assistant does not recommend simultaneous multiprotocol operation.

ZBT-2 #1 → Zigbee
ZBT-2 #2 → Thread

Alternatively, use one ZBT-2 for Zigbee and an existing compatible Apple, Google or other Thread border router for Thread.

Thread Network Credentials Are Managed by Home Assistant

Home Assistant’s current Thread documentation explains that a Home Assistant-managed Thread network is managed by Home Assistant rather than being stored solely on the adapter. When migrating a compatible Thread radio, Home Assistant can continue using the existing Thread network credentials and migrate the OpenThread Border Router settings.

Create a current Home Assistant backup before changing Thread hardware anyway.

Matter-over-Thread Also Depends on Your LAN

Passing the Thread radio into HAOS is only one part of a Matter-over-Thread deployment. The border router also bridges the Thread mesh to the local IPv6 network.

Home Assistant’s Matter guidance recommends compatible local network placement and warns that multicast/discovery restrictions can cause commissioning or control problems. If Zigbee works but Matter-over-Thread does not, USB passthrough may not be the cause.

Two Identical USB Radios

Two identical adapters can advertise the same USB vendor/product IDs. For example:

Zigbee radio → 10c4:ea60
Thread radio → 10c4:ea60

In that situation, physical-port mapping is clearer. Dedicate one host socket to Zigbee and another to Thread, and label the cables or ports.

USB Passthrough and Proxmox Clusters

A local USB device physically belongs to one Proxmox node. Proxmox documents that host USB passthrough prevents transparent online movement of the VM to another node because the hardware remains attached to the original host.

HAOS VM can move
USB Zigbee radio cannot move by itself

If high availability or frequent VM migration is part of your design, local USB passthrough is not ideal.

When a Network Zigbee or Thread Adapter Is Better

A network-connected coordinator separates the radio from the Proxmox host. Depending on the supported hardware and integration, this can improve:

• Radio placement.
• VM mobility.
• PoE deployment.
• Separation from USB 3.x interference.
• Independence from one physical USB socket.

It also adds network dependencies. Our planned comparison covers that choice separately: USB Passthrough vs Network Zigbee and Thread Adapters for Proxmox.

Troubleshooting: The USB Radio Does Not Appear

1. Run lsusb on the Proxmox host and confirm the host sees the radio.
2. Open the HAOS VM hardware page and confirm the USB device is assigned.
3. Make sure another VM is not using the same physical device.
4. Restart the HAOS VM after changing the assignment.
5. Check Home Assistant’s hardware list.
6. Only after HAOS sees the radio should you troubleshoot ZHA or OpenThread Border Router.

If the Proxmox host cannot see the radio, the problem is below Home Assistant. Check the cable, extension, USB port and device power first.

Troubleshooting: OpenThread Border Router Will Not Start

• Verify the adapter is running OpenThread firmware.
• Select the correct serial device.
• Use the correct baud rate.
• Check the App logs.
• Toggle the hardware-flow-control option if the App cannot communicate with the radio.

Do not troubleshoot Matter commissioning until the OpenThread Border Router is healthy and visible in the Thread integration.

Back Up Before Radio Migration

• Create a current Home Assistant backup.
• Store a copy away from the Proxmox SSD.
• Record which physical radio is Zigbee and which is Thread.
• Record the Proxmox VM ID and USB mapping.
• Do not delete integrations simply because a serial path has changed.

A Practical Proxmox Radio Layout

Proxmox mini PC
│
├── HAOS VM
│   ├── usb0 → Zigbee coordinator
│   └── usb1 → Thread coordinator
│
├── Other VM/LXC workloads
│
└── Ethernet → LAN

Put both 2.4GHz radios on short USB extension cables and physically separate them from each other and from the mini PC where practical.

When Direct HAOS Is Still Better

If the mini PC exists only for Home Assistant and you do not need other VMs, Proxmox adds little value to the radio setup. Direct HAOS gives you direct USB access, fewer reboot dependencies and less infrastructure to maintain.

Use Proxmox because you want a multi-service server, not because Home Assistant itself needs virtualisation.

Home Assistant on Proxmox USB Passthrough: The Bottom Line

USB passthrough is reliable when you treat the radio as infrastructure rather than a disposable USB peripheral.

Identify the adapter correctly, use a persistent Proxmox mapping, keep Zigbee and Thread on separate radios, use extension cables for 2.4GHz coordinators, and create Home Assistant backups before changing hardware.

Vendor/product mapping is convenient for unique radios. Physical-port mapping is useful for identical devices. Both approaches tie the radio to the physical Proxmox node, so network-connected coordinators become attractive when VM mobility or radio placement matters more than USB simplicity.

Continue the Home Server Series

• Home Assistant OS vs Docker vs Proxmox
• Best Mini PCs for Proxmox and Multiple Virtual Machines
• USB Passthrough vs Network Zigbee and Thread Adapters for Proxmox

Datasheets & External Resources

• Home Assistant – KVM/Proxmox HAOS installation
• Home Assistant – Zigbee Home Automation (ZHA)
• Home Assistant – Thread and OpenThread setup
• Home Assistant – OpenThread Border Router integration
• Home Assistant Connect ZBT-2 – Official product and protocol guidance
• Home Assistant – Matter networking requirements
• Proxmox VE Administration Guide – USB passthrough