How to Install Home Assistant on UGREEN NASync

Quick Summary (TL;DR):
There are two sensible ways to run Home Assistant on a current x86 UGREEN NASync DXP model such as the DXP2800 or DXP4800 Plus. The easiest is Home Assistant Container using the Docker app in UGOS Pro. UGREEN officially supports Docker on current DXP models, and its Docker interface supports Compose Projects, so you can deploy the official ghcr.io/home-assistant/home-assistant:stable image with persistent /config storage and host networking. The trade-off is that Container does not include Home Assistant Supervisor or Apps, and you maintain updates and supporting services yourself. The second route is to import the official Home Assistant OS QCOW2 virtual disk into UGREEN’s Virtual Machine app. DXP models support virtual machines and UGREEN currently accepts QCOW2 images. This gives you the full HAOS experience with Supervisor and Apps, but needs more RAM and introduces VM networking and USB-passthrough complexity. If the HAOS VM must access a backup share on the same UGREEN NAS, use LinuxBridge, not MacVTap, because UGREEN documents that MacVTap guests cannot communicate directly with the NAS host.

Which Installation Method Should You Use?

Method	Home Assistant Container	HAOS Virtual Machine
UGREEN requirement	Docker-capable model	DXP model with Virtual Machine Manager
Supervisor	No	Yes
Home Assistant Apps	No	Yes
Backups	Yes	Yes
Updates	Container image/redeploy	Managed inside HAOS
USB radios	Docker device mapping	VM USB passthrough
Thread/Z-Wave experience	More manual	Normal HAOS Apps workflow
Best fit	Existing Docker user	User wanting the full HAOS experience

For most UGREEN NAS owners who already use Docker, Container is the more direct route. For users who specifically want Supervisor, Home Assistant Apps and the normal HAOS management model, use a VM.

Which UGREEN NASync Models Can Run Home Assistant?

UGREEN’s current software guidance separates models by application capability.

Current DXP models: Docker and Virtual Machine Manager.
DH4300 Plus: Docker, but no Virtual Machine Manager.
DH2300: no official Docker or Virtual Machine Manager support.

This guide focuses on the x86 DXP line, especially the DXP2800 and DXP4800 Plus. If you are choosing between them, see UGREEN DXP2800 vs DXP4800 Plus.

Method 1: Install Home Assistant Container with Docker

UGREEN’s Docker implementation is the most straightforward Home Assistant route inside UGOS Pro.

UGREEN NAS hardware
    ↓
UGOS Pro
    ↓
Docker
    ↓
Home Assistant Container
    ↓
persistent /config folder

Install Docker in UGOS Pro

Sign in to UGOS Pro.
Open App Center.
Find Docker.
Select Install.
Choose the storage location for Docker data.
Open Docker when installation finishes.

UGREEN’s current Docker interface includes Images, Containers, Networks and Projects. Projects are the graphical Docker Compose workflow.

Create Persistent Home Assistant Storage

Create a dedicated NAS folder for Home Assistant’s /config directory. A typical layout is:

docker/
└── homeassistant/
    └── config/

The exact host path depends on the UGOS Pro volume. UGREEN commonly exposes paths similar to /volume1/docker/..., but check your real path rather than copying an example blindly.

Create a Docker Compose Project

Open Docker → Project → Create and use a Compose definition based on Home Assistant’s official Container example:

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - /YOUR/UGREEN/PATH/homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
    stop_grace_period: 60s
    privileged: true
    network_mode: host
    environment:
      TZ: Europe/Athens

Replace the example host path with the actual persistent folder on your NAS and change the timezone if required.

Home Assistant’s current Container documentation uses the stable image, persistent /config storage, host networking, a restart policy and privileged mode in its standard Docker example.

Why Host Networking Matters

Home Assistant relies on local discovery protocols. Host networking lets the container use the NAS network stack directly rather than sitting behind a separate Docker bridge.

After startup, open:

http://<UGREEN-NAS-IP>:8123

If the page does not appear immediately, wait for the first-start process to finish and check the Docker container logs.

What Home Assistant Container Does Not Include

Home Assistant Supervisor.
Home Assistant Apps.
HAOS host management.
The complete HAOS one-click update workflow.

Home Assistant recommends HAOS for most users. Container is aimed at people who already manage Docker and are comfortable maintaining the host and related services.

For the detailed architecture comparison, see Home Assistant OS vs Docker vs Proxmox.

Home Assistant Container Still Supports Backups

Current Home Assistant backups work across supported installation types. A Container backup covers Home Assistant itself, but separately deployed Docker services need their own backup strategy.

If Mosquitto, Node-RED or InfluxDB are separate UGREEN containers, their data is not automatically included just because Home Assistant itself is backed up.

Updating Home Assistant Container

Container updates replace the running image while preserving the mapped configuration folder. The underlying Compose workflow is equivalent to:

docker compose pull homeassistant
docker compose up -d

UGREEN’s Project interface can manage Compose deployments graphically. Before updating, create a current backup and verify that /config is mapped to persistent NAS storage.

Using Zigbee or Z-Wave USB Adapters with Container

Home Assistant Container supports Docker device mappings for serial radios. Conceptually:

devices:
  - /dev/ttyUSB0:/dev/ttyUSB0

The exact serial path depends on the adapter and UGOS Pro host. A persistent /dev/serial/by-id/ path is preferable when available because simple device names can change.

Verify the device on the UGREEN host before assigning it, and ensure no other container or VM is already using it.

Thread and Z-Wave Are Less Turnkey on Container

Home Assistant’s installation documentation notes that Container does not provide the same out-of-the-box experience for integrations such as Thread and Z-Wave that rely on Home Assistant Apps.

You can run supporting services separately in Docker, but then you manage their deployment, networking, updates and backups yourself.

Bluetooth on Home Assistant Container

Home Assistant’s official Docker example mounts the host D-Bus socket when Bluetooth is required:

- /run/dbus:/run/dbus:ro

Whether this is convenient on a NAS depends on the UGREEN host and hardware. ESPHome Bluetooth proxies are often cleaner because they put the Bluetooth radio close to the devices instead of inside a metal NAS enclosure.

Method 2: Run Home Assistant OS in a UGREEN Virtual Machine

UGREEN DXP models support the UGOS Pro Virtual Machine application. UGREEN’s current VM documentation supports standalone disk images in .img, .qcow2, .vdi and .vmdk formats.

Home Assistant publishes a generic KVM/Proxmox QCOW2 HAOS image, so the UGREEN disk-image import route is technically compatible with the image format.

Home Assistant does not publish a dedicated UGREEN NAS installation guide, so this should be treated as an advanced generic-KVM deployment rather than a UGREEN-specific officially documented Home Assistant appliance path.

Download and Extract the HAOS QCOW2 Image

Download the current KVM/Proxmox image from Home Assistant’s official alternative-installation page. If the file is compressed, extract it until you have the actual .qcow2 disk image.

Import the QCOW2 Image into UGOS Pro

Install/open the Virtual Machine application.
Upload the extracted HAOS .qcow2 image to the NAS.
Open Virtual Machine → New.
Choose the existing-disk-image/import route.
Select the QCOW2 file.
Choose a storage volume for VM data.
Name the VM, for example Home Assistant OS.
Select an appropriate x86-64/Linux-style guest type.
Use UEFI boot mode.
Assign CPU and memory.
Configure VM networking.
Finish the import and boot the VM.

How Much CPU and RAM Should You Allocate?

Home Assistant’s current virtual-machine documentation lists a minimum of 2GB RAM and 2 vCPUs.

For a normal HAOS VM, 4GB RAM and 2 vCPUs are a comfortable practical starting point. Leave enough memory and CPU for UGOS Pro, file services, indexing and other containers.

This matters particularly on the DXP2800, which ships with 8GB RAM. A 4GB HAOS VM consumes a significant share of the stock memory.

UGREEN VM Networking: MacVTap vs LinuxBridge

Mode	Visible on LAN?	Can talk to NAS host?	Home Assistant fit
MacVTap	Yes	No	Okay only if HA does not need host-local NAS services
LinuxBridge	Yes	Yes	Best when HAOS needs NAS SMB/NFS shares
NAT	Not directly	Limited	Poorer fit for discovery-heavy HA
Host-only	No	Yes	Not suitable for normal LAN discovery

UGREEN documents that MacVTap lets a guest appear on the LAN but prevents direct guest-to-NAS-host communication.

Therefore this design can fail under MacVTap:

HAOS VM on UGREEN NAS
      ↓
Home Assistant backup
      ↓
SMB share on same UGREEN NAS

Use LinuxBridge When HAOS Must Access the NAS

Open Control Panel.
Go to Network → Network Connection.
Open Network Bridging → Virtual Bridging.
Enable Virtual Bridging on the physical LAN port used by the NAS.
Allow UGOS Pro to create the VBR adapter.
Open Virtual Machine → Manage → Network.
Select the virtual subnet used by HAOS.
Change it to Bridge Mode – LinuxBridge.
Map it to the new VBR adapter.
Fully shut down and restart the VM.

UGREEN warns that creating or changing a bridge can briefly interrupt the NAS network connection, so avoid doing this during important transfers.

Why NAT Is Usually a Poor Home Assistant Choice

Home Assistant relies heavily on mDNS, SSDP and other local discovery traffic. A bridged LAN presence is generally cleaner than hiding HAOS behind a NAT subnet.

First Boot of the HAOS VM

Once the VM has an address on your LAN, try:

http://homeassistant.local:8123

or:

http://<HAOS-VM-IP>:8123

Complete normal Home Assistant onboarding.

Why the HAOS VM Gives You More Than Docker

Home Assistant Supervisor.
Home Assistant Apps.
HAOS updates.
Integrated backup management.
OpenThread Border Router App.
Other Supervisor-managed services.

This is the main reason to choose a VM over Home Assistant Container on the same NAS.

USB Zigbee, Thread and Z-Wave in the VM

UGREEN’s Virtual Machine app can attach hardware devices to guests, but exact USB passthrough behaviour depends on the NAS model and UGOS Pro version.

For a radio-heavy smart home, verify USB passthrough before making the NAS your only Home Assistant host. Network-connected Zigbee or Thread coordinators can avoid tying the smart-home radio to one local USB device.

Back Up the HAOS VM Properly

If HAOS runs as a VM on the NAS, do not keep the only Home Assistant backup inside the same VM disk.

HAOS VM
   ↓
Home Assistant backup
   ↓
UGREEN shared folder
   ↓
External drive / second NAS / cloud copy

Use LinuxBridge if HAOS needs direct access to a share hosted by the same NAS.

See Home Assistant Backups to UGREEN, Synology or QNAP NAS for the network-storage setup.

VM Snapshots Are Not Your Only Backup

UGREEN’s Virtual Machine application supports snapshots and OVA export. Snapshots are useful before risky changes, but they usually remain on the same NAS storage as the VM. If the storage pool fails, the snapshot can disappear with it.

Docker vs HAOS VM on DXP2800

The DXP2800’s Intel N100 and 8GB DDR5 are capable of either route. Docker is lighter and leaves more memory available to UGOS Pro. A 4GB HAOS VM uses a large share of the stock 8GB configuration, especially if you also run other containers or media services.

Docker vs HAOS VM on DXP4800 Plus

The DXP4800 Plus has more headroom with its Intel 8505, 8GB DDR5, support for much more RAM, two M.2 slots and faster networking. It is the stronger UGREEN host when Home Assistant is one workload among several.

Should the NAS Host Home Assistant at All?

Combining storage, backups, Docker and Home Assistant on one machine reduces the number of boxes but creates a larger failure domain.

One UGREEN NAS
├── storage
├── backups
├── Docker
└── Home Assistant

If the NAS reboots, updates or develops a storage problem, all services are affected together.

For the most resilient design, we still prefer a dedicated HAOS mini PC plus UGREEN NASync for backups and bulk storage.

Troubleshooting: Container Starts but Home Assistant Is Unreachable

Verify network_mode: host.
Confirm the container is running.
Check Docker logs.
Try http://NAS-IP:8123.
Check UGOS Pro firewall/security settings.
Make sure another service is not already using port 8123.

Troubleshooting: Home Assistant Resets After an Update

This usually means /config was not mapped to persistent NAS storage correctly. The container is disposable; the configuration folder must live outside it.

Troubleshooting: HAOS VM Can Reach the Internet but Not the NAS

If the VM uses MacVTap, this is expected behaviour. Change it to a LinuxBridge network attached to a VBR interface, then fully power off and restart the VM.

Troubleshooting: Imported HAOS QCOW2 Will Not Boot

Confirm the image was fully extracted to .qcow2.
Use UEFI boot mode.
Verify the imported disk is the first boot disk.
Check the guest/system type.
Verify CPU and memory allocations.
Review the UGREEN Virtual Machine app logs.
Re-download the HAOS image if corruption is suspected.