Manage App (add-on)

Manage a Home Assistant App (formerly known as an add-on, and this tool as ha_manage_addon) — 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_app(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).

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), which is what summarize is for. INFO/WARNING/ERROR/exit lines always pass through it, and pagination via message_offset / message_limit works on the raw collected list before summarize runs.

• python_transform runs after slicing and summarize, and before the response size cap, so it can narrow an oversized response back under the limit. What response binds to and what may be done to it is on the parameter itself. Only the interaction is here: undecodable WebSocket frames arrive as ANSI-stripped strings, and elision markers as {"elided": N, "note": "..."} dicts when summarize ran.

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_app(slug="...", action="install")

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

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

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

• Set add-on option: ha_manage_app(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_app(slug="...", auto_update=False)

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

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

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

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

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

• ESPHome read a device's YAML (WS one-shot): ha_manage_app(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_app(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_app(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_app(slug="...", path="/flows", python_transform="response = [f['id'] for f in response]")

• Array-patch (Node-RED, rename a node): ha_manage_app( 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_app( 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_app(slug="...", path="/api/state", request_headers={"Accept": "text/plain"})

manage app apps 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