#!/usr/bin/env python3 # Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. """The Edge Agent's start as a Home Assistant add-on (runs as root). - Home Assistant's instance id: .storage/core.uuid is root-only; a copy in /data for the link (the site id comes from it, as on the Hub). - The add-on's options (/data/options.json): the owner's consent, mode, claim code, dashboards. - Consent (the owner's decision of 2026-10-30): given when the add-on is installed from Cantabile's repository, in its configuration: sharing the energy data of the devices chosen for Cantabile (needed: until it is given the add-on does not enrol or connect, and its page says why) and, separately, control. The same texts and version as the Hub's setup wizard and panel; recorded in the agent's consent file (/data/state/consent.json: share, control, when, the texts' version, the source), which the link sends to Cantabile with its heartbeat. Taken back in the configuration: nothing more is collected or sent. - The hardware fingerprint (hashed ids: the DMI ones are root-only): written once per start for the link, which recognises a reinstall with it. - MQTT: the broker the Supervisor offers (the Mosquitto add-on), with the login it made for this add-on; without one, no discovery in HA. - First start: config.yaml and an empty mapping, as the Hub's edge-prepare; the agent then proposes one from Home Assistant's devices (propose.py), consent off: nothing is read for Cantabile until the owner agrees. - An earlier install's mapping (/share/cantabile/mapping.yaml, the owner or support puts it there): copied to /data/mapping-import.yaml for the agent, which imports it once per content, consent off. Then the link and the agent (cantabile-run) as uid 10001, without root's capabilities: /homeassistant stays mapped, but only what is readable for everyone is readable for them. ADDON_DATA, ADDON_HA_CONFIG, ADDON_ETC, SUPERVISOR_URL and ADDON_DRY_RUN=1 (print the environment instead of starting) are for tests. """ import html import json import os import pwd import re import signal import subprocess import sys import time import urllib.request DATA = os.environ.get("ADDON_DATA", "/data") HA_CONFIG = os.environ.get("ADDON_HA_CONFIG", "/homeassistant") SHARE = os.environ.get("ADDON_SHARE", "/share") ETC = os.environ.get("ADDON_ETC", "/etc/cantabile") SUPERVISOR = os.environ.get("SUPERVISOR_URL", "http://supervisor") DRY = os.environ.get("ADDON_DRY_RUN") == "1" USER = "cantabile" # edge/Dockerfile: uid 10001 CONFIG = """# The Edge Agent as a Home Assistant add-on (written once by addon-run). mode: shadow mapping: /data/mapping.yaml state_dir: /data/state sink: {kind: link, path: /run/cantabile/link.sock} """ MAPPING = """# Which HA entities Cantabile may read (edge/cantabile_edge/mapping.py). # None yet: the agent proposes them from Home Assistant's devices, or imports # an earlier install's mapping (/share/cantabile/mapping.yaml), consent off. version: 1 assets: [] """ IMPORT = "cantabile/mapping.yaml" INGRESS_PORT = 8099 RESTART = 75 # The consent's texts: the Hub's (hub/.../cantabile/web CONSENT_TEXT, # CONTROL_TEXT and CONSENT_VERSION), working texts until the legal team's. CONSENT_TEXT = "Cantabile may receive the energy data of the devices chosen for it." CONTROL_TEXT = ("Allow Cantabile to control the devices you choose (heating, charging, battery, shades) " "within the limits you set.") CONSENT_VERSION = "working-2026-10-29" CONSENT_SOURCE = "given at installation in the add-on's configuration" WAITING = { "en": ("Cantabile is not connected", "Cantabile connects only with your consent. In the add-on's Configuration (Settings, Apps or Add-ons, " "Cantabile Edge Agent), turn on \"Share energy data with Cantabile\" (and, if you want, \"Cantabile may " "control devices\"), save and restart the add-on.", "Open the configuration"), "de": ("Cantabile ist nicht verbunden", "Cantabile verbindet sich nur mit Ihrer Einwilligung. Schalten Sie in der Konfiguration des Add-ons " "(Einstellungen, Apps bzw. Add-ons, Cantabile Edge Agent) „Energiedaten mit Cantabile teilen“ ein (und, " "wenn Sie möchten, „Cantabile darf Geräte steuern“), speichern Sie und starten Sie das Add-on neu.", "Konfiguration öffnen"), } def log(msg): print(f"addon-run: {msg}", flush=True) def owner(): if DRY or os.geteuid() != 0: return None pw = pwd.getpwnam(USER) return pw.pw_uid, pw.pw_gid def put(path, text, mode=0o600, own=None, keep=False): """Write a file the agent's user owns; keep=True: only if missing.""" if keep and os.path.exists(path): return os.makedirs(os.path.dirname(path), exist_ok=True) tmp = path + ".tmp" with open(tmp, "w") as f: f.write(text) os.chmod(tmp, mode) if own: os.chown(tmp, *own) os.replace(tmp, path) def chown_tree(path, own): """The agent's files in /data (options.json stays the Supervisor's).""" for root, dirs, files in os.walk(path): for n in dirs + files: p = os.path.join(root, n) if p != os.path.join(DATA, "options.json") and not os.path.islink(p): os.chown(p, *own) os.chown(path, *own) def consent(opts, own, now=None): """The owner's consent from the configuration into the agent's consent file; True when sharing is given. Kept as it was (and when it was given) while unchanged; the operators' consents (the add-on's page) stay.""" path = f"{DATA}/state/consent.json" try: with open(path) as f: d = json.load(f) d = d if isinstance(d, dict) else {} except (OSError, ValueError): d = {} share = opts.get("consent_data") is True control = share and opts.get("consent_control") is True if (d.get("share"), d.get("control"), d.get("text_version"), d.get("by")) != \ (share, control, CONSENT_VERSION, "ha-addon-config") or not os.path.exists(path): d.update(share=share, control=control, at=int(now or time.time()), by="ha-addon-config", source=CONSENT_SOURCE, text_version=CONSENT_VERSION, texts={"share": CONSENT_TEXT, "control": CONTROL_TEXT}) os.makedirs(os.path.dirname(path), exist_ok=True) put(path, json.dumps(d, ensure_ascii=False), 0o600, own) log(f"consent from the configuration: sharing {'given' if share else 'not given'}, " f"control {'given' if control else 'not given'} (texts {CONSENT_VERSION})") return share def own_slug(): """This add-on's slug from the Supervisor (for the link to its configuration); "" when it can't be asked.""" token = os.environ.get("SUPERVISOR_TOKEN", "") req = urllib.request.Request(f"{SUPERVISOR}/addons/self/info", headers={"Authorization": f"Bearer {token}"}) try: with urllib.request.urlopen(req, timeout=10) as r: return str((json.load(r).get("data") or {}).get("slug") or "") except (OSError, ValueError): return "" def waiting_html(accept_language, slug=""): """The page while there is no consent, in German or English, in HA's light or dark look, with a button to the add-on's configuration.""" lang = "de" if (accept_language or "").strip().lower().startswith("de") else "en" title, text, button = WAITING[lang] link = (f'

{html.escape(button)}

' if re.fullmatch(r"[a-z0-9_]+", slug or "") else "") return (f'{html.escape(title)}" f"

{html.escape(title)}

{html.escape(text)}

{link}") def waiting_page(own): """No consent: the add-on's page (HA's ingress) says why Cantabile is not connected and where to give it; nothing is enrolled or sent.""" from http.server import BaseHTTPRequestHandler, HTTPServer slug = own_slug() class Page(BaseHTTPRequestHandler): def do_GET(self): body = waiting_html(self.headers.get("Accept-Language"), slug).encode() ok = self.client_address[0] in ("172.30.32.2", "127.0.0.1", "::1") self.send_response(200 if ok else 403) self.send_header("Content-Type", "text/html; charset=utf-8" if ok else "text/plain") self.send_header("Cache-Control", "no-store") self.end_headers() self.wfile.write(body if ok else b"Open this page from Home Assistant.") do_POST = do_GET def log_message(self, *a): pass server = HTTPServer(("0.0.0.0", INGRESS_PORT), Page) if own: os.setgroups([]) os.setgid(own[1]) os.setuid(own[0]) server.serve_forever() def mqtt(env, own): token = os.environ.get("SUPERVISOR_TOKEN", "") req = urllib.request.Request(f"{SUPERVISOR}/services/mqtt", headers={"Authorization": f"Bearer {token}"}) try: with urllib.request.urlopen(req, timeout=10) as r: d = json.load(r)["data"] except Exception as e: # no broker add-on: the agent runs without HA discovery log(f"no MQTT broker from the Supervisor ({e}): no Cantabile device in Home Assistant") return if d.get("ssl"): log("the MQTT broker wants TLS, which the agent does not speak yet: no Cantabile device in Home Assistant") return env["CANTABILE_MQTT_HOST"] = str(d["host"]) env["CANTABILE_MQTT_PORT"] = str(d.get("port", 1883)) if d.get("username"): env["CANTABILE_MQTT_USER"] = d["username"] put(f"{DATA}/mqtt-password", d.get("password", ""), own=own) env["CANTABILE_MQTT_PASSWORD_FILE"] = f"{DATA}/mqtt-password" log(f"MQTT broker {d['host']}:{env['CANTABILE_MQTT_PORT']}") def fingerprint(env, own): """The box's hardware ids, hashed by the link itself (`cantabile-link fingerprint`, as root); no raw serial is written.""" if DRY: return try: out = subprocess.run(["cantabile-link", "fingerprint"], capture_output=True, text=True, timeout=30).stdout json.loads(out) except (OSError, ValueError, subprocess.TimeoutExpired) as e: log(f"no hardware fingerprint: {e}") return put(f"{DATA}/fingerprint.json", out, own=own) env["CANTABILE_FINGERPRINT_FILE"] = f"{DATA}/fingerprint.json" def main(): own = owner() with open(f"{DATA}/options.json") as f: opts = json.load(f) env = dict(os.environ) # The platform this build belongs to (ha-addon/build.sh: addon.env). with open(f"{ETC}/addon.env") as f: for line in f: k, sep, v = line.strip().partition("=") if sep and not k.startswith("#"): env.setdefault(k, v) env["CANTABILE_COMMAND_CERT"] = f"{ETC}/commands.pem" if os.path.exists(f"{ETC}/bundles.pem"): env["CANTABILE_BUNDLE_CERT"] = f"{ETC}/bundles.pem" if os.path.exists(f"{ETC}/devices-ca.pem"): # the direct path's CA (docs/direct-link.md) env["CANTABILE_DEVICES_CA"] = f"{ETC}/devices-ca.pem" with open(f"{HA_CONFIG}/.storage/core.uuid") as f: put(f"{DATA}/ha-core.uuid", f.read(), own=own) env["CANTABILE_HA_UUID_FILE"] = f"{DATA}/ha-core.uuid" if not consent(opts, own): log("no consent to share energy data (the add-on's configuration): not connecting to Cantabile. " "Turn on \"Share energy data with Cantabile\" in the Configuration tab and restart the add-on.") if DRY: print(json.dumps({"consent": False})) return waiting_page(own) return fingerprint(env, own) code = (opts.get("claim_code") or "").strip() if code: put(f"{DATA}/claim-code", code + "\n", own=own) env["CANTABILE_MODE"] = opts.get("mode", "shadow") env["CANTABILE_DASHBOARDS"] = "1" if opts.get("dashboards", True) else "0" # Remote Home Assistant for Cantabile support (edge/link/hatunnel.go): # only when the owner turns it on here (off by default); the link then # offers it and keeps HA's "Cantabile support" user, through the # Supervisor. Turning it off (and the add-on's restart) ends a session. if opts.get("support_ha") is True: env["CANTABILE_HA_REMOTE"] = "1" log("remote Home Assistant for Cantabile support: allowed in the configuration") else: env.pop("CANTABILE_HA_REMOTE", None) mqtt(env, own) put(f"{DATA}/config.yaml", CONFIG, 0o644, own, keep=True) put(f"{DATA}/mapping.yaml", MAPPING, 0o644, own, keep=True) env["CANTABILE_PROPOSE"] = "1" try: with open(f"{SHARE}/{IMPORT}") as f: put(f"{DATA}/mapping-import.yaml", f.read(), 0o600, own) log(f"an earlier install's mapping in /share/{IMPORT}: the agent imports it once, consent off") except FileNotFoundError: pass except (OSError, UnicodeDecodeError) as e: log(f"/share/{IMPORT} not read: {e}") os.makedirs(f"{DATA}/state", exist_ok=True) if own: chown_tree(DATA, own) cmd = ["cantabile-run", "--config", f"{DATA}/config.yaml", "run"] if DRY: print(json.dumps({"cmd": cmd, "env": {k: v for k, v in env.items() if k.startswith(("CANTABILE_", "HA_"))}})) return if own: # Drop to the agent's user and every capability; no way back. cmd = ["setpriv", f"--reuid={own[0]}", f"--regid={own[1]}", "--init-groups", "--inh-caps=-all", "--bounding-set=-all", "--no-new-privs"] + cmd # 75: the agent asks to start again (a device's consent or controls # changed on its page, as the Hub's devices tool restarts it) child = None def forward(sig, _frame): if child is not None: child.send_signal(sig) for sig in (signal.SIGTERM, signal.SIGINT): signal.signal(sig, forward) while True: child = subprocess.Popen(cmd, env=env) rc = child.wait() if rc != RESTART: sys.exit(rc) log("the agent starts again") if __name__ == "__main__": try: main() except FileNotFoundError as e: log(f"missing {e.filename}") sys.exit(1)