In this guide, we will install and configure the Home Assistant companion app for macOS.
Home Assistant has gone through many changes since the last time that I made a guide on how to get started with Home Assistant. So, today, we’re going to do just that. We’re going to talk about what Home Assistant is. What hardware we can use. Install it and go over some initial configuration like setting up the WiFi connection, remote access, and add a few add-ons to manage the configuration files.
Table of Contents
On top of that, we’re going to configure the Home Assistant companion app for both iOS and Android. And at the end, I’m going to show you how to create a backup of your Home Assistant instance, so you can quickly recover the configuration.
What’s Home Assistant?
Home Assistant is a home automation platform where you can add and manage all your smart home devices. It’s open-source and powered by a large community that is constantly working on improving the platform. One of the great benefits of Home Assistant is that it’s not a cloud-based like other similar platforms. It was built with security and privacy in mind, so everything is done locally.
You can install Home Assistant in several ways and in different operating systems. There is a simple method that is excellent for beginners and there are also other methods for more advanced users.
Home Assistant image
This method is the easiest. It automatically downloads the packages needed and installs the latest version of Home Assistant. It also includes the Add-on Store where you can install software directly from the Home Assistant web interface. Another great benefit of this method is that you can quickly update Home Assistant and the add-ons with a click on a button.
Home Assistant Core
Another method is to install the core version of Home Assistant in operating systems like Windows, Mac, and Linux. However, the core version is a little more advanced, so it requires a little more tinkering, and it also doesn’t include the add-on store.
Home Assistant Supervised
There is also a supervised version of Home Assistant that you can installed in a Linux machine, and it does include the add-on store. I actually made a guide not too long ago on how to install the Supervised version on a Linux machine. It’s a little more advanced, but if you’re interested, definitely check it out.
Common hardware to use
The most common way to run the Home Assistant image is on a Raspberry Pi. They’re inexpensive, small, and it doesn’t consume that much electricity. This is actually the method that we are going to use for this guide.
If you are looking to purchase a Raspberry Pi, you can find a kit on Amazon for $100 or less that includes everything that you would need. Case, power supply, a 32GB Micro SD card, and obviously the Raspberry Pi 4. (Raspberry Pi 4 Starter Kit)
Flash Home Assistant image to SD card
First, download the Home Assistant image for your specific device from the Home Assistant website. If you’re using the Raspberry Pi 4, download the 32-bit version for that device. Then, use the program balenaEtcher to flash the image to the SD card. So, insert the SD card to the computer, open Etcher, click on Select Image and locate the Home Assistant image. The SD card should be automatically detected. However, if the wrong drive was selected, you can click on Change and select the correct one. Lastly, click on Flash and give it a minute for the process to finish.
If you are going to connect the Raspberry Pi via WiFi, you need to add a text file with the WiFi configuration to the SD card. So, after the Home Assistant image is flashed to the SD card, go back to the File Explorer. The SD card would now be labeled hassos-boot. Click on it and create a new folder named CONFIG. Then, inside that folder, create another folder and name it, network. Now using Notepad, create a new text file with the following:
[connection] id=my-network uuid=**YOUR_UUID_NUMBER** type=802-11-wireless [802-11-wireless] mode=infrastructure ssid=**YOUR_WIFI_NAME**#Uncomment below if your SSID is not broadcasted #hidden=true [802-11-wireless-security] auth-alg=open key-mgmt=wpa-psk psk=**YOUR_WIFI_PASSWORD** [ipv4] method=auto [ipv6] addr-gen-mode=stable-privacy method=auto
There are 3 things that you need to set up here:
uuid: Random number
ssid: WiFi name
psk: WiFi password
NOTEThe UUID is a 128-bit number used to identify information in a computer. You can generate a new number by going to uuidgenerator.net
When finished, save the file inside the network folder. Name it my-network and after that, remove the SD card from the computer.
Insert the SD card to the Raspberry Pi and power on the Pi. Give it like a minute and on a browser, go to, homeassistant.local:8123. You can also use the Raspberry Pi’s IP address with port
8123 at the end
( 192.168.XX.X:8123 ). If the Pi connected to the WiFi with no problem, the preparing page comes up, and the latest version of Home Assistant starts downloading.
The installation can take a few minutes, but when finished, it refreshes the page and loads the initial configuration:
- Step one: Create an administrator user account that can manage all the configuration. Later on, you can create standard accounts that can use Home Assistant but not have access to make any changes to the settings.
- Step two: You can set up a custom name for Home Assistant and also set up the location, time zone, and the unit system. You can manually enter this information or let Home Assistant detect your location and set it up for you.
- Step three: Home Assistant auto-discovers the smart devices in your network. You can start integrating them and assign them to specific rooms, or you can skip it for now and do it later via the Configuration page.
Click on Finish, and Home Assistant is now ready to go.
How to manage configuration files
To manage the Home Assistant configuration files. There are a few methods that you can use. A simple one would be to use the File editor add-on. It’s lightweight, and it allows editing the configuration files directly from the Home Assistant web interface.
The other way is by setting the Samba add-on and using a text editor on your computer. I preferred this way because you can easily backup all the files to a computer and also use a more feature-rich text editor like, for example, Microsoft VS Code.
Let’s take a look at how to set up these 2 methods.
Set up the File editor
To set up the File editor add-on, go into Supervisor and Add-on Store. Locate the File editor, open it, and click on Install. Then, to make it easily accessible, switch on the option Show in Sidebar. Click on Start, and after a minute, click on Open web UI.
On the top left of the File editor, you have a folder icon. When you click on it, you can see all the configuration files inside the Home Assistant Config folder. When you click on a file, let’s say the
configuration.yaml file, it opens the content in the built-in text editor. You can edit it, save the changes, and also restart Home Assistant directly from the add-on. Just click on the Gear icon on the top right and select Restart Hass.
Set up Samba
To manage and edit the config files directly from a computer, go back to the Add-on Store and locate the Samba add-on. Open it and click on Install.
There are a few things that you need to set up before starting the add-on. So, scroll down and under Config, set up a
username, and a
password. This would be used to gain access to the folder when trying to access it from any computer in your network. Also, if you have a specific
workgroup name set up on your network, you can enter it here as well. Otherwise, leave it with the default name, which is
workgroup: WORKGROUP username: homeassistant password: Your_Password interface: '' allow_hosts: - 10.0.0.0/8 - 172.16.0.0/12 - 192.168.0.0/16 veto_files: - ._* - .DS_Store - Thumbs.db - icon? - .Trashes
When finished, click on Save and then Start the add on. After a minute, go to the file explorer on your computer, click on Network, and refresh the page. The HOMEASSISTANT Shared folder should now come up. If you have issues where the shared folder is not showing up, you can map the drive to the computer by right-clicking the Network folder and selecting Map network drive. The path for the Home Assistant config folder would be
\\homeassistant\config or you can also use the Raspberry Pi’s IP address
( \\192.168.XX.X\config ).
When you try to access the shared folder for the first time, it asks you to enter the username and password set up in the Samba configuration.
Set up remote access
There are 2 ways that I want to show you. The easy way would be to use the Home Assistant Cloud service provided by Nabu Casa. Nabu Casa was founded by the same developer of Home Assistant. It allows a secured connection to your Home Assistant without having to open any ports on a router. The cloud service has a monthly subscription fee of $5. However, you do get a 30-days free trial so that you can test it. Also, remote access is not the only feature that you get with the cloud service. You can also integrate both Google Assistant and Amazon Alexa so you can control your Home Assistant using your voice.
The other method is free but requires a few more steps. You would use the DuckDNS add-on, create a DuckDNS sub-domain, and set up a port forwarding rule in the home network.
Home Assistant Cloud set up
To set up the Home assistant Cloud, go into Configuration, Home Assistant Cloud, and click on Start your free 1 month trial. Then, enter your email address and set up a new password. After you sign in, Home Assistant generates a new SSL certificate, so the connection is secured. It also provides you with a new Nabu Casa URL so you can use it to access your Home Assistant remotely.
The Remote Control feature can also be enabled and disable at any time. So you can enable it when you’re not going to be home and disabled when you are. You can even set up an automation to do the process for you instead of doing it manually. That’s a little more advanced, so we’re not going to cover it in this article.
All right, that’s pretty much all the configuration that you need for remote access when using the Home Assistant Cloud. You just need to use the Nabu Casa URL when you’re on another network and sign in using your Home Assistant credentials.
To use the DuckDNS method, there are 2 things that you need to set up on your router. Assign a static IP address for the Raspberry Pi and set up a port forwarding rule. After you have the Pi set up with a static IP, go to the port forwarding settings on your router. Then, add a new rule with the following information:
Name: Home Assistant Port: 443 Forwarding IP: 192.168.XX.X #Raspberry Pi's IP address Forwarding Port: 8123 Protocol: TCP
Save the new rule, and depending on the router, you might need to restart it to apply the changes.
Next, create a DuckDNS sub-domain. Go to duckdns.org, sign in with one of the available methods, and create a new sub-domain. Your new DuckDNS URL would be:
Towards the top, there is a token number. Copy that number and go back to Home Assistant. Then, go into Supervisor, Add-on store, click on the DuckDNS add-on and install it. After that, scroll down to the Config area and under
token, enter the DuckDNS token number. Then, under
domains, enter your new DuckDNS URL. The DuckDNS add-on uses Let’s Encrypt to set up an SSL certificate, making the remote connection encrypted. So, under
accept_terms change it from
lets_encrypt: accept_terms: true certfile: fullchain.pem keyfile: privkey.pem token: Your-DuckDNS-Token-#-12345 domains: - your_domain.duckdns.org seconds: 300
Save the changes and Start the add-on. Then, under Log, refresh a few times to follow the setup and make sure that the process completes with no issues.
Next, using the File editor, open the
configuration.yaml file, uncomment
http by removing the hashtag
# and then enter the following below it:
http: base_url: your_domain.duckdns.org ssl_certificate: /ssl/fullchain.pem ssl_key: /ssl/privkey.pem
base_url, enter the DuckDNS URL that you created before. Another thing that I suggest adding here is the
ip_ban_ebabled set to
true and the
login_attempts_threshold set to either
http: base_url: your_domain.duckdns.org ssl_certificate: /ssl/fullchain.pem ssl_key: /ssl/privkey.pem ip_ban_enabled: True login_attempts_threshold: 3
What this would do is that if someone tries to log in, let’s say 3 times using the wrong password, that individual’s IP address would get banned. Also, a login attempt failed alert would come up in Home Assistant, advising what happened. The alert would also contain the IP address that attempted to log in.
After you edit the file, save it, and restart Home Assistant. When it’s back online, to reaccess the web interface, you would now use the DuckDNS URL from both inside and outside your home network.
To add more integrations into Home Assistant, go into Configuration, Integrations, and click on the plus
+ icon to add a new one.
As of right now, Not all integrations can be configured directly via the web interface. Some would have to be added manually. You can go to the Home Assistant website and under Integrations search for the one that you would like to add. The documentation would provide the configuration that you would need to add to the
configuration.yaml file. After adding the settings manually, restart Home Assistant to apply the changes. Then, when Home Assistant is back, the entities for the new integration would be available for you to use.
Home Assistant Companion app
You can access Home Assistant from a mobile browser with no problem, but it’s limited. With the companion app, you have features like notifications, battery stats, and location tracking.
The set up on both versions is slightly different, so I’m going to show you how to do the initial configuration on both.
iOS Companion app
In an iOS device, download the Home Assistant companion app from the App Store. Open it, click on Continue, and the app scans your network for a Home Assistant instance. If, for some reason, it doesn’t find it, you can click on Enter address manually and type your Home Assistant URL. If the app finds your instance, click on it and then click on Connect. You would then need to sign in using your Home Assistance credentials.
If you want the app to track your location and also receive notifications, click on Allow on both options. Then, Continue and give it a second for the app to finish the setup.
Android Companion app
To set up the app on an Android device, download the companion app from the Google Play Store. Open the app, and it should’ve automatically found your Home Assistant instance. If not, click on Enter address manually and enter your Home Assistant URL. After that, sign in with your Home Assistant username and password.
To enable location tracking and consistent background updates, click on Grant Permission. Then, Allow Home Assistant to access your device’s location and also Allow the app to update your location in the background periodically. Lastly, click on Finish, and the Home Assistant app is ready to go.
I would like to cover the companion app in more detail in a separate guide and go over things like sending custom notifications and much more. So, if you’re interested and have any suggestions, let me know in the video comments or via social media.
After you have Home Assistant all set. It’s important to create a snapshot of your instance. So, if something happens and you need to reinstall Home Assistant, you can easily recover your configuration from that backup.
To create a snapshot, go into Supervisor and then Snapshots. When creating a new one, you can select if you want to do a full or a partial backup of your Home Assistant instance. If you select, Partial snapshot, you can select what you want to include in the backup. Then, for security, you can password protect it, so a password is required when restoring the snapshot.
When selecting an available snapshot, you have several options. You can download it to your computer for safekeeping. Delete it from your Home Assistant. Choose what you want to restore from the snapshot. And, if you password protected it, you would have to enter that password to be able to restore it.
Anytime you create a snapshot of your Home Assistant, you definitely want to download it to your computer. So, if you do a clean install of Home Assistant, you can recover your configuration with that snapshot.