Running Home Assistant alongside a UniFi OS gateway like a Cloud Gateway Ultra, Cloud Key Gen2 Plus, or Dream Machine gives you complete control over your home network and automation routines. While UniFi OS hardware doesn't natively run third-party container managers directly as a supported app store package out of the box, you can host Home Assistant on dedicated hardware—such as a Mini PC, Raspberry Pi, or Proxmox server—and tightly couple it with your Ubiquiti ecosystem. This combination lets you turn network events, camera feeds, and door access logs into powerful automation triggers.
Getting the most out of this setup requires understanding how to bridge the two platforms securely. You'll need to configure local administrative accounts, avoid common database bloat traps, and map out your network tracking parameters correctly. Let's look at how to connect your UniFi ecosystem to Home Assistant for maximum performance and reliability.
Preparing Your UniFi OS Environment
Before you link Home Assistant to your Ubiquiti gateway, you need to set up a dedicated local user account. Relying on cloud-based single sign-on credentials can break your integrations if your internet drops or Ubiquiti's cloud services experience downtime. Local authentication ensures your automations keep running during an outage.
Log into your local UniFi OS portal directly via its local IP address rather than using the remote management dashboard. Navigate to the system settings and create a new local administrator user specifically for Home Assistant. Restrict this account to local access only. Assign only the necessary privilege levels depending on which subsystems you plan to integrate—such as full management for the Network or Protect applications, while keeping OS settings restricted to none.
Creating Dedicated API Keys
For certain UniFi applications, you can generate a specific API token instead of creating a full user profile. This approach limits the blast radius if an integration credential ever gets compromised.
- Open your console's local IP address in a browser.
- Navigate to the specific application settings, such as UniFi Access or Protect.
- Locate the API token or integration section and select Create New.
- Label the token clearly—for example, "Home Assistant"—and copy the string immediately. You won't be able to view it again once you leave the page.
Integrating UniFi Network for Presence Detection
The UniFi Network integration brings your router, switches, access points, and connected clients directly into your automation engine. One of the most popular uses for this integration is presence detection. By tracking whether a family member's phone is connected to your Wi-Fi access points, you can trigger homecoming routines, adjust smart thermostats, or disarm security systems.
To add the network hub, navigate to your Home Assistant dashboard, go to Settings > Devices & services, select Add Integration, and choose UniFi Network. Enter your local gateway credentials or API details when prompted.
Once connected, configure these essential options carefully:
- Track network clients: Generates device tracker entities for your phones, tablets, and IoT gear.
- Include wired network clients: Useful for desktop computers, smart TVs, and media servers.
- Ignore Wi-Fi clients with private MAC addresses: Enable this if modern mobile devices with randomized MAC addresses are spamming your entity list with temporary entries.
Crucial Warning: Be very careful when enabling auxiliary sensors like client bandwidth usage or uptime trackers. Tracking uptime for dozens of network clients generates a massive volume of state changes that can bloat your Home Assistant database within days. Exclude these specific sensor entities in your recorder configuration unless you have enterprise-grade storage allocated.
Bringing in UniFi Protect and Access
If you run security cameras or smart doorbells on your UniFi OS console, the UniFi Protect integration allows you to pull high-resolution local video feeds and motion alerts into Home Assistant. Because the integration utilizes local WebSocket connections, streams update in real time without cloud latency.
Each camera automatically provisions multiple quality streams (high, medium, low) along with a package camera feed if you use a doorbell like the G4 Doorbell Pro. You can use these video streams on dashboard panels or trigger automations when a person is detected in your driveway.
Similarly, the UniFi Access integration turns IP-based door locks and readers into native buttons. By pairing these buttons with Home Assistant template helpers, you can expose secure smart locks to local voice assistants or Apple HomeKit securely.
Common Setup Mistakes to Avoid
Even experienced administrators run into a few recurring pitfalls when bridging Ubiquiti hardware with Home Assistant:
- Clock Drift Issues: If Home Assistant and your UniFi OS console run on separate physical machines, ensure your Network Time Protocol (NTP) servers are synchronized. If your clocks drift by even a few minutes, presence detection algorithms will fail to mark devices as home.
- Over-Polling the Gateway: Avoid writing custom scripts that poll the UniFi API every few seconds. Rely exclusively on the built-in WebSocket push mechanisms provided by the native integrations to keep CPU utilization low on your cloud gateway.
- Ignoring VLAN Isolation Rules: If your Home Assistant instance lives on a trusted IoT or server VLAN while your UniFi gateway management interface is locked down, make sure your firewall rules allow local API communication over ports 443 and 8443.
Frequently Asked Questions
Can Home Assistant run directly on a UniFi Dream Machine?
No. UniFi OS consoles run a customized, locked-down version of Linux optimized for networking and security workloads. While advanced users have occasionally experimented with root container overrides, it's unsupported and will likely break during the next firmware update. Always run Home Assistant on dedicated external hardware.
How do I stop random IoT devices from creating entities?
Go to the UniFi Network integration settings inside Home Assistant and filter out devices that don't need tracking. You can also toggle on the setting to ignore clients using randomized private MAC addresses to keep your entity registry clean.
Why is my presence detection delayed?
By default, UniFi controllers wait a set number of seconds before marking a disconnected client as away to prevent flapping when a device drops its signal momentarily. You can adjust this timeout threshold inside the integration configuration menu under the "Time in seconds from last seen until considered away" parameter.
Do I need internet access for these local integrations to work?
No. Once authenticated locally, both UniFi OS and Home Assistant communicate entirely over your local area network, ensuring your smart home keeps functioning smoothly even during a wide-area network outage.
Learn more about managing your network devices through the official Home Assistant UniFi Integration Documentation and explore official hardware specifications on the Ubiquiti Official Website.
