Setting Up Tailscale Funnel for Home Assistant

Setting Up Tailscale Funnel

Using Staykey? You probably don't need Tailscale Funnel. The Staykey plugin connects your Home Assistant to Staykey directly — no public URL required. Tailscale Funnel is only needed if you use the direct connection method or want remote access to Home Assistant for other purposes.

Tailscale Funnel gives you a free, secure way to access your Home Assistant from anywhere — no monthly subscription, no opening ports on your router, and no VPN app needed on the devices you use to connect. Anyone with the link (and your Home Assistant login) can reach your instance.

What you get

• Free remote access: No subscription required
• Secure HTTPS URL: A dedicated https://your-device.your-tailnet.ts.net address
• No port forwarding: Works even if your internet provider blocks incoming connections
• Encrypted traffic: Your connection is protected by TLS and Wireguard

Before you start

You'll need:

• Home Assistant OS or Home Assistant Supervised installed and running
• A free Tailscale account — sign up at tailscale.com

That's it. No terminal or command-line experience required.

Step-by-step setup

1. Install the Tailscale app in Home Assistant

1. In Home Assistant, go to Settings → Apps
2. Click the Install app button in the bottom-right corner
3. Search for Tailscale and click on it
4. Click Install and wait for it to finish
5. Once installed, go to the Configuration tab
6. Under Share Home Assistant with Serve or Funnel, select the funnel option
7. Don't start the app yet — we have a few more things to set up first

2. Update your Home Assistant configuration

This step tells Home Assistant to trust traffic coming from the Tailscale app running on your device.

1. In Home Assistant, go to Settings → Apps
2. Open a file editor app (like File editor or Studio Code Server) — install one from the Apps page if you don't have one
3. Open the file called configuration.yaml (it's in your main config folder)
4. Add these lines at the bottom:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1

5. Save the file

Tip: If your configuration.yaml already has an http: section, just add use_x_forwarded_for and trusted_proxies underneath it instead of creating a second http: block.

3. Set up your Tailscale domain name

1. Log into your Tailscale admin panel and go to the DNS section
2. Choose a domain name for your network (Tailscale will suggest a randomly generated one — that's fine to use)
3. Scroll down on the same page and enable HTTPS certificates

4. Allow Funnel in your Tailscale access controls

This tells Tailscale that devices in your network are allowed to use Funnel.

1. Open the Access Controls page in the Tailscale admin panel
2. Expand the Funnel section
3. Click Add Funnel to policy

That's it — Tailscale will add the required settings and save automatically.

If you don't see the Funnel section: You can add the policy manually instead. In the text editor on the Access Controls page, add the following inside the main curly braces { }, after any existing rules, then click Save:

"nodeAttrs": [
  {
    "target": ["autogroup:member"],
    "attr":   ["funnel"]
  }
]

5. Start Tailscale and log in

1. Go back to Home Assistant and open the Tailscale app (under Settings → Apps → Tailscale)
2. Click Start
3. Open the Log tab — you'll see a login link appear in the logs
4. Click or copy that link and follow the instructions to sign in and connect the device to your Tailscale network

6. Finalize your device settings

1. Go back to the Tailscale admin panel
2. You should see a new device called homeassistant in your device list
3. Click the ⋯ (three-dot menu) next to it and choose Disable key expiry — this prevents your connection from breaking when the key expires
4. You can also rename the device from this menu if you'd like. Your access URL will be https://<device-name>.<your-tailnet>.ts.net. If you rename it, restart the Tailscale app in Home Assistant for the change to take effect

7. Wait a moment, then test

Funnel can take a few minutes to become ready after setup.

1. On your phone, turn off WiFi so you're using mobile data (this makes sure you're testing over the internet, not your local network)
2. Open your Funnel URL in a browser — for example: https://homeassistant.my-tailnet.ts.net
3. You should see your Home Assistant login page
4. Log in to make sure everything works

Using your Tailscale URL with Staykey

Once Funnel is working, use your Tailscale URL when connecting Home Assistant to Staykey:

• URL format: https://your-device.your-tailnet.ts.net
• Don't include a port number — Funnel handles this for you
• Generate a Long-Lived Access Token in Home Assistant for Staykey to use

Is this secure?

Yes. Here's how it works in plain terms:

1. Your phone to Tailscale: The connection from your phone (or any device) to Tailscale's servers is encrypted with TLS — the same encryption that protects online banking and every other secure website.
2. Tailscale to Home Assistant: The connection from Tailscale's servers to your Home Assistant is encrypted with Wireguard — a trusted, modern VPN protocol.
3. No open ports at home: Unlike opening a port on your router, Funnel doesn't expose any device on your home network directly. Traffic flows through Tailscale's servers and into Home Assistant through the secure VPN tunnel.

The only thing someone on the internet could reach is your Home Assistant login page, and they'd need your username and password to get in. Use strong, unique passwords and enable multi-factor authentication in Home Assistant for extra protection.

Troubleshooting

Funnel URL shows an error or won't load:

• Make sure you selected funnel in the Tailscale app configuration (Step 1)
• Verify Funnel was added to your Access Controls policy (Step 4)
• Check that HTTPS certificates are enabled in Tailscale DNS settings (Step 3)
• Wait 5 minutes — Funnel can take a little while to become available after first setup
• Restart the Tailscale app in Home Assistant and check the logs for errors

"502 Bad Gateway" or blank page:

• Make sure you added the http section to configuration.yaml (Step 2)
• Restart Home Assistant after editing configuration.yaml — go to Settings → System → Restart

URL not resolving (page not found):

• Double-check your domain name in the Tailscale admin DNS settings
• If you renamed your device, restart the Tailscale app so it picks up the new name
• Try from a different device or network

Connection works but keeps logging you out:

• This can happen if the trusted proxy setting isn't configured. Double-check Step 2
• Make sure there's only one http: section in your configuration.yaml

Alternatives

Staykey Plugin (Recommended for Staykey)

• No public URL needed at all
• Handles the Staykey connection automatically
• Provides faster device control and real-time state streaming

Nabu Casa (Home Assistant Cloud)

• Even simpler setup (~5 minutes)
• $6.50/month subscription
• Directly supports Home Assistant development