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.
The layer split
Section titled “The layer split”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.
Connection model
Section titled “Connection model”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):
scripts/calgary-playbook.sh --check --diff # dry runscripts/calgary-playbook.sh # applyVault path
Section titled “Vault path”| 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/*.
Seed or rotate the key
Section titled “Seed or rotate the key”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.
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:
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-okrm -rf "$d"The command prints key-ok.
Network
Section titled “Network”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:
dig +short calgary.core.lan.fzymgc.house calgary.main.lan.fzymgc.houseMove calgary to another switch port
Section titled “Move calgary to another switch port”- If the new port has another native network, change the address of the entry
calgaryto a free address on that network first. - Move the cable. When the link comes back, systemd-networkd asks for a new lease.
- If calgary takes a pool address, run
sudo networkctl reconfigure enp1s0on calgary at that address. The reconfigure drops the lease and starts a new DHCP exchange, so Kea answers with the reservation. Do not usenetworkctl renew. Kea extends the pool lease that a renew asks for. - Declare the new port in
tf/unifiand 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.
Host baseline
Section titled “Host baseline”calgary-common does five things:
- It makes sure that the Incus storage pool
defaultis the ZFS datasetrpool/incus. It creates and changes no pool. - It deletes the leftover VM
test-vm. - It purges the
libvirt*packages, so Incus is the only virtualization manager. QEMU and Incus stay installed. - It sets the time zone to
America/New_York. - 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 Home Assistant VM
Section titled “The Home Assistant VM”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 |
The network legs
Section titled “The network legs”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 seed rule
Section titled “The seed rule”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.
No Incus agent
Section titled “No Incus agent”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:
dig +short ha.fzymgc.housecurl -sS -o /dev/null -w '%{http_code}\n' https://ha.fzymgc.house/manifest.jsonThe 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.
Snapshots
Section titled “Snapshots”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:
incus snapshot list haos -f csvincus stop haosincus snapshot restore haos <snapshot>incus start haosThe Thread radio
Section titled “The Thread radio”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:
incus restart haos --timeout 120After 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:
readlink -f /sys/bus/usb/devices/*/driver | grep -E 'usbfs|cdc_acm'To read the IDs that the radio shows, run this on calgary:
grep -H . /sys/bus/usb/devices/*/idVendor /sys/bus/usb/devices/*/idProductIf the radio shows an ID that calgary_haos_radio_devices in host_vars/calgary.yml does not list,
add it there and converge.
The Thread network
Section titled “The Thread network”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:
- 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.
- In Home Assistant, open Settings, then Devices & services, then Thread, and select Configure. On
MyHome16, select Make preferred network. - In Settings, then Devices & services, set up the discovered ZBT-2 and select Thread.
- 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.
The ZHA network forms last
Section titled “The ZHA network forms last”A Zigbee network keeps the channel that it forms on. So form the ZHA network last, in this order:
- Write the Thread and Hue channels in the 2.4 GHz table of
docs/reference/network.md. - Run a ZHA energy scan from the location of the SLZB-06MG24.
- Form the ZHA network on a channel that Wi-Fi channels 1, 6 and 11 and the other two networks do not use.
Remove the VM
Section titled “Remove the VM”This deletes Home Assistant and its content. Take a Home Assistant backup first. Run on calgary:
incus delete --force haosTo 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.
Backups
Section titled “Backups”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:
-
In Home Assistant, open Settings, then System, then Storage, and add network storage. Use the name
nas, the usage Backup, the server192.168.20.200, the protocol NFS and the remote share path/mnt/main/home-assistant-backups. Use the IPv4 address, notnas.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. -
In Settings, then System, then Backups, set a daily automatic backup to the location
nas. -
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:
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:
-
Read the token:
Terminal window vault kv get -field=cloudflare_api_token secret/fzymgc-house/infrastructure/home-assistant/acme -
Install the Let’s Encrypt app. Add the domain
ha.fzymgc.house, choose the challengedns, set the provider todns-cloudflare, and enter the token incloudflare_api_token. Leavecloudflare_api_keyandcloudflare_emailempty. -
Set the private key file to
privkey.pemand the certificate file tofullchain.pem. These are file names in/ssl. The app adds/ssl/itself, so a full path fails withcp: cannot create regular file '/ssl//ssl/privkey.pem'. -
Start the app and read its log. It ends with the expiry date of the certificate.
-
In Settings, then System, then Network, set the server port to
443, the certificate file to/ssl/fullchain.pemand the key file to/ssl/privkey.pem. These fields take full paths. -
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_startand the appcore_letsencrypt. - The Certificate Expiry integration on
ha.fzymgc.houseport 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:
echo | openssl s_client -connect ha.fzymgc.house:443 -servername ha.fzymgc.house 2>/dev/null | openssl x509 -noout -issuer -enddateTailnet access
Section titled “Tailnet access”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:
-
Install the Tailscale app from the community repository and open its configuration.
-
Set these options and leave every other option at its default:
Option Value advertise_tagstag:homeassistantadvertise_routesan empty list advertise_exit_nodefalseaccept_routesfalseuserspace_networkingfalseshare_homeassistantdisabledservicesone entry: name svc:ha, targethttps+insecure://127.0.0.1:443, protocolhttps, port443The 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.
+insecuretells it to accept any certificate on that hop, because the certificate namesha.fzymgc.house. -
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.1to the trusted proxies, and save. The save restarts Home Assistant. This Home Assistant version keeps the HTTP settings in the UI. It ignores anhttp:block inconfiguration.yamland raises a repair that asks for its removal.The Service proxy adds an
X-Forwarded-Forheader to each request. Without these settings, Home Assistant answers400: Bad Requestto every request through the Service and logsA 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 answers400and logsReceived X-Forwarded-For header from an untrusted proxy. A request without the header, such as one from the LAN, is not affected. -
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.
-
Read the Services page of the admin console. It lists
homeassistantas an active host ofsvc: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:
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 -enddateTo make sure that the node advertises nothing but the Service, from a client of group:admin:
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.
Telemetry
Section titled “Telemetry”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:
export VAULT_TOKEN="$(vault print token)"scripts/calgary-playbook.shTo make sure that logs arrive, run this query on the ClickStack server:
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
Section titled “Community integrations”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.
cd /tmp && curl -sSL -o hacs.zip https://github.com/hacs/integration/releases/download/2.0.5/hacs.zipecho "97be6b824a4f38e683728cc6dd72367f6b8bad0a43428b1b3b987a3087adf413 hacs.zip" | sha256sum -c -mkdir -p /config/custom_components/hacs && unzip hacs.zip -d /config/custom_components/hacs && rm hacs.zipThen 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
domaininmanifest.jsonhas only lowercase letters, digits and_. - Do not automate
update.installfor 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
Section titled “The MCP server”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:
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"}}}'doneThe 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.
Tesla Fleet
Section titled “Tesla Fleet”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.
The developer application
Section titled “The developer application”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.
The key pair
Section titled “The key pair”Generate the pair on a workstation, before the integration is added. The vehicle accepts only
prime256v1 keys.
openssl ecparam -name prime256v1 -genkey -noout -out tesla-fleet-private-key.pemopenssl ec -in tesla-fleet-private-key.pem -pubout -out com.tesla.3p.public-key.pemvault kv put secret/fzymgc-house/infrastructure/home-assistant/tesla-fleet private_key=@tesla-fleet-private-key.pem domain=ha.fzymgc.netCopy 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:
openssl ec -in /config/tesla_fleet.key -puboutCommit 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:
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 sameThe integration
Section titled “The integration”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.
Rotate the key
Section titled “Rotate the key”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.
Reboot policy
Section titled “Reboot policy”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:
ssh fzymgc@calgary.fzymgc.house shutdown --showssh fzymgc@calgary.fzymgc.house ls /var/run/reboot-requiredssh fzymgc@calgary.fzymgc.house last -x rebootssh fzymgc@calgary.fzymgc.house apt-config dump Unattended-Upgradeshutdown --show prints the scheduled reboot, or No scheduled shutdown.. To cancel a scheduled
reboot, run sudo shutdown -c on calgary.
Failure domains of the lighting
Section titled “Failure domains of the lighting”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 |