This section will provide guides to some common tasks and information which you will need in order to run, maintain, and edit your Home Assistant OS system. For further details on any particular subject, make sure to refer to the documentation for specific add-ons or topics listed here.
Best practice for updating a Home Assistant installation:
Backup your installation, using the backup functionality Home Assistant offers.
Check the release notes for breaking changes on Home Assistant release notes. Be sure to check all release notes between the version you are running and the one you are upgrading to. Use the search function in your browser (
CTRL + f/
CMD + f) and search for Breaking Changes.
Check your configuration using the Check Home Assistant configuration add-on.
If the check passes, you can safely update. If not, update your configuration accordingly.
Update Home Assistant.
To update Home Assistant Core when you run Home Assistant Operating System you have 2 options.
- Open your Home Assistant UI
- Navigate to the Configuration panel
- On the top you will be presented with an update notification
If you do not see that notification you can navigate to the Configuration > Add-ons & Backups > System panel. and click the “Reload Supervisor” button.
ha core update
In the event that a Home Assistant Core version doesn’t play well with your hardware setup, you can downgrade to a previous release. In this example
2021.12.10 is used as the target version but you can choose the version you desire to run.
ha core update --version 2021.12.10
If you would like to test next release before anyone else, you can install the beta version.
- In your Home Assistant UI navigate to Configuration > Add-ons & Backups > System
- Click the link that says “Join beta”
- Navigate to Configuration panel
- Install the update that is presented to you
Join the beta channel
ha supervisor options --channel beta
Reload the supervisor
ha supervisor reload
Update Home Assistant core to the latest beta version
ha core update
If you want to stay on the bleeding-edge Home Assistant Core development branch, you can upgrade to
dev branch is likely to be unstable. Potential consequences include loss of data and instance corruption.
Join the dev channel
ha supervisor options --channel dev
Reload the supervisor
ha supervisor reload
Update Home Assistant core to the latest dev version
ha core update
ha core check
Your Home Assistant Operating server includes two repositories by default: The official core add-on repository, and the community add-on repository. All of the add-ons mentioned here can be installed by navigating to the add-on store using Configuration > Add-ons & Backups > Add-on Store in the UI.
One of the first things to take care of after installing Home Assistant OS is to provide yourself access to files. There are several add-ons commonly used for this, and most users employ a mix of various add-ons. Default directories on the host are mapped to the add-ons so that they can be accessed by the services any particular add-on might provide. On the host system these directories exist on the
/data partition at
Using any of the add-ons listed below,the following directories are made available for access:
The Samba add-on creates smb shares which can be accessed from another computer. You can also edit files using the editor of your preference from your client computer. This add-on can be installed from the add-on store’s official repository.
To configure the Samba add-on, you only need to set a user and password of your choice on the configuration page, save, and then start the add-on. The add-on will not start without setting a password!
To connect to the Samba server from another device, you will use the IP address or hostname of your server. Either of these can be found on the Configuration > Add-ons & Backups > System page of your UI within the Host card.
For connecting from Windows 10, you can enter the IP address or hostname in File Explorer’s address bar with two backslashes, as shown in the example screenshot.
You should then be prompted for the credentials you entered in the Samba add-on configuration. You also have the option of having the credentials stored so that you do not need to enter them again. After that, you’ll have access to the directories which you can then mount as a drive or pin to Quick Access.
For OS X, connecting to the shares is a matter of using the Finder menu > Go > Connect to Server…
You would then enter the IP address or hostname of your Home Assistant OS instance as
smb://homeassistant and enter your credentials when prompted.
The Terminal & SSH add-on provides access over an SSH connection, and also includes nano and vi editors. It can be installed from the add-on store’s Official add-on repository after enabling advanced mode for your Home Assistant user’s profile. Additionally, this add-on provides access to the Home Assistant Command Line Interface (CLI) which provides custom commands for checking logs, stopping and starting Home Assistant and add-ons, creating/restoring backups, and more. (See Home Assistant via Command Line for further info). The Terminal & SSH add-on does not provide access to the underlying host file system.
To use the add-on, enter a password or public key on its configuration page, then save and start the add-on.
The Terminal & SSH add-on also provides a web terminal which allows you to access a terminal via the Home Assistant user interface. In order to access from an ssh client, a port needs to be entered in the network section of the add-on’s configuration page.
The Visual Studio Code add-on provides access through a feature packed web-based version of the Visual Studio Code editor and currently only supports AMD64 and aarch64/ARM64 machines. This add-on can be installed in the add-on store from the Community add-on repository. The add-on also provides access to the Home Assistant Command Line Interface (CLI) using VSC’s built in terminal, which allows for checking logs, stopping and starting Home Assistant and add-ons, creating/restoring backups, and more. (See Home Assistant via Command Line for further info).
There is no configuration required for editing files within your
/config directory. In order to enable access to other directories, it is necessary to edit the add-on’s configuration from its configuration tab. See the add-on documentation for details.
A more basic and light weight alternative to Visual Studio Code, the File Editor add-on provides access through Hass-Configurator, which is a web-based filesystem-browser and text-editor. YAML files are automatically checked for syntax errors while editing. This add-on can be installed via the add-on store from the official add-on repository.
There is no configuration required for editing files within your
/config directory. In order to enable access to further directories, editing the add-on configuration is required. See the add-on documentation for details.
Backup of your Home Assistant and add-on data and configuration. They are stored in a compressed archive file (.tar). Backups are made from the Supervisor Backups panel. There is also a service available that allows you to trigger the creation of a backup from an automation. Backups are stored in the /backup directory.
A full backup includes the following directories:
addons(only manually installed or created add-ons, not those installed from the store)
A partial backup consists of any number of the above default directories and installed add-ons.
- Go to Configuration > Add-ons & Backups > Backups in the UI.
- Provide a name for the backup.
- Choose full or partial.
- Choose to password protect or not. Password-protected backups cannot easily be browsed outside of Home Assistant OS.
- Click “Create” to begin the backup.
You can make use of backup which you have copied off of a previous install to restore to a new installation during the onboarding process. Follow the link at the bottom of the account creation page to upload your backup from the previous installation.
For restoring a backup at any other time, visit the Supervisor backup panel in your UI and use the following steps:
- Select “Upload Backup” from the icon in the upper right of the page.
- Click on the folder icon to navigate to your backup .tar file and select it.
When the upload is completed, you will be presented with the backup restore dialog for restoring it, and can then choose to restore in full or in part by manually selecting individual items.
If the backup you are uploading is more than 1GB in size, it can be faster and more efficient to make use of the Samba add-on in order to transfer files to the
The length of time it takes to create or restore backup will depend on how much you have to compress or decompress.
If you’re looking to slim down your backup, check if your configuration directory contains a large database file (
home-assistant_v2.db). See the
recorder integration page for options to keep your database data down to a size that won’t cause issues. Note the keep days, purge interval, and include/exclude options.
When the restore is complete, Home Assistant will restart to apply the new settings. You will lose the connection to the UI and it will return once the restart is completed.
ha backups list- lists backups and their slugnames
ha backups restore slugname- restores a specific backup
ha backups new --name nameofbackup- create a backup
ha help to get more information about the command line usage.
You often need a backup in case your system has crashed. If you only store them on the crashed device, you won’t be able to access them easily. We recommend that you manually copy them from
/backup to another machine on occasion. Or even better, create an automation to handle that, or make use of one of the following add-ons:
Home Assistant upgrade process from the SSH command line
On the SSH command line, you can use the
ha command to retrieve logs, check the details of connected hardware, and more.
ha core check ha core info ha core logs ha core options ha core rebuild ha core restart ha core start ha core stats ha core stop ha core update
ha supervisor info ha supervisor logs ha supervisor reload ha supervisor update
ha host reboot ha host shutdown ha host update
ha hardware info ha hardware audio
To update Home Assistant to a specific version, use the command:
ha core update --version x.y.z
Replace x.y.z with the desired version like
You can get a better description of the CLI capabilities by typing
The Home Assistant CLI is a small and simple command line utility that allows you to control and configure different aspects of Home Assistant Usage: ha [command] Available Commands: addons Install, update, remove and configure Home Assistant add-ons audio Audio device handling. authentication Authentication for Home Assistant users. backups Create, restore and remove backups banner Prints the CLI Home Assistant banner along with some useful information cli Get information, update or configure the Home Assistant cli backend core Provides control of the Home Assistant Core dns Get information, update or configure the Home Assistant DNS server docker Docker backend specific for info and OCI configuration hardware Provides hardware information about your system help Help about any command host Control the host/system that Home Assistant is running on info Provides a general Home Assistant information overview jobs Get information and manage running jobs multicast Get information, update or configure the Home Assistant Multicast network Network specific for updating, info and configuration imports observer Get information, update or configure the Home Assistant observer os Operating System specific for updating, info and configuration imports resolution Resolution center of Supervisor, show issues and suggest solutions supervisor Monitor, control and configure the Home Assistant Supervisor Flags: --api-token string Home Assistant Supervisor API token --config string Optional config file (default is $HOME/.homeassistant.yaml) --endpoint string Endpoint for Home Assistant Supervisor (default is 'supervisor') -h, --help help for ha --log-level string Log level (defaults to Warn) --no-progress Disable the progress spinner --raw-json Output raw JSON from the API Use "ha [command] --help" for more information about a command.
You can also access the Home Assistant Operating System via a directly connected keyboard and monitor, the console.
Please refer to the I’m locked out! documentation page.
Home Assistant allows anyone to create add-on repositories to share their add-ons easily. To try this locally, you can use our example add-on repository at
From Configuration > Add-ons & Backups open the add-on store.
Add the URL of the repository and then press "Add". A new card for the repository will appear.
If you have added a repository, but it’s not showing up, it means that the repository contains invalid configuration. Go to Configuration > Add-ons & Backups > System to find the System log. It should tell you what went wrong. Report this information to the repository author.
Home Assistant Operating System supports storing most data on an external storage medium (e.g. USB attached SSD or HDD). This data disk contains not only user data but also most of the Home Assistant software as well (Core, Supervisor etc.). This means a fast data disk will make the system overall much faster.
The data disk feature can be used on an existing installation without losing data: The system will move existing data to the external data disk automatically. However, it is recommended to create and download a full Backup before proceeding!
All data on the target disk will be overwritten!
The storage capacity of the external data disk must be larger than the storage capacity of the existing (boot) disk.
If you have been using a data disk previously with Home Assistant Operating System, you need to use your host computer to delete all partitions before using it as a data disk again.
- Connect the data disk to your system.
- Go to Configuration > Add-ons & Backups > System in the UI.
- Press the three dots on the bottom right of the Host card and choose “Move datadisk”
- Select the data disk from the list of available devices.
- Press “Move”.
To see the current data disk use:
$ ha os info ... data_disk: /dev/mmcblk1p4 ...
To getting a list of supported detected devices which can be used by
ha os datadisk list
To initiate the move to the new data disk use the
ha os datadisk move /dev/sdx
The system will prepare the data disk and immediately reboot. The reboot will take 10 minutes or more depending on the speed of the new data disk; please be patient!
Using an USB attached SSD can draw quite some power. For instance on Raspberry Pi 3 the official Raspberry Pi power supply (PSU) only provides 2.5A which can be too tight. Use a more powerful power supply if you experience issues. Alternatively use a powered USB hub. Connect the Hub to one of the USB slots of your Raspberry Pi, and connect the SSD to the Hub. In this setup the power supply of the Hub will power the attached device(s).
Home Assistant can be flashed to an ODROID-N2+ by connecting the device directly to your computer via the USB-OTG connection on the front of the board. The device contains the Petitboot bootloader, which allows the ODROID-N2+ storage to show up as it were a USB drive.
All these instructions work the same for the ODROID-N2 (non-plus version).
To flash your eMMC using Petitboot and OTG-USB, you will need the following items:
- HDMI cable and monitor
- USB keyboard
- USB 2.0 to micro-USB cable
To enable the SPI boot mode:
Power off the ODROID-N2+ by unplugging the power cable.
Remove the case.
Locate the toggle for boot mode and switch it from MMC to SPI.
Connect the ODROID-N2+ directly to your computer via the USB-OTG port located on the front of the board.
Connect a USB keyboard and a monitor (using HDMI) to your ODROID-N2+.
Plug in the power cable to power on the ODROID-N2+.
After The ODROID-N2+ is set to SPI boot mode and powered on, it boots into a terminal. To enable the USB drive mode:
Exit to shellfrom the menu.
When using the command line, it may return the following message:
can't access tty; job control turned off.
You can safely ignore this message and proceed with the installation
Use the following command at the console to confirm the storage device node:
Set the storage device on the ODROID-N2+ as a mass storage device using the
umscommand (USB Mass storage mode). This will configure the ODROID-N2+ and OTG to act as a memory card reader:
Connect the ODROID-N2+ to your PC via the micro-USB port at the front of the ODROID-N2+. When the ODROID-N2 is recognized as a USB connected storage device, you can flash the eMMC with Etcher using the latest stable version of Home Assistant OS for the ODROID-N2+ (haos_odroid-n2-7.1.img.xz).
When the flash process is complete, disconnect the ODROID-N2+ from your PC and remove the power cable. Remove the USB and HDMI cable, and make sure to toggle the boot mode switch back to MMC.
Once it is back in its case, connect your ODROID-N2+ to your network with an Ethernet cable and plug in power.
If your router supports mDNS, you will be able to reach your installation on
http://homeassistant.local:8123. If your network doesn’t support mDNS, you’ll have to use the IP address of your ODROID-N2+ instead of
homeassistant.local. For example,
http://192.168.0.9:8123. You should be able to find the IP address of your ODROID-N2+ from the admin interface of your router.
Home Assistant using the Home Assistant Operating System which is a managed environment, which means you can’t use existing methods to enable the I2C bus on a Raspberry Pi. In order to use I2C devices you will have to
- Enable I2C for the Home Assistant Operating System
- Setup I2C devices e.g. sensors
You will need:
- SD card reader
- SD card with Home Assistant Operating System flashed on it
Shutdown/turn-off your Home Assistant installation and unplug the SD card.
Plug the SD card into an SD card reader and find a drive/file system named
hassos-boot. The file system might be shown/mounted automatically. If not,
use your operating systems disk management utility to find the SD card reader
and make sure the first partition is available.
- In the root of the
hassos-bootpartition, add a new folder called
- In the
CONFIGfolder, add another new folder called
- Inside the
modulesfolder add a text file called
rpi-i2c.confwith the following content:
- In the root of the
hassos-bootpartition, edit the file called
config.txtadd two lines to it:
- Insert the SD card back into your Raspberry Pi.
- On startup, the
hassos-config.servicewill automatically pickup the new
- Another reboot might be necessary to make sure the just imported
rpi-i2c.confis present at boot time.
Alternatively, by attaching a keyboard and screen to your device, you can access the physical terminal to the Home Assistant Operating System.
You can enable I2C via this terminal:
loginand press enter to access the shell.
Type the following to enable I2C, you may need to replace
mmcblk0p1depending on your platform:
mkdir /tmp/mnt mount /dev/sda1 /tmp/mnt mkdir -p /tmp/mnt/CONFIG/modules echo -ne i2c-dev>/tmp/mnt/CONFIG/modules/rpi-i2c.conf echo dtparam=i2c_vc=on >> /tmp/mnt/CONFIG/config.txt echo dtparam=i2c_arm=on >> /tmp/mnt/CONFIG/config.txt sync reboot
After rebooting the host there should be
i2c-0 and similar device files in
/dev. If such device files are missing, enabling I2C failed for some reason. You can check the status of I2C kernel modules by using
lsmod | grep i2c in the terminal. If they are loaded, you should find at least the entry
i2c_dev. Active usage of the modules is indicated by a number, e.g.
i2c_dev 20480 2 would indicate two active I2C device files.
An active I2C can also be checked with a multi meter showing 3.3 V on the I2C pins GPIO2 and GPIO3.