Home Assistant Companion App: Phone Setup Guide

The Home Assistant Companion app turns your phone into a remote control, a sensor, and a notification hub for your smart home. You can check camera feeds, toggle lights, receive alerts when a door opens, and even use your phone’s location to trigger automations when you arrive or leave. Before you start, make sure you have a working Home Assistant server (Home Assistant OS, Supervised, or Container) and your phone’s operating system is up to date.

What You’ll Need

A Home Assistant server (version 2023.1 or newer recommended) that you can access from your phone’s network.
A smartphone running iOS 15+ or Android 8+.
The Home Assistant Companion app installed from the Apple App Store or Google Play Store.
Your Home Assistant login credentials (username and password).
If you want to use the app away from home, a secure remote access method like Nabu Casa (the official cloud service) or a properly configured reverse proxy with HTTPS.

Step-by-Step

Install the app. Download the Home Assistant Companion app from your phone’s app store. The app is free and developed by the Home Assistant community.
Open the app. On first launch, you’ll see a welcome screen. Tap “Get Started” to begin the setup.
Enter your server address. The app will ask for your Home Assistant URL. If you’re on the same Wi-Fi network, you can often use the local address (e.g., http://192.168.1.10:8123). If you have a Nabu Casa subscription, you’ll see a “Login with Nabu Casa” optionâ€”tap that and follow the browser prompt. Otherwise, type your full URL (including http:// or https://) and tap “Connect.”
Authenticate. A browser window will open asking you to log in to your Home Assistant instance. Enter your username and password, then tap “Log In.” If you have two-factor authentication enabled, complete that step as well.
Authorize the app. After logging in, you’ll see a screen asking if you want to authorize the Companion app. Tap “Authorize” to grant it access to your Home Assistant API.
Return to the app. The browser will show a success message. Tap “Open in App” or manually switch back to the Companion app. The app will now connect and load your Home Assistant dashboard.
Grant permissions. The app will ask for various permissions (location, notifications, motion, etc.). For the best experience, grant all of them. You can always adjust these later in your phone’s settings.
Enable sensors (optional but recommended). Go to the app’s Settings > Companion App > Sensors. Toggle on the sensors you want to send to Home Assistant, such as battery level, Wi-Fi SSID, and location. These appear as entities in Home Assistant and can be used in automations.
Set up notifications. In the app, go to Settings > Companion App > Notifications. Tap “Test notification” to verify that notifications work. You can then use the notify.mobile_app_<your_device_name> service in Home Assistant to send messages to your phone.
Create a shortcut (optional). On Android, you can add a Home Assistant widget to your home screen for quick access. On iOS, use the Share sheet to add a bookmark to your home screen.

Common Mistakes

Using the wrong URL. If you type https:// when your server only uses http://, the app won’t connect. Check your server’s configuration.
Forgetting to enable remote access. If you only set up the app on your local network, it won’t work when you’re on cellular data. You need Nabu Casa or a reverse proxy for off-network access.
Ignoring permission prompts. Denying location permission means location-based automations won’t work. Denying notification permission means you won’t get alerts.
Not updating the app. Old versions of the app may not support the latest Home Assistant features. Keep both the app and your server updated.
Multiple connections. If you have multiple Home Assistant instances, make sure you’re connecting to the correct one. The app stores only one server URL at a time.

Tips

Use a static IP or hostname. If your server’s IP changes, you’ll have to reconfigure the app. Set a DHCP reservation or use a hostname like homeassistant.local.
Enable the “Notify on disconnect” option. This sends a notification when your phone loses connection to Home Assistant, which helps you notice problems early.
Customize your dashboard. The app shows the same Lovelace dashboard as your browser, but you can create a mobile-specific dashboard with larger buttons and simpler cards. Go to your server’s dashboard settings and add a new view with the “Mobile” visibility condition.
Use the app’s action shortcuts. On Android, you can add a “Home Assistant” action to the quick settings tile. On iOS, you can use Siri Shortcuts to trigger Home Assistant services with voice commands.
Check the companion app documentation. The official Home Assistant website has a dedicated section for the Companion app that covers every feature in detail.

Troubleshooting

App says “Cannot connect to server.” First, check that your phone and server are on the same network. Then try entering the server’s IP address directly in your phone’s browser to see if it loads. If it does, the issue is likely with the app’s stored URLâ€”delete the app and reinstall, or clear the app’s data in your phone settings.
Login works but the app is blank. This usually means the app is connecting but the dashboard isn’t loading. Try refreshing the app by pulling down. If that fails, check your Home Assistant logs for errors. Also, make sure you haven’t accidentally set the dashboard to a view that’s only visible on desktop.
Notifications aren’t arriving. Go to Settings > Companion App > Notifications and tap “Test notification.” If it doesn’t work, check that notifications are enabled for the app in your phone’s system settings. On Android, battery optimization can also block notificationsâ€”exclude the app from battery optimization.
Location sensors are not updating. Make sure you’ve granted location permission and that the app’s location tracking is enabled in Settings > Companion App > Sensors. On iOS, you may need to set location access to “Always” rather than “While Using.”
App is slow or unresponsive. This could be due to a slow internet connection or a heavy dashboard. Try disabling some sensors or using a simpler dashboard. Also, check your server’s CPU loadâ€”if it’s maxed out, the app will lag.

Frequently Asked Questions

Do I need Nabu Casa to use the Companion app?

No. The app works perfectly on your local network without Nabu Casa. However, to use it away from home, you need a secure remote access method, and Nabu Casa is the easiest way to set that up.

Can I connect multiple phones to the same Home Assistant?

Yes. Each phone will appear as a separate device in Home Assistant, with its own sensors and notification service. You can manage them all from the same server.

Does the app drain my phone’s battery?

Location tracking can be battery-intensive. The app uses adaptive location tracking, which learns your patterns and only updates when you move significantly. You can also adjust the update interval in the app’s settings.

Can I use the app to control devices even if I’m not home?

Yes, as long as you have remote access set up (via Nabu Casa or a reverse proxy). The app will automatically use the remote URL when you’re not on your home Wi-Fi.

What sensors does the app provide?

It provides a variety, including battery level, charging state, Wi-Fi SSID, location (GPS), activity (walking/driving), and more. The exact list depends on your phone’s operating system and permissions.

Is the app free?

Yes, the Companion app is completely free and open-source. There are no in-app purchases or subscription fees.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →