Hyper-v checkpoints with hass agent

This is a guide on how to trigger Hyper-V checkpoints within Home Assistant and somewhat manage them with an automation. (it deletes old ones depending on how much free space we want. Checkpoints are a strong feature of hyper-v, it’s possible to do it on vbox as well courtesy of hass.agent but the machine freezes when creating snapshots and needs to be off when restoring.

Quick reminder: they are not proper backups, use hassio-onedrive-backup or -home-assistant-google-drive-backup addons as well. Checkpoints however do save time and make possible to recover short term data. For example, at power failure, i can just restore a less than a hour old snapshot in seconds if database gets corrupted.


  • Install Home Assistant OS on Hyper-V.
  • Install and configure hass.agent on both the Home Assistant and Windows PC.
  • Enable and configure the Samba Share add-on for accessing files from Windows (if you want ha core version mentioned in the checkpoint name)

Create a PowerShell script named “checkpoint.ps1” and replace ‘vm-name’ and ‘ha-ip’(optional) with your specific information.

$vmName = "<vm-name>"
$versionFilePath = "\\<ha-ip>\config\.HA_VERSION"
$snapshotName = ""

if (Test-Path $versionFilePath) {
    $versionNumber = (Get-Content -Path $versionFilePath).Trim()
    $snapshotName = "hassagent auto - {0:dd.MM.yyyy - HH:mm:ss} - ha core v.{1}" -f (Get-Date), $versionNumber
} else {
    $snapshotName = "hassagent auto - {0:dd.MM.yyyy - HH:mm:ss}" -f (Get-Date)

Get-VM -Name $vmName | Checkpoint-VM -SnapshotName $snapshotName

Create a task in task scheduler:

Under the “General” tab, check “Run whether the user is logged on or not” and “Run with highest privileges.”

Under the “Actions” tab, configure the following:
Program/script: Powershell.exe
Add arguments:

-ExecutionPolicy Bypass -File <path to ps1 file>

(e.g., -ExecutionPolicy Bypass -File A:\checkpoint.ps1 )
Save and enter credentials.
Run the task. It should work.

Create a hass.agent command (button for Home Assistant) in Windows:
open hass,agent->commands-> add new → type: custom ->button, command:

schtasks /run /tn "<name_of_task_you_created>"

test button from ha.

now, to manage space, we need a new powershell script triggered by task sheduler with its correspunding hass agent command.


$VMName = "HomeAssistant"
$Snapshots = Get-VM -Name $VMName | Get-VMSnapshot
$Snapshots = $Snapshots | Sort-Object CreationTime
$OldestSnapshot = $Snapshots[0]
$OldestSnapshot | Remove-VMSnapshot -Confirm:$false
Write-Host "Oldest snapshot '$($OldestSnapshot.Name)' has been deleted."
Get-VM -Name $VMName | Get-VMSnapshot

create a hass agent storage sensor. sensors->add new->storage.
We need the attribute UsedSpacePercentage for the drive where the avhdx files appear.
On ha, go to dev tools->status and find the attribute there.

New ha automation:
trigger checkpoint once an hour: time pattern-> hours: /1
if-then->if template condition

{{ state_attr('sensor.storage_x', 'UsedSpacePercentage')| float > 90 }}

repeat-> under repeat select “while” template condition:

{{ state_attr('sensor.storage_x', 'UsedSpacePercentage')| float > 85 }}

actions while template true:
service->button press->remove_oldest_hyperv_checkpoint
wait for time to pass 30s

action after repeat over:
service->button press->checkpoint
*end of if
service->button press->checkpoint
Update: added load_load_lastest_checkpoint.ps1, usefull for automatic recovery after a power failure.

1 Like

This really interests me! I can’t test it right now, but I’ll keep an eye on this thread and I hope I can give it a go next week.

I’ve also been asking around regarding Hyper-V… here and elsewhere.

I just tried this and it works well.

I am interested in having HA watch other Hyper-V instances, not just the one inside which it is running.

Do you know any way to get information from Hyper-V back into HA, through HASS-Agent?

For example, getting just the output of Get-Vm made available in a HA, in JSON format sensor, for example?

If something would do it, that would be a VMI query sensor, but its beyond my capabilities right now.

Is there a way without hass-agent?

I can ssh on my Hyper-V host (works on windows server 2022 so with any server on the net without having the need to install scripts and tasks on the servers), Within the ssh shell I can execute powershell and then Checkpoint-VM.

Anyone already tried this?