If you already own a UGREEN NAS, buying a Raspberry Pi or an HA Green just to run Home Assistant feels like paying for hardware you don’t need. UGREEN clearly agrees. Home Assistant is now an officially featured app on UGOS Pro, the company’s own NAS operating system, and a growing pile of NAS-as-smart-home-host content covers the general install. What almost none of it covers is the one detail that actually decides whether Zigbee2MQTT works on this box: getting a USB Zigbee coordinator recognized reliably, and whether that happens through UGOS Pro’s Docker app center or a full virtual machine.
Before writing this, I went through UGREEN’s own NAS documentation and community forum, a Home Assistant GitHub issue from someone who hit this exact wall, and a separate Chinese-language writeup on the generic Docker USB behavior that’s biting people here. The short version: UGREEN documents USB device passthrough as a virtual-machine feature. It does not document it for the Docker app center. If you install the official Home Assistant Docker app expecting to plug in a Zigbee dongle the way you would on a Pi, you’re in undocumented territory, and the one confirmed real-world report of this failing doesn’t even give you an obvious error message to search for.
UGOS Pro’s two install paths: Docker app center vs. a full VM
UGOS Pro runs a Docker-based App Center and a separate virtual-machine subsystem as two distinct features, not two ways of doing the same thing. Home Assistant is listed as a “third-party featured app” (第三方精品应用) in the App Center, alongside Jellyfin and EasyNVR, as of UGREEN’s developer-platform launch in mid-2026. UGREEN’s own quick-start guide for the App Center install specifies a minimum NAS firmware of 1.2.0.2121 and a minimum Home Assistant app version of 1.0.0.3768.
Running Home Assistant OS as a full VM is the other path, and it’s an actively used one. Several 2026 Chinese-language walkthroughs (Zhihu, SMZDM) cover setting up a full HAOS VM on UGREEN hardware, some specifically for bridging Xiaomi/Mijia devices through the xiaomi_home plugin rather than Zigbee2MQTT. The tradeoff is straightforward on paper: a VM costs more RAM and CPU than a lightweight container, in exchange for the hardware access a VM gets by default.
| Path | USB passthrough documented? | Resource footprint | Where UGREEN documents it |
|---|---|---|---|
| Docker App Center | No — UGREEN’s passthrough guide only covers VMs | Light (single container) | App Center install guide only |
| Virtual machine (HAOS) | Yes — dedicated USB passthrough toggle | Heavier (full OS overhead) | VM subsystem + community forum guide |
The USB passthrough catch: why UGREEN documents this for VMs, not Docker
UGREEN’s own NAS community forum has a guide specifically on enabling USB device passthrough for virtual machines. It’s framed entirely around the VM subsystem, not the App Center.
One caveat on sourcing: that forum page is access-restricted and wouldn’t load directly, so this rests on the indexed description of its contents rather than the live page. Treat the VM-only detail as directionally right rather than fully confirmed. It lines up with two things I could check independently: everything else UGREEN documents about the App Center, and the community walkthroughs for this hardware, which only ever set USB passthrough up through the VM subsystem and never through the Docker app. But it’s the one fact in this piece that’s a step removed from a primary source, so I’m flagging it rather than stating it flat.
That same forum guidance describes two practical limits on VM-based passthrough. First, once a USB device is handed to a VM, the NAS host can’t use it at the same time. The safe sequence is ejecting or detaching it in the VM before switching contexts. Second, passthrough is tied to the specific USB bus and port the device is plugged into, so moving the dongle to a different port can mean reconfiguring the passthrough setting from scratch.
If you try the Docker route anyway: the USB renumbering trap
Nothing UGREEN-specific stops you from trying the standard approach Zigbee2MQTT installs use on a Raspberry Pi or any other Linux Docker host: pass the device straight into the container.
services:
zigbee2mqtt:
image: koenkk/zigbee2mqtt
devices:
- /dev/ttyUSB0:/dev/ttyUSB0
volumes:
- ./data:/app/data
Whether UGOS Pro’s App Center actually exposes a raw device-mapping field like the one above — versus only the Home Assistant app’s pre-configured settings — isn’t something I could confirm against a live UGOS Pro instance. Treat the compose snippet as the generic Docker pattern, not a guaranteed in-GUI option on this platform.
Even if the App Center lets you map the device this way, it inherits an ordinary Docker/Linux problem that has nothing to do with UGREEN specifically. Docker maps a USB device’s bus and device-number path, something like /dev/bus/usb/001/029, at the moment the container starts. Unplug and replug the same physical dongle, or reboot the host, and Linux can assign it a new number. Anything hardcoded to the old path silently stops working, with no obvious error pointing back at the real cause.
The documented fix is a udev rule that creates a stable symlink tied to the device’s vendor and product ID rather than its bus position, so the path doesn’t change no matter which physical port or renumbering event happens next. Home Assistant’s own ecosystem has a version of this built in already, the /dev/serial/by-id/... path, which is worth pointing your configuration at instead of a raw /dev/ttyUSB0 reference from the start.
SUBSYSTEM=="tty", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea60", SYMLINK+="zigbee_coordinator"
That’s a generic Linux fix, not something I’ve confirmed against a UGOS Pro shell specifically — and whether the App Center’s containerized environment even gives you enough host access to write that udev rule is an open question here. It’s another reason to prefer the /dev/serial/by-id/... path pointed at from inside the container or VM: it doesn’t depend on host-level config that a locked-down NAS OS might reset on its own.
If you go the VM route: what the passthrough toggle does and doesn’t do
The VM path at least has an official mechanism behind it: a dedicated USB passthrough toggle in UGOS Pro’s VM settings, built for exactly this use case. Once passed through, the dongle behaves inside the HAOS VM the same way it would on bare-metal Linux. Zigbee2MQTT or ZHA sees it as a normal serial device.
The two limits from the forum guidance still apply here, and they matter more on a VM than they would on a Pi you don’t share with anything else. If the NAS host tries to grab the same USB port for another purpose while it’s passed through, you’ll need to detach it from the VM first. And if you ever move the dongle to a different physical port, expect to redo the passthrough configuration rather than have it just reappear.
A real failure case: the “serial port locked” error
A Home Assistant GitHub issue documents exactly this kind of setup going wrong. Someone passed a ConBee 2 Zigbee dongle through to a VM running on a UGREEN NAS and hit a ZHA setup failure reading “the serial port is locked by another application.”
That’s a genuinely unhelpful message to troubleshoot from cold. It doesn’t say “device not found,” which would at least point you toward a passthrough or driver problem. “Locked by another application” reads like something else on the system grabbed the port first, which is consistent with a stale device-path reference, a passthrough handoff that didn’t fully release, or another process still holding the serial connection open, but the message alone doesn’t tell you which. The GitHub issue is unresolved as of writing, a bug report rather than a guide, but it’s real confirmation that this specific pain point shows up on this specific platform and not just in theory. If you hit unexplained device drops after getting this far, our Zigbee2MQTT ghost-device troubleshooting guide covers the more common Zigbee-mesh-side causes worth ruling out alongside the passthrough angle.
If ZHA or Zigbee2MQTT reports a locked or busy serial port on a UGREEN NAS VM, check the device path first (has it been unplugged and replugged, or has the NAS rebooted since setup) before assuming the dongle itself has failed.
A simpler alternative: skip USB passthrough entirely
Everything above only matters because a USB Zigbee coordinator has to physically attach to something. A networked coordinator, one that connects over Ethernet or PoE instead of USB, sidesteps the entire Docker-vs-VM passthrough question. The SMLIGHT SLZB-06 Ethernet coordinator is one option built specifically for this, and it turns “does my NAS support USB passthrough” into a non-question because there’s no USB device to pass through in the first place.
Honestly, if I were setting this up today on a NAS I didn’t already own a coordinator for, I’d buy the networked option and skip this whole decision tree. The extra cost over a bare USB dongle buys back an entire category of platform-specific troubleshooting that has nothing to do with Zigbee itself. If you’re still comparing USB coordinator options for other reasons, our Sonoff ZBDongle-E vs ZBDongle-P comparison covers the two most common ones.
It’s also worth separating this from a different UGREEN-supported product entirely: Sonoff’s own eWeLink CUBE hub software also officially supports UGREEN NAS models as a host, running in a VM with a stated 4GB RAM minimum and its own list of tested dongles. That’s not Home Assistant and not Zigbee2MQTT in the sense this article covers. It’s a different, closed hub product that happens to run on the same hardware, worth knowing about only so you don’t confuse a CUBE tutorial with a Home Assistant one.
Which UGREEN models and firmware this applies to
The Chinese-language tutorials I checked cover this across several current UGREEN lines: the DX4600 and DX4600 Pro, the DH2600, and the DXP2800/DXP4800 series, all running UGOS Pro. The App Center’s Home Assistant listing itself requires firmware 1.2.0.2121 or newer.
If you’re coming at this from a general “run Home Assistant on my NAS” search, it’s worth knowing that HowToGeek’s 2026 piece on NAS-as-smart-home-host features UGREEN models by name and recommends the same class of USB Zigbee dongles covered here, but it doesn’t address Docker-vs-VM passthrough at all. That’s not a gap in that piece so much as a different scope; it’s a general recommendation, not a Zigbee2MQTT setup guide. And Home Assistant’s own documentation doesn’t call out UGREEN specifically either way. UGREEN is a third-party-supported platform through its own App Center and VM tooling, the same way any other Docker or VM host is, not an endorsed reference platform. If you found your way here through the Xiaomi/Mijia integration route rather than Zigbee2MQTT, our breakdown of Xiaomi’s official Home Assistant integration and what “local” actually means covers that separate integration path.
Frequently asked questions
Can I run Zigbee2MQTT on a UGREEN NAS?
Yes, either through the Docker App Center’s Home Assistant app or a full HAOS virtual machine. The catch is USB coordinator passthrough, which UGREEN documents for the VM path but not for Docker.
Does UGREEN NAS support USB passthrough for a Zigbee dongle?
For virtual machines, yes, through a dedicated toggle in UGOS Pro’s VM settings. For the Docker App Center, UGREEN’s own documentation doesn’t cover device passthrough at all.
Should I use Docker or a virtual machine for Home Assistant on a UGREEN NAS?
If you need a USB Zigbee coordinator, the VM path has an official passthrough mechanism behind it, at the cost of more RAM and CPU overhead. If you’re using a networked coordinator instead, or don’t need a USB dongle at all, the Docker App Center install is the lighter option with no passthrough question to solve.
Why does my Zigbee dongle stop working after I unplug and replug it?
Docker and Linux generally map USB devices by bus and device number, which can change on replug or reboot. A udev rule that creates a stable symlink by vendor/product ID, or pointing your configuration at the /dev/serial/by-id/... path instead, avoids the problem.
Is a UGREEN NAS good enough hardware to run Home Assistant and Zigbee2MQTT together?
Nothing in UGREEN’s own specs or the community reports checked for this piece suggests a hardware limitation for either the Docker or VM path. The open question on this platform is USB device handling, not raw CPU or RAM.
What this piece verifies, and what’s still unconfirmed
This is built from UGREEN’s own App Center and VM documentation, its community forum’s passthrough guide (one source flagged above as snippet-sourced rather than directly fetched), a Home Assistant GitHub issue documenting a real ConBee 2 failure on this exact platform, and a separate technical writeup on the generic Docker USB-renumbering behavior. No UGREEN NAS model and no Zigbee dongle has been tested on this platform for this piece. If a UGREEN NAS ever lands on this site’s test bench, confirming the App Center’s actual device-mapping options and reproducing the “serial port locked” failure firsthand would turn this from a documented-and-reported guide into a verified one.