Skip to content

Home Assistant (calgary)

calgary is a Beelink SER mini PC in a closet. It runs Ubuntu 24.04 on a ZFS root and Incus 6.0 from the Ubuntu archive. It is the host for Home Assistant OS (HAOS), which runs in an Incus virtual machine. Apple Home on the HomePods also controls the house, through Matter where a device supports it.

The baseline role is ansible/roles/calgary-common. ansible/calgary-playbook.yml runs it against the group calgary_hosts. Host values live in ansible/inventory/host_vars/calgary.yml. The design is docs/engineering/specs/2026-10-04-calgary-home-assistant-host-design.md.

calgary has no rg. Commands that run on the host use grep.

This repository manages the host and the estate around it. Home Assistant manages everything inside its VM. No Home Assistant content is in git.

Owner What it holds
ansible/ The host baseline, Incus, the network legs of the host, and the definition of the VM
dns-control The curated entries, with their names and Kea reservations
tf/unifi The switch ports
tf/cloudflare, tf/vault The DNS-01 token of the HTTPS certificate, and the PKI role and the AppRole cert-agent-calgary of the collector certificate
tf/uptime-kuma The monitor of Home Assistant
Home Assistant Integrations, automations, dashboards, .storage/, device pairing and the backup schedule

Ansible never changes the root disk of the VM. HAOS updates itself after its first boot.

Ansible connects as the login fzymgc at the literal address that ansible/inventory/hosts.yml names. fzymgc has passwordless sudo. The address is 192.168.40.21, the Core reservation of the dns-control entry calgary (Network).

The private key lives only in Vault. The wrapper scripts/calgary-playbook.sh reads it, writes it to a 0600 temporary file, and deletes the file on exit. It forces IdentitiesOnly=yes and IdentityAgent=none, so ssh offers only this key. An SSH agent with many keys trips the sshd MaxAuthTries limit. A working agent also hides a broken Vault path.

The login shell of fzymgc is fish. Ansible wraps every command in /bin/sh -c, so the default sh shell plugin works. Do not set ansible_shell_type: fish. That plugin writes fish syntax that /bin/sh then runs, and every task that copies a file fails. A ping passes either way, because pipelining sends the ping without a remote temporary directory.

To run the playbook, you need an authenticated Vault session (vault login):

Terminal window
scripts/calgary-playbook.sh --check --diff # dry run
scripts/calgary-playbook.sh # apply
Field Value
Path secret/fzymgc-house/infrastructure/calgary/automation-ssh
Fields private_key, public_key
Key type ed25519, comment calgary-automation

An operator seeds the path. Terraform does not declare it. The wrapper runs with the Vault token of the operator, and the infrastructure-developer policy already grants read on secret/data/fzymgc-house/infrastructure/*.

Run these commands on your workstation. The key pair goes to a temporary directory, never to the repository checkout. The append uses your own SSH key, because the automation key is not on calgary yet.

Terminal window
d=$(mktemp -d)
ssh-keygen -t ed25519 -C calgary-automation -f "$d/key" -N ''
vault kv put -mount=secret fzymgc-house/infrastructure/calgary/automation-ssh \
private_key=@"$d/key" public_key=@"$d/key.pub"
ssh fzymgc@calgary.fzymgc.house 'cat >> ~/.ssh/authorized_keys' < "$d/key.pub"
rm -rf "$d"

Append the key. Do not rewrite authorized_keys, because it holds the keys of people.

To make sure that the key in Vault opens calgary, offer that key alone. -F /dev/null skips the IdentityFile lines of your SSH configuration, and IdentityAgent=none skips the agent:

Terminal window
d=$(mktemp -d)
vault kv get -mount=secret -field=private_key fzymgc-house/infrastructure/calgary/automation-ssh > "$d/key"
chmod 600 "$d/key"
ssh -F /dev/null -o IdentitiesOnly=yes -o IdentityAgent=none -i "$d/key" fzymgc@calgary.fzymgc.house true && echo key-ok
rm -rf "$d"

The command prints key-ok.

calgary is on switch-main port 5, in the closet. tf/unifi/ports.tf declares the port as a trunk. Core is the native network, and Main and IoT are tagged for the VM. PoE is off.

Name Address Leg Holder
calgary 192.168.40.21 Core, untagged on enp1s0 The host, MAC 78:55:36:01:3b:b8
ha 192.168.20.220 Main, tagged The Home Assistant VM, MAC calgary_haos_eth0_hwaddr in host_vars/calgary.yml

Each name is a dns-control curated entry with a MAC, so Kea reserves its address. Change an address through a dns-control plan and apply, never in Kea. The host holds no address on Main or IoT. The Incus NAT bridge incusbr0 keeps its private address, and no instance uses it.

If calgary is not at its reservation, find its current lease from the name that Kea D2 publishes on each leg:

Terminal window
dig +short calgary.core.lan.fzymgc.house calgary.main.lan.fzymgc.house
  1. If the new port has another native network, change the address of the entry calgary to a free address on that network first.
  2. Move the cable. When the link comes back, systemd-networkd asks for a new lease.
  3. If calgary takes a pool address, run sudo networkctl reconfigure enp1s0 on calgary at that address. The reconfigure drops the lease and starts a new DHCP exchange, so Kea answers with the reservation. Do not use networkctl renew. Kea extends the pool lease that a renew asks for.
  4. Declare the new port in tf/unifi and reset the old one, in one pull request.

To undo the move to switch-main port 5, change the entry calgary back to 192.168.22.35 with ptr false. Then move the cable back to switch-office port 5, which is Main native.

calgary-common does five things:

  1. It makes sure that the Incus storage pool default is the ZFS dataset rpool/incus. It creates and changes no pool.
  2. It deletes the leftover VM test-vm.
  3. It purges the libvirt* packages, so Incus is the only virtualization manager. QEMU and Incus stay installed.
  4. It sets the time zone to America/New_York.
  5. It installs unattended-upgrades with the policy that Reboot policy describes.

The NAT bridge incusbr0 and the Incus profile default stay. The Home Assistant VM uses neither.

If libvirt is needed again, run sudo apt-get install libvirt-daemon-system on calgary. The deletion of test-vm is final, and the VM held nothing.

The role ansible/roles/calgary-haos defines the Incus VM haos. Ansible owns the definition of the VM. HAOS owns everything inside it.

Item Value
Instance haos, a virtual machine with no profile, so every device is on the instance
CPU and memory 4 vCPUs and 8 GiB
root 64 GiB on the pool default
eth0 Bridged to br-main, MAC calgary_haos_eth0_hwaddr, the reservation ha 192.168.20.220
eth1 Bridged to br-iot, MAC calgary_haos_eth1_hwaddr, a pool lease named homeassistant.iot.lan.fzymgc.house
thread-radio-4001, thread-radio-831a USB passthrough of the ZBT-2, one device per product ID, required=false
Other Secure boot off, autostart on, a snapshot every day that expires after 14 days

These systemd-networkd files on calgary carry Main and IoT to the VM:

File Purpose
10-enp1s0.network The Core lease of the host, and the two tagged legs
20-enp1s0.3000.netdev, 20-enp1s0.3000.network The Main leg, a port of br-main
20-enp1s0.3020.netdev, 20-enp1s0.3020.network The IoT leg, a port of br-iot
30-br-main.netdev, 30-br-main.network The Main bridge, with no host address
30-br-iot.netdev, 30-br-iot.network The IoT bridge, with no host address

When one of these files changes, the role reloads systemd-networkd and waits for SSH. The reload reconfigures enp1s0, so the host drops its Core lease for a few seconds and takes it again.

The role downloads the pinned HAOS image, makes sure that its SHA-256 matches, and imports it as the image haos-seed-<version>. It does this only while the VM haos does not exist. After the first boot, HAOS updates itself on its A and B slots. Update HAOS from Home Assistant, not from this repository. A new calgary_haos_seed_version changes nothing on a running VM. It matters only when the VM is created again. A dry run skips the download and the import.

HAOS ships no Incus agent. incus exec haos fails, and incus list shows no address for the VM. Read the VM through DNS and HTTP instead:

Terminal window
dig +short ha.fzymgc.house
curl -sS -o /dev/null -w '%{http_code}\n' https://ha.fzymgc.house/manifest.json

The second command prints 200 when Home Assistant runs. On the first boot, HAOS downloads the Home Assistant container before Home Assistant answers.

Home Assistant serves HTTPS on port 443 (HTTPS). Inside the VM, HAOS names the two NICs enp5s0 and enp6s0. Match them to eth0 and eth1 of Incus by MAC.

Incus takes a snapshot of haos every day and deletes it after 14 days. Without an agent, Incus cannot quiesce HAOS, so a snapshot is crash-consistent. The Home Assistant backups are the consistent copy. Use a snapshot to roll the whole VM back after a bad update. Run these commands on calgary:

Terminal window
incus snapshot list haos -f csv
incus stop haos
incus snapshot restore haos <snapshot>
incus start haos

Plug the ZBT-2 into calgary on a USB 2.0 extension cable, away from the USB 3 ports. USB 3 adds noise on 2.4 GHz. The radio enumerates under either of two product IDs, and the VM has a USB device for each. Incus 6.0.0 attaches the radio only when the VM starts. A radio plugged in while the VM runs stays with the host, where cdc_acm makes it ttyACM0. So restart the VM once after you plug the radio in:

Terminal window
incus restart haos --timeout 120

After that, and after every reboot of calgary, the VM holds the radio. The host then creates no serial device for it, so ls /dev/serial/by-id on calgary names no ZBT-2. The driver of the radio on the host is usbfs when the VM holds it and cdc_acm when the host holds it:

Terminal window
readlink -f /sys/bus/usb/devices/*/driver | grep -E 'usbfs|cdc_acm'

To read the IDs that the radio shows, run this on calgary:

Terminal window
grep -H . /sys/bus/usb/devices/*/idVendor /sys/bus/usb/devices/*/idProduct

If the radio shows an ID that calgary_haos_radio_devices in host_vars/calgary.yml does not list, add it there and converge.

Home Assistant uses MyHome16, the Thread network of Apple Home, on channel 25. A border router connects a Thread network to the LAN. The other border routers of MyHome16 are the Apple TV, the HomePod and the Aqara Hub M3. If calgary fails, they carry the network, and Apple Home still reaches every device on it.

The OpenThread border router joins the preferred network only if it has no network yet. If you set up the radio before Home Assistant holds the credentials of MyHome16, the border router forms a second network. The ZBT-2 is then the only border router of that network, and its devices go offline when calgary does.

To set up the radio:

  1. On an iPhone on the home Wi-Fi, open the Thread item in the configuration of the Home Assistant Companion app. Select Send credentials to Home Assistant.
  2. In Home Assistant, open Settings, then Devices & services, then Thread, and select Configure. On MyHome16, select Make preferred network.
  3. In Settings, then Devices & services, set up the discovered ZBT-2 and select Thread.
  4. If the border router shows under a network other than MyHome16, open its menu and select Add to preferred network. Each device on the other network must join again.

To read the channel, call the tool ha_manage_radio of the MCP server. Set radio to thread and action to network_status. The result gives channel for each border router. Do not copy active_dataset_tlvs out of the result. It holds the network key of the Thread network.

A Zigbee network keeps the channel that it forms on. So form the ZHA network last, in this order:

  1. Write the Thread and Hue channels in the 2.4 GHz table of docs/reference/network.md.
  2. Run a ZHA energy scan from the location of the SLZB-06MG24.
  3. Form the ZHA network on a channel that Wi-Fi channels 1, 6 and 11 and the other two networks do not use.

This deletes Home Assistant and its content. Take a Home Assistant backup first. Run on calgary:

Terminal window
incus delete --force haos

To remove the network legs too, delete the eight 20- and 30- files in The network legs. Keep 10-enp1s0.network, because it holds the only host address, and delete only its two VLAN= lines. Then run sudo networkctl reload. systemd-networkd does not delete a link whose file goes away, so also run sudo ip link delete br-main, sudo ip link delete br-iot, sudo ip link delete enp1s0.3000 and sudo ip link delete enp1s0.3020.

Home Assistant writes its backups to an NFS share on the NAS. The role nas-ha-backups creates the dataset main/home-assistant-backups and its export, and the NAS runbook has the procedure (NAS). The export allows 192.168.20.220, the reservation ha, and no other client, so the share needs no password. Kopia copies the dataset to B2 with the other leaves.

The network storage entry and the backup schedule are Home Assistant content, not repository content. Set them up once:

  1. In Home Assistant, open Settings, then System, then Storage, and add network storage. Use the name nas, the usage Backup, the server 192.168.20.200, the protocol NFS and the remote share path /mnt/main/home-assistant-backups. Use the IPv4 address, not nas.fzymgc.house. The name also has an IPv6 address on which the NFS service does not listen, and the export admits only the IPv4 address of the VM.

  2. In Settings, then System, then Backups, set a daily automatic backup to the location nas.

  3. Home Assistant encrypts each backup. Store the encryption key outside the VM, because a restore needs it:

    Terminal window
    vault kv put secret/fzymgc-house/infrastructure/home-assistant/backup-key key=<key>

To restore, add the network storage on the new or repaired VM and restore from Backups, or upload a backup file during onboarding. Both need the encryption key.

To make sure that the backups arrive:

Terminal window
scripts/nas-adhoc.sh nas -b -m ansible.builtin.command -a 'midclt call sharing.nfs.query'
scripts/nas-adhoc.sh nas -b -m ansible.builtin.find -a 'paths=/mnt/main/home-assistant-backups age=-1d'

The first command lists the export of /mnt/main/home-assistant-backups with 192.168.20.220 as its only host. The second shows matched above zero one day after the first backup.

Home Assistant serves HTTPS on port 443 with a Let’s Encrypt certificate for ha.fzymgc.house. Every client verifies it with the system trust store. Port 80 and port 8123 do not answer. The certificate comes from a DNS-01 challenge through Cloudflare. tf/cloudflare/ha_acme.tf creates the Cloudflare token ha-acme-dns01, which can edit DNS records and read the zone of fzymgc.house, and writes it to Vault at secret/fzymgc-house/infrastructure/home-assistant/acme.

The Let’s Encrypt app, the web server settings and the URLs are Home Assistant content. To set them up on a new VM:

  1. Read the token:

    Terminal window
    vault kv get -field=cloudflare_api_token secret/fzymgc-house/infrastructure/home-assistant/acme
  2. Install the Let’s Encrypt app. Add the domain ha.fzymgc.house, choose the challenge dns, set the provider to dns-cloudflare, and enter the token in cloudflare_api_token. Leave cloudflare_api_key and cloudflare_email empty.

  3. Set the private key file to privkey.pem and the certificate file to fullchain.pem. These are file names in /ssl. The app adds /ssl/ itself, so a full path fails with cp: cannot create regular file '/ssl//ssl/privkey.pem'.

  4. Start the app and read its log. It ends with the expiry date of the certificate.

  5. In Settings, then System, then Network, set the server port to 443, the certificate file to /ssl/fullchain.pem and the key file to /ssl/privkey.pem. These fields take full paths.

  6. In the same page, under Home Assistant URL, turn off Automatic for the local network and set https://ha.fzymgc.house. For the Internet, use Home Assistant Cloud. The estate publishes no public name for Home Assistant.

The app does not renew the certificate by itself. It runs once and exits, and it renews only when started within 30 days of expiry. Home Assistant also serves the certificate that it loaded at start. So keep two automations in Home Assistant:

  • An automation that starts the app every day, with the action hassio.addon_start and the app core_letsencrypt.
  • The Certificate Expiry integration on ha.fzymgc.house port 443, and an automation that restarts Home Assistant Core when that sensor shows fewer than 25 days.

The Uptime Kuma monitor Home Assistant alerts before the certificate expires. To read the certificate that Home Assistant serves:

Terminal window
echo | openssl s_client -connect ha.fzymgc.house:443 -servername ha.fzymgc.house 2>/dev/null | openssl x509 -noout -issuer -enddate

The VM is a tailnet node through the Tailscale app of Home Assistant OS. The app names the node homeassistant, and no option changes that name. The node carries the tag tag:homeassistant, advertises no route and no exit node, and hosts the Tailscale Service svc:ha. A Tailscale Service is a named resource of the tailnet with its own addresses and its own MagicDNS name. An operator on the tailnet reaches Home Assistant at https://ha.hound-skate.ts.net with a certificate from Tailscale, from anywhere, with no subnet route. The companion app keeps Home Assistant Cloud as its Internet URL.

tf/tailscale/services.tf defines the Service. tailscale/policy.hujson holds the tag owner, the auto-approver that lets a tag:homeassistant node host it, and the grant for group:admin on port 443. The app configuration is Home Assistant content. To set it up on a new VM:

  1. Install the Tailscale app from the community repository and open its configuration.

  2. Set these options and leave every other option at its default:

    Option Value
    advertise_tags tag:homeassistant
    advertise_routes an empty list
    advertise_exit_node false
    accept_routes false
    userspace_networking false
    share_homeassistant disabled
    services one entry: name svc:ha, target https+insecure://127.0.0.1:443, protocol https, port 443

    The app’s own Serve option needs Home Assistant on plain HTTP, so it stays off. The Service proxy dials the HTTPS listener of Home Assistant on the loopback. +insecure tells it to accept any certificate on that hop, because the certificate names ha.fzymgc.house.

  3. In Settings, then System, then Network, open the Reverse proxy section of the HTTP server card. Turn on Trust X-Forwarded-For, add 127.0.0.1 to the trusted proxies, and save. The save restarts Home Assistant. This Home Assistant version keeps the HTTP settings in the UI. It ignores an http: block in configuration.yaml and raises a repair that asks for its removal.

    The Service proxy adds an X-Forwarded-For header to each request. Without these settings, Home Assistant answers 400: Bad Request to every request through the Service and logs A request from a reverse proxy was received from 127.0.0.1, but your HTTP integration is not set-up for reverse proxies. The trust covers the loopback only. If a request from any other address carries the header, Home Assistant answers 400 and logs Received X-Forwarded-For header from an untrusted proxy. A request without the header, such as one from the LAN, is not affected.

  4. Start the app, open its web UI and log the node in as the admin user. The node registers tagged, so it has no node-key expiry.

  5. Read the Services page of the admin console. It lists homeassistant as an active host of svc:ha. The auto-approver in the policy approves the host, so you click nothing.

To make sure that the Service answers, from a tailnet client off the LAN:

Terminal window
curl -sS -o /dev/null -w '%{http_code}\n' https://ha.hound-skate.ts.net/
echo | openssl s_client -connect ha.hound-skate.ts.net:443 -servername ha.hound-skate.ts.net 2>/dev/null | openssl x509 -noout -subject -enddate

To make sure that the node advertises nothing but the Service, from a client of group:admin:

Terminal window
tailscale status --json | jq '.Peer[] | select(.HostName == "homeassistant") | {Tags, PrimaryRoutes, ExitNodeOption}'

Tags is ["tag:homeassistant"] and ExitNodeOption is false. PrimaryRoutes holds the two addresses of svc:ha and nothing else. A client outside the grant sees null there, because Tailscale shows a Service address only to a client that the policy lets reach it.

The role calgary-otel-collector runs otelcol-calgary, the same pinned otelcol-contrib release as dns-otel-collector. It sends the whole journal of calgary and its host metrics to otel-gateway.fzymgc.house:443 over mTLS. Each journal entry gets the name of its systemd unit as service.name, and every record has host.name calgary. Home Assistant does not send telemetry, because it runs inside the VM.

The role vault-cert-agent renders the client certificate of the collector from the Vault PKI role otel-collector-calgary-client. It renews the certificate at half of its 90-day life, and the collector reads the new certificate within one hour. Host certificates describes the agent, the expiry alert and a manual issue. The converge reads the ClickStack ingest token and the AppRole role id from Vault, so it needs a Vault session in the environment:

Terminal window
export VAULT_TOKEN="$(vault print token)"
scripts/calgary-playbook.sh

To make sure that logs arrive, run this query on the ClickStack server:

Terminal window
kubectl exec -n clickstack "$(kubectl get pod -n clickstack \
-l clickhouse.com/role=clickhouse-server -o name | head -1 | cut -d/ -f2)" \
-- clickhouse-client --query "SELECT count() FROM default.otel_logs \
WHERE ResourceAttributes['host.name'] = 'calgary' AND Timestamp > now() - INTERVAL 10 MINUTE"

The count is above zero.

Community integrations, apps and cards run inside Home Assistant with full access to it. Each one gets a security review of a pinned version before it is installed. Updates stay manual, so a new version gets a review first.

HACS installs community integrations and cards from GitHub. A review on 2026-10-05 of tag 2.0.5 (commit c0dfd8b4) found it safe to use with these rules. HACS verifies nothing that it installs, and it reads an unsigned feed from data-v2.hacs.xyz every 6 hours. A repository that the feed marks as critical is uninstalled, and Home Assistant restarts, with no click. Sean decided on 2026-10-05 to keep the feed, so that the store stays browsable. The Home Assistant backups and the daily Incus snapshot are the recovery.

To install HACS, run these commands in the Terminal & SSH app. Do not use the get.hacs.xyz script or the Get HACS app, because both install an unpinned version with no checksum.

Terminal window
cd /tmp && curl -sSL -o hacs.zip https://github.com/hacs/integration/releases/download/2.0.5/hacs.zip
echo "97be6b824a4f38e683728cc6dd72367f6b8bad0a43428b1b3b987a3087adf413 hacs.zip" | sha256sum -c -
mkdir -p /config/custom_components/hacs && unzip hacs.zip -d /config/custom_components/hacs && rm hacs.zip

Then restart Home Assistant, add the HACS integration and complete the GitHub device login. Make sure that “HACS” shows no scopes in the settings of your GitHub account, under Applications.

Rules for each repository:

  • Install a specific tag, not the latest, and keep the pre-release switch off.
  • Before you install, read the tag on GitHub. Make sure that the project is maintained, that it has no open security advisory, and that domain in manifest.json has only lowercase letters, digits and _.
  • Do not automate update.install for the update entities of HACS.
  • An integration that asks for shell, file or admin power gets a full security review.
  • A card is JavaScript that runs in the browser session of each user, so it gets the same bar.

The MCP server lets Claude Code read and change Home Assistant. It runs as two apps from the repository homeassistant-ai/ha-mcp: Home Assistant MCP Server 8.6.0, and Nabu Casa - Webhook Proxy for HA MCP 3.0.4, with its integration mcp_proxy. The proxy publishes the server at a webhook of the Home Assistant Cloud URL. Security reviews found both apps safe to keep with these settings. The reviews covered these two versions. After you update an app, review the changes from the version here, and then change the version here.

App Setting Value
Webhook proxy Enable OAuth On, with the OAuth mode ha_auth
Webhook proxy Log inbound requests Off
Both apps Auto update Off
MCP server Disabled tools ha_manage_app,ha_manage_updates,ha_manage_hacs

Do not trust the OAuth mode by itself. With Enable OAuth off, the webhook answers with no authentication, and a client login still reports success. After any change to the apps, make sure that an unauthenticated request fails. The command tests the webhook and its read-only path /readonly, and prints HTTP 401 twice:

Terminal window
U=$(claude mcp get homeassistant | sed -n 's/^ *URL: //p')
for p in "" /readonly; do
curl -sS -o /dev/null -w 'HTTP %{http_code}\n' -X POST "$U$p" -H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'
done

The webhook id in the URL is a secret, so do not print the URL.

Do not add the webhook of the proxy in Settings, then Home Assistant Cloud, then Webhooks. Such a cloudhook sends the login token and each MCP request through a relay of Nabu Casa that reads them. The MCP client uses the remote URL <id>.ui.nabu.casa instead, where the TLS session ends in Home Assistant.

The proxy accepts the login of any active Home Assistant user, and the server then acts with the full power of the Supervisor token. Sean is the only user, so this is safe today. Before you add any other user, also a guest or a tablet account, replace the two apps with the in-process component ha_mcp_tools from homeassistant-ai/ha-mcp-integration tag v2.2.1. Its login requires an admin.

The Tesla Fleet integration reads the vehicles and the energy products of the Tesla account of Sean through the Fleet API of Tesla. Tesla needs three things from the estate: a developer application, a public key on a domain that Sean owns, and that key paired with each vehicle. Home Assistant cannot host the key, because ha.fzymgc.house resolves only inside the estate. A Cloudflare Worker serves it at https://ha.fzymgc.net/.well-known/appspecific/com.tesla.3p.public-key.pem. The Worker is tesla-fleet-key in tf/cloudflare/workers.tf, and the key is the file cloudflare/workers/tesla-fleet-key/com.tesla.3p.public-key.pem. A change to that file publishes a new key on merge.

The private key lives in two places: /config/tesla_fleet.key in Home Assistant, which signs every vehicle command, and Vault at secret/fzymgc-house/infrastructure/home-assistant/tesla-fleet, as the backup for a restore. It never enters this repository.

Create the application at https://developer.tesla.com/request with the Tesla account. The account needs a verified email and multi-factor authentication. On the Client Details step:

Field Value
OAuth Grant Type Authorization Code and Machine-to-Machine
Allowed Origin URL(s) https://ha.fzymgc.net
Allowed Redirect URI(s) https://my.home-assistant.io/redirect/oauth
Allowed Returned URL(s) empty

The form rejects an origin whose hostname holds the word tesla, which is why the name is ha.fzymgc.net and not tesla.fzymgc.net. The redirect goes through my.home-assistant.io, which the browser follows to ha.fzymgc.house. So Tesla never calls Home Assistant, and the estate publishes no public name for it. Make sure that the browser that runs the setup has https://ha.fzymgc.house saved at https://my.home-assistant.io.

On the API & Scopes step, select Vehicle Information, Vehicle Location, Vehicle Commands, Vehicle Charging Management, Energy Product Information and Energy Product Settings. The integration asks for all six, and a missing scope fails the login.

Tesla bills the Fleet API per request, with a $10 discount each month. Data polls cost $1 per 500, commands $1 per 1,000, and wakes $1 per 50. Energy product calls are free. The integration polls each awake vehicle every 10 minutes, which stays inside the discount for a few vehicles. An application with no payment method is disabled, so add one on the Billing Details step, and set the billing limit to $10 on https://developer.tesla.com/dashboard/usage. The limit caps the bill before tax.

After the application exists, open View Details, then Credentials & APIs, and keep the Client ID and the Client Secret in 1Password.

Generate the pair on a workstation, before the integration is added. The vehicle accepts only prime256v1 keys.

Terminal window
openssl ecparam -name prime256v1 -genkey -noout -out tesla-fleet-private-key.pem
openssl ec -in tesla-fleet-private-key.pem -pubout -out com.tesla.3p.public-key.pem
vault kv put secret/fzymgc-house/infrastructure/home-assistant/tesla-fleet private_key=@tesla-fleet-private-key.pem domain=ha.fzymgc.net

Copy the private key to /config/tesla_fleet.key through the Terminal & SSH app or the Samba share. If the file exists before the integration is added, Home Assistant reads it. If not, Home Assistant generates its own key, and the setup fails with public_key_mismatch against the key that the Worker serves. To check the copy, run this in the Terminal & SSH app:

Terminal window
openssl ec -in /config/tesla_fleet.key -pubout

Commit the public key as cloudflare/workers/tesla-fleet-key/com.tesla.3p.public-key.pem, merge, and wait for the HCP Terraform apply. Then delete the private key from the workstation. To check the published key against the checkout:

Terminal window
diff <(curl -sS https://ha.fzymgc.net/.well-known/appspecific/com.tesla.3p.public-key.pem) cloudflare/workers/tesla-fleet-key/com.tesla.3p.public-key.pem && echo same

Add the Tesla Fleet integration in Home Assistant. Enter the Client ID and the Client Secret, log in at Tesla, select all scopes, allow, and confirm the link to Home Assistant. Keep the detected region. Enter the domain ha.fzymgc.net. Home Assistant then calls the register endpoint of Tesla, which reads the key from the Worker, and compares it with /config/tesla_fleet.key.

The Tesla account holds four Powerwall 2 units and no vehicle, so the pairing below applies only when a vehicle joins the account. Energy product calls are free, so the usage page stays at $0.

Pair the key with each vehicle. Open https://tesla.com/_ak/ha.fzymgc.net on the phone that holds the Tesla app, in Safari on an iPhone, and approve the key. The Locks screen of the vehicle then lists the key. Vehicles made since late 2023 reject every command until the key is paired. To remove the key, delete it in the Locks screen.

A rotation is a new key pair. Run the commands above again, replace /config/tesla_fleet.key, commit the new public key, and reconfigure the integration from Settings, then Devices & services, then Tesla Fleet. Then pair the new key with each vehicle again.

unattended-upgrades installs Ubuntu updates every day without a person. It takes packages from the release, -security and -updates pockets. The stock file 50unattended-upgrades allows the first two. The drop-in /etc/apt/apt.conf.d/52unattended-upgrades-calgary adds -updates, and apt adds list entries from each file. The two periodic switches are lines in 20auto-upgrades. The -updates pocket also carries new kernels and new builds of ZFS and Incus, so these install without a person too.

apt-daily-upgrade.timer runs unattended-upgrades at 06:00 local time, with a random delay of up to one hour. If an update requires a reboot, it schedules one for the next 04:00 local time. calgary-common sets the time zone to America/New_York. unattended-upgrades reboots calgary only at 04:00. A person or a power loss can still restart it at any time. After a reboot, Incus starts the VM haos again, because the VM sets boot.autostart.

The reboot has no gate, unlike the reboot of heimdall. Lighting does not depend on Home Assistant, as Failure domains of the lighting describes. A reboot at night stops the automations for a few minutes and turns off no light.

To read the state of the policy:

Terminal window
ssh fzymgc@calgary.fzymgc.house shutdown --show
ssh fzymgc@calgary.fzymgc.house ls /var/run/reboot-required
ssh fzymgc@calgary.fzymgc.house last -x reboot
ssh fzymgc@calgary.fzymgc.house apt-config dump Unattended-Upgrade

shutdown --show prints the scheduled reboot, or No scheduled shutdown.. To cancel a scheduled reboot, run sudo shutdown -c on calgary.

Lighting must keep working when any one hub fails. Two parts carry the lights, and Home Assistant is neither of them:

  • Matter-over-Thread wall switches drive the load of each wired fixture. A switch turns its fixture on and off with no hub.
  • One Hue Bridge Pro runs the color lights.

Apple Home and Home Assistant are both controllers above these parts. Either one can fail and the other still controls the house.

Failure Lights What stops
calgary or the Home Assistant VM Every light works. Apple Home controls them. The automations and the dashboards of Home Assistant
The Hue Bridge Pro The wired fixtures work from their switches. Control of the color lights
One Thread border router Every light works. The switches work with no hub, and the other border routers carry the Thread network. Nothing