# Home Assistant Time Machine: browsing and restoring YAML item by item

> Home Assistant Time Machine is a web tool that lets you walk through YAML backups of a Home Assistant instance and put a single automation, script or dashboard back, rather than restoring everything. It ships as a Home Assistant add-on or a standalone Docker container on port 54000.

**saihgupr/HomeAssistantTimeMachine** — Home Assistant Time Machine is a web-based tool that acts as a "Time Machine" for your Home Assistant configuration.

- Repository: https://github.com/saihgupr/HomeAssistantTimeMachine
- Stars: 714 · Forks: 20
- Language: JavaScript
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/saihgupr-homeassistanttimemachine

## A time machine for configuration files, not for the whole instance

Home Assistant Time Machine is a web-based tool that acts as a time machine for a Home Assistant configuration. The problem it addresses is narrow but real: a configuration directory is a pile of YAML files, and when a change breaks an automation it is rarely obvious which of dozens of automations, scripts and packages caused it. A full instance restore would undo unrelated work along with the bad change. This tool instead lets you browse YAML backups across automations, scripts, Lovelace dashboards, ESPHome files and packages, then restore an individual item back to the live setup. The repository is JavaScript, licensed under MIT, with a `main` default branch and a `custom_components/` directory alongside a `homeassistant-time-machine/` folder and a `hacs.json` file, which is what makes it usable both as an add-on and as a HACS companion integration. It is a tool for the person who edits YAML by hand and regrets one line of it.

## A file manifest makes restore know where files belong

The mechanism that separates this from a naive file browser is the manifest. Every backup now includes a detailed file manifest, and the stated purpose is that restores and change detection stay aware of where your files live and place them back exactly where they belong in your YAML structure. That matters for anyone using a split configuration, because the feature list calls out support for `!include`, `!include_dir_list` and other split configuration methods. In a single-file setup, a restore is a matter of overwriting one document. In a split setup, an automation may live in a directory that includes several fragments, and putting it back requires knowing the original path and how it was merged. The manifest is that memory. Change detection leans on the same data, which is what allows the interface to compare a backup against the live configuration rather than only against another backup.

## Restoring one automation instead of the whole instance

The headline capability is restoring individual automations or scripts without restoring an entire backup. Around that sit several smaller mechanisms that share the same model. A filter called Show Changes Only narrows the backup list to snapshots that contain changed or deleted items when compared with the live config, so the history view does not fill up with identical snapshots. Safety First is described as automatically creating a backup before restoring anything, which means a restore is itself undoable, and the newer Backup Lock feature prevents accidental deletion of snapshots by locking selected ones. A right-click context menu on any backup offers lock, release the lock, export or delete, with export producing a `.tar.gz` archive. After a restore, the Reload Home Assistant action can reload automations or scripts directly from the interface, which saves a restart in the common case where the change is safe to load live.

## Add-on install, Docker install and the local build

There are two install paths, and the add-on is presented as the recommended one for most users. The repository to add in Settings, Add-ons, Add-on Store, Repositories is the `ha-addons` repository, and after adding it the Home Assistant Time Machine add-on appears in the store to install. The standalone route assumes Docker. The compose file shipped in the repository is the shortest path, and it maps port 54000, points the container at the configuration directory and a backup directory, and keeps its own data in a named volume:

```yaml
services:
  ha-time-machine:
    image: ghcr.io/saihgupr/homeassistanttimemachine:latest
    container_name: ha-time-machine
    ports:
      - "54000:54000"
    environment:
      - HOME_ASSISTANT_URL=http://ha-ip-address:8123
      - LONG_LIVED_ACCESS_TOKEN=your-long-lived-access-token
    volumes:
      - /mnt/homeassistant/config:/config
      - /mnt/homeassistant/timemachine:/media/timemachine
      - ha-time-machine-data:/data
    restart: unless-stopped
volumes:
  ha-time-machine-data:
```

You would edit the two paths to match your machine before starting it. If you prefer to build the image yourself, the project documents a local build that clones the repository and targets the `homeassistant-time-machine` directory:

```bash
git clone https://github.com/saihgupr/HomeAssistantTimeMachine.git
cd HomeAssistantTimeMachine/homeassistant-time-machine
docker build -t ha-time-machine .
```

Once the container runs, the interface is served at `http://localhost:54000`.

## Where the credentials live and who can trigger a backup

Credentials can be supplied two ways, and the README is explicit that both are optional. Setting `HOME_ASSISTANT_URL` and `LONG_LIVED_ACCESS_TOKEN` keeps the login out of the web form and makes the settings fields read-only. If you omit them, you can type the URL and token into the settings modal after the container starts, and the values are written to `/data/docker-ha-credentials.json` inside the container. The pre-built image also accepts `ESPHOME_CONFIG_PATH` for a custom ESPHome configuration location, plus `THEME` and `DEBUG_LOGS`:

```bash
docker run -d \
  -p 54000:54000 \
  -e HOME_ASSISTANT_URL="http://your-ha-instance:8123" \
  -e LONG_LIVED_ACCESS_TOKEN="your-long-lived-access-token" \
  -e ESPHOME_CONFIG_PATH="/path/to/esphome/config" \
  -e THEME="dark" \
  -e DEBUG_LOGS="false" \
  -v /path/to/your/ha/config:/config \
  -v /path/to/your/backups:/media \
  -v ha-time-machine-data:/data \
  --name ha-time-machine \
  ghcr.io/saihgupr/homeassistanttimemachine:latest
```

A long-lived access token is a broad credential, so a copy of it in a container file or an environment variable deserves the same care as the token itself. The same theme of automation appears in the trigger side: backups can be run from Home Assistant automations or scripts through the `hassio.addon_stdin` service, and the HACS companion integration adds a native sensor for backup status and a `time_machine.backup_now` service.

## Retention, storage locations and scheduling

Backups are not free, so the project gives you controls over them rather than letting them accumulate. A Smart Backup mode works incrementally and saves only changed files, which the documentation presents as a significant storage reduction. A maximum backup count sets the retention limit, and the storage target can be `/share`, `/backup`, `/media` or a remote share. Scheduled backups let the tool take snapshots on a timetable instead of waiting for you to remember. Incremental storage and a retention cap interact in a way that is worth understanding before you rely on old snapshots: if a file changed in an early incremental backup and you later restore it, the tool has to reassemble the state of that file across the chain of backups, and the manifest is what makes that placement accurate. The `data/` directory in the container is where the credential file lives, so a volume there is worth backing up separately from the backup storage itself.

## Item level history instead of file level history

The honest alternative to this project is not another dashboard, it is a version control repository over the configuration directory. A git repository of your YAML gives you file level diffs, a full history and a plain clone on another machine, with no extra service and no access token at all. The difference in approach is granularity. Git shows you that a file changed and shows you the whole file before and after, while Home Assistant Time Machine works on items, an automation or a script, and shows side-by-side diffs of that item with a choice of eight color palettes. For a configuration split across many includes, where a single logical automation is assembled from fragments, item level history is more useful, since it survives the reorganisation of files. Git has the advantage of being text and diffable, portable and free of a long-lived token, and it also has no web interface to serve and no backup format to migrate.

## Where the tool does not reach

Two limits are worth naming before you deploy it. First, this is a configuration level time machine, not an instance level backup. The feature set covers automations, scripts, Lovelace dashboards, ESPHome files and packages, and it reads a mounted `/config` directory. It does not describe itself as a way to restore an operating system, an add-on database or a database of recorder rows, so anyone who needs full instance recovery still needs a different mechanism. Second, the interface expects a broad credential. The README requires a long-lived access token, and in the container case that token can end up in `/data/docker-ha-credentials.json` in plain form, so the container needs to be reachable only by people you would hand the token to. The port mapping publishes 54000, and there is no mention of an authentication layer in front of the web interface itself. The README does not document a reverse proxy setup or a login for the web UI, so treat the exposed port as trusted-network only.

## Conclusion

Home Assistant Time Machine is worth adopting if you edit configuration.yaml by hand, split your setup across !include files, and want to undo one automation without rolling back the whole instance. It is the wrong tool if you expect a full system snapshot, since it works at the level of YAML items inside a configuration directory. Check Doc/CONFIG-style details for yourself: read the add-on store listing, confirm that the REST API and the time_machine.backup_now service appear in your HACS install, and decide whether a long-lived access token stored in the container is acceptable. The last push was on 2026-09-01 and version v2.3.2 was released on 2026-08-05.

## FAQ

### How do I install Home Assistant Time Machine in Home Assistant?

Add the ha-addons repository under Settings, Add-ons, Add-on Store, Repositories, then install the Home Assistant Time Machine add-on from the store. The project also offers a standalone Docker container as an alternative.

### Can Home Assistant Time Machine restore a single automation instead of a full backup?

Yes. Restoring individual automations or scripts without restoring an entire backup is a listed feature, and a backup is created automatically before a restore so the change can be undone.

### Does Home Assistant Time Machine work with split configuration using !include?

The project states it is optimized for advanced setups using !include, !include_dir_list and other split configuration methods, and that every backup includes a file manifest so restores place files back where they belong.

## Sources

- [Issues](https://github.com/saihgupr/HomeAssistantTimeMachine/issues)
- [License: MIT](https://github.com/saihgupr/HomeAssistantTimeMachine/blob/main/LICENSE)
- [README](https://github.com/saihgupr/HomeAssistantTimeMachine/blob/main/README.md)
- [Releases](https://github.com/saihgupr/HomeAssistantTimeMachine/releases)
- [saihgupr/HomeAssistantTimeMachine on GitHub](https://github.com/saihgupr/HomeAssistantTimeMachine)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/saihgupr-homeassistanttimemachine