First-class ingress-aware embedding for Lovelace iframe/webpage cards

[dankarization]

This is a broader follow-up to the old Grafana-specific ingress iframe thread. The problem still exists in 2026 and also affects current add-ons such as Music Assistant and Zigbee2MQTT.

Proposal: First-class ingress-aware embedding for Lovelace iframe/webpage cards

Problem statement

Home Assistant add-ons that rely on Supervisor ingress do not embed reliably inside Lovelace when rendered through the built-in iframe / webpage card.

In practice, the add-on itself is healthy and reachable, but the embedded UI may fail to load, show 401 / No valid ingress session, or get stuck in an infinite loading state until the user first visits the add-on through its normal sidebar/panel route.

This is still affecting real users in current versions of Home Assistant and is not limited to Grafana:

• Grafana dashboards embedded in Lovelace
• Zigbee2MQTT links using ingress-based frontend URLs
• Music Assistant embedded for non-admin / kiosk / dashboard-only users

The current situation forces users into workarounds:

• visit the add-on panel first to "warm up" ingress
• bypass ingress and expose a direct port
• add hidden pre-auth cards/views
• install custom cards such as ha-addon-iframe-card

That is a bad UX and pushes users away from the built-in dashboard primitives.

Current behavior

Today, the standard Lovelace iframe / webpage card behaves like a generic iframe wrapper:

• it accepts a URL
• it renders the iframe
• it does not manage ingress session lifecycle

For ingress-backed add-ons, this creates a mismatch:

1. the add-on expects a valid Supervisor ingress session
2. the Lovelace card loads the URL without ensuring such a session exists
3. the iframe fails unless the session was already created elsewhere

Related navigation behavior also remains awkward:

• direct panel routes may work, but they are not always suitable for kiosk/dashboard-only users
• ingress-based URLs with fragments or router-sensitive paths have historically hit frontend routing edge cases
• users embedding add-on UIs in dashboard flows often need a clean "open inside dashboard and go back" experience, not a sidebar detour

Desired behavior

Home Assistant frontend should provide a first-class way to embed ingress-backed add-on UIs inside Lovelace without custom cards.

Expected behavior:

1. If a Lovelace card points to an ingress-backed add-on, the frontend should transparently ensure a valid ingress session exists before the iframe is loaded.
2. While the card remains mounted, the frontend should keep that session valid as needed.
3. The behavior should work equally for admin and non-admin users, subject to the add-on's own access rules.
4. Users should not need to visit the sidebar panel first.
5. Users should not need to expose direct ports or weaken security to make embedding work.

Minimal frontend/core design

Option A: Upgrade the existing webpage/iframe card

Teach the built-in card to recognize ingress-backed targets, for example:

• /api/hassio_ingress/...
• add-on slugs / ingress routes
• homeassistant://... ingress-style URLs where applicable

When such a target is detected:

1. call Supervisor ingress session creation before initial load
2. store/reuse that session in the frontend
3. validate/refresh the session while the card is active
4. then load the iframe

This is the smallest UX change because it preserves the existing Lovelace card concept.

Option B: Introduce a dedicated ingress-aware Lovelace card

Add a new first-party card, for example:

• type: addon-webpage
• type: ingress-webpage

This avoids overloading the generic iframe card and makes the special behavior explicit.

Possible config:

type: ingress-webpage
addon: d5369777_music_assistant
path: /
aspect_ratio: 150%

Advantages:

• clearer mental model
• easier docs
• lower risk of surprising behavior for generic external URLs

Shared implementation note

The backend building blocks already exist conceptually: the missing piece is mainly frontend orchestration of ingress session lifecycle around embedded usage.

Compatibility / risk notes

Security

This proposal should not bypass ingress or weaken auth.

It should only automate the same authenticated ingress session flow that already works when users open the add-on through the intended panel route.

Scope boundaries

This proposal is about ingress-backed add-ons embedded in Lovelace.
It is not about arbitrary third-party iframes on the open web.

Backward compatibility

If implemented as detection inside the existing webpage card, care is needed to avoid changing behavior for normal external URLs.

That is why a dedicated first-party ingress-aware card may actually be safer.

UX edge cases

Even with ingress session handling fixed, dashboard-only flows still need good navigation patterns.
That is separate from session creation itself, but worth acknowledging in docs/examples:

• kiosk users may need a built-in back action
• mobile users may not see the sidebar
• full-panel add-on experiences inside dashboards are valid use cases

Why this matters

This is no longer just an old Grafana issue.
It affects current real-world dashboard use cases with modern add-ons like Music Assistant.

The existence of successful community workarounds such as ha-addon-iframe-card is strong evidence that users need this behavior and that the missing functionality is small but important.

The question is not whether ingress-backed embedding is useful.
Users are already doing it.

The question is whether Home Assistant wants this solved natively in frontend/core, or to keep pushing users toward custom cards and brittle workarounds.

Suggested ask to maintainers

Would the frontend team accept either:

1. a proposal to make the built-in webpage card ingress-aware for add-on URLs, or
2. a small first-party ingress-aware Lovelace card with explicit Supervisor session handling?

If yes, I can turn this into a narrower implementation proposal with:

• exact detection rules
• session lifecycle expectations
• suggested YAML/API shape
• risk boundaries
• test scenarios based on Grafana, Zigbee2MQTT, and Music Assistant