Cloudflare Tunnel in Practice: Domain, DNS, Tunnel, and Diagnostics

With the concept clear from Lesson 5, this lesson walks through the actual setup, migrating DNS to Cloudflare, installing the tunnel add-on, configuring your public hostname, and diagnosing problems methodically.

What this lesson doesn't do

This lesson doesn't cover buying a domain itself, any domain registrar's own site walks you through that in a few minutes. It doesn't cover Cloudflare's other products either, this course only uses the free Tunnel feature specifically. Its job is a clear, orderly walkthrough from an unconfigured domain to a fully working home.yourdomain.com address reaching your Home Assistant server.

A glossary, without the chaos

A domain is the name you own, yourdomain.com. A subdomain is a prefix on it, home.yourdomain.com. DNS is the system translating domain names into the technical information that tells the internet where to send traffic, effectively the internet's address book. A DNS record is one entry in that address book, and the specific type Cloudflare Tunnel uses is called a CNAME record, pointing your subdomain at Cloudflare's tunnel infrastructure rather than a fixed IP address. Keep these five terms in mind, every step ahead uses them directly.

A map: where do you actually type things

Three different places matter in this setup, and confusing them is the most common source of confusion. Your domain registrar, where you bought the domain, is where you point your domain's nameservers at Cloudflare, a one-time step. Cloudflare's own dashboard is where you manage DNS records and configure the tunnel itself, where you'll spend most of this lesson. And your Home Assistant server, through the tunnel add-on's own configuration, is where you tell the tunnel which local address to actually forward traffic to.

Migrating DNS to Cloudflare, briefly

Create a free Cloudflare account, add your domain from the dashboard, and Cloudflare scans your domain's existing DNS records automatically, importing them so nothing already working, like an existing website or email, breaks during the switch. Cloudflare then gives you two nameserver addresses to enter at your original domain registrar, replacing whatever nameservers were there before. This handoff can take anywhere from a few minutes to about a full day to fully propagate across the internet, genuine patience here matters far more than any specific technical step you might take.

Installing on HAOS: the general steps

Add the Cloudflare Tunnel add-on's repository to the Add-on Store, install it following Module 6's familiar install-and-start pattern, and authenticate it to your Cloudflare account through the add-on's configuration, generating a tunnel token in Cloudflare's dashboard first and pasting it in. Once authenticated and started, the tunnel establishes its outbound connection automatically, visible as active in Cloudflare's own Zero Trust dashboard within moments.

Public hostname and Service URL: don't confuse these fields

In the tunnel's configuration, Public Hostname is the address the outside world will type, home.yourdomain.com. Service URL is where the tunnel should actually send that traffic once it arrives, your Home Assistant server's local address, something like http://homeassistant.local:8123 or its local IP. These two fields serve opposite directions of the same connection, and mixing them up is the single most common setup mistake, worth double-checking carefully before saving.

Home Assistant's reverse proxy setting

Home Assistant needs to know it's being reached through a reverse proxy, the concept Lesson 5 previewed, or it may reject the incoming connection as untrusted. This means adding a small http section to configuration.yaml, using File Editor from Module 6, listing Cloudflare's proxy addresses as trusted. This is genuinely the one piece of manual YAML editing in this entire module, and it's worth taking slowly, using the configuration checker habit from Module 6 before restarting.

Your first tunnel test

Once DNS has propagated and Home Assistant's trusted proxy setting is saved, open home.yourdomain.com from your phone's mobile data, WiFi off, exactly the same test pattern this module has used since Lesson 3. A working login page appearing here means every piece, DNS, tunnel, reverse proxy trust, is correctly connected end to end, and you now have a genuinely custom, professional-looking address for your Home Assistant server.

Diagnosing problems, in order

If your address doesn't load, check things in this order: is the tunnel showing as active in Cloudflare's dashboard, has DNS actually propagated, checkable with any online DNS lookup tool, is the Service URL correct and reachable from the server the add-on runs on, and does configuration.yaml's trusted proxy setting match what the error, if any, in Home Assistant's own log is complaining about. Working through these four checks in this exact order resolves nearly every Cloudflare Tunnel setup problem without guesswork, and it's worth resisting the urge to jump straight to the last step just because it feels like the most likely culprit.

Configuration details worth knowing

A few specific settings are worth understanding rather than blindly copying. The tunnel token, generated once when you create the tunnel in Cloudflare's dashboard, authenticates the add-on to your account, treat it exactly like a password, never share it publicly, and regenerate it if you ever suspect it's been exposed. The Service URL's protocol prefix matters too, http rather than https is correct here specifically, since the tunnel itself, not your Home Assistant server, is what handles the public-facing encryption, Home Assistant only needs to speak plainly to the tunnel add-on sitting right beside it on your own network. And the trusted proxy addresses added to configuration.yaml should match Cloudflare's own currently published IP ranges exactly, available directly from Cloudflare's own documentation, rather than a rough guess copied from an outdated tutorial somewhere online.

Container on a NAS

On Home Assistant Container, the official cloudflared Docker image runs as its own separate container alongside your Home Assistant container, configured with the same tunnel token generated in Cloudflare's dashboard. The Public Hostname and Service URL concepts work identically, only the specific location where you enter them changes, a Docker environment variable or mounted configuration file rather than an add-on's configuration tab. The trusted proxy setting in configuration.yaml is identical regardless of installation method, since that piece is entirely a Home Assistant Core setting rather than anything specific to HAOS or Container, and it needs to be added exactly the same way either way.

Common problems

A "502" or "bad gateway" error usually means the Service URL is wrong or Home Assistant isn't reachable at that address from wherever the tunnel add-on runs. A "400 Bad Request" error appearing directly from Home Assistant itself usually points to the trusted proxy configuration being missing entirely or set up incorrectly in configuration.yaml. And a tunnel showing as inactive in Cloudflare's dashboard almost always means the add-on itself has stopped or lost its authentication, restarting it from Settings, then Add-ons, is the first thing to try before assuming a deeper problem exists anywhere else in the chain.

Common questions

Do I need to keep my domain's original DNS provider? No, moving nameservers to Cloudflare doesn't cost anything extra beyond your existing domain registration. Can I use a subdomain I already use for something else? No, choose a dedicated, unused subdomain like home.yourdomain.com specifically for Home Assistant to avoid conflicts with anything else already running on that domain. Will this work on Container? Yes, using the official cloudflared Docker image alongside your Home Assistant container, following the same public hostname and Service URL concepts covered throughout this lesson.

A real story: the trusted proxy mistake nearly everyone makes once

One reader in this course's community got everything working, DNS propagated cleanly, the tunnel showed active in Cloudflare's dashboard, the Public Hostname and Service URL were both correctly set, only to be met with a confusing "400 Bad Request" error the moment they tried loading home.yourdomain.com from their phone. Everything about the tunnel itself was genuinely correct, the missing piece was Home Assistant's own trusted proxy setting in configuration.yaml, without which Home Assistant treats traffic arriving through the tunnel as suspicious and refuses it outright, regardless of how correctly everything upstream is configured. Adding the small http section with Cloudflare's proxy ranges, then restarting, resolved it immediately, and this exact scenario is common enough that it's worth expecting rather than being surprised by it.

The broader lesson generalizes well: with four separate systems involved, DNS, Cloudflare's tunnel, the add-on, and Home Assistant's own trust settings, a single missing piece anywhere in that chain produces a working-looking tunnel that still doesn't quite connect, which is exactly why this lesson's ordered diagnostic checklist matters more here than in any other lesson in this module.

Keeping the tunnel add-on updated

Like every add-on covered since Module 6, the Cloudflare Tunnel add-on updates through the Add-on Store's normal update badge, no special process required. Because the tunnel is a critical piece of infrastructure once configured, this course recommends checking for updates on a regular basis alongside your other add-ons rather than letting it go stale for months, an outdated tunnel client occasionally loses compatibility with Cloudflare's evolving infrastructure, though this is genuinely uncommon given how actively and consistently Cloudflare maintains backward compatibility for existing tunnels already running in production use around the world.

A short exercise before moving on

Work through this lesson's steps in order, migrate DNS, install the add-on, configure the public hostname and Service URL, add the trusted proxy setting, then test from mobile data with WiFi off. If something doesn't load on the first attempt, walk the diagnostic order above rather than guessing, it will get you to the actual root problem far faster than randomly trying fixes one after another.

How long DNS propagation really takes

Nameserver changes at your registrar are the slowest part of this whole process, sometimes resolving within an hour, occasionally taking closer to 24 hours depending on your specific registrar and domain extension. Individual DNS record changes made afterward, directly in Cloudflare's own dashboard, propagate much faster, typically within a few minutes. If home.yourdomain.com isn't loading yet, checking an online DNS propagation checker tells you honestly whether you're still waiting on nameservers or whether the problem lies elsewhere entirely, saving you from troubleshooting a step that simply hasn't finished yet and never actually needed fixing in the first place.

Adding a second self-hosted service later

Once the tunnel is working for Home Assistant, extending it to a second service, a NAS, a media server, a personal wiki, is straightforward: add another Public Hostname on the same tunnel, files.yourdomain.com for example, pointing at that service's own local Service URL, without touching the DNS migration or reverse proxy trust settings already in place. This is one of the genuine long-term advantages Lesson 5 mentioned when comparing Cloudflare Tunnel against Nabu Casa and the VPN options, one tunnel, one domain, and every additional self-hosted service you add later reuses the same infrastructure you already set up here, rather than requiring its own separate remote access solution from scratch.

Key takeaways

With four working methods behind you, Lesson 7 closes this module by helping you decide which one, or which combination, actually fits your household.