Add isolated physical network access for apps

[agners]

Proposed change

Implements the first phase of isolated physical network access: users can assign apps that use host networking an isolated endpoint on a physical network interface instead. The app then runs in bridge mode with its own IP and MAC address on the selected interface (Docker macvlan), providing full multicast/mDNS support and interface selection on multi-homed hosts while restoring the isolation that host networking gives up.

Key design points:

• Dual attachment: the container stays attached to the internal hassio network, so ingress, API proxy, DNS plug-in and inter-app communication work unchanged. The macvlan endpoint provides the physical network presence and wins the default route via GwPriority.
• Shared networks per interface: Docker allows only one macvlan network per parent interface, so networks (hassio-macvlan-<iface>) are a shared resource derived from the host interface configuration (subnet/gateway via NetworkManager), created on demand, recreated on drift and garbage collected when no app references them.
• Static IPv4, stable MAC: the user assigns a static IP (validated against subnet, host/gateway addresses and other apps); the MAC is pinned with the IP-derived scheme older engines used, since Docker 28 assigns random MACs per endpoint creation. Both are exposed in the app info API so users can set up router/firewall rules before the first start.
• IPv6 via SLAAC: external networks have IPv6 enabled (engine-allocated ULA satisfies the driver, real addressing comes from router advertisements). Endpoints set accept_ra=2 and accept_ra_rt_info_max_plen=64 so RFC 4191 routes announced by Thread border routers reach the container.
• Graceful degradation: if the endpoint cannot be set up at start (interface gone, subnet changed), the app falls back to host networking and a network_isolation_failed issue is raised; a scheduled resolution check detects drift. The fallback is blocked when the Docker gateway is unprotected, since that protection does not apply to isolated apps (their traffic bypasses the host network namespace, which also lifts the security rating penalty for host networking).

The feature requires Docker >= 28 (for GwPriority and per-endpoint sysctls) and is gated accordingly; existing installations and apps are unaffected unless a user opts in per app.

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New feature (which adds functionality to the supervisor)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Additional information

• This PR fixes or closes issue: fixes #
• This PR is related to issue: Supervisor isolated physical network access/macvlan support architecture#1034
• Link to documentation pull request:
• Link to cli pull request:
• Link to client library pull request:

Checklist

• The code change is tested and works locally.
• Local tests pass. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.
• I have followed the development checklist
• The code has been formatted using Ruff (ruff format supervisor tests)
• Tests have been added to verify that the new code works.

If API endpoints or add-on configuration are added/changed:

• Documentation added/updated for developers.home-assistant.io
• CLI updated (if necessary)
• Client library updated (if necessary)

[agners]

This is AI assisted based on the design and discussion in home-assistant/architecture#1034. Currently it allows Apps which use host network to isolate.

I've tested this with the ESPHome and Matter App. The Matter App required a small tweak in the startup script to not fetch the primary interface from Supervisor (rather use the ip route based fallback). With this tweak I was able to communicate to Thread devices behind a BR running on a different host, which means the Matter app's isolated network processed IPv6 ND RIO correctly 🎉 .

I think I'd prefer to make IPv4 completely optional. Currently the MAC address is derrived from the IPv4 address, which seems to be a design which Docker used previously. However, I think I'd rather prefer it to just assign a random MAC.

I am also not sure if we maybe should only support ipvlan. While macvlan is strictly more isolated, it seems not to work with WiFi really. If ipvlan gives all the isolation needs we have, maybe we can simply default to it instead 🤔

[Copilot]

Pull request overview

Adds the first phase of “isolated physical network access” for Supervisor-managed apps by allowing host-network apps to instead attach an isolated endpoint on a physical interface (Docker macvlan), while keeping the internal hassio network attachment for Supervisor ingress/DNS/inter-container connectivity.

Changes:

• Introduces external physical network management (DockerExternalNetworks) and support for attaching extra network endpoints to containers at start.
• Adds app-level network isolation configuration (schema + persistence), API support (options + info fields), and host-interface capability reporting.
• Adds a new resolution issue/check (network_isolation_failed) plus test coverage across API, docker, apps, and resolution layers.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/resolution/check/test_check_app_network_isolation.py	Adds tests for the new resolution check behavior.
tests/docker/test_external_network.py	Adds unit tests for external network create/ensure/connect/gc logic.
tests/docker/test_app.py	Adds integration-style tests for isolated run path and fallback behavior.
tests/conftest.py	Wires docker.external_networks.coresys in the test CoreSys fixture.
tests/apps/test_network_isolation.py	Tests schema validation, persistence round-trip, and security rating interaction.
tests/apps/test_app.py	Adjusts mocks to avoid false-truthy persisted isolation config.
tests/api/test_apps_network_isolation.py	Adds API tests for setting/clearing/validating isolation options.
supervisor/validate.py	Adds ipv4_address() validator helper for schema normalization.
supervisor/resolution/const.py	Adds IssueType.NETWORK_ISOLATION_FAILED.
supervisor/resolution/checks/app_network_isolation.py	New check to detect drift/broken assigned isolation endpoints.
supervisor/exceptions.py	Adds API error types for isolation validation failures.
supervisor/docker/manager.py	Adds support for connecting extra (external) network endpoints during container start.
supervisor/docker/external_network.py	New external network manager: ensure/recreate/connect/gc for per-interface macvlan networks.
supervisor/docker/const.py	Adds ExternalNetworkDriver, NetworkIsolationConfig, and ExtraNetworkEndpoint types.
supervisor/docker/app.py	Implements isolated endpoint setup + fallback logic and ensures internal IP reporting stays correct.
supervisor/const.py	Adds new constants used by network isolation config/persistence.
supervisor/apps/validate.py	Adds persisted user schema for network_isolation.
supervisor/apps/utils.py	Adjusts security rating penalty so host-network apps with isolation don’t get penalized.
supervisor/apps/model.py	Adds network_isolation property to the model interface (default None).
supervisor/apps/manager.py	Updates boot gating so isolated apps are not blocked by Docker gateway firewall state.
supervisor/apps/app.py	Adds persistence for isolation config, derived external MAC exposure, and gc on uninstall.
supervisor/api/network.py	Exposes per-interface network_isolation_capable flag.
supervisor/api/const.py	Adds API attribute constants for isolation info/availability/mac.
supervisor/api/apps.py	Adds options validation + info fields for network isolation and triggers external network gc.

[github-actions]

There hasn't been any activity on this pull request recently. This pull request has been automatically marked as stale because of that and will be closed if no further activity occurs within 7 days.
Thank you for your contributions.