Docs / Concepts / Capabilities & pass-through

Capabilities & pass-through

Capabilities control high-impact actions such as restarting Home Assistant, controlling locks, writing automations, and reading logs. Start with a persona, then change individual capabilities only when needed.

How the modes work

Every capability holds one of three modes. Reading a mode in any code path goes through a single helper, so the pass-through interaction is always consistent.

confirm is only meaningful for the write, system, and irreversible capabilities; the read-tier capabilities are deny or allow only.

A pending approval stores the requested action so the admin can review it. For file and configuration.yaml writes, the before/after diff shown for review and the admin API responses are run through a secret redactor: values on sensitive-looking keys (password, api_key, secret, and similar) and any embedded access keys or URL credentials are replaced with <redacted>, while the structure of the change stays visible. The pending record itself keeps the raw tool arguments while the approval is queued, because an approved action has to re-run with the real content; so for write_file, set_yaml_config and patch_yaml_config the unredacted content can exist in .storage/phoenix_mcp while pending and for up to one hour after resolution. Terminal history is bounded to 500 records and seven days; raw arguments, diffs and results are cleared after one hour.

Compare all 30 capability flags

The capability flags

The pass-through column shows what happens under a pass-through access key: granted means pass-through turns it on for you, must enable means it stays off until you set it explicitly, even for pass-through access keys. Each row names the capability as it appears in the panel, with its API field id (used by the admin API) beneath.

Read and discovery

Capability	Enables	Pass-through
Automation traces cap_traces	Automation execution traces via get_automation_traces	granted
Broadcast cap_broadcast	Announcements via assist_satellite__HassBroadcast through assist satellite devices	granted
Configuration read cap_config_read	Read HA configuration data, the Energy dashboard configuration and its health check plus solar forecasts (get_energy_config, get_solar_forecast, both read-only), and the event-bus listener list, plus the MESA retrieval tools (mesa_query_profiles, mesa_get_profile, mesa_explain_profile, mesa_get_caller_context); it can also enable the read-only recognize_intent diagnostic without Search & discovery. See MESA.	granted
Camera image read cap_camera_read	Retrieve still images from explicitly permitted Home Assistant cameras through get_camera_image. This capability is denied by default, including for pass-through access keys.	denied
Diagnostics cap_diagnostics	get_system_health, check_ha_config, validate_automation_or_script, get_radio_network, get_radio_device, get_zigbee_groups, and, together with Radio management, scan_zigbee_topology; together with System log read, get_phoenix_diagnostics	granted
System log read cap_log_read	Read HA's bounded system-log ring (get_logs), permission-scoped event narrative (get_logbook), and, together with Diagnostics, Phoenix's more strongly scrubbed self-diagnostics (get_phoenix_diagnostics) and protected crash dumps (get_logs(source="fault_log")). A sensitive grant: third-party logs are free-form text.	must enable
Registry read cap_registry_read	Registry enumeration: list_areas, list_floors, list_zones, list_devices, get_device	granted
Search & discovery cap_search	Discovery and comprehension reads: search_entities, get_overview, describe_area, describe_entity, find_available_actions, get_relationships, and the read-only recognize_intent sentence diagnostic	granted
Service response data cap_service_response	Return response data from services that declare a response schema	granted
Template render cap_template_render	Render Jinja2 templates in a permission-scoped environment	granted

Write, system, and irreversible

Every capability in this group must be explicitly enabled, pass-through never grants them, and every one can be set to confirm.

Capability	Enables	Modes
Manage automations cap_automation_write	Create, edit, and delete automations. See the warning below.	deny / allow / confirm
Backup cap_backup	Create and list backups; restore is never exposed	deny / allow / confirm
Manage dashboards cap_lovelace_write	Create, edit, and delete dashboards; read and write view/card layouts; list the installed custom cards. Also lets get_relationships name the dashboards that use an entity; without it, dashboards are left out of that answer and reported as not searched	deny / allow / confirm
Filesystem access cap_filesystem	Read and write files under www/, themes/, custom_templates/	deny / allow / confirm
Restart or stop Home Assistant cap_restart	homeassistant.restart and homeassistant.stop	deny / allow / confirm
Manage helpers cap_helper_write	Create, edit, and delete helpers	deny / allow / confirm
Calendar write cap_calendar_write	Create, update, and delete events on writable calendars	deny / allow / confirm
Integration management cap_integration_write	List accessible integration entries; change safe title/preferences and user-controlled enabled state; reload supported entries; and remove entries through Home Assistant's integration-aware cleanup. Entry visibility is inherited from accessible owned entities and devices, while writes require complete entity WRITE plus explicit WRITE on every owned device. Lifecycle and removal actions also enforce inherited MESA safety and revalidate approved context. Phoenix MCP's own entry remains hidden. Also lets get_relationships name config-entry consumers; without it, they are reported as not searched.	deny / allow / confirm
Integration reconfiguration cap_integration_reconfigure	Submit reviewed credentials, hosts, and other values through an integration's official Home Assistant reconfigure flow. Requires complete entry WRITE and inherited MESA approval. Phoenix shows a redacted review rather than Home Assistant's form, does not support browser/OAuth or progress steps, and cannot automatically roll changes back. Also makes list_integrations available when Integration management is denied.	deny / allow / confirm
Integration log levels cap_log_control	Change or clear process-wide integration-aware logger overrides with set_integration_log_level. Also requires System log read. Timed runtime-only changes restore the exact prior setting when still current; INFO and DEBUG can consume disk and expose sensitive third-party output.	deny / allow / confirm
Physical control cap_physical_control	Lock, alarm, cover, and valve mutation services (lock.unlock, alarm_control_panel.alarm_disarm, cover.open_cover, valve.open_valve, and related), plus direct Zigbee2MQTT exposed-property fallback writes	deny / allow / confirm
ESPHome device YAML cap_esphome_yaml	Read and edit ESPHome device YAML in its own jail under esphome/, separate from cap_filesystem, plus validating and compiling it. Credentials are masked on read and frozen against change; secrets.yaml is never readable or writable. Compiling only builds a binary; putting it on a device is the separate capability below	deny / allow / confirm
ESPHome firmware flashing cap_esphome_flash	Install compiled firmware onto an ESPHome device over the air, replacing what it is running. Split from the capability above so an access key can author and verify firmware without being able to put it on hardware. A bad image can leave a device unreachable until it is reflashed over a cable, so Confirm is the intended setting; only the ESPHome persona grants it at all	deny / allow / confirm
Edit raw YAML cap_yaml_edit	Edit configuration.yaml and the YAML files it loads through an !include, either one key or list entry at a time (patch_yaml_config, which leaves the rest of the file untouched and shows you just that part for approval) or a whole file (set_yaml_config), and apply the core config-reload services (automation.reload, script.reload, scene.reload, and the other domain reloads)	deny / allow / confirm
Manage entity registry cap_registry_write	Edit an entity's user-controlled registry metadata (name, icon, area, device class, enabled/hidden state, labels, categories, aliases, and same-domain entity ID) and delete stale registry entries (set_entity, delete_entity). Rename and delete also enforce the entity's inherited MESA profile	deny / allow / confirm
Manage Energy dashboard cap_energy_write	Change which statistics feed the Energy dashboard: repoint an entry at a different statistic, start or stop tracking an individual device, rename an entry, and set, create or remove the grid, solar, battery, gas or water source (edit_energy_config). Reading the configuration, its health check and the solar forecast needs Configuration read instead. Each call changes one addressed part; Phoenix MCP never sends Home Assistant a whole Energy configuration, so the entries you did not touch cannot be lost. Every change is recorded in Changes and can be rolled back.	deny / allow / confirm
Radio management cap_radio_write	Manage the Zigbee network via Zigbee2MQTT or ZHA: actively scan the scoped topology, open it for pairing, re-interview devices, remove devices, bind or unbind devices, change Zigbee2MQTT reporting, change converter options, and change one direct-fallback exposed property (scan_zigbee_topology, permit_zigbee_join, reconfigure_zigbee_device, set_zigbee_binding, configure_zigbee_reporting, set_zigbee_device_options, set_zigbee_device_property, remove_zigbee_device, create_zigbee_group, set_zigbee_group_members, remove_zigbee_group). Topology scans also require Diagnostics and may temporarily reduce mesh responsiveness. Group changes, binding and direct property writes also require Physical control and inherited MESA approval. Phoenix MCP assumes the default Zigbee2MQTT base topic (zigbee2mqtt); a Z2M install using a custom base topic is not currently supported.	deny / allow / confirm
Manage scenes cap_scene_write	Create, edit, and delete scenes	deny / allow / confirm
Manage scripts cap_script_write	Create, edit, and delete scripts. See the warning below.	deny / allow / confirm
Manage blueprints cap_blueprint_write	Create, edit, and delete blueprints. Also requires the matching automation or script capability. See the warning below.	deny / allow / confirm

Personas

You rarely set capabilities one at a time. A persona is a named preset that fills in the entire matrix at once, and choosing one applies the whole set, not just a label. For ordinary personas, adjusting capabilities changes the label to Custom unless the combination matches another preset. Home Companion is different: it retains an enforced, fixed tool boundary until you choose another persona.

Compare the default capability settings

All capabilities omitted from Allow and Confirm default to Deny. These are initial settings when you select the persona; saved overrides still apply. Home Companion also retains its separate household tool boundary.

Persona	Allow	Confirm
Home Companion	Registry read, Search & discovery	Physical control
New user	Configuration read, Registry read, Search & discovery, Service response data, Template render	Physical control
Read-only observer	Automation traces, Configuration read, Diagnostics, Registry read, Search & discovery, Service response data, System log read, Template render	None
Voice assistant	Broadcast, Configuration read, Registry read, Search & discovery, Service response data, Template render	Physical control
Automation builder	Automation traces, Broadcast, Calendar write, Configuration read, Diagnostics, Manage automations, Manage blueprints, Manage helpers, Manage scenes, Manage scripts, Registry read, Search & discovery, Service response data, System log read, Template render	Physical control, Restart or stop Home Assistant
Power user	Automation traces, Broadcast, Calendar write, Configuration read, Diagnostics, Manage automations, Manage blueprints, Manage helpers, Manage scenes, Manage scripts, Registry read, Restart or stop Home Assistant, Search & discovery, Service response data, System log read, Template render	Backup, Integration management, Integration reconfiguration, Manage dashboards, Manage Energy dashboard, Manage entity registry, Physical control, Radio management
Home administrator	Automation traces, Broadcast, Calendar write, Configuration read, Diagnostics, Manage automations, Manage blueprints, Manage helpers, Manage scenes, Manage scripts, Registry read, Search & discovery, Service response data, System log read, Template render	Backup, Edit raw YAML, ESPHome device YAML, Filesystem access, Integration management, Integration reconfiguration, Manage dashboards, Manage Energy dashboard, Manage entity registry, Physical control, Radio management, Restart or stop Home Assistant
Dashboard designer	Configuration read, Manage dashboards, Registry read, Search & discovery, Template render	Filesystem access, Manage Energy dashboard
Maintenance / backups	Automation traces, Backup, Configuration read, Diagnostics, Registry read, Search & discovery, Service response data, System log read, Template render	Manage entity registry, Radio management, Restart or stop Home Assistant
ESPHome devices	Configuration read, Diagnostics, Registry read, Search & discovery, Service response data, System log read	ESPHome device YAML, ESPHome firmware flashing

Home Companion

Home Companion is a persona for household tasks in Agent Chat and Voice. An external client sees a single tool, home_request, which takes a complete plain-language task such as "Turn off the kitchen ceiling lights; leave the counter lights on". Phoenix works out the steps itself using a fixed, household-only toolkit. It runs on the provider and model chosen in Voice settings, with this access key's own permissions (Voice itself does not need to be enabled). Your request and the permitted tool results are sent to that provider. It uses the same permission tree, capabilities, MESA and approvals as every other access key.

Home Companion has no memory between calls: each home_request must carry the whole task, including the action, target and restrictions. If a target is ambiguous, for example "turn those lights off", it asks you to try again with the complete request. Replies are built from what Home Assistant actually reported. A completed control means the command was accepted; Phoenix then checks the resulting state where it can, and verification says whether it did. If the state is unverified, check it in Home Assistant rather than resending. Never retry an outcome_unknown action automatically; unresolved actions block new requests until you review them under Needs attention. Configuration, authoring, filesystem, camera, lock and alarm tools are not available through this persona.

Automation and script write

Manage automations and Manage scripts are elevated-trust capabilities. Enable them only for clients you fully control.

• All or nothing. There is no per-entity scoping for these tools. The flag is on or off.
• Triggered actions run outside Phoenix MCP. An automation created through Phoenix MCP is run by Home Assistant's own engine, under its own context. Phoenix MCP's permission checks do not apply to what a triggered automation does.
• Net effect. an access key with a narrow entity scope but this flag enabled could, through a crafted automation, indirectly control entities it cannot reach directly. Treat the flag as broad HA access. See Indirect control risk for the full explanation and an example.
• Manage blueprints is dual-gated, and its edits reach further than they look. cap_blueprint_write alone is not enough: a blueprint write also requires the capability for the domain it targets, so an access key cannot rewire scripts through a script blueprint while script write is denied. Beyond that, editing a blueprint makes Home Assistant reload every automation or script built from it, while those entities' own configurations do not change at all, so the change leaves no trace in their history. The approval names the entities that will be reloaded; read that list. Deleting is refused by Home Assistant while anything still uses the blueprint.

Pass-through mode

Pass-through access keys skip the three-level permission check and have GREEN access to every entity, or only to the entities exposed to Assist when Limit to Assist-exposed entities is on. They are for trusted tools where maintaining a full tree is impractical.

Pass-through does not bypass:

• The phoenix_mcp domain blocklist and sensitive-attribute scrubbing
• Rate limiting
• Any capability in the write, system, and irreversible group (each must still be enabled)
• System log read and Camera image read
• A capability set to confirm, which is gated even under pass-through

All other read-tier capabilities are granted by pass-through. Use pass-through only for tools you fully control.

Pass-through and MESA

Pass-through bypasses Phoenix MCP's per-access-key tree, but it does not bypass MESA, the per-entity safety layer that always runs last (the MESA page covers it in full). When MESA is active, a pass-through access key's writes are still governed by each entity's MESA control_mode. In effect, pass-through hands entity gating to MESA with Phoenix MCP's per-access-key permissions out of the way.

In practice this pattern is niche, for two reasons:

• The access key and open-read costs above apply in full; every agent sees the entire home.
• MESA does not provide general read privacy. Camera images have an explicit privacy check; other reads use Phoenix scope and scrubbing. Unprofiled lights are autonomous, locks and alarm panels are prohibited, and every other domain requires confirmation under enforced mode. Advisory mode mostly warns about these control limits. Use the access key tree for least privilege and configure enforced profiles for restrictions that must block.

MESA can be made fail-closed for writes with deployment defaults and enforced mode, but reads stay open and the context cost remains. For most deployments a scoped access key plus MESA is the better combination: the tree scopes what the agent sees (cheap context and read security) and MESA governs write nature on top.