Networking and remote access

Why remote access is so easy to get wrong

Appendix A compares the four remote-access options and helps you choose one. This chapter explains how to implement that choice—and what can go wrong.

The stakes are higher here than in the preceding chapters. A broken automation might leave a light off. A broken remote-access setup can expose your home to the entire internet.

Home Assistant can reveal occupancy in every room, door and window states, camera feeds, smart-lock controls, and the times you leave and return. Someone who gains access has effectively copied your house key. That is why this chapter follows a deliberate order: stabilize the local network before configuring external access. Many people skip the first step, then find that even access from home is unreliable.

By the end of this chapter, you will be able to:

• Reserve a permanent IP address for the Home Assistant host on your router
• Understand why homeassistant.local works sometimes, why it may fail, and what to use instead
• Choose one of four remote-access options and complete its setup
• Understand the two reverse-proxy settings required for successful sign-in
• Recognize what you must never do, including the common advice to “forward port 8123”

LAN basics: IP, DHCP, and why the address must stay fixed

The easiest analogy is an apartment building's street addresses.

Your router is the building manager. It gives every device connected by Wi-Fi or Ethernet—a phone, laptop, television, or Home Assistant host—an address such as 192.168.1.37. This is an IP address.

The process of assigning addresses is called DHCP. It happens automatically, which is convenient, but has one crucial property: the address is leased, not owned.

A lease expires. Your Home Assistant host may be 192.168.1.37 today, receive 192.168.1.52 after restarting following a power outage, and leave .37 to your new robot vacuum.

What breaks when the address changes

The rule is simple: the Home Assistant host must have a fixed IP address. This is not an advanced technique; it is an essential prerequisite.

Two ways to fix an IP address—and which to choose

Learn to identify the MAC address

Before making a reservation, the router must identify which device is Home Assistant. It does so by its MAC address—an identifier assigned to each network interface, such as DC:A6:32:1B:4E:F0.

The IP address can change, but the MAC address does not. A reservation therefore tells the router: “Whenever the device with this MAC address requests an address, always assign 192.168.1.37.”

Hands-on: reserve the host's IP and verify the network page

1. Find the host's IP and MAC addresses

   Go to Settings → System → Network. This page lists the host's wired and wireless network interfaces and their current IP addresses. Record the relevant IP.

   The MAC address may not appear here. The easiest place to find it is the router's connected-device list. Open the router's administration page and find the device named homeassistant, or the device whose IP matches the one you just recorded. Its MAC address should appear alongside it. You will already be in the right place for the next step.

2. Sign in to the router's administration page

   The router's administration address is often 192.168.1.1 or 192.168.0.1, and it may be printed on a label underneath the router. The credentials may be there too. If you have never changed the default password, change it now; every later security measure depends on it.

3. Find the DHCP reservation page

   Manufacturers use different names, making this the most difficult step. Look for Reserved Address, DHCP Reservation, Address Reservation, Static DHCP, Static Lease, or Fixed Assignment. It is usually under “Local Network / LAN” or “Advanced Settings → DHCP Server.”

   If you cannot find it, search for your router model plus “DHCP reservation.” Even inexpensive home routers usually support the feature, although it may be buried in the interface.

4. Add a reservation

   Enter the MAC address from step 1 and choose the IP to assign. Pick something memorable and unlikely to collide, such as 192.168.1.10. Enter “Home Assistant” in the description field; your future self will appreciate it.

   Save the setting. Some routers must restart before it takes effect.

5. Renew the host's address

   The host will not switch immediately after you create the reservation; its old lease remains valid. The quickest method is to restart the Home Assistant host (Settings → System, open the power menu in the upper-right corner, then choose Restart system), or disconnect and reconnect its Ethernet cable.

6. Verify the result

   After the restart, return to Settings → System → Network and confirm that the displayed IP is the address you reserved. Open Home Assistant at the new address and sign in. Replace your old bookmark with this URL.

7. Set the internal URL

   On the same Settings → System → Network page, find the Internal URL and External URL fields. Set the Internal URL to the address you reserved, for example http://192.168.1.10:8123.

   For both fields, stop after the port; do not append a path. A value such as http://192.168.1.10:8123/lovelace can cause features that generate links to produce malformed URLs.

Understanding homeassistant.local and port 8123

The technology behind .local addresses is mDNS

When you first installed Home Assistant, the instructions may have told you to open homeassistant.local:8123. It worked even though you had not configured a DNS server at home. How did the computer know where that name led?

The answer is mDNS (Multicast DNS). In plain language, it works like calling out to everyone in a room:

1. Your computer sends a multicast query across the LAN

   “Is any device named homeassistant?” Every device on the same network segment can hear the query.

2. The Home Assistant host responds

   “That's me. I am at 192.168.1.10.”

3. Your computer records the answer and connects directly

   No central server is required. Apple calls its implementation Bonjour; Linux commonly uses Avahi. Both implement the same underlying concept.

Why it often fails

Several conditions can block that local multicast exchange:

Port 8123 and the change in 2026.8

If the IP is a street address, a port is the extension number at that address. One host can run many services at once, and ports distinguish them. Home Assistant has traditionally used 8123, hence http://192.168.1.10:8123.

Version 2026.8 introduced an important change:

The release notes are explicit: nothing changes on an existing system, and you do not need to take any action. The new default affects only fresh Home Assistant OS installations. The :8123 found in most online guides is therefore probably still correct for your system.

Why change it? Port 80 is the default for HTTP, so browsers add it automatically. The result is a shorter URL and one less obstacle for beginners.

Which of the four options suits you?

Appendix A introduces all four options. The table below is a decision aid: choose one, then proceed to its implementation section.

Choose in thirty seconds

• You want the simplest setup, use Alexa or Google, and wish to support official development → Nabu Casa. Home Assistant documentation describes it as the simplest and most secure option for most people.
• Only you and a partner need access, you do not need a cloud voice assistant, and you want a free, secure option → Tailscale. It offers the strongest isolation.
• You already own a domain, want a polished custom URL, and need easy access for family → Cloudflare Tunnel.
• You want to learn networking, have a fixed or relatively stable public IP, and can devote a weekend → DDNS + reverse proxy.

Option 1: Home Assistant Cloud (Nabu Casa)

This subscription service is operated by the organization behind Home Assistant. Revenue directly supports development of Home Assistant, ESPHome, Z-Wave JS, and related projects. It is both the easiest option and the most direct way to fund the ecosystem.

What it does

Your host establishes an outbound connection to Nabu Casa's servers. External requests then travel through that existing connection. You do not open any inbound port on the router. This is why the service works behind CGNAT and remains unaffected when your public IP changes.

Setup

1. Find the cloud settings

   Go to Settings → System → Network. Under “Home Assistant URL,” find the Internet section and enable “Use Home Assistant Cloud.” You can also use Settings → Home Assistant Cloud; both routes lead to the same place, so use whichever appears in your version.

2. Register or sign in

   Register a Nabu Casa account with your email address. This is separate from your local Home Assistant account. You can begin the one-month free trial without paying first.

3. Enable remote access

   After signing in, enable the remote-control switch. Home Assistant assigns you a permanent URL containing a long identifier followed by .ui.nabu.casa, such as https://abcd1234-ef56-7890-abcd-ef1234567890.ui.nabu.casa.

   It is not memorable, but it is unique, stable, and protected by HTTPS.

4. Save the URL in the mobile app

   Open the Companion App installed in Chapter 7. In the app settings, enter this address as the External URL. Keep the local IP as the Internal URL. The app will choose the appropriate address for the current network.

5. Test

   Turn off Wi-Fi on your phone, use mobile data only, and open the app. If you can sign in, setup is complete.

Option 2: Cloudflare Tunnel

The underlying idea matches Nabu Casa: your host initiates an outbound connection, so no inbound port is opened. Cloudflare operates the service, and it uses your own domain, allowing a polished custom URL.

Requirements

Setup

1. Move the domain's DNS to Cloudflare

   Add your domain in the Cloudflare dashboard. Cloudflare provides two nameservers. At the registrar where you bought the domain, replace the existing nameservers with those two values. Propagation may take a few minutes or several hours.

2. Add the third-party app repository

   Cloudflared is not included in the default repository. Go to Settings → Apps (“Add-ons” in older versions) → Install app → the three-dot menu in the upper-right corner → Repositories. Paste https://github.com/homeassistant-apps/repository, then select Add.

   Older guides may show brenner-tobias/addon-cloudflared. That repository now states that the project moved to the homeassistant-apps organization, so use the current address above. Chapter 20 explains the complete process for third-party repositories.

3. Install and configure Cloudflared

   After adding the repository, find the new Cloudflared card and install it. On its configuration tab, enter the external address you want, such as ha.yourdomain.com.

4. Start the app and authorize it

   Start the app, then open its log tab. The log displays an authorization URL. Open it in a browser, sign in to Cloudflare, and authorize the tunnel for your domain. Beginners often miss this step because the prompt appears in the log.

5. Configure trusted proxies

   Traffic enters Home Assistant through the app container, which acts as an additional proxy layer. Home Assistant blocks those requests unless the proxy is explicitly trusted. Typical symptoms are a page that opens but will not accept your sign-in, or a full-page 400 Bad Request. Follow the “Trusted proxies” section below.

6. Test

   Turn off your phone's Wi-Fi and open https://ha.yourdomain.com over mobile data.

Option 3: VPN (Tailscale or WireGuard)

The first two options put Home Assistant securely on the internet. A VPN takes a different approach: it brings your phone into your home network.

Think of the first two options as a door guarded by strict security. A VPN has no public door at all; only people with a key know how to reach the building. Because Home Assistant is never exposed to the public internet, this option provides the strongest isolation of the four.

Tailscale: the straightforward choice for beginners

Tailscale automates the difficult parts of a VPN, including key exchange, NAT traversal, and routing. It can even traverse CGNAT, which is essential for many connections worldwide.

1. Create a Tailscale account

   Sign in with a Google or GitHub account. The free personal allowance is ample for a typical home.

2. Add the community app repository

   Go to Settings → Apps → Install app → the three-dot menu in the upper-right corner → Repositories, then add https://github.com/hassio-addons/repository. This is the Home Assistant Community Add-ons repository, now called Community Apps; it includes both Tailscale and WireGuard.

3. Install and start Tailscale

   Install and start the app, then open its log tab. Follow the authorization URL shown there to add this host to your Tailscale network.

4. Install Tailscale on your phone

   Install the Tailscale app from the App Store or Play Store and sign in with the same account.

5. Connect through the Tailscale address

   Once the VPN is connected, use Home Assistant's address on the Tailscale network. With MagicDNS enabled, it resembles homeassistant.tail1234.ts.net, where tail1234 is assigned to your network.

WireGuard: the self-hosted alternative

WireGuard is the underlying technology used by Tailscale, but you host it and manage its keys yourself. The community app repository above (hassio-addons/repository) includes a WireGuard app.

The usual reason to choose WireGuard is simple: you do not want to depend on a third-party service. If that is not a requirement, Tailscale saves considerable time.

Option 4: DDNS + reverse proxy + Let's Encrypt

This is the most traditional, hands-on, and error-prone option. It combines three independent components, each solving a different problem:

Three official apps

All three components are available in the official app repository, so you do not need to add a third-party repository:

Setup using the shortest Duck DNS path

1. Confirm that you are not behind CGNAT

   Do this first, or every later step may be wasted. Sign in to your router and find the public IP on its WAN status page. Then search for “my IP” on a phone or computer and note the address visible to the internet.

   If they match, proceed. If they differ, you are likely behind CGNAT and this option will not work. Choose one of the preceding three options instead.

   You can also identify CGNAT when the router's WAN address falls between 100.64.x.x and 100.127.x.x, a range reserved for carrier-grade NAT.

2. Register with Duck DNS

   Sign in to the Duck DNS website with a supported account, create a subdomain, and copy the token shown at the top of the page.

3. Install and configure the Duck DNS app

   Install Duck DNS from the official app store. On its configuration tab, enter the token and domains value for your domain. Under Let's Encrypt, set accept_terms to true; the service will not run until you accept its terms.

   The default certificate filenames are fullchain.pem and privkey.pem. Do not change them without a specific reason.

   This app obtains certificates through DNS-01 validation. Let's Encrypt checks your domain's DNS record rather than connecting to your home. You do not need to open an inbound router port merely to obtain the certificate. The documentation also notes that if you point your own domain at a Duck DNS domain, you must add the required CNAME for the validation name or DNS-01 validation will fail.

4. Install the NGINX SSL proxy

   Install the official NGINX Home Assistant SSL proxy. On its configuration tab, enter the domain for your Duck DNS address plus the certfile and keyfile names above. The files are stored in the /ssl directory.

5. Configure trusted proxies

   If you skip this step, the next one will fail. Follow the next section.

6. Forward port 443 on the router

   This is the one step that opens an inbound path: forward only port 443 (HTTPS) to the Home Assistant host's reserved IP.

   Do not open any port other than 443. In particular, never forward port 8123; doing so exposes the unencrypted sign-in page directly to the internet. Port 80 is unnecessary: the NGINX app disables port 80 by default, and DNS validation does not rely on port 80.

7. Set the external URL and test

   Go to Settings → System → Network and enter https://yourdomain.duckdns.org as the External URL. Turn off Wi-Fi on your phone and test over mobile data.

The two reverse-proxy settings required for sign-in

This is the chapter's most common source of support requests. It applies whenever you use Cloudflare Tunnel, NGINX, Tailscale Serve or Funnel, or any other reverse proxy.

Why it breaks: Home Assistant sees the proxy, not you

Normally, Home Assistant checks the source IP of each request to record sign-ins, distinguish local traffic, and enforce IP bans.

With a reverse proxy in the middle, every request appears to Home Assistant to come from the proxy itself. You in one city, a relative in another, and a hostile internet scanner all look identical.

The proxy solves this by attaching an X-Forwarded-For header that identifies the request's real source. Home Assistant does not trust this header by default, because anyone can forge one. If it trusted arbitrary headers, an attacker could claim to be 127.0.0.1 and impersonate a local client.

You must therefore tell Home Assistant two things explicitly: (1) trust X-Forwarded-For, and (2) accept that header only from these specific proxy addresses.

2026.8 and later: configure it in the UI (recommended)

1. Open the network settings

   Go to Settings → System → Network and find the HTTP server section.

2. Enable “Trust X-Forwarded-For”

   Turn on the field named Trust X-Forwarded-For.

3. Enter the trusted proxy addresses

   In Trusted proxies, enter the IP addresses or CIDR subnets of reverse proxies allowed to set X-Forwarded-For. Use the table below to determine the value.

4. Save and restart

   Save the setting, restart Home Assistant, and test again.

Which address to enter

Before 2026.8: configure it in configuration.yaml

Older versions do not provide these UI fields, so use configuration.yaml. For an app-based proxy, add:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.30.33.0/24

For Tailscale Serve or Funnel:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1

List multiple proxies on separate lines:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.30.33.0/24
    - 127.0.0.1
    - 192.168.1.20

Non-negotiable security rules

Home Assistant's security checklist identifies three core principles: use a strong, unique password for every account and enable multi-factor authentication; keep sensitive values in secrets and remember to back them up; and install the monthly updates. The actions below put those principles into practice.

Rule 1: Never forward port 8123 directly to the public internet

If you have already created such a rule, delete it from the router now, then implement one of the four options above. This is the chapter's single most important instruction.

Rule 2: Enable MFA

Multi-factor authentication (MFA, also called two-step verification) requires both a password and the six-digit code that changes every 30 seconds in an authenticator app. A stolen password alone is then insufficient.

1. Open the Security tab in your profile

   Select your name in the lower-left corner to open User profile, then select Security.

2. Enable a multi-factor authentication module

   Find “Multi-factor authentication modules” and select Enable.

3. Scan the QR code with an authenticator app

   Install an authenticator app on your phone, scan the QR code, then enter the six-digit code shown in the app to confirm.

4. Store the recovery information safely

   Keep the recovery information somewhere other than your phone. If the phone is lost and no recovery method is available, you can lock yourself out.

5. Repeat this for every household account

   Your own MFA cannot protect a relative's account with a password such as 123456. Chapter 5 covers multi-user management.

Rule 3: Enable IP banning

Home Assistant can ban an IP after a configured number of consecutive failed sign-in attempts. This is an effective defense against brute-force attacks.

Under Settings → System → Network, configure these two fields:

Each banned address is written to ip_bans.yaml with the UTC time when it was added. To remove a ban, delete the corresponding entry and restart Home Assistant.

Rule 4: Expose only essential services

Audit every inbound rule on your router. Many were created years ago for a camera, a download service, or a game and then forgotten.

Temporary external testing demands discipline

You may occasionally need ten minutes of external visibility to test a webhook, show someone a page, or debug an OAuth callback. Understand the risks and safeguards:

Professional deployments: VLANs, guest networks, and multiple NAT layers

The preceding guidance assumes one household and one router. Offices, shops, and more sophisticated residential installations introduce three additional concerns.

Isolate IoT devices on a separate network

Inexpensive smart plugs, bulbs, and cameras vary widely in firmware quality, and some never receive another update. A compromised smart plug on the same subnet as your laptop or NAS becomes a ready-made foothold.

A VLAN (virtual local area network) creates several isolated logical networks over the same physical infrastructure. A common design is:

Multiple NAT layers: two routers at home

A common setup uses an internet provider's modem that also acts as a router, followed by a second router added for better Wi-Fi. This creates two NAT layers, placing Home Assistant behind two boundaries.

To identify this setup, sign in to your own router and inspect its WAN IP. If it shows a private address such as 192.168.x.x or 10.x.x.x, another NAT layer sits upstream.

This is why the chapter emphasizes those three options: they bypass CGNAT, multiple NAT layers, and changing public IP addresses at once.

Pre-handover checklist

• The host IP is reserved on the router and recorded in the handover documentation
• The router's administration password has been changed from the factory default
• Both Internal URL and External URL are configured and tested
• MFA is enabled on every account and IP banning is active
• No router rule points to port 8123
• UPnP and remote router administration are disabled
• Backups are scheduled and stored away from the host (see Chapter 9)
• If VLANs are used, mDNS forwarding is configured and device discovery has been tested
• Automatic certificate expiration and renewal behavior has been verified

Troubleshooting

1. Let's Encrypt repeatedly fails to issue a certificate

   First establish one fact: the Duck DNS app uses DNS-01 validation. Let's Encrypt checks your domain's DNS records and does not connect to your home. Certificate failure is therefore usually unrelated to ports; do not start opening router ports.

   Check in this order. (1) DNS configuration: confirm that the Duck DNS domain exists, the token is correct, and the validation CNAME is present if you use your own domain. (2) DNS propagation: a new record takes time to become visible worldwide. Trying too soon fails. (3) Terms: forgetting to set accept_terms to true in the Duck DNS app is extremely common. (4) Rate limits: Let's Encrypt limits repeated requests for one domain. Repeated retries can block further attempts temporarily; stop and wait rather than making it worse. (5) App logs: read the complete log, which contains the actual cause, rather than relying on the red status message alone.

2. It works at home but not away—or the reverse

   This almost always indicates incorrect local and external URLs. Under Settings → System → Network, confirm that both Internal URL and External URL are present and correct. Then open the Companion App settings and verify both values there as well.

   For each field, stop after the port and do not append a path. A value ending in .../lovelace can corrupt generated notification and camera links, producing varied and misleading symptoms.

   If access works away from home but fails when you return, the IP in the Internal URL has probably changed. Return to the first section and reserve it.

3. The page opens, but sign-in fails or returns 400

   This is the classic symptom of an untrusted reverse proxy. Return to the Trusted proxies section, enable Trust X-Forwarded-For, and enter the correct Trusted proxies value: 172.30.33.0/24 for an app-based proxy, or 127.0.0.1 for Tailscale Serve or Funnel. Save and restart.

   If the values are already present, check whether they remain only in the old configuration.yaml after an upgrade to 2026.8. The UI values now take precedence, and the YAML block should be removed after verifying migration. If the values do not appear in the UI, force-refresh the browser.

4. DDNS is configured, but external access still fails: CGNAT

   Compare the WAN IP shown by your router with the result of an online “my IP” search. If they differ, you are probably behind CGNAT, through which an internet provider lets many customers share one public address.

   Behind CGNAT, DDNS and port forwarding cannot provide inbound access; you do not have a unique public address. Your choices are: (1) ask the provider whether it offers a public IP, possibly for an additional charge or plan change; (2) use Nabu Casa, Cloudflare Tunnel, or Tailscale, none of which is affected; or (3) forgo remote access. Option (2) is practical for most households.

5. homeassistant.local suddenly stops working

   First confirm that you are at home and that your phone is not on guest Wi-Fi or another subnet. Then connect directly by IP to verify that the host is running. If IP access works, only mDNS has failed. The most reliable long-term solution is to reserve the IP and bookmark that address.

6. You cannot connect after changing the port

   If you changed it in the 2026.8 or later UI, do not panic or make further changes. Home Assistant waits for confirmation after changing the port. If you do not confirm within five minutes, it restores the old value and restarts. Wait for the automatic rollback.

   On an older release, or after a manual change to a Container installation, restore the value from the host itself by attaching a monitor and keyboard or correcting the Docker port mapping.

7. Your own IP has been banned

   Too many incorrect passwords triggered the ban. From the host, edit ip_bans.yaml, delete your entry, and restart Home Assistant. If you cannot access the file, connect through another network—for example, a mobile hotspot—so your source IP changes.

8. New devices disappear after you create VLANs

   This is expected. Automatic discovery depends on multicast traffic that does not cross subnets. Enable mDNS forwarding on the router or firewall—mDNS Repeater, Avahi Reflector, or Bonjour Gateway—and add a rule allowing Home Assistant to initiate connections to the IoT network.

Frequently asked questions