diff --git a/blog/2025-12-31-backup-sync-agents.md b/blog/2025-12-31-backup-sync-agents.md new file mode 100644 index 00000000000..ce9bf0970bb --- /dev/null +++ b/blog/2025-12-31-backup-sync-agents.md @@ -0,0 +1,13 @@ +--- +author: Joakim Sørensen +authorURL: https://github.com/ludeeus +authorImageURL: /img/profile/ludeeus.jpg +authorTwitter: ludeeus +title: "Backup sync agents" +--- + +As of Home Assistant Core 2025.12, integrations can provide [sync agents](/docs/core/platform/backup#sync-agents) to allow users to back up and restore their data to and from external services. + +Sync agents allows integrations to store backups in a remote location, such as a cloud service or a network-attached storage (NAS) device. + +More details can be found in the [backup platform documentation](/docs/core/platform/backup#sync-agents). diff --git a/docs/core/platform/backup.md b/docs/core/platform/backup.md index 25852f890a0..df5bdcfa65c 100644 --- a/docs/core/platform/backup.md +++ b/docs/core/platform/backup.md @@ -2,11 +2,15 @@ title: "Backup" --- +The backup platform consists of two parts; [Pre/Post backup hooks](#prepost-backup-hooks) and [Sync agents](#sync-agents). + +## Pre/Post backup hooks + When Home Assistant is creating a backup, there might be a need to pause certain operations in the integration, or dumping data so it can properly be restored. This is done by adding 2 functions (`async_pre_backup` and `async_post_backup`) to `backup.py` -## Adding support +### Adding support The quickest way to add backup support to a new integration is by using our built-in scaffold template. From a Home Assistant dev environment, run `python3 -m script.scaffold backup` and follow the instructions. @@ -22,3 +26,32 @@ async def async_pre_backup(hass: HomeAssistant) -> None: async def async_post_backup(hass: HomeAssistant) -> None: """Perform operations after a backup finishes.""" ``` + +## Sync agents + +Sync agents are used to dispatch a backup to a remote location. This is done by implementing the a `BackupSyncAgent` class. + +To register your sync agent, you need to add a `async_get_backup_sync_agents` function to your integrations backup platform. + +```python +async def async_get_backup_sync_agents( + hass: HomeAssistant, +) -> list[BackupSyncAgent]: + """Register the backup sync agents.""" + return [LoremIpsumBackupSyncAgent("syncer")] + +class LoremIpsumBackupSyncAgent(BackupSyncAgent): + ... +``` + +### Sync agent methods + +The base class `BackupSyncAgent` has several methods that needs to be implemented. + +Method | Description +:--- | :--- +`async_download_backup` | Download a backup from the remote location. The `id` parameter is the ID of the synced backup that was returned in `async_list_backups`. The `path` parameter is the full file path to download the synced backup to. +`async_upload_backup` | Upload a backup. The `path` parameter is the full file path to the backup that should be synced. The `metadata` parameter contains metadata about the backup that should be synced. +`async_list_backups` | List backups. + +When a user creates a backup, Home Assistant will call the `async_upload_backup` method on the sync agent to store the backup in the remote location.