Chapter 8

Serve

When you need a clean HTTPS entry point, first understand the security difference between Serve and Funnel; this guide covers tailnet-only Serve and nothing else. This chapter walks you through one task at a verifiable, reversible pace: keep access private first, and never expose Home Assistant directly to the internet.

Why this matters

Serve and Funnel are not the same risk. Tailscale Serve makes a local service available to the devices inside your tailnet; Funnel makes it available to the wider internet. The official docs draw a clear line between the two, so this chapter deals only with Serve's private entry point, and Funnel stays outside the scope of this guide.

Chapter scope: the share_homeassistant option described in the app docs can turn on Serve or Funnel behavior, and it defaults to disabled. Do not switch it to public mode until you understand the reverse proxy and HA's HTTP settings.

Core concepts

A tailnet is your private Tailscale network; a machine is one device that has joined it; and the Home Assistant app is the Tailscale service managed by Supervisor, which you open and configure from the Apps page in HA. Tell these three layers apart first, so that later you do not click in the wrong place.

LayerWhat it handlesHow this chapter verifies it
Tailscale admin consoleAccounts, Machines, routes and policyHA appears in Machines
HA Tailscale appRuns Tailscale on the HA hostStatus healthy, no blocking errors in the log
Home AssistantLogin, dashboard and admin rightsLog in normally with a personal account

Hands-on: complete this chapter safely

  1. Record the current state first

    In the Home Assistant left-hand menu, go to Settings → Apps and find Tailscale; if your screen uses the old name, it may say Add-ons. Note whether it is running, and for now do not change any advanced options you are not using.

  2. Open the entry point you need

    Depending on this chapter's goal, look at the app's Info, Configuration, Log or Web UI. Complete the Web UI sign-in (log in and authorize the device) only on a personal device you trust.

  3. Cross-check in the admin console

    Open the Machines page in the Tailscale admin console and confirm the machine that corresponds to Home Assistant, its last-seen status and its feature badges; do not copy the names or IPs in the screenshots as your own values.

  4. Test from another device

    Take a phone or laptop logged in to the same tailnet and run one access test for this chapter's goal. Once it succeeds, note the time and the device you tested with, so troubleshooting is easier later.

Walkthrough: enable Tailscale Serve for the tailnet only

  1. Keep HA on local HTTP

    The official app docs assume HA is reachable over HTTP. If you already have another HTTPS reverse proxy, do not mix the two setups; assess it against the docs first.

  2. Set up trusted proxies

    In configuration.yaml, in the existing or a new http: section, set use_x_forwarded_for: true and trusted_proxies: - 127.0.0.1; save, then restart Home Assistant.

  3. Enable HTTPS in the admin console

    Go to the DNS settings, choose a tailnet name, enable MagicDNS, and choose Enable HTTPS under HTTPS Certificates. This is the prerequisite for Serve to obtain a certificate.

  4. Enable serve in the app and restart

    Set the app's share_homeassistant to serve, leave share_on_port at its default of 443, and restart the app. Do not choose funnel.

  5. Test the URL from a tailnet device

    Open https://<machine>.<tailnet>.ts.net (without the old port number) from another device logged in to the tailnet, then log in with your personal HA account.

Out of scope: Funnel lets internet devices that do not have Tailscale installed reach the service; that is not what this guide sets up.

How to choose options without adding risk

Start with the smallest workable setup, then expand step by step. If all you want is to see your dashboard while away from home, private access over the tailnet is usually easier to control than a public entry point; if you need a LAN subnet, list one subnet with a clear purpose first, and do not advertise every network at once.

NeedRecommended startNot yet
View HA remotelyPrivate access from a device logged in to the tailnetOpen ports and unnecessary public sharing
Manage devicesThe Machines list and personal accountsA shared admin login
Reach your home LANA single approved subnet routeAdvertising multiple subnets without taking inventory

Security check before you finish

Check that the account logged in to Tailscale is the right one, that Home Assistant is still managed with separate personal accounts, and that the Machines list has no unknown or retired devices. Permissions follow least privilege: only the people who need to reach HA get a path to it, and only the people who need to manage the tailnet get admin console access.

Warning: do not post login URLs, auth keys, your tailnet domain, full IP addresses, device serial numbers or raw logs in issues, group chats or screenshots.

Acceptance test on two networks

  1. Home network

    Open HA on your local LAN and confirm that the existing accounts and dashboard were not affected by this chapter's changes.

  2. A different network

    Switch the test phone to mobile data or another secure network, confirm that Tailscale is connected, then open HA once. If this chapter is about routes, test only targets you are authorized to manage.

  3. Record the result

    Note success or failure, the device you used and the time. That makes a problem easier to pin down later than only remembering "it used to work".

  4. Stop at the security boundary

    This guide does not cover exit nodes, DNS override or public Funnel setup; leave them disabled unless you need them.

Leave a handover-ready record

The biggest risk with network settings is "it worked at the time, but nobody remembers why". When you finish this chapter, write down the date, who did it, the purpose, the state before and after, and the device you verified with in your password manager or your site maintenance notes. The record is not there to store passwords, auth keys or full private subnets; those secrets belong in a controlled secrets manager, and the notes hold only the description the next maintainer needs to understand the decision.

For example: "2026-08-19, the administrator confirmed the Home Assistant machine is still in the designated tailnet; private access tested successfully from a managed laptop on a non-home network." For a subnet router, add "only a single approved LAN CIDR is advertised, approved in the admin console", and never write street addresses, customer names, the full Tailscale domain or device identifiers into a public repo. That is what lets you judge which layer to roll back when a phone is lost, a router is replaced, the app is updated or admin rights are handed over.

Record thisKeep out of public docsWho needs it next
Purpose of the change, date, verification resultCredentials, auth keys, login URLsHA maintainer
Each machine's purpose and its owner's roleThe full tailnet domain and private IPsTailscale admin
Which subnet with a clear purpose was approvedUnredacted CIDRs, scan results, street addressesNetwork maintainer
The minimal-change principle: change one thing at a time, test from another network when you are done, then write down the result. That preserves reversibility better than flipping routes, policy, DNS and public sharing all at once.

Troubleshooting: check these first

  • Cannot find Apps: confirm whether your HA install is managed by Supervisor; Container/Core cannot follow the app path in this guide.
  • HA is not in Machines: go back to the app's Web UI and complete the login, then read the app log, instead of reinstalling over and over.
  • Machines shows HA but HA will not open: first confirm the client is logged in to the same tailnet, then check the HA login account and URL.
  • The route seems to exist but the LAN is unreachable: confirm the route has been approved in route settings on the Machines page; then test with the correct CIDR against a target you are authorized to reach.
  • Things got uncertain after a change: go back to the last known-good state, keep the logs and the change record, then change one thing at a time.

FAQ

Do I need to open a router port?
The private tailnet flow in this guide does not require you to set up public port forwarding for HA; assess it against your own network and security policy.
Does Tailscale replace the Home Assistant login?
No. Tailscale manages the network path; Home Assistant should still use personal accounts, strong passwords and appropriate admin rights.
What if I see the old name, Add-on?
The HA interface and its translations vary by version; recognize the Tailscale app, Info, Configuration, Log and Web UI, then go by what your screen and the official docs say.
Can I set up an exit node or DNS override while I am at it?
This guide deliberately leaves out these advanced topics. Finish verifying private HA access and a single subnet route first, then plan them separately from the official docs.

Official sources and version notes

This guide treats the Home Assistant Community App: Tailscale docs and Tailscale Docs as authoritative. Interface text changes with the app and admin console versions; when a name differs, go by your screen and the official docs first.