Runtime Runner

Optional Runtime Runner

The BackupCheckup Runtime Runner is an optional Home Assistant app for Home Assistant OS. It receives only a backup that has already passed structural verification and starts its Home Assistant configuration in Recovery Mode inside a temporary environment.

When should it be used?

Structural verification proves that the archives and files are readable. The runner adds evidence that the included configuration can start with the installed Home Assistant runtime and reach an internal HTTP endpoint. It is not required for inventory, Health Score, or integrity monitoring.

Installation

1. Install and configure the BackupCheckup integration first.
2. Open Settings → Apps → App Store → Repositories.
3. Add https://github.com/jl0906/BackupCheckup.
4. Install and start BackupCheckup Runtime Runner.
5. Wait for Home Assistant to pass the discovered runner to BackupCheckup.
6. Run Check backup protection again.

The App Store reads runtime_runner from the repository's default branch, not from the HACS release archive. After a runner update, refresh the App Store and install the offered app update.

The app log must show the expected version, for example:

runner initialized version=3.0.12 isolation_available=True

Runtime-test sequence

1. The integration structurally verifies the backup.
2. The verified archive is transferred internally over certificate-pinned TLS.
3. The runner checks size and SHA-256.
4. Home Assistant configuration is extracted into a temporary private workspace.
5. A separate network namespace with loopback only is created.
6. Home Assistant starts in Recovery Mode as an unprivileged user without Linux capabilities or Supervisor credentials.
7. An internal readiness probe waits for the temporary HTTP endpoint.
8. The process stops and the upload, configuration, password, and logs are removed.
9. Only bounded, signed evidence is returned to the integration.

Security model

• no Supervisor restore endpoint,
• no production-configuration mount,
• no host network or published host port,
• no Docker socket or Home Assistant API access,
• separate network namespace,
• unprivileged child, empty capabilities, and no_new_privs,
• minimal environment without inherited Supervisor tokens,
• hard process, file-descriptor, core-dump, file-size, and address-space limits,
• one runtime test at a time,
• authenticated discovery, bearer token, certificate pinning, and HMAC-signed terminal evidence.

The controller needs NET_ADMIN and SYS_ADMIN only to create and initialize the network namespace. These capabilities are not inherited by restored Home Assistant.

Options

Option	Default	Range	Purpose
maximum_archive_gb	50	1–2048	Rejects larger uploads.
maximum_expanded_gb	250	1–8192	Stops extraction beyond this limit.
runtime_timeout_minutes	20	2–60	Stops an instance that does not become ready.

The child additionally has an 8 GiB virtual-address-space limit and a 2 GiB file-size limit. These retain hard boundaries without unnecessarily rejecting large but valid Home Assistant backups during startup.

Result states

• Runner not available: no connected compatible app
• Not run: no runtime test for the current backup
• Running: upload, extraction, boot, or probing is active
• Runtime start verified: Recovery Mode, isolation, and readiness were confirmed
• Failed: Home Assistant exited or never became ready
• Stopped by a safety limit: timeout or controlled resource boundary
• Inconclusive: internal or incomplete result

Stable error codes distinguish memory limit, file limit, permission failure, missing runtime, CLI incompatibility, startup timeout, generic exit, and sandbox preflight failure.

Updating

The integration and runner use separate update paths. A HACS update does not replace the app. Verify the runner version in its log after every runner update.

For 3.0.12, refresh the App Store and rebuild or reinstall the runner from the current default branch. Updating only the HACS integration leaves an older runner image installed.