# Cantabile Edge Agent The agent connects this Home Assistant to Cantabile. It reads the devices an installer chose with you, plans your home's energy every 15 minutes (48 hours ahead, from prices, weather and your devices) and, only where you agreed, runs those devices through Home Assistant: heating, charging, the battery. ## Before you start - **Mosquitto broker** add-on, installed and started (Settings → Add-ons → Add-on store). The agent shows itself in Home Assistant through it: the device "Cantabile" in the area "Cantabile", prices, what Cantabile asked for and why. Without the broker the agent still works, but you don't see it in Home Assistant. - Your **claim code**, from the Cantabile card. ## Your consent You give your consent when you install the add-on, in its **Configuration** tab (Settings → Add-ons → Cantabile Edge Agent → Configuration): - **Share energy data with Cantabile** (needed): "Cantabile may receive the energy data of the devices chosen for it." Without it the add-on does not connect to Cantabile at all: nothing is enrolled, read for Cantabile or sent, and the add-on's page says so. - **Cantabile may control devices** (optional, separately): "Allow Cantabile to control the devices you choose (heating, charging, battery, shades) within the limits you set." These are the same texts, in the same version, as on a Cantabile Hub's setup. The add-on records what you agreed to, the texts' version and when, "given at installation in the add-on's configuration", and tells Cantabile. Which devices Cantabile may read or control you choose device by device on the add-on's **Devices** page. You can take your consent back in the Configuration tab at any time (save and restart the add-on): from then on nothing more is collected or sent. ## Options - **Mode:** `shadow` (default) reads and plans, controls nothing. `off` only keeps the connection. Advising and running devices are turned on from Cantabile, never here, and only with your consent. - **Claim code:** ties this home to your Cantabile account. - **Dashboards:** one dashboard, "Cantabile" in the sidebar, with a view for each part your home has: **Overview** (Cantabile's connection and mode, the plan and the price, power now from solar, grid, battery and home, energy today), **Energy** (over days and months), **Heating & cooling**, **Devices** (Cantabile's devices and their main values, with a link to their settings) and **Building** (joining a building). It also sets up Home Assistant's Energy dashboard while you have none of your own. Your own dashboards are never changed. - **Cantabile support may open this Home Assistant** (off by default): when you turn it on, Cantabile's support team can open this Home Assistant through Cantabile's connection to help you, signed in as a user of its own, "Cantabile support" (an administrator, so that it can look at your integrations, logs and repairs; never the owner, and never with your password, which it cannot change either). The add-on makes that user and gives it a new password for each session that nobody sees; afterwards the user is disabled again and has no password. A session lasts at most an hour, ends after 15 minutes without use, and every request is recorded. You see the user in Settings → People while it exists, and while a session is open the add-on's own pages (below) say so at the top, with **End now**: it ends the session at once and disables the user again. Turning the option off and restarting the add-on ends it too. On these pages the user "Cantabile support" cannot switch reading or control on, change a protection or make the other choices that are yours. Home Assistant must answer plain HTTP on its own port for this (with an `ssl_certificate` in its `http:` configuration support is told it cannot open it). ## Pages The add-on's own pages are not in the sidebar: open them from Cantabile's dashboard ("Devices" under the status, "Building"), or from Settings → Add-ons → Cantabile Edge Agent → Open web UI. "Show in sidebar" on that page puts it there if you want it. Only an administrator of Home Assistant can use them. - **Devices:** Home Assistant's devices that a Cantabile device profile knows, and what Cantabile would read from each and could control. See "Using a device with Cantabile" below. - **Building or community:** joining a building or an energy community. ## Your devices in Cantabile (the mapping) At its first start the agent proposes which of Home Assistant's devices Cantabile uses (the mapping, `/data/mapping.yaml` in the add-on's folder): Cantabile's own devices first (their device profiles say what each value is), then devices Cantabile knows, then solar, grid, battery and room sensors by their names. New devices are added while the proposal is unchanged. The proposal only shows your home in Cantabile's dashboard; **nothing is read for Cantabile or sent** until you agree. ### Using a device with Cantabile On the add-on's **Devices** page each device Home Assistant has and a Cantabile device profile knows is listed with what Cantabile would read from it (for example solar power, the battery's charge, a room's temperature) and what it could control (heating, cooling, charging, the battery). A thermostat that no specific profile knows gets the generic one (any device with a climate entity). **Use with Cantabile** confirms the device: - Cantabile takes the device's values as its profile describes them, instead of the proposal's guesses, and keeps the proposal away from that device from then on. Stop using it on the same page and the proposal takes it back. - The device appears on Cantabile's dashboard, and in the area "Cantabile" if it has no area of its own (a thermostat in its room keeps its room). - Reading and control start **off**. Switch them on for the device on the same page ("Cantabile may read these values", "Cantabile may control it"): this needs your consent in the Configuration tab first (above; control needs its own). The agent starts again for a few seconds to apply it. The dashboard here shows the device either way: that stays in your home. - Controls that must not be switched off are **protected** as their profile says (a thermostat, an inverter's output): Cantabile never switches them off. You can lift or set protection on the page. A device **sealed** by its custodian (a grid or metering operator) is shown locked. - A thermostat that heats and cools: choose **heating**, **cooling**, **by season** (the default: heating October to April) or **by outdoor temperature**. Cantabile uses one at a time. Nothing is installed or set up in Home Assistant here: the page uses the devices Home Assistant already has. Values your own mapping (written by hand) already reads stay there, and a control on an entity another control already writes is left out: one writer per device. ### Moving from an earlier install A mapping an installer confirmed for an earlier install of Cantabile (for example the agent's container, `/root/cantabile-agent/mapping.yaml`) is taken over once: 1. Copy it to Home Assistant's share folder as `cantabile/mapping.yaml` (`/share/cantabile/mapping.yaml`, e.g. with the Samba or SSH add-on). 2. Restart the add-on. Its log says "an earlier install's mapping … imports it once". Its entries keep their names; consent is **not** taken over (you decide again). An entry whose sensor has no value here is replaced by the same value from Cantabile's own devices, and the file lists what changed. The copy in the share folder can stay; it is not taken again unless it changes. ## What it reads, and what leaves your home - Nothing leaves until you agreed to share data (the Configuration tab) and switched reading on for the devices Cantabile may read (the Devices page). - At start the add-on reads Home Assistant's instance id once (in `/homeassistant/.storage`), as the identity of your home in Cantabile. Then it runs as its own user without any special rights; it never reads your `secrets.yaml`, passwords or tokens. - Everything goes to Cantabile over one encrypted connection that the agent opens; nothing in your network is opened for it. ## Backups Home Assistant's backups include the add-on's data: its identity with Cantabile, the mapping, your consent. Restored on a new machine, the home keeps its history with Cantabile. ## Help Cantabile's support, from your Cantabile account. --- © 2026 Setti Solutions S.R.L, [www.setti.md](https://www.setti.md). All rights reserved.