SSH Development Access (Core SSH, Root CLI)

Community Guides
1

This is not a duplicate of the excellent instructions on debugging/Dev SSH.

Rather, this is a high-level overview with links to the four options to gain root OS access, a primer on the architecture/reason the core OS is separate, along with some important reminders/pitfalls which reappear in every one of the related posts.

How to gain access to the root OS (HA OS) and Docker

Remember that Home Assistant runs inside Docker, with each add-on running in its own isolated Docker container.

When you connect to the Home Assistant CLI via any SSH add-on, you are connecting to a Docker container named “homeassistant”, not the root OS.

To make root-level configuration changes, such as modifying /boot/config.txt, you cannot use the Home Assistant Add-On SSH servers.

There are four methods to access the root OS:

1. Reboot with Pre-configured USB

2. Copy from Pre-configured USB via SSH

  • Insert the USB drive with the pre-configured public key (using the same instructions from Step 1).
  • From the Home Assistant shell, type ha os import
  • Reboot

3. Copy from Pre-configured USB via Local Console

  • Insert the USB drive with the pre-configured public key.
  • From the local console at the ha prompt, type os import

4. Install an Add-On

Next Step: After Choosing an Option

  • From your SSH client, add your private key, set the connection port to 22222 (five two’s), and connect to “homeassistant.local” or the device’s IP address.
  • Once you have Developer SSH access, you’ll be able to use the “docker” command, but not in the Home Assistant directory.
  • For example, you can run docker container ls to see a list of all running containers
  • You can then move to the Home Assistant container’s bash CLI by executing it: docker exec -it homeassistant /bin/bash
  • Remember to exit the container’s shell, back to the root OS
  • The root OS is where you can access the mnt/boot/config.txt file.
  • This is a buildroot environment, no package manager is available. When you switch to the Home Assistant container, you have access to the apk package manager. Just remember it’s a container so any changes will be lost upon restart.

Reminders / Pitfalls:

  • The SSH connection for the root OS is on port 22222
  • It’s possible to run the Add-On at port 22 with the “Development” SSH at 22222; easy to confuse them.
  • If you login locally at the console, you’re at the “ha” prompt; type login to gain access to the root OS CLI.
  • If you’ve connected by SSH, there is no reason to use login; you have full priveledges.
  • Do a hard reboot (the default reboot is soft) after configuring and running the HassOS SSH Port 22222 Configurator Add-On.
  • Developer SSH sessions will connect with PPK cert, not credentials.
  • It’s a common mixup: Remember to paste the public key (PuTTY format) in the USB “authorized_keys” file, or SSH Configurator, and the private key in your SSH client.

Most reminders are very simple; however, these mistakes reappear in hundreds of replies on this topic; while simple, this can save people much confusion.

3 Likes