Manage Add-on

Manage a Home Assistant add-on — update its configuration or call its internal API.

Five mutually exclusive operating modes:

Lifecycle mode (when action is one of install/uninstall/start/ stop/restart/rebuild/update): Runs a Supervisor add-on action on slug. install / update go through the store (the add-on's repository must be registered — it shows up in ha_get_addon(source="available")); the rest act on an installed add-on. This is how an assistant brings an add-on online for the user (e.g. installing + starting the dashboard screenshot engine).

Store-repository mode (when action is add_repository or remove_repository): Registers or unregisters a custom add-on store repository. These actions operate on the store rather than an installed add-on, so they take the repository param and no slug: add_repository POSTs the repository URL to /store/repositories; remove_repository DELETEs /store/repositories/{slug} by the repository's slug. Adding a repository (e.g. balloob's add-ons) is the missing step that lets an assistant then install an add-on from it via action="install".

Config mode (when any of options/network/boot/auto_update/watchdog is provided): Updates the add-on's Supervisor configuration via POST /addons/{slug}/options. All config parameters are optional; only provided fields are updated — current values are fetched and merged automatically (including one level of nested dicts).

Proxy mode (when path is provided without array_patch): Routes HTTP or WebSocket requests through Home Assistant's Ingress proxy by default (works on HAOS, Supervised, and off-host PyPI/uvx installs). Pass port=... to bypass Ingress and connect directly to an add-on's container port — that mode requires the MCP host to share Home Assistant's container network (i.e. only the HAOS addon). Use ha_get_addon(slug="...") to discover available ports and endpoints.

ESPHome Device Builder dashboard (current rewrite): config and log access is a WebSocket JSON-command API, NOT REST. The legacy endpoints are gone — GET /edit?configuration= now returns the dashboard SPA, and the old /compile /validate /logs WebSocket paths (which took {"type": "spawn", ...} bodies) reject the upgrade (HTTP 200). Use instead:

• HTTP GET /devices → JSON list of configured devices; each entry's configuration field is the YAML filename to pass below.

• WebSocket path="/ws" with body {"command": "<cmd>", "message_id": "1", "args": {...}}. The server sends a server_info message first, then one reply per message_id. Wire-confirmed commands: devices/get_config {configuration} → raw YAML (in the reply's result); devices/logs (stream) {configuration, port: "OTA"} → live device logs. Also exposed by the dashboard frontend (command/arg names not wire-tested here): devices/update_config {configuration, content} → save, devices/validate, firmware/compile.

• The /ws channel stays open, so for a one-shot read or a bounded log capture pass wait_for_close=False with message_limit (and message_offset to skip the server_info / config-banner preamble). Reach the dashboard through Ingress — omit port; direct port= does not route to it.

Array-patch mode (when path AND array_patch are provided): Atomic "GET array, mutate, POST array" workflow for addon APIs whose write contract is "send the whole resource collection back". Operations are applied in order to a working copy; if any op fails validation (unknown id, collision, malformed shape) nothing is posted. Returns a compact summary instead of the full array. Designed for Node-RED /flows and similar endpoints.

Response shaping (proxy mode):

• WebSocket streams can be noisy (e.g. the ESPHome dashboard's devices/logs dumps the device's full config banner on connect). By default, summarize=True collapses long runs of non-signal messages into short elision markers; INFO/WARNING/ERROR/exit lines always pass through. Pagination via message_offset / message_limit works on the raw collected list before summarize runs.

• python_transform applies a sandboxed Python expression as a final post-processing step in both HTTP and WebSocket modes. The variable response is bound to:

  • WebSocket: list[dict | str] — parsed JSON messages are dicts, undecodable frames stay as ANSI-stripped strings. Elision markers appear as {"elided": N, "note": "..."} dicts when summarize ran.

  • HTTP: dict | list | str — whichever the content-type produced. Transforms may mutate in place (response.append(...), del response[k]) or reassign (response = [...]). This is post-processing only — it does NOT provide optimistic-locking or write-back semantics.

WARNING: Setting boot="auto"/"manual" will fail for add-ons whose Supervisor metadata locks the boot mode. The Supervisor returns an error in this case.

NOTE: This tool only works with Home Assistant OS or Supervised installations.

Examples:

• Install an add-on: ha_manage_addon(slug="...", action="install")

• Start an add-on: ha_manage_addon(slug="...", action="start")

• Add a store repository: ha_manage_addon(action="add_repository", repository="https://github.com/balloob/home-assistant-addons")

• Remove a store repository: ha_manage_addon(action="remove_repository", repository="0f1cc410")

• Set add-on option: ha_manage_addon(slug="...", options={"log_level": "debug"}) Note: only the fields you provide are updated — current values are fetched first and merged automatically. Fields not in the add-on's schema are ignored with a warning.

• Disable auto-update: ha_manage_addon(slug="...", auto_update=False)

• Change host port: ha_manage_addon(slug="...", network={"5800/tcp": 8082})

• Set boot mode: ha_manage_addon(slug="...", boot="manual")

• Call HTTP API: ha_manage_addon(slug="...", path="/api/events")

• Direct port: ha_manage_addon(slug="...", path="/flows", port=1880)

• ESPHome list devices (HTTP): ha_manage_addon(slug="_esphome", path="/devices")

• ESPHome read a device's YAML (WS one-shot): ha_manage_addon(slug="_esphome", path="/ws", websocket=True, wait_for_close=False, message_limit=2, body={"command": "devices/get_config", "message_id": "1", "args": {"configuration": "device.yaml"}})

• ESPHome live logs (WS, bounded): ha_manage_addon(slug="_esphome", path="/ws", websocket=True, wait_for_close=False, message_limit=60, body={"command": "devices/logs", "message_id": "1", "args": {"configuration": "device.yaml", "port": "OTA"}})

• Filter WS errors only: ha_manage_addon(slug="...", path="/ws", websocket=True, python_transform="response = [m for m in response if 'ERROR' in str(m) or 'WARN' in str(m)]")

• HTTP subset: ha_manage_addon(slug="...", path="/flows", python_transform="response = [f['id'] for f in response]")

• Array-patch (Node-RED, rename a node): ha_manage_addon( slug="a0d7b954_nodered", path="/flows", array_patch={"operations": [ {"op": "patch", "id": "abc123", "patches": {"name": "New Name"}}, ]}, )

• Array-patch (Node-RED, replace one tab's nodes atomically): ha_manage_addon( slug="a0d7b954_nodered", path="/flows", array_patch={"operations": [ {"op": "delete_where", "field": "z", "value": "tab-id"}, {"op": "add", "item": {"id": "n1", "type": "inject", "z": "tab-id", ...}}, {"op": "add", "item": {"id": "n2", "type": "function", "z": "tab-id", ...}}, ]}, request_headers={"Node-RED-Deployment-Type": "full"}, )

• Custom request headers (proxy mode): ha_manage_addon(slug="...", path="/api/state", request_headers={"Accept": "text/plain"})

manage addon add-on configure settings options port network boot watchdog auto_update supervisor ingress proxy websocket api rest esphome nodered node-red frigate mosquitto mqtt zigbee2mqtt zigbee z-wave zwave appdaemon hacs studio code server file editor terminal ssh samba grafana influxdb deconz motioneye compile validate upload deploy firmware ota flash yaml device logs flows events stats