Install the app
Find Tailscale on the Home Assistant Apps page, install it and start it; do not guess at settings, and do not rush to make the service public. 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
First, confirm that your install type applies. This guide is for Supervisor-managed installs that show Apps in HA (older interfaces may call them Add-ons). If you run Home Assistant Container or Core, there is no Apps page, and the click path in this chapter does not apply.
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.
| Layer | What it handles | How this chapter verifies it |
|---|---|---|
| Tailscale admin console | Accounts, Machines, routes and policy | HA appears in Machines |
| HA Tailscale app | Runs Tailscale on the HA host | Status healthy, no blocking errors in the log |
| Home Assistant | Login, dashboard and admin rights | Log in normally with a personal account |
Hands-on: complete this chapter safely
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.
Open the entry point you need
Depending on this chapter's goal, look at the app's Info, Configuration, Log or Web UI. Log in and authorize the device from the Web UI only on a personal device you trust.
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.
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: install and do the first start only
Confirm you have Apps
Go to Settings → Apps, open the store and search for Tailscale. If there is no Apps entry, stop: this install is not a Supervisor-managed environment where the app can be installed as this chapter describes.
Install the official app
Open the Tailscale entry, read the current version and permissions, then choose Install; when it finishes, press Start. Do not enable options you are not using before you have logged in to the tailnet.
Check the three tabs
Go back to the app's Info, Configuration and Log and confirm that it starts and does not fail right away. Login and machine verification are left for Chapter 3.
Create a restore point
Create a Home Assistant backup first, or at least write down the original settings, so you can always get back to a known state before updating the app or changing network settings.
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.
| Need | Recommended start | Not yet |
|---|---|---|
| View HA remotely | Private access from a device logged in to the tailnet | Open ports and unnecessary public sharing |
| Manage devices | The Machines list and personal accounts | A shared admin login |
| Reach your home LAN | A single approved subnet route | Advertising 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.
Acceptance test on two networks
Home network
Open HA on your local LAN and confirm that the existing accounts and dashboard were not affected by this chapter's changes.
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.
Record the result
Note success or failure, the device you used and the time. That makes a problem far easier to pin down later than only remembering "it used to work".
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 this | Keep out of public docs | Who needs it next |
|---|---|---|
| Purpose of the change, date, verification result | Credentials, auth keys, login URLs | HA maintainer |
| Each machine's purpose and its owner's role | The full tailnet domain and private IPs | Tailscale admin |
| Which subnet with a clear purpose was approved | Unredacted CIDRs, scan results, street addresses | Network maintainer |
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?
Does Tailscale replace the Home Assistant login?
What if I see the old name, Add-on?
Can I set up an exit node or DNS override while I am at it?
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.