Ha-auto-restore: bring a dead Home Assistant OS back from your PC with one command

Hi all,

I wanted a plan B for the day my HAOS box breaks and I’m not at my best: no web UI, no terminal, just a broken install and a backup somewhere. Restoring by hand is fine when you have time and a clear head; I wanted something I could start with a double-click (or ask an AI assistant to start for me).

So I wrote ha-auto-restore: a small Python script (standard library only) that runs on the PC next to your HA box (Windows, Linux or macOS) and picks the least destructive fix that works:

What broke What it does
Only HA Core (bad config, bad update) Over the SSH app: ha core restart, then ha core rebuild, then restores HA from the newest backup on the box
HAOS boots but is messed up (even the SSH app is down) Over HAOS system SSH (port 22222) it wipes the data partition with os-agent; HAOS comes back as a fresh install and the script restores your backup
Disk dead You put HAOS on a new disk or a USB stick and boot it; the script waits for the onboarding screen, uploads the newest backup and restores it

It asks you to type YES before every destructive step, never prints the backup key, and picks the newest backup from the folders you configure (NAS share, Google Drive folder, local copy).

How it works, for the curious

  • The restore on a fresh install uses the onboarding backup API (no login needed during onboarding): /api/onboarding/backup/upload and /api/onboarding/backup/restore, available since 2025.1.
  • The wipe uses busctl call io.hass.os /io/hass/os/System io.hass.os.System ScheduleWipeDevice on the HAOS host, so it works even when the Supervisor is down.

Things I learned along the way (maybe useful even if you never use the script)

  • A fresh HAOS 18+ serves onboarding on port 80; 8123 redirects there. After the restore HA goes back to 8123.
  • The Supervisor refuses to restore without internet.
  • backup.json is at the end of the backup tar: read it with random access, or you download the whole file from a cloud-synced folder.
  • Never plug a USB stick that still holds an old HAOS into your HA box: I had one whose data partition was labelled hassos-data-dis - booted next to the real disk it would have mounted the SSD’s data with an old system.
  • ha os import over SSH needs a login shell (bash -l), otherwise “No API token provided”.

What has been tested (HAOS 18.4 / HA 2026.11, x86-64)

  • The full “fresh install + upload + restore” path, twice, in an isolated VirtualBox VM (from a VDI and from a freshly written USB stick), with a 2.7 GB backup from a NAS share and from Google Drive.
  • Diagnose, backup discovery, system SSH and the wipe method on my real box.
  • Not yet tested for real: restart/restore/wipe on a real broken box, and restoring add-ons in the VM (no internet there by design). The README explains how to test it safely in a VM - please do that before you need it.

Requirements, setup (including enabling port 22222 with a CONFIG USB stick) and the VM test guide are in the README (English and Italian).

A related project worth knowing: ha-disk-swap prepares a replacement disk while HA still works; this one is for when it doesn’t anymore.

Feedback, bug reports and test results are very welcome - especially from anyone on a Raspberry Pi or a VM install, where I couldn’t test it.

Built with the help of an AI coding assistant (Claude); I tested and reviewed it on my own setup.

1 Like