Run Home Assistant on macOS with a Debian 12 Virtual Machine

Welcome to the definitive guide on running Home Assistant on macOS using a Debian 12 virtual machine! If you’re eager to transform your Mac computer into a smart home hub, this article is your roadmap to success.

In today’s interconnected world, home automation has become an essential aspect of modern living.

Home Assistant, a powerful open-source platform, empowers you to seamlessly control and monitor various smart devices from a single centralized interface.

While Home Assistant is traditionally deployed on dedicated hardware like Raspberry Pi, we will take a unique approach by running it on macOS through a Debian 12 UTM virtual machine.

This step-by-step tutorial will demystify the process, making it accessible to both beginners and seasoned tech enthusiasts.

From setting up the virtual machine to installing and accessing Home Assistant for your specific needs, this article has got you covered!

In this article, you can expect to find:

1. A brief introduction to virtual machines and how they can be used to run Home Assistant on Mac.
2. A detailed guide on how to create a virtual machine using a freely available program called UTM.
3. Step-by-step instructions for installing and configuring the Debian Linux operating system within a virtual machine.
4. Step-by-step instructions for installing Home Assistant on a Debian virtual machine.
5. How to configure the virtual machine network settings to access Home Assistant from other devices.
6. Further resources and troubleshooting.

By the end of this journey, you’ll have a fully functional Home Assistant instance running on macOS, opening up a world of possibilities to enhance your home’s efficiency, security, and comfort.

Home Assistant on Mac: How Does it Work?

Home Assistant can be set up and run on macOS using a virtual machine with a freely available open source application called UTM.

UTM is a virtualization application that allows you to run various operating systems, including Windows and many Linux distributions, on macOS devices with both Apple Silicon (M1/M2) and Intel processors.

Here’s an overview of how Home Assistant works on macOS using UTM:

1. Install UTM on macOS: To begin, you’ll need to download and install the UTM application from the Mac App Store. UTM provides a user-friendly interface for setting up and managing virtual machines.
2. Set up a new virtual machine: With UTM installed, you can create a virtual machine and choose Debian 12 as the guest operating system. Debian is a popular Linux distribution known for its stability and versatility.
3. Configure the Virtual Machine: During the virtual machine setup process, you’ll need to allocate resources such as CPU cores, RAM, and storage to the Debian guest. The performance of Home Assistant will depend on these resource allocations.
4. Install Debian 12 in the Virtual Machine: Once the virtual machine is configured, you can install Debian by following the standard Debian installation procedure.
5. Install Home Assistant: After Debian 12 is installed, you can access the Linux environment within the virtual machine. From there, you’ll follow the standard installation instructions for Home Assistant on Linux.
6. Configure the network: To enable communication between Home Assistant and external devices, you will need to configure bridged networking in UTM. This ensures that Home Assistant services are accessible from both your macOS environment and other devices on your local network.
7. Accessing Home Assistant on macOS: Once Home Assistant is up and running within the Debian virtual machine, you can access the Home Assistant web interface through your macOS web browser. This interface serves as the central hub for managing your smart home devices and automations.
8. Enjoy Smart Home Automation: With Home Assistant successfully running on macOS through UTM, you can now control and monitor your smart home devices seamlessly from your macOS computer.

Prerequisite

In order to get Home Assistant running on your Mac, you will need a Mac which meets the minimum system requirements of UTM and adequate disk space:

• Apple Silicon (M1/M2 etc…) or Intel processor
• Requires macOS 11.3 or later
• Recommended 32GB or more free disk space
• 4GB of RAM

Downloading Debian 12

To install Debian on a virtual machine, you will need the Debian 12 installation image. You will need to choose the correct version that matches your Mac’s processor architecture.

If you have an Apple Silicon Mac (M1/M2 etc..) then you will need the ARM architecture version. If you have an Intel Mac then you will need the AMD architecture version

If you are not sure which architecture you need, you can find out what processor you have by opening the macOS Terminal and entering the following command:

uname -m

This will output the architecture that you are using. Next, go ahead and download the Debian installation disk image (.iso file) for the architecture that matches your system:

• arm64 – Download Debian 12 Linux for ARM architecture (Apple Silicon Mac)
• x86_64 – Debian Linux 12 for Intel architecture (Intel Mac)

Downloading UTM

You will also need to download and install UTM, which is the macOS application that actually creates the virtual machine. Once downloaded, place the UTM app in your applications folder and launch it from there.

UTM is open source and is completely free to download and use. However if you wish to support the project, there is a paid version available on the app store for a small fee.

The app store version does not have any additional features, but you will benefit from automatic updates.

Creating a New UTM Virtual Machine

Once you have installed UTM, the next thing to do is create a new virtual machine for running Debian. You can start this process whilst you wait for Debian to download, if you are still downloading it.

Add a new virtual machine

In order to add a new virtual machine in UTM, click the ‘+’ button at the top of the main window, or choose Create a New Virtual Machine from the main screen:

Next, select the virtualization option by clicking the large button:

Choose an operating system

On the next screen we are given the option to choose the type of operating system, which can help to simplify the configuration.

Debian is a Linux distribution, therefore you can go ahead and choose Linux for the operating system.

Choose the boot image

Next, we need to supply UTM with the disk image that contains the Debian installation image.

Click the Browse button and locate the Debian .iso installation image file and select it. Then click Continue to move to the next section.

Choosing the hardware settings

Next, we will configure the hardware settings for our virtual machine. In most cases you can use the system requirements given by Home Assistant:

• 2 GB RAM
• 32 GB Storage
• 2vCPU

On the first screen, set the Memory to 2000MB (2GB) or greater. Set the CPU cores to 2, or leave it blank to let UTM manage the number of cores used.

On the next screen, set the drive size to a value of your preference with a minimum of 32GB as per the Home Assistant system requirements.

Note that you can always change these settings at a later date if you prefer. In some cases you will need to allocate more system resources for more intensive tasks, such as video processing.

Changing RAM and CPU cores is very easy, it can be done from the virtual machine settings in UTM.

However changing the hard drive is more complicated, therefore I would recommend setting it to the size that you require at this stage.

If you do need to change the disk size at a later date, you can learn how to do it in my article about resizing UTM virtual drives.

Choosing a shared location

There is no need to set up file sharing between the virtual machine and your macOS host, as file sharing can be set up later in Home Assistant.

Therefore you can skip this screen and just click continue.

Finalizing and starting the VM

On the final screen you have the opportunity to give your new VM a name, such as Home Assistant. You can review the settings and then click save to add your new virtual machine to UTM.

Next, we can start the newly created virtual machine. Select the VM from the left-hand sidebar menu and then click the play button to boot up the virtual machine.

Note that the default display and network settings should be adequate to get things up and running. You can adjust these at a later point if necessary.

Installing Debian on a UTM Virtual Machine

Once you have created and booted up the new virtual machine, the Debian installation will begin.

1. Choose Install to begin the installation (you can use Graphical Install if you prefer).

Set up Languages and Location

2. First, choose the default system language. This will also be the language used for the installation process:

3. Choose your home country. This location will be used to set your time zone and other aspects of the system that are dependent on location.

4. Choose your keyboard layout.

Set Up the Accounts

5. The hostname is a single word that usually describes the system and can be thought of simply as a name for the system. For this example I will use the default hostname debian.

6. A domain name is not required, leave this blank and press enter to continue.
7. Enter a password for the root user. Re-enter the password when prompted in order to confirm. It is important that you make a note of this password and keep it safe somewhere as it can be used to log in to the root account and perform any necessary system tasks.
8. Enter a name for the system user account. This would usually be your real name, however in this example I will use debian.

9. Enter a username for the user account. This will be the username that you use to login to Debian. In this example I will create the username user.

10. Enter a password for the user account. This will be the password used to login to Debian. Re-type the password when prompted to confirm.

Set Up the Timezone

11. Choose your timezone. If you do not see the correct timezone listed, you will need to go back and change the system language. Note that you can change the timezone after installation using the Debian command line.

Create the Disk Partitions

12. Next, Debian will create the disk partitions. Choose the guided – use entire disk option.

13. Choose Virtual Disk 1, it should be the only option available.

14. Choose the option to put all files in one partition.

15. You will be shown a summary of the partition settings. Select finish partitioning and write changes to disk and then choose yes in order to complete the process.
16. Next, the base files will be installed and package manager will be configured. When prompted to scan extra installation media, choose no.

Choose a Mirror

17. Next, Debian will connect to the internet to fetch the required files. In order to do this it will connect to one of the available mirrors. Choose the region closest to you in order to select the best mirror. This is not essential, but can speed up the installation process.

18. Select a mirror from the list. If you are unsure of the best mirror to use, just choose deb.debian.org.
19. When prompted to choose a proxy, just leave it blank and choose continue.

Complete the Installation

20. Debian will now proceed to download and install the necessary files. When prompted to opt in to the popularity contest, you can choose whether or not you wish to take part. Including yourself in the popularity contest can help the Debian developers, however it is not mandatory. If in doubt, just choose no.

21. You will now be given the choice of software tools that you wish to include. In this example we will not opt to install a GUI, as this can be done after the installation. Therefore ensure that only SSH server and standard system utilities are selected. Choose Continue to begin the installation.

22. Once the installation has completed you will be prompted to remove the installation media before continuing. Do not click continue yet. First you need to remove the installation media from UTM. From the main UTM window, click the CD/DVD dropdown and then click clear. This will remove the Debian installation .iso file from the virtual CD drive.

22. Once you have removed the installation media, click continue to complete the installation.

23. The virtual machine will restart and take you to the Debian command prompt. Here you can log in with the credentials you created earlier in order to get to the command prompt.

Installing Home Assistant on Debian 12

At this stage you should have a working virtual machine and you should be able to access the Debian command line. The next step is to install Home Assistant.

First, you will need to login to Debian using the credentials you created during the installation. Enter your username and password to login to the Debian command line.

Next, enter the following command to display the IP address of the virtual machine.

hostname -I

The IP address will most likely be something like 192.168.64.X.

Now that you have your virtual machine IP address, you can log into it using the macOS Terminal.

To do this, open a new macOS terminal window and enter the following command, replacing <username> with your Debian username and <IP-address> with the IP address from the previous command.

ssh <username>@<IP-address>

Note that using the macOS terminal is not essential and you can enter everything directly into the Debian virtual machine. However using the macOS terminal instead makes things much easier, as you can easily copy and paste commands.

For the first few tasks we need to be logged in as root, which we can do with the following command:

su -

You will need to enter the credentials that you chose during installation.

Install Dependencies

Firstly, we need to install all of the system dependencies that are required by Home Assistant. This can be done with the following command.

apt install \
apparmor \
jq \
wget \
curl \
udisks2 \
libglib2.0-bin \
dbus \
lsb-release \
systemd-journal-remote \
systemd-resolved \
network-manager -y

Note that the Home Assistant developers sometimes amend the list of dependencies.

If something is added and the command above becomes out of date, you may encounter a missing package/dependency error during the installation of Home Assistant later in the tutorial.

If you do encounter this error, you can resolve the issue by checking the official list of required dependencies. Simply copy and paste the command from there instead and then try the Home Assistant installation again.

Update Networking Settings

Once the dependencies are installed, we need to move control of the network interfaces over to Network Manager. First, we need to remove the interfaces configuration.

mv /etc/network/interfaces /etc/network/interfaces.bak

Next, we will reboot the virtual machine.

reboot now

Once the virtual machine has rebooted, log back in and switch to the superuser account again.

su -

Install Docker-CE

Next, we will install Docker-CE with the following command.

curl -fsSL get.docker.com | sh

Install OS-Agent

The Home Assistant OS-Agent acts as a communication channel between the operating system and the Home Assistant Supervisor. It allows the Home Assistant Supervisor to interact with and control the operating system functionalities.

We will need to install the OS-Agent, which is used to connect the Debian operating system to Home Assistant.

The easiest way to download the latest version of OS-Agent is by using either of the following commands. Alternatively you can download OS-Agent manually.

ARM architecture:

curl -s https://api.github.com/repos/home-assistant/os-agent/releases/latest | jq -r '.assets[] | select(.name | endswith("aarch64.deb")) | .browser_download_url' | xargs wget

Intel architecture:

curl -s https://api.github.com/repos/home-assistant/os-agent/releases/latest | jq -r '.assets[] | select(.name | endswith("x86_64.deb")) | .browser_download_url'| xargs wget

Manual Download

The commands above will automatically download the latest version of OS-Agent for the specified architecture using the GitHub API. If for any reason these commands don’t work, you can also download OS-Agent manually.

To do this, first go ahead and visit the releases download page and locate the correct package for your architecture. You will need the package with a .deb extension in order to install it on Debian.

Right-click the package and copy the link address, then use this address with the wget command.

wget <OS-agent URL>

For example, at the time of writing the current version is 1.2.2, therefore the command would be as follows.

wget https://github.com/home-assistant/os-agent/releases/download/1.2.2/os-agent_1.2.2_linux_aarch64.deb

Installing OS-Agent

Once the package has downloaded, we can install it with dpkg followed by the package name. Replace <os-agent-version> with the version of OS Agent that you are using.

dpkg -i os-agent_<os-agent-version>.deb

Once complete, you can test the installation with the following command.

gdbus introspect --system --dest io.hass.os --object-path /io/hass/os

This command should not produce and error. The output should look something like the following.

Install Home Assistant Supervised

The last thing remaining to do is install Home Assistant. This can be done with the Home Assistant supervised Debian package.

First we can go ahead and download the package using wget.

wget https://github.com/home-assistant/supervised-installer/releases/latest/download/homeassistant-supervised.deb

Once the download has completed, we can install it with dpkg.

dpkg -i homeassistant-supervised.deb

Choose a machine type

You may need to select a machine type. For Apple Silicon Mac builds running Debian arm64, choose qemuarm-64. For Intel Mac builds running Debian x86_64, choose qemux86-64.

Once the installation has completed, Home Assistant will start up but it will take a few minutes before we can access it.

The IP address of our Home Assistant server is given at the end of installation, in my case 192.168.64.5:8123.

In order to check that the installation was successful, go ahead and visit the IP address using a browser.

http://<your-ip-address>:<your-port>

So in my case it would be as follows.

http://192.168.64.5:8123

Configuring Bridged Mode Networking

By default the VM is configured to use a network mode called “shared network” as it offers the most compatibility out of the box.

This mode creates a virtual network between the guest OS (Debian) and the host OS (Mac OS) and provides the guest OS with access to the internet.

One disadvantage to this method of networking is it does not allow devices on your local network outside of the host OS to access the guest OS, which means you can only access Home Assistant from the browser on your host OS.

The following diagram can help you better understand the difference between the network modes:

In order to access Home Assistant from other devices on your local network (the mobile app, other computers on the network or IP-based smart devices), the Debian guest operating system should have it’s own IP address on your external network that is in the same subnet, for example 192.168.1.X.

This can be achieved by changing the networking mode. You can change the network mode with the following steps:

1. Shut down the Home Assistant Debian virtual machine if it is currently running.
2. Right click the Home Assistant Debian virtual machine on the left-hand sidebar and click edit.
3. Under Devices, click Network to show the network settings.
4. In the Network Mode drop down list, change the setting to Bridged (Advanced) and then click Save.
5. Start the Home Assistant Debian virtual machine.

When you boot the virtual machine with the new network settings, the IP address assigned should now match your local area network and you should be able to connect from external devices, such as other computers or the mobile app.

Bridged network mode and Ethernet

If you want to switch to bridged networking mode and use Ethernet, you will need to complete an additional step. By default UTM will create a network bridge to your WiFi adapter

If you have both WiFi and wired network connections (Ethernet) on your Mac and you want to use Ethernet, you will need to manually change the network bridge so that it uses Ethernet.

In mostly all cases the WiFi interface is called en0 and the Ethernet is called en1.

To connect the network bridge to ethernet, simply enter en1 as the value for Bridged Interface on the Network settings menu.

Conclusion

In conclusion, running Home Assistant on macOS with a Debian 12 virtual machine offers a compelling and accessible approach to creating a smart home hub within your existing computing environment.

By harnessing the power of virtualization through UTM, you can seamlessly integrate Home Assistant into your macOS ecosystem and gain control over a diverse range of smart devices from a centralized interface.

Throughout this journey, we have explored the intricate workings of this setup, from configuring the virtual machine and installing Debian 12 to setting up Home Assistant as the heart of your smart home automation.

The flexibility and convenience of this approach eliminate the need for dedicated hardware, making it an enticing option for both newcomers and experienced enthusiasts.

Embrace the power of Home Assistant on macOS with a Debian 12 virtual machine, and let your home thrive in the world of interconnected possibilities. It’s time to experience the magic of home automation at your fingertips. Happy automating!