Where to Run Home Assistant on a UniFi Network

Read Home Assistant's installation pages closely and one item repeats under every option that runs on its own device, from the Green to a Raspberry Pi to an x86-64 machine: an Ethernet connection. Not a recommendation, a listed requirement.

That tells you something about where this software expects to live. It wants a wired spot on the network, a stable address and a host you do not reboot casually.

The hardware question gets most of the attention while the network consequences get almost none, yet the choice between Home Assistant OS and a container decides which integrations you can run at all. In addition, the address you give the host decides how much of your configuration breaks later.

What follows takes the decision from the network's side, in order. Installation type, cabling, addressing, VLAN placement, what virtualization changes, and where the backups land.

Home Assistant offers two installation types, and the split is cleaner than the hardware catalog suggests. Home Assistant OS is an embedded operating system that runs the whole ecosystem, while Home Assistant Container is the application alone on a system you maintain.

The apps are, in practice, the dividing line. They are how the OpenThread Border Router runs, how Z-Wave is driven, and how Tailscale or Cloudflare Tunnel reach Home Assistant in the remote access guide.

In fact, that single difference reaches most of this series. A container install cannot become the Thread border router the Matter and Thread guide describes, and it cannot host the tunnel that keeps your phone reporting.

Hardware follows from the type rather than leading it. The Green ships with Home Assistant OS already installed, while a Raspberry Pi, Odroid or x86-64 machine can be flashed with it.

A Windows, macOS or Linux box, for its part, can run the same operating system in a virtual machine. Naturally, that adds the layers covered further down.

Of course, the container route stays legitimate for people already running Docker. Just go in knowing which integrations you are giving up, rather than discovering it when a Thread device refuses to pair.

The reasoning is not mysterious, after all. Home Assistant is the hub every integration talks through, so its link quality sets a floor under everything else.

Discovery makes the case sharper. For instance, zeroconf, SSDP and Matter all lean on multicast, which Ubiquiti's own guidance warns eats airtime at the lowest data rate.

What's more, a wired host stops competing with the devices it serves. Every announcement your smart plugs send has to cross the same radio, and the hub's replies join the queue behind them.

Keep in mind that this is about the host, not the radios. A Zigbee or Thread coordinator belongs out in the house, which is the argument for putting it on PoE, while the server itself belongs on a switch port.

Where that port sits matters as well, naturally. A host on a UniFi switch can be given a port profile, a VLAN and a policy, none of which a Wi-Fi client gets as cleanly.

A DHCP reservation costs nothing, of course, and prevents a class of failure that surfaces weeks later. The host reboots, takes a different address, and half a dozen references quietly point at nothing.

In fact, the list of things referencing it is longer than most people expect. Sonos speakers connect back to it, Chromecasts fetch media from it, a networked Zigbee radio is reached at a socket address, and every firewall allow names it.

A local DNS record is, naturally, the companion to that. Ubiquiti's gateway serves the name to clients using it for DNS, which keeps a hostname working inside the house even when an address does change.

Remember to note the web port while you are there. Existing installations keep the port they had, usually 8123, while new Home Assistant OS installations since the 2026.8 release use port 80.

Whichever one Settings then System then Network shows is the one your firewall policies need.

The IoT VLAN guide works through the three layouts and the zone policies each one needs, so this is the short version. Put it with the devices, and write one deliberate exception for the people who need to reach it.

Home Assistant OS can also take a tagged VLAN interface on an Ethernet port from its command line, which turns the host into a bridge between segments. That is powerful and worth thinking about twice, since it undoes part of what the segmentation bought you.

Whichever you choose, keep in mind that the switch port needs to match. A trunked port with the right networks tagged is a UniFi port profile decision, and the VLAN fundamentals guide covers building those cleanly.

Naturally, the host's placement shapes its credentials too. A machine on the least-trusted network holding an administrator account for your console deserves a second look, which the presence detection guide touches on when it sets up the UniFi user.

Virtualization is legitimate, of course, and Home Assistant documents running its OS in a VM on Windows, macOS and Linux. The catch is that each layer between the software and the wire can drop the traffic discovery depends on.

The libvirt case is the clearest example. Home Assistant's zeroconf documentation states that a macvtap adapter does not let the guest receive zeroconf or multicast traffic by default, and gives the exact XML attribute that fixes it.

Containers have their own rule. The Cast integration's documentation says a container must run with host network mode, that running without it is unsupported, and that discovery will fail otherwise.

Thread adds the IPv6 layer on top. Its documentation asks for working IPv6 on the host, the hypervisor's virtual NIC, the Docker daemon and the router, and warns that the border router app checks only the host.

As a result, a virtualized install is not worse, merely less forgiving. Every layer you add is a layer that has to be told to pass multicast and IPv6 through.

Home Assistant supports both NFS and Samba targets as network storage, added under Settings then System then Storage, where a usage type decides whether a share holds backups, media or general files. On Home Assistant OS that feature wants version 10.2 or newer.

As a result, a UniFi storage device is a natural destination rather than a host. The backups leave the machine that might fail, and they land on hardware built to keep them.

Keep the network path in mind when you set it up. If Home Assistant sits on an IoT VLAN and the NAS sits on the trusted side, that mount needs one of the narrow allows the IoT VLAN guide describes.

Point it from the host to that server alone, rather than opening the zone.

Other NAS boxes that do run containers are, however, a different conversation. Home Assistant lists a container install with a NAS among its options, which brings back the apps limitation from the top of this guide.

Doing this in the wrong sequence is, after all, what creates an afternoon of rework. This order keeps each decision from invalidating the last:

1. Pick the installation type first, since Home Assistant OS or container decides which integrations exist at all.
2. Wire the host and put it on a switch port you can give a profile to.
3. Reserve its address in UniFi and add a local DNS record for it.
4. Choose the VLAN before pairing devices, because moving the host later means re-commissioning Matter devices.
5. Mount the backup share and take a backup before the first integration goes in.
6. Add the remote path you chose in the remote access guide, then the integrations.

Note that step 4 is the one people regret skipping. Matter devices are commissioned onto the network they will live on, so moving Home Assistant across a VLAN boundary afterwards means doing that work twice.

Finally, write down what you chose. The port, the address, the VLAN and the backup target are four facts that every future troubleshooting session starts from.