Below are the instructions for setting up Tailscale Funnel with Home Assistant.
This guide is specifically about Tailscale Funnel, a free service that lets family, visitors and everybody else securely access your Home Assistant instance without installing an app or connecting to a VPN on their devices. If you are willing to connect your devices to Tailscale VPN you don’t need this guide, instead please see the Tailscale add-on docs.
There’s also Home Assistant Cloud, which not only lets you access your home from anywhere with zero manual setup, you’ll also be able to easily connect to voice assistants, get peace of mind with seamless backup and restore, and support the development of Home Assistant, all while not depending on any third parties like Tailscale, Cloudflare or Google.
Steps
- Sign up for Tailscale.
- In Home Assistant, install the Tailscale Addon from the add-on store.
- In the add-on configuration, under Share Home Assistant with Serve or Funnel, select the funnel option. Don’t start the add-on yet.
- Add this to your Home Assistant
configuration.yamlfor it to accept the traffic from the Tailscale proxy:
http:
use_x_forwarded_for: true
trusted_proxies:
- 127.0.0.1
- Log in to your Tailscale admin panel. In the DNS section, choose a randomly-generated domain name.
- Scrolling down the same page, enable HTTPS certificates.
- In the Access controls page, add the following to your ACL config file, after other rules. It should still be inside the top-level brackets (i.e. it should be surrounded by one level of brackets).
"nodeAttrs": [
{
"target": ["autogroup:member"],
"attr": ["funnel"],
},
],
- Start the Tailscale add-on now. Go to logs page.
- In the logs, you’ll find a log in link to log in the device to your tailnet. Open it and follow instructions.
- Go to your Tailscale admin console. Click on the three-dot menu of the newly connected
homeassistantdevice. Choose Disable key expiry. - You can also rename your device from this menu. You’ll access it by
<device_name>.<your-tailnet-name>.ts.net.
That’s it. Don’t forget that anybody will be able to access your Home Assistant instance from your tailscale domain link, so always use strong auto-generated passwords securely stored in your password manager for your Home Assistant user logins.
There’s indeed much room for improvement in the setup process of the Tailscale add-on.
FAQ
I’m an average Joe and not a network engineer, what’s the risk here?
Expand
With the setup described here, there are no real risks for you to worry about. There are exactly three potential risks:
- Your phone connects to Funnel servers using TLS encryption. The world runs on TLS. If TLS was compromised, the entire world would go up in flames, so you don’t have to worry about it.
- Funnel servers connect to your Home Assistant instance using Wireguard. The world also runs on Wireguard (to a lesser degree), so same as above, you don’t have to worry about it.
- The security of the Home Assistant login page and API. This is the only realistic source of risk here. Even then, as a HA user, there is no reason to be concerned about it.
Home Assistant is the 2nd most active open source project in the world, and many people heavily depend on it in their everyday lives. At the time of writing, Home Assistant has over 500.000 confirmed active installations. The analytics are opt-in, the estimated real count is ~2.2 million.
Github Security Labs and others audit and/or discover vulnerabilities in HA which then responsibly get fixed.
There is not a single reason you shouldn’t trust Home Assistant developers, users and the broader community to keep the HA login page and API secure.
Why not just open a firewall port on my home router?
Expand
If you are behind CGNAT, which many people are, even if you open a port on your router it won’t work. You’ll need a proxying/tunneling solution.
Setting that aside, if you open a firewall port on your router, any device that is on your home network becomes accessible from the internet. And most devices on your network (Wi-Fi connected appliances, sensors, cameras, robot vacuums) are insecure and vulnerable to attacks, even if your HA device might not be. This is just the unfortunate reality today.
With Tailscale funnel however, it’s only the Home Assistant UI that is exposed to internet:
- Tailscale funnel accepts encrypted HTTPS traffic from the internet at your Tailscale domain, and decrypts it.
- It forwards the traffic to the Tailscale addon in Home Assistant through the VPN. You don’t need to open any ports on your firewall, nor any devices on your home network are exposed, because the traffic remains inside the VPN.
- The addon forwards the traffic only to port 8123 on HA, which is the port the HA UI and API is served from.
With this setup, the only thing exposed to the internet is the Home Assistant login page and the API.
You wil not have a device on your local network that’s always accesible via port 8123[1]. Automated port scanning software won’t be able to detect that you are running Home Assistant based on the port number, and the IP address of your home network will remain totally private.
Why not directly use the Tailscale VPN?
Expand
When you use a VPN like Tailscale to access your Home Assistant instance, only the devices in your Tailscale network (a.k.a tailnet) can connect to Home Assistant. While this is indeed more secure than exposing your HA instance to the public internet, it has some potential drawbacks:
- You need to ensure family members’ devices are reliably connected to the VPN for them to be able to access Home Assistant.
- Always-on VPNs constantly consume a small amount of power in the background which can lead to slightly faster battery degradation in smartphones.
- You can’t use two VPN solutions at the same time on most devices, e.g. if you’re already using a VPN for another purpose.
The “official” way to remotely access HA, the Home Assistant Cloud, doesn’t require you to use a VPN. Furthermore, it has the same architecture as Tailscale Funnel[2].
If you are the single user of HA, and don’t mind the potential slight battery drain from a VPN, you can simply use the Tailscale add-on without Funnel to connect to your HA instance through the Tailscale VPN. If not, you might find it harder in practice. Ultimately the decision is yours.
How to set up multiple subdomains with this?
Expand
Warning: There’s no guide for setting up multiple subdomains yet. Below is only a user report.
The Tailscale add-on is a container with the tailscale client running in it. This add-on has a reverse proxy which forwards requests sent to your tailscale domain (aka tailnet name) to local port 8123, which is the port Home Assistant UI is served from.
The end result is: https://home-assistant.my-tailnet.ts.net → localhost port 8123.
With this knowledge, we can simply duplicate the Tailscale add-on, give it any name (e.g. my-app) in Tailscale admin console and modify it to forward requests to whatever local port we want (e.g 8080).
The end result would be: https://<my-app>.my-tailnet.ts.net → localhost port 8080
I did this to host the Immich add-on on its separate immich.my-tailnet.ts.net subdomain, and so far it works. There were a few modifications I had to do to the add-on (message me if interested).
It’s not exactly a great idea to run another tailscale client for every app you want to host, a better setup would be integrating a proxy tool like Nginx with the add-on to create subdomains. Let me know if you do this!
Here is an example untested nginx config from ChatGPT for multiple subdomains:
# Untested, I have no idea whether this would work at all!
server {
listen 80;
server_name your.funnel.domain;
location /ha/ {
rewrite ^/ha(/.*)$ $1 break;
proxy_pass http://127.0.0.1:8123/;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location /immich/ {
rewrite ^/immich(/.*)$ $1 break;
proxy_pass http://127.0.0.1:8181/;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
Feel free to publish any parts of this guide in the official addon docs, suggest improvements or fixes, and comment whether this worked for you or not. I’ll try to update this post as feedback comes.
Funnel will only expose the standard HTTPS port 443. This port will be exposed not on your local network but on their Funnel relay servers, which will then be forwarded to your HA port 8123 through the VPN. ↩︎
(technical) The one difference is Funnel servers communicate with HA through a VPN instead of HTTPS. ↩︎