Home Assistant: Local Source of Truth

This project implements a workflow that treats your Home Assistant server as a Read-Only Runtime and your local machine as the Source of Truth. This prevents state corruption and enforces atomic deployments.

Core Philosophy

1. Manifest Driven: We do not guess file paths. A ha_manifest.yaml defines exactly where files live and how to edit them (Append vs. Create).
2. Atomic Deployment: Stop Core -> Push Files -> Start Core. No writing to a running server.
3. Versioned State: Every action (Pull or Inject) is automatically committed to a local Git repo.

Prerequisites

• Python 3
• pip
• git
• SSH access to your Home Assistant server (public key authentication recommended)

Install Python dependencies:

pip install paramiko pyyaml

Setup

1. Generate Manifest: Run ha_setup.py once to scan your Home Assistant server and generate the ha_manifest.yaml mapping file.

   python ha_setup.py --host <HA_IP> --user <SSH_USER> --key <PATH_TO_SSH_KEY>

   • --host: IP address of your Home Assistant server.
   • --user: SSH username (default: root).
   • --key: Path to your SSH private key (default: ~/.ssh/id_rsa).
   • --root: Path to the Home Assistant config directory (default: /config).

Usage

Use ha.py for daily management.

Sync State

Pull the current state from the server to your local repository.

python ha.py pull

Add/Modify Items

Inject new configurations or modify existing ones. This updates the local files and creates a git commit.

python ha.py inject <CATEGORY> <NAME> "<YAML_CONTENT>"

• category: One of automations, scripts, scenes, dashboards.
• name: Identifier for the item (used for filename or commit message).
• content: The YAML content to inject.

Example:

python ha.py inject automations night_mode "- alias: Night Mode\n  trigger: ..."

Deploy Changes

Deploy your local state to the server. This performs a configuration check, stops the core, pushes files (deleting remote files not present locally), and restarts the core.

python ha.py deploy

Architecture

• ha_setup.py: Connects to the server via SSH/Paramiko, reads configuration.yaml, and detects file structures (e.g., !include vs !include_dir_merge_list). Generates ha_manifest.yaml.
• ha.py: The CLI tool.
  • Pull: Uses rsync to download files based on the manifest.
  • Inject: Modifies local files based on strategy (Append or Create) and commits to local git.
  • Deploy: Checks config via ha core check, stops core, rsync --delete to server, starts core.

Scope & Capabilities

This workflow captures and manages the following:

• YAML Configuration: automations.yaml, scripts.yaml, configuration.yaml, etc.
• UI-Configured Integrations: By syncing the .storage directory, integrations configured via the UI (like MQTT, Z-Wave JS) are preserved.
• HACS:
  • Code: custom_components/ and themes/ are synced.
  • State: HACS state (tracked repositories) in .storage/hacs.* is synced.
• Add-on Configuration: If you use the /config/addon_configs feature (HA 2023.12+), those configurations are captured.
• Local Assets: The www/ directory is synced.

Limitations

• Add-on Installation: The installation state of Add-ons (managed by Supervisor) is not captured. If you restore to a fresh server, you must manually re-install Add-ons (though their configs in addon_configs will be waiting for them).
• OS/Supervisor Settings: Network configuration, OS updates, and Supervisor specific settings are generally outside /config and not captured.

Security Note

• Secrets: Since this workflow syncs .storage and secrets.yaml, your local git repository will contain sensitive tokens and passwords. Ensure your local machine is secure.
• SSH: The scripts use SSH for communication. Ensure your SSH keys are secure.
• Downtime: The deploy command stops the Home Assistant core, so there will be a brief downtime during deployment.