Installing Home Assistant Supervised using Debian 12

Installing Home Assistant Supervised using Debian 12

:stop_sign: Before proceeding, please read the following information :stop_sign:

It is being made increasing difficult to run a Supervised installation, by choosing to do so you understand the guidelines linked in the next paragraph. If you are new to Home Assistant and/or Linux, then this installation type is most likely not for you and you should choose to run Home Assistant OS on your machine.

:warning: A PR has now been merged into the Supervised installer that will block any attempt at installation on an OS that is not supported, such as Ubuntu. DO NOT post in this thread about your OS not being supported, you must run Debian.

:warning: Using Debian 12 and following a strict set of guidelines available HERE will give you an officially supported installation of Home Assistant Supervised. If you choose at anytime to install additional software to the Debian operating system, your installation may become officially unsupported.

:warning: If you do not understand what this means, or that making almost any changes to the underlying OS may render your install Unsupported/Unhealthy, this installation method is not for you and you should install HA OS. If you do not require the supervisor, then installing HA Container may be a better option and will allow you full control over the OS to install additional software and Docker containers.

:white_check_mark: This guide will help you to install Home Assistant Supervised, on almost any machine type you choose. This guide has been tested on machines including a Lenovo m72e, Dell Optiplex SFF 990, Dell Optiplex USFF 780 and a HP T520 thin client. If you are using a Raspberry Pi, follow this guide.

While every effort has been made to ensure this guide complies with ADR-0014, no guarantee can be made it does now, or in the future.

In this guide, you will be using Debian 12 as the operating system. This type of installation is what is called “headless” and after the installation is complete, you will not need to have a keyboard, mouse or monitor attached, although you can if you prefer.

What is Home Assistant Supervised?

Home Assistant is a full UI managed home automation ecosystem that runs Home Assistant Core, the Home Assistant Supervisor and add-ons. It comes pre-installed on Home Assistant OS, but can be installed on any Linux system. It leverages Docker, which is managed by the Home Assistant Supervisor plus the added benefit of dozens of add-ons (think app store) that work natively inside the Home Assistant environment.

If you are new to Home Assistant, you can now proceed to Section 1 if you need assistance with installing Debian 12. If you already have Debian 12 installed and wish to move on to installing Home Assistant, move on to Section 2.

Section 1 – Install Debian 12

If you would like a step by step guide on how to install Debian 12 to your machine, click here to expand for instructions.

1.1) Start by downloading debian-live-12.x.x-amd64-standard.iso from HERE.

1.2) While Debian is downloading, you will need some other programs to help with the setup and installation. To burn the Debian ISO image to a USB thumb drive, you will use a program called Rufus which can be downloaded from HERE.

1.3) You will now create a bootable USB drive using Rufus and the Debian image you have downloaded. Insert a blank USB drive of at least 8gb into your PC, open Rufus and choose your USB from the drop-down menu. Now select the Debian ISO image you downloaded, and click Start. If you get any prompts, select OK or Yes to continue. When this has completed, you can move on.

1.4) Insert the USB you have just made into the new machine, connect a monitor, Ethernet cable, keyboard and mouse, and power on the machine. You will need to select the USB drive as the boot device, to do this, you will need to press something like F12 or DEL on your keyboard immediately when the machine is powered on.

1.5) The first screen you should be able to select from is Boot Menu, on this screen, select Advanced Install Options, then Graphical Debian Installer and Install

1.6) Next will be Language. Choose your language and click continue.

1.7) Next will be Select your location. Choose your country and click continue.

1.8) Next will be Configure the keyboard. Select your keyboard type and click continue. The installer will now perform some automated tasks which will take 1-2 minutes.

1.9) Next will be Configure the network. Here you can name your machine, the default name will be debian. Choose a name and click continue. You can skip the next page by clicking continue as you do not need to set a domain name.

1.10) Next will be Set up users and passwords. You will be asked to create a password for the root user. Make a note of the password you choose here, and click continue.

1.11) Next will be Set up users and passwords again. Enter a username, click continue and on the next screen, enter a password for this user account. Make note of both of these, you will need them later.

1.12) Next will be Configure the clock. Select the correct time zone and click continue.

1.13) Next will be Partition Disks. Select Guided - use entire disk and then click continue. On the next screen make sure the correct disk is selected and click continue. On the next screen select All files in one partition and click continue. On the next screen, make sure Finish partitioning and write changes to disk is selected, and click continue. On the next screen, select Yes and then click continue. The installer will now perform some automated tasks. This will take 1-2 mins.

1.14) Next will be Configure the package manager. Select Yes and click continue. Select your Country and click continue. You can leave the default selection selected, or select another mirror of your choosing, and click continue. Leave the next page blank and click continue. The installer will now perform some automated tasks. This will take a few minutes.

1.15) Next will be Install the GRUB bootloader. Select Yes and click continue. Now select the drive you are installing Debian on, and click continue. The installer will now perform some automated tasks. This will take 1-2 mins and then installation will be complete.

1.16) In Debian, your user will not be a member of the sudo group so cannot run administrative commands. After the system has rebooted, log in as the root user and the password you set during Step 1.10. To add your user to the sudo group enter this command, and press Enter.

usermod -aG sudo username

where username is the one you setup during Step 1.11

1.17) Log out of the root account by pressing ctrl-d on your keyboard then to login to the machine using the username and password you created in Step 1.11.

1.18) Once this has completed, you will need to find the IP address of the machine. You can do this by checking your router, or by typing this command into the terminal.

ip a

You should now see some information on your screen showing network configuration. You are looking for information like inet, or, inet depending on your network setup. This is the IP of the machine and you can now use this to connect to the machine from another PC using a program lite Putty. Information on how to do this is at Step 3.3 below.

Section 2 - Install OS Agent, Docker and Dependencies

You will now install the OS Agent for Home Assistant. It is used for Home Assistant OS and Home Assistant Supervised installation types and it allows the Home Assistant Supervisor to communicate with the host operating system.

2.1) In terminal (or connected to your machine via SSH using Putty - see Step 3.3 for info), run the following commands to update the Debian OS, install Docker and the required dependencies for the OS Agent and the Supervised installer. Execute the following commands one at a time.

sudo -i

apt update && sudo apt upgrade -y && sudo apt autoremove -y

apt --fix-broken install

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

curl -fsSL | sh

2.2) Visit the OS Agent page and then replace the version number with the latest available, into the commands below. (i.e. replace all references to 1.6.0 with the latest available)

Execute the following commands one at a time.


dpkg -i os-agent_1.6.0_linux_x86_64.deb

Section 3 – Install Home Assistant Supervised

With the OS Agent and dependencies installed, you can move on to installing Home Assistant Supervised.

3.1) Enter each line of the below commands into the terminal and execute them one at a time.

If you have rebooted since section 2, make sure you are running as root before executing the below commands.

sudo -i

Execute the following commands one at a time.


apt install ./homeassistant-supervised.deb

:exclamation: If you run into the ‘Waiting for - network interface might be down…’ error, open a 2nd Putty/SSH Window (leave the first one going) and enter

sudo nano /etc/resolv.conf 

Then arrow down to nameserver and change the default value to, then press ‘Ctrl+x’ on your Keyboard, Press ‘y’ and then ‘enter’ to confirm. The installer should now continue without error.

3.2) You may be prompted to choose a machine type during the installation process, if so, choose generic-x86-64.

The installation time is generally under 5 mins, however it can take longer so be patient. You can check the progress of Home Assistant setup by connecting to the IP address of your machine in Chrome/Firefox on port 8123. (e.g.

Once you can see the login screen, the setup has been completed and you can set up an account name and password. If you are new to Home Assistant you can now configure any smart devices that Home Assistant has automatically discovered on your network. If you have an existing Home Assistant install and you have a snapshot or YAML files you wish to restore, refer to the document Backing up and Restoring your configuration.

You have completed the installation of Home Assistant Supervised on your Debian machine. It is recommended that you log into your machine at least once a month and use the following command to download security patches and keep the OS up to date. You can do this directly on the machine itself via the terminal.

sudo apt update && sudo apt upgrade -y && sudo apt autoremove -y

3.3) If you wish to install Open-SSH so you can remotely connect to your Home Assistant machine from another PC.

:warning: If you install Open-SSH you will not be adhering to the guidelines of ADR-0014 and therefore will not have an officially supported installation, however, installing Open-SSH will not break your machine. Run the following from console.

sudo apt install openssh-server -y

If you do choose to install and use Open-SSH, you can then use software called PuTTY, available HERE.

Putty is a free and open-source terminal emulator, serial console and network file transfer application. You can use Putty to execute commands on the Debian machine from your Windows PC. (Use Terminal on a Mac). To connect to the Debian machine via Putty, you will need the IP of the machine from Step 1.19, and the username and password you created from Step 1.10.

If you have an existing Home Assistant install and you have a snapshot or YAML files you wish to restore, refer to Home Assistant website on backing up and restoring your configuration, located HERE

Section 4 - Unhealthy Installation

If you are faced with the HA Supervisor showing you the 'Unhealthy Installation' error, click here to expand and follow this procedure to fix it.

4.1) Install the SSH & Web Terminal add-on from with the HA Supervisor add-on store. It looks like this.

Configure the add-on so you can connect to the HA container. Here is an example of a simple working configuration you can use, adjust the username and password to suit.

  username: USERNAME
  password: PASSWORD
  authorized_keys: []
  sftp: false
  compatibility_mode: false
  allow_agent_forwarding: false
  allow_remote_port_forwarding: false
  allow_tcp_forwarding: false
zsh: true
share_sessions: false
packages: []
init_commands: []

You will need to change the port to 23 (or other unused port number of your choosing) in the Network section of the Configuration tab. Once you have installed and configured the add-on, move on to the next step.

4.2) Using Putty, login to the HA machine using the IP of the machine and port 23. Use the username and password you configured in the previous step.

4.3) Once logged in you can now execute the following command;

ha jobs options --ignore-conditions healthy

Once you have done this, you should see a message saying, Command completed successfully. You can type exit to leave the shell connection. You can now also turn off/stop the SSH & Web Terminal add-on in HA as you will no longer need it. It can be restarted at anytime.


I welcome feedback on this guide, please feel free to tag me or PM if you have suggestions on how to make improvements.

Thank you to nickrout for testing, feedback and edits to help improve this guide and to others who have contributed code and ideas including Tamsy, you support is appreciated.

Old installation instructions using the script installer can be found on my Github, HERE

What Linux OS is ideal for HA?
HA on Intel NUC - which way?
Install NUC image in laptop? Better performance than HA supervised?
Installation Methods & Community Guides Wiki
Not updated in a while!
I got stuck... no addons
Installing Home Assistant Supervised on Ubuntu 18.04.4
Noob question about front end issues
Restore backup from Google Drive add-on not working
Finally upgraded home assistant. now everything is broken
Debian 10 HA docker You are running an unsupported installation. Learn More
HassOS for custom board (hardware)
Ubuntu Upgrade Killed Everything
New User... what do I need?
No user integration in HA supervised - missing in settings panel
Restore backup from Google Drive add-on not working
Homeassistant update to 118.5 from 107.5 issue
Problem install Home Assistant Supervised in a Docker on a Ubuntu 20.04
Yet another hardware question. New starter
Best way to install Home Assistant with linux desktop and proxmox(?)
Unable to update - Supervisor not privileged
Nuc and Docker: HAOS in VM, performance, experience?
How to modify homeassitant container to include docker.sock?
HA Core is keep crashing in Supervisor installation
Home Assistant Supervised installed on a desktop PC
Home Assistant Supervised installed on a desktop PC
Install HA on Acer laptop
Optimizing old laptop for HA server use
What's better? VM or supervised (for a laptop)
No eth0 after install generic x64 image
Home Assistant OS on a small PC with an AMD E350 APU?
Home Assistant installation
HA supervised on a 32 bit laptop?
NUC install: HA OS image vs. Proxmox vs. HA Supervised on Debian
Where did ssh go?
How to restore a snapshot on unhealthy HA
No space :(
TADO/ SONOFF Does not work after core-2021.3.2 upgrade ODROID docker
Issue witm Home Assistant Supervised 2021.4.6 intalled on Synology VM DSM 7
Home assistant on UBUNTU SERVER 20.04
Need Help Passing Usb Card to a Docker Container Running Hass OS
Installation on Docker
Install For Home Assistant
Install failed- no /etc/docker?
Best way to install on a NUC
[Solved] hassio_audio is in boot loop and spams my syslog with errors
Hardware, Software and configuration for my home, Noob
Mount Google Drive in Home Assistant OS
Simple Automations Don't Work
Installing Home Assistant OS on a Mini-PC
Why is it so complex and difficult to install and maintain HomeAssistant?
Local realtime person detection for RTSP cameras
Buying a device to run Home Assistant (April 2022 edition)
Supervised Debian 11 installation
Docker ha install error: network is unreachable. why?
Mouse on wheel
My steps to success for on Intel NUC
Nothing bootable found in an acer laptop
Home Assistant Supervised: “You are running an unsupported installation” and Debian version
No port opened - Debian
Supervisor update
WTH can't I easily run Add-ons via docker-compose when running Home Assistant Container?
HomeAssistant Core Image support for Node Red integrations
Suddenly complaining about systemd-resolved
Home Assistant Supervised: “You are running an unsupported installation” and Debian version
Install HA supervised in Docker Container
Installation Problem - Proxmox VM
What the best
HA Supervised vs HA Container - what are main differences?
HA Update Problems
Newbie questions: z-wave secure connection?
Ha supervised installation on pi4 (arm64) not working
Best method to install HA into old PC?
Install HA on 32bit - i386 intel
Supervised Install Leaves Addons In a Broken State, Until the Supervisor is Upgraded
Install HA on old laptop without UEFI
Installing Home Assistant Supervised on Debian 11 - IP address not being assigned
Lenovo Yoga 900 (only wifi) HA installation issue
HA installation failed
HAOS installation on old x64 laptop
Local "Virtual" Media player entity
Updating Home Assistant Core fails with vague "Unknown error, see supervisor" error
Problem with HA Supervised installation
Mount Google Drive in Home Assistant OS
New machine for HA, frigate, mariadb and NAS. Advice?
HAOS not booting on old Laptop (ASUS P52F)
Crashing logs?
Running docker stack on supervised HA install
Home assistant supervised on Debian 11: What exactly is meant by "managed os" not supported
Help needed: backup HA configuration using command line
Full Hardware Monitoring - no matter the platform
Can't install or run HA
HA Supervised / Debian11 - UI not opening after Restore on a different machine > Router port FW!
Change default docker ip
'HomeAssistantCore.update' blocked from execution, system is not healthy
HA & Frigate in a docker
Can't access Home Assistant GUI (supervised, debian 11) anymore
Installing HAOS on Debian 12 into Docker
How to use firmware search path? (e.g. `/mnt/data/supervisor/share/firmware`)
Backup / restore questions
Sonoff NSPanel by ITead - Smart Scene Wall Switch based on ESP32 and custom Nextion Touch Screen Panel Display (non-Pro variant)
Supervised on Debian Bullseye, dpkg -i homeassistant-supervised.deb fails
Supervised install: Which OS Agent for Rockchip ARM SBC?
HAOS install on Nano Pi R2S/R4S/R5C with separated networks?
Will HA work on an old (ex-Win7) PC?
HA supervised install on Debian bullseye brings cgroup and apparmor warnings
Add support for Odroid M1
Debian 12 (bookworm) supported?
Starting up HA on macbook pro
Home Assistant OS on Dell R220 with Perc H310 and RAID1?
Home Assistant without Zigbee2Mqtt installed
Time out waiting for hardware cmd interrupt Deb 11
Install on a NUC, help please
HA running but not healthy!
HassOS installation/network problem on Intel NUC
All looks ok but Home Assistant Supervised does not run - on Debian Buster
ESPHome 502 error
1 year in, where do I go next? (brain dump, sorry)
Trying to run before I can crawl? Attempt to port HA from Rpi to Docker on Ubuntu
Installing Home Assistant on NUC using image
My steps to success for on Intel NUC
More than 20 minutes to restart Home Assistant, normal?
Installation Methods & Community Guides Wiki
My steps to success for on Intel NUC
Installing Home Assistant OS on a Mini-PC
New installation on small PC
Generic x64 install
Installing Home Assistant Supervised on CoreELEC
Could not load the Supervisor panel! (after trying to update from 2021.8.8 to 2021.9.2)
How to install HA on my Sony Vaio with Linux Mint 20 (xfce 64 bit)
Installation of Home Assistant Operating System on old pc
[error] missing: apparmor
Server crashed- Reinstalling Home Assistant- no backup folder
More Trouble Than It's Worth? - Install Home Assistant Operating System on Generic x86-x64 PC
Unable to update - Supervisor not privileged
Home Assistant Cloud (Nabu Casa) Dissapeared from the configuraton menu?
Home Assistant Supervisor on Docker on Ubuntu Changed to Core
How to install HASS on OpenMediaVault on a Virtual Machine?
Problem instaling hassio supervised on Ubuntu & Intel NUC
System Showing as an Unsupported Instillation. NUC/Ubuntu/Docker
Installing Home Assistant OS using Proxmox 8
Meaning of "OS" for a returner
Home Assistant Supervised installed on a desktop PC
Installation Of Home Assistant OS over Ubuntu HELP
Auf Netbook installieren
Rebuild needed - hardware advice please - HP N54L to Rasp Pi?
Just installed HA on Ubuntu 20.04 - not flawless

On Debian in my experience it doesn’t install sudo if you set a root password so I ignore the prompt for a root password and create a user. I then add that user to the sudoers group.
It’s bad practice to actually use the root user for anything.

I wrote a guide for this on my blog (with screenshots) a year or so ago and a lot of people seem to have used this.


Can you link your blog or PM it to me please, I’d love to check it out.
I have not updated it after the repo moved a few months ago (I didn’t realise it had and now it’s going to move again anyway)


Thank you for your guide. Work out good

1 Like

Great guide, thank you.

It’s possible I missed something, but I couldn’t install the openssh-server as detailed above. I was getting an error message that dependency libwrap0 was not installable. I searched for the errors, and as per I checked . My /etc/apt/sources.list file looked like this:


# deb cdrom:[Official Debian GNU/Linux Live 10.4.0 standard 2020-05-09T10:43]/ buster main

#deb cdrom:[Official Debian GNU/Linux Live 10.4.0 standard 2020-05-09T10:43]/ buster main

deb buster/updates main
deb-src buster/updates main

# buster-updates, previously known as 'volatile'
# A network mirror was not selected during install.  The following entries
# are provided as examples, but you should amend them as appropriate
# for your mirror of choice.
# deb buster-updates main
# deb-src buster-updates main

# This system was installed using small removable media
# (e.g. netinst, live or single CD). The matching "deb cdrom"
# entries were disabled at the end of the installation process.
# For information about how to configure apt package sources,
# see the sources.list(5) manual.

I added these two lines (thought I’d try without uncommenting updates lines first):

deb buster main
deb-src buster main

… then ran sudo apt-get update, before running sudo apt-get install openssh-server again. This time it worked.


It’s odd they are commented out. I just checked my install and they are not commented out. Perhaps a region issue, I’m not sure.

Glad you found the solution.

1 Like

Simply disabling the service does not stop another unit starting it, it simply means it is not started automatically. you need to issue a mask command to prevent it being started in any way.

Or simply

sudo apt-get purge modemmanager

I suggest configuring apt unattended upgrades rather than relying on remembering to login and upgrade every so often.

1 Like

I suggest that is a really bad idea. I assume you have never done that? If you have and have ever had a docker upgrade you would never do that.


You can exclude docker from automatic upgrades. Installing security updates for everything else is important though. I have many production servers running this.

1 Like

TLDR: can I install Home Assistant of any variety on a 32 bit netbook or am I wasting everyone’s time?

I note that this guide is for 64 bit machines but I am appealing to the combined wisdom and experience of the community here. I’ve been trying for the last 3 days to install Home Assistant (whether Core, Supervised or other) with no success. This is mostly due to the fact that I am trying to install to a Samsung NC10, 32 bit, 1.60 Atom, 2GB RAM, with the 32 bit architecture being a limiting factor.

I have tried to install on a VM within Ubuntu 16.04 (their last 32 bit release) and also with Python on Ubuntu and Lubuntu. I keep on running into Python version conflicts (the install requires minimum version 3.7) that I cannot resolve. What I have discovered is that uninstalling Python from Ubuntu is a Very Bad Idea.

Edit: reason I am posting here is that I am busy downloading Debian Buster to have a try on that.

It’s for any machine x64/86 machine.

If your download the 32bit Debian image, you should be fine.

Good news, thanks for your prompt reply. I’m done with the download and will start installing shortly, I’ll post the outcome…

The Debian install hangs at ‘‘Configure the network’’. I used debian-live-10.4.0-i386-lxde+nonfree.iso from

The SHA-1 checksum is good so I’m a little puzzled. I will download a different ISO and try that.

You might try this one :

Thanks francisp, downloading now.

Edit: Debian installed, busy now wiith the Home Assistant install,but stuck on:

curl -fsSL | sh

response is: curl: (6) Could not resolve host:

Advice please?

Edit 2: I tried the curl command a few times., have now progressed a little but the response ends with:

E: Package ‘docker-ce’ has no installation candidate

I vaguely recall reading that docker does not work on 32 bit machines, but I could be completely wrong.

Thanks for the guide, all the details were helpful!

I’ll just add that I also had to add the two lines mentioned by @SadGamerGeek to my sources.list file.

I’m really happy with the results already.

1 Like

Those lines are already in the file, but commented out, so they don’t need to be added, just have the comment removed.

I’ve tried to replicate that issue with a couple more test installs myself, and don’t have the problem. Perhaps it’s a region issue.

1 Like