Common tasks - Operating System


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.

Update

Best practice for updating a Home Assistant installation:

  1. Backup your installation, using the backup functionality Home Assistant offers.

  2. Check the release notes for backward-incompatible 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 Backward-incompatible changes.

  3. Select “Create backup before updating” in case you encounter an issue that requires a rollback.

  4. Update Home Assistant.

  5. Review persistent notifications and log to see if there are any issues with your configuration that need to be addressed.

To update Home Assistant Core when you run Home Assistant Operating System you have 2 options.

  1. Open your Home Assistant UI
  2. Navigate to the Settings panel
  3. On the top you will be presented with an update notification

If you do not see that notification you can click the overflow menu in the top right and select “Check for updates”.

ha core update --backup

The --backup flag here ensures that you have a partial backup of your current setup incase you need to downgrade.

Run a specific version

You can use the CLI to upgrade to a specific version (2024.2.3 in this example), to downgrade your installation you should do a partial restore of a backup instead.

ha core update --version 2024.2.3 --backup

The --backup flag here ensures that you have a partial backup of your current setup incase you need to downgrade.

Run a beta version

If you would like to test next release before anyone else, you can install the beta version.

  1. In your Home Assistant UI navigate to System > Updates
  2. Click the overflow menu in the top right corner
  3. Click “Join beta”
  4. Navigate to Configuration panel
  5. Install the update that is presented to you
  1. Join the beta channel

    ha supervisor options --channel beta
    
  2. Reload the supervisor

    ha supervisor reload
    
  3. Update Home Assistant core to the latest beta version

    ha core update --backup
    

    The --backup flag here ensures that you have a partial backup of your current setup incase you need to downgrade.

Run a development version

If you want to stay on the bleeding-edge Home Assistant Core development branch, you can upgrade to dev.

The dev branch is likely to be unstable. Potential consequences include loss of data and instance corruption.

  1. Join the dev channel

    ha supervisor options --channel dev
    
  2. Reload the supervisor

    ha supervisor reload
    
  3. Update Home Assistant core to the latest dev version

    ha core update --backup
    

    The --backup flag here ensures that you have a partial backup of your current setup incase you need to downgrade.

Configuration check

ha core check

Configuring access to files

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 Settings > Add-ons > 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 /mnt/data/supervisor/.

Using any of the add-ons listed below,the following directories are made available for access:

  • addons
  • backup
  • config
  • media
  • share
  • ssl

Installing and using the Samba add-on

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 Settings > System > Network page of your UI.

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://your.ha.ip.address or smb://homeassistant and enter your credentials when prompted.


Installing and using the SSH add-on (requires enabling advanced mode for the HA user)

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.


Installing and using the Visual Studio Code (VSC) add-on

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.


Installing and using the File Editor add-on

The File Editor add-on is a web-based file system browser and text editor. It is a more basic and light weight alternative to Visual Studio Code. YAML files are automatically checked for syntax errors while editing. To install and use the File Editor in Home Assistant, follow these steps:

  1. To install the add-on, go to Settings > Add-ons > File editor.
    • Once you have the add-on installed, you can edit files within your /config directory.
  2. If you want to be able to access directories outside the /config directory, in the add-on, open the Configuration tab and disable the Enforce basepath option.
    • Note: The Enforce basepath option is intended to protect you from inadvertently making changes to settings files.
  3. For information on other configuration settings, open the Documentation tab.
  4. To confirm your changes, select Save.
  5. To start browsing, on the Info tab, select Open Web UI.

Backups

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 backups panel under Settings > System > Backups. There is also a service available that allows you to trigger the creation of a backup from an automation. By default, backups are stored locally in the /backup directory.

A full backup includes the following directories:

  • config
  • share
  • addons (only manually installed or created add-ons, not those installed from the store)
  • ssl
  • media

A partial backup consists of any number of the above default directories and installed add-ons.

Preparing for a backup

  1. Before creating a backup, check if you can reduce the size of the backup.
    • Check if your configuration directory contains a large database file. Go to Settings > System > Repairs. From the three dot menu, select System information and under the Recorder section, look for the Estimated Database Size (MiB).
    • By default, the data is kept for 10 days. If you have modified that to a longer period, check 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.
    • If you have add-ons installed that you no longer use, uninstall those add-ons. Some add-ons require quite a bit of space.
  2. Old backups are not included in the backup. However, while you are here, you could delete all old and unneeded backups.

Making a backup from the UI

  1. Go to Settings > System > Backups in the UI.
  2. Select the Create backup button in the lower right.
  3. Provide a name for the backup.
  4. Choose full or partial.
  5. Optionally, enable password protection.
  6. Select Create to begin the backup.

Alternative: Creating a backup using the Home Assistant Command Line Interface

  1. ha backups list - lists backups and their slugnames
  2. ha backups restore slugname - restores a specific backup
  3. ha backups new --name nameofbackup - create a backup

Use ha help to get more information about the command line usage.

Copying your backups to another location

You might need a backup in case your system has crashed. If you only store them on the device itself, you won’t be able to access them easily. We recommend that you copy them from /backup to another machine on occasion.

There are multiple ways to store the backup on another device:

Restoring a backup

There are two ways to use a backup:

  • On your current system to recover your settings.
  • During onboarding, to migrate your setup to a new device or a to device on which you performed a factory reset and a new installation.

Estimated duration

The time it takes to restore a backup depends on your installation. Home Assistant Core and all add-ons are being reinstalled. For a larger installation, this process can take about 45 minutes.

Restoring a backup during onboarding

You can use a backup during the onboarding process to restore your configuration.

Migration: This procedure also works if you want to migrate from one device to another. In that case, use the backup of the old device on the new device. The target device can be a different device type. For example, you can migrate from a Raspberry Pi to another device.

Prerequisites
  • This procedure assumes you have already completed the installation procedure on your target device and are now viewing the welcome screen as part of the onboarding.
  • The login credentials of the device from which you made the backup.
  • Required storage capacity: If you migrate the installation to a new device, make sure the new device has more storage capacity than the existing device.
    • Before migrating, on the old system, check how much storage you used.
      • Go to Settings > System > Repairs -> … -> System Information, and under Home Assistant Supervisor, look at the Disk used value.
      • The target device must have more free space than the source device.
        • If your target device is a Home Assistant Yellow, note that it is the size of the eMMC that is relevant.
        • The restore process mainly uses the eMMC, not the NVMe.
        • The size of the backup file is no indication of the size of your installation. To know the size of your installation, you need to check the Disk used value mentioned above.
  • If you are migrating to a new device:
    • You do not need to transfer the backup to a USB or SD card to bring it to your device.
    • You will be able to upload the backup file from the device you are accessing the onboarding from.
To restore a backup during onboarding
  1. If you are migrating to a new device and you had controllers or radios connected (such as a Z-Wave stick or SkyConnect):
    • make sure to plug them into the new device.
  2. After Home Assistant has been installed, on the welcome screen, select Restore from backup.
    • Then, select Upload backup.
    • The file explorer opens on the device on which you are viewing the Home Assistant User interface.
    • You can access any connected network drive from there.
  3. Select the backup file, then, in the dialog, select Full backup and Restore.
    • The restore may take a while, depending on the amount of data.
    • To see if the restore is complete, reload the page from time to time.
    • If your previous installation had certificates enabled directly for the http integration, when the restore is complete, it will no longer respond to http:// requests. In this case, use https:// (added s) instead.
  4. On the login screen, enter the credentials of the system from which you took the backup.
    • Your dashboard should show all the elements as they were when you created the backup.
    • If some devices are shown as unavailable, you may need to wake the battery powered devices.
  5. If you had network storage connected on the previous system, you may need to reconnect those.
  6. If you had Zigbee devices, and you migrated to a new device with its own Zigbee radio built-in:
    • Because this is now a different Zigbee radio, you need to migrate Zigbee.

To restore a backup on your current system

  1. Go to Settings > System > Backups.
  2. From the list of backups, select the backup from which you want to restore.
  3. If you want to restore the complete configuration with all directories and add-ons, select Full backup.
  4. If you only want to restore specific elements, select Partial backup.
    • From the list, select the installation, folders, and add-ons you want to restore.
  5. Select Restore.
    • This may take a while, depending on how much you have to compress or decompress.
  6. Once the restore is complete, Home Assistant restarts to apply the new settings.
    • You will lose the connection to the UI and it will return once the restart is completed.

Network storage

You can configure both Network File Share (NFS) and Windows samba (CIFS) targets to be used within Home Assistant and add-ons. To list all your currently connected network storages, go to Settings > System > Storage in the UI.

You need to update to Home Assistant Operating System 10.2 before you can use this feature.

Screenshot of the list of network shares inside the storage panel.

Add a new network storage

  1. Go to Settings > System > Storage in the UI.
  2. Select Add network storage.
  3. Fill out all the information for your network storage.
  4. Select Connect.

Screenshot of connecting a new network storage.

Network storage configuration

Name

This is the name that will be used for the mounted directory on your system.

Usage

Here, you select how the target should be used. See usage types below

Server

The IP/hostname of the server running NFS/CIFS.

Protocol3

The service the server is using for the network storage.

[NFS]1 Remote share path

The path used to connect to the remote storage server.

[CIFS]2 Username

The username to use when connecting to the storage server.

[CIFS]2 Password

The password to use when connecting to the storage server.

[CIFS]2 Share

The share to connect to on the storage server.

1 Options prefixed with [NFS] are only available for NFS targets.
2 Options prefixed with [CIFS] are only available for CIFS targets.
3 For the CIFS option, only version 2.1+ is supported.

Usage types
Backup

This will become a target. You can use it in service calls or when manually creating a backup. The first storage you add of this type becomes your new default target. If you want to change the default target, check out the documentation below.

Media

A new directory with the name you gave your network storage will be created under /media. This directory can be accessed by Home Assistant and add-ons.

Share

A new directory with the name you gave your network storage will be created under /share. This directory can be accessed by Home Assistant and add-ons.

Change default backup location

By default, the first network storage of type Backup that you add will be set as your default backup target.

If you want to change the default backup target, you can do the following:

  1. Go to Settings > System > Backups in the UI.
  2. Select the menu in the top right of the screen and select the Change default backup location option.
  3. In the dialog, there is a single option to set the default backup target.
  4. Choose the one you want from the list.
  5. Select Save.

This list will contain all the network storage targets you have added of usage type Backup. It also contains another option to set it back to use /backup again.

Screenshot of changing the default backup target.

Home Assistant via the command line

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.

Home Assistant

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

Supervisor

ha supervisor info
ha supervisor logs
ha supervisor reload
ha supervisor update

Host

ha host reboot
ha host shutdown
ha host update

Hardware

ha hardware info
ha hardware audio

Usage examples

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 --version 2024.2.3

You can get a better description of the CLI capabilities by typing ha help:

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.

Console access

You can also access the Home Assistant Operating System via a directly connected keyboard and monitor, the console.

Lost Password and password reset

Please refer to the I’m locked out! documentation page.

Installing third-party add-ons

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

https://github.com/home-assistant/hassio-addons-example
Home Assistant cannot guarantee the quality or security of third-party add-ons. Use at your own risk.

From Settings > Add-ons open the add-on store.

Add the URL of the repository and then press "Add". A new card for the repository will appear.

Help: Repository is not showing up

If you have added a repository, but it’s not showing up, it means that the repository contains invalid configuration. Go to Settings > System > Logs to find the System log. It should tell you what went wrong. Report this information to the repository author.

Using external data disk

Home Assistant Operating System supports storing most data on an external storage medium, such as an 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.

Graphics showing the architecture of the data disk feature

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.

Using UI to move the data partition

  1. Connect the data disk to your system.
  2. Go to Settings > System > Storage in the UI.
  3. Select Move data disk.
  4. Select the data disk from the list of available devices.
  5. Select Move.

Screenshot of the “Move datadisk” feature

Using CLI to move the data partition

To see the current data disk use:

$ ha os info
...
data_disk: /dev/mmcblk1p4
...

To get a list of potential targets which can be used by datadisk:

ha os datadisk list

To initiate the move to the new data disk use the move command:

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).

Flashing an ODROID-N2+

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).

What you will need

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
  • If your board came in a Home Assistant Blue: No.2 hex key to open the case

Enabling SPI boot mode

To enable the SPI boot mode:

  1. Power off the ODROID-N2+ by unplugging the power cable.

  2. Remove the case.

    Photo of the removed case

  3. Locate the toggle for boot mode and switch it from MMC to SPI.

    Photo of the SPI toggle switch

  4. Connect the ODROID-N2+ directly to your computer via the USB-OTG port located on the front of the board.

  5. Connect a USB keyboard and a monitor (using HDMI) to your ODROID-N2+.

  6. Plug in the power cable to power on the ODROID-N2+.

Enabling USB drive mode

After The ODROID-N2+ is set to SPI boot mode and powered on, it boots into a terminal. To enable the USB drive mode:

  1. Select Exit to shell from the menu.

    Exit to shell

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

  1. Use the following command at the console to confirm the storage device node:

    ls /dev/mmc*
    
  2. Set the storage device on the ODROID-N2+ as a mass storage device using the ums command (USB Mass storage mode). This will configure the ODROID-N2+ and OTG to act as a memory card reader:

    ums /dev/mmcblk0
    

Flashing Home Assistant

  1. Connect the ODROID-N2+ to your PC via the micro-USB port at the front of the ODROID-N2+.

  2. When the ODROID-N2 is recognized as a USB connected storage device, you can flash the eMMC with Etcher.

    • Use the latest stable version of Home Assistant OS for the ODROID-N2+ (haos_odroid-n2-11.5.img.xz).
    • In Balena, use Flash from file. Flash from URL does not work on all systems.
  3. When the flash process is complete, disconnect the ODROID-N2+ from your PC.

    • Remove the power cable.
    • Remove the USB and HDMI cables.
    • Make sure to toggle the boot mode switch back to MMC.
  4. Put the ODROID back in its case.

  5. Connect your ODROID-N2+ to your network with an Ethernet cable and plug in power.

  6. If your router supports mDNS, you can reach your installation at 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.
  7. Continue with onboarding.

Enable I2C

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

Enable I2C with an SD card reader

Access the boot partition

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.

Add files to enable I2C

  • In the root of the hassos-boot partition, add a new folder called CONFIG.
  • In the CONFIG folder, add another new folder called modules.
  • Inside the modules folder add a text file called rpi-i2c.conf with the following content:
    i2c-dev
    
  • In the root of the hassos-boot partition, edit the file called config.txt add two lines to it:
    dtparam=i2c_vc=on
    dtparam=i2c_arm=on
    

Start with the new OS configuration

  • Insert the SD card back into your Raspberry Pi.
  • On startup, the hassos-config.service will automatically pickup the new rpi-i2c.conf configuration.
  • Another reboot might be necessary to make sure the just imported rpi-i2c.conf is present at boot time.

Enable I2C via Home Assistant Operating System Terminal

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:

  • Login as root.

  • Type login and press enter to access the shell.

  • Type the following to enable I2C, you may need to replace sda1 with sdb1 or mmcblk0p1 depending 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
    

Troubleshooting

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.