Use .Internal TLD instead of .local

[ryan-winkler]

[Update]: Based on the feedback below, I am pivoting this request! I originally suggested replacing .local entirely, but completely blanked on the fact that HA relies on mDNS for its zero-config plug-and-play experience. .local absolutely needs to stay the default for that. I've updated the request below to focus on adding official support for .internal alongside it for traditional unicast DNS setups.

Describe the feature

Home Assistant OS should officially support and document the .internal TLD for users running locally-configured DNS zones, alongside the existing .local default used for mDNS.

On 29 July 2024, the ICANN Board passed Resolution 2024.07.29.06, permanently reserving .INTERNAL from the DNS root zone for private-use applications:

"The Board reserves .INTERNAL from delegation in the DNS root zone permanently to provide for its use in private-use applications. [...] Network administrators unable to use a name in the global DNS for their private, or internal, uses can now safely use .INTERNAL."

Additionally, IETF draft-davies-internal-tld-05 formalizes .internal as the DNS equivalent of RFC 1918 private IP ranges. It explicitly distinguishes .internal from .local:

"The 'local' namespace (RFC 6762) is reserved for use with the multicast DNS protocol. [...] It is expected 'internal' will be used for applications where names are specified in locally-configured zones."

While Home Assistant relies on mDNS (and therefore .local) for its zero-config discovery, a massive portion of the community runs traditional local unicast DNS (Pi-hole, AdGuard, pfSense, etc.). For these setups, .internal is now the global standard.

Proposed changes:

• Keep homeassistant.local as the default for mDNS / zero-configuration setups so out-of-the-box discovery doesn't break.
• Add an option in the HAOS network settings to easily broadcast/register a .internal hostname (e.g., homeassistant.internal) to local DHCP/DNS servers.
• my.home-assistant.io suggests or allows .internal as a valid local domain option for those not using mDNS.
• Documentation updates to reference .internal as the recommended domain for users configuring their own local DNS, rather than encouraging them to fight with .local in unicast DNS.
• Also consider adding a short alias, such as https://ha.internal/

Use cases

While .local is perfect for fresh installs, it is strictly reserved for multicast DNS (RFC 6762). On Linux (Avahi), macOS (Bonjour), and some Windows configurations, the OS intercepts .local queries and routes them through mDNS rather than standard DNS — causing resolution delays, timeouts, or outright failures when HA is behind a proper DNS server.

my.home-assistant.io currently suggests http://homeassistant.local:8123 as the default URL. While great for mDNS, it reinforces the usage of a TLD that was never designed for unicast DNS.

Home Assistant is one of the largest self-hosted platforms in the world. Adopting .internal as a supported secondary standard would align HA with the ICANN/IETF standard, reduce DNS resolution issues for homelabbers, and help drive broader ecosystem adoption of the TLD that internet governance bodies spent years establishing for exactly this use case.

Current workarounds

I run my own DNS (MikroTik + step-ca) and have already migrated all my services to .internal. But Home Assistant's defaults, documentation, and my.home-assistant.io all still primarily reference .local, creating friction. I have to manually override the suggested URLs and mentally translate every .local reference in the docs.

Anything else?

Key references:

• ICANN Board Resolution 2024.07.29.06 — permanently reserves .INTERNAL for private use.
• IETF draft-davies-internal-tld-05 — "A Top-level Domain for Private Use"
• SSAC SAC113 — the original advisory that started this process.

This is not a speculative request — .internal is an approved, permanently reserved TLD backed by both ICANN and the IETF. Providing a hybrid approach (mDNS for beginners, .internal for custom DNS) would make HA a leader in adopting the standard.

[mik-laj]

I'm not a network expert, but do you think this roadmap item: HTTP server configuration through the UI (removing port 8123) #47
is related to your proposal? I just think that if we want to change the URL it might be easier to make two changes at once rather than migrate users twice.

[ryan-winkler]

It's definitely part of the reason why I would want to use my own TLD, so I would say highly related and complementary to each other for sure

[mik-laj]

Home Assistant uses configured DNS zones, not mDNS peer discovery.

Can I get the source for this information? I thought HA uses mDNS so it doesn't have to configure anything on the network to make this address resolvable.

[Entropy512]

Home Assistant uses configured DNS zones, not mDNS peer discovery

This is wrong. HA uses mDNS - which is why homeassistant.local functions in environments with no cooperation whatsoever from any DNS server. As such, .internal is NOT the correct TLD for this use case, and in fact the documentation that you cite explicitly states that .local IS the correct TLD for this use case.

Can I get the source for this information? I thought HA uses mDNS so it doesn't have to configure anything on the network to make this address resolvable.

You are most assuredly correct. This is most obvious by the inability to use homeassistant.local from operating systems that do not support mDNS (such as Android)

[ryan-winkler]

@Entropy512 Yep, you're 100% right. I completely blanked on the mDNS requirement for fresh installs since I'm so used to routing everything through my own DNS.
I'll update my request: keep .local for mDNS, but add a paved path/UI option to register a .internal domain with local DNS/DHCP for those of us running homelabs. Thanks for keeping me honest there!

[mik-laj]

• Add an option in the HAOS network settings to easily broadcast/register a .internal hostname (e.g., homeassistant.internal) to local DHCP/DNS servers.

How would you like this to happen? How do we authenticate to this DNS server so we can add entries?

my.home-assistant.io suggests or allows .internal as a valid local domain option for those not using mDNS.

.internal TLD is allowed.

Documentation updates to reference .internal as the recommended domain for users configuring their own local DNS, rather than encouraging them to fight with .local in unicast DNS.

Maintaining your own DNS server for internal use at home is not something we recommend at all. mDNS is better suited for this situation. DNS is only needed if you have external access. Besides, I don't see the value in recommending .internal TLD if the application would be accessible via .local TLD. The same service available at different addresses is a potential source of problems .e. g. double login

Also consider adding a short alias, such as https://ha.internal/

If needed, users can add an alias. For new users, the full name is easier to use than acronyms. And those who have been using HA for a while now have the address saved in their browser/app.

Overall, I see little value in implementing these suggestions, as they affect a very niche group of people. And those already affected by this problem are savvy enough to create workarounds themselves. For example, if you can install a local DNS server, you certainly already know how to add entries to it manually. Adding this feature only adds complexity and maintenance cost, but I doubt it will be actually used.

[mik-laj]

Why do you need to maintain a local DNS server at home?

[Entropy512]

Why do you need to maintain a local DNS server at home?

Android clients, lower latency than mDNS, ability to access multiple services via reverse proxy

That said I'm fairly certain all of this is outside of the scope of HA. I had refrained from commenting until I could confirm/retest but I'm 90% certain that unlike many services (Cockpit, Universal Media Server come to mind) HA doesn't care what URL was used to access it. Point DNS to it and go, configuring that DNS server is outside of the scope of HA. I know for a fact HA doesn't care if you access it via IP instead of homeassistant.local (my current Android workaround). I'll confirm this tonight.

[Entropy512]

I just ran a test to confirm, and as I expected, HA doesn't care what domain was used to access it. So point homeassistant.internal to your HA instance and that's all. Configuring DNS is outside of the scope of HA. There's no way for HA to automatically do this since there are countless different DNS implementations each with their own method of configuration - which is why mDNS is the primary method of finding an HA instance.