TailScale Setup

Unlock Your Home Assistant: Secure Remote Access with Tailscale (No Port Forwarding Needed!)

Ever wished you could check your security cameras, adjust the thermostat, or open your garage door via Home Assistant while you're away from home, without the security headaches of port forwarding? Meet Tailscale – your new best friend for secure, private remote access.

Tailscale creates a "private tunnel" between your devices (like your phone) and your Home Assistant instance, making it feel like they're all on the same local network, no matter where you are. This guide will walk you through setting it up step-by-step.

What You'll Need:

• A running Home Assistant instance (preferably Home Assistant OS or Supervised).

• A smartphone (iOS or Android).

• An internet connection.

Step 1: Set Up Your Tailscale Account (Your Private Network)

First things first, you need a Tailscale account, which will become your "Tailnet" – your very own private network.

1. Sign Up for Tailscale: Head over to Tailscale.com and sign up for a free account. You can use your Google, Microsoft, or GitHub ID for easy authentication.

2. Install on Your Phone: Download the Tailscale app from your phone's App Store (iOS) or Google Play Store (Android). Install it and log in using the same account you just created. Ensure Tailscale is "Connected" on your phone.

Step 2: Install and Configure Tailscale on Home Assistant

Now, let's get Home Assistant connected to your new private network.

1. Open Home Assistant: Navigate to your Home Assistant interface in your web browser.

2. Go to Add-ons: Click on Settings (the gear icon) in the sidebar, then select Add-ons.

3. Visit the Add-on Store: Click the Add-on Store button in the bottom right corner.

4. Find Tailscale: Search for "Tailscale" and click on the official add-on.

5. Install: Click the Install button and wait for the installation to complete.

6. Start the Add-on: Once installed, toggle on Watchdog (to auto-restart if it crashes) and Start on boot (so it always runs with HA). Then, click Start.

7. Authenticate HA: Click Open Web UI. This will provide you with a unique link. Click it to authenticate this Home Assistant instance with your Tailscale account. Follow the prompts in your browser to log in and authorize the new device.

   • You should now see your Home Assistant instance listed as a device in your Tailscale Admin Console (login.tailscale.com/admin/machines).

Step 3: Identify Your Home Assistant's Tailscale Address

Every device on your Tailnet gets a special IP address (usually starting with 100.x.x.x) and potentially a MagicDNS name.

1. Find the IP: In your Tailscale Add-on in Home Assistant, check the Logs tab. You'll often see the Tailscale IP address listed there.

   • Alternatively, log into your Tailscale Admin Console in a web browser. Find your "homeassistant" device. Note its Tailscale IP address (e.g., 100.x.y.z) and its MagicDNS name (e.g., homeassistant.yourtailnetid.ts.net).

   • For this guide, we'll assume you enable MagicDNS. If not, just use the numerical IP.

2. Enable MagicDNS (Recommended): In your Tailscale Admin Console, go to the DNS tab and ensure MagicDNS is enabled. This lets you use friendly names like homeassistant.yourtailnetid.ts.net instead of just numbers.

Step 4: Configure the Home Assistant Companion App on Your Phone

This is the crucial step that tells your phone how to find Home Assistant through the Tailscale tunnel when you're away.

1. Ensure Tailscale is ON: On your phone, open the Tailscale app and confirm it says "Connected". Your phone's VPN should be active.

2. Open HA Companion App: Launch the Home Assistant Companion App.

3. Navigate to Server Settings: Go to Settings (bottom right) > Companion App.

4. Select Your Server: Tap on your Server name (e.g., "Home Assistant").

5. Configure URLs:

   • Internal URL: Keep this as your local IP address (e.g., http://192.168.1.xxx:8123).

   • External URL: This is where the Tailscale address goes! Enter the MagicDNS name you found earlier, followed by the Home Assistant port.

     • Example: http://homeassistant.yourtailnetid.ts.net:8123

     • Crucial: Make sure it's http:// (not https:// unless you've set up certificates) and includes :8123at the end.

6. Verify Home Network SSIDs: Scroll down to the Network section (if visible). Tap Home Network WiFi SSIDs and ensure your actual home Wi-Fi network name(s) are listed. This tells the app to use the Internal URLwhen you're home, and the External URL (your Tailscale tunnel) when you're not.

   • If you don't see the "Network" section, ensure "Prioritize Internal URL" is OFF, or use the "Cheat Code" below.

Step 5: Test Your Connection!

It's time for the moment of truth!

1. Disable Wi-Fi: Turn off Wi-Fi on your phone, so it's running purely on cellular data.

2. Open Home Assistant App: Launch the Home Assistant Companion App.

If all goes well, your Home Assistant should load as if you were sitting on your couch! You can now control your garage door, lights, thermostat, or anything else from anywhere with an internet connection, all securely tunneled through Tailscale.

Troubleshooting & Pro-Tips:

• Browser Test is Key: If the HA app won't connect, first open your phone's web browser (Safari/Chrome), turn off Wi-Fi, and type your External URL (e.g., http://homeassistant.yourtailnetid.ts.net:8123) directly. If it loads, the issue is likely in the HA app settings; if not, Tailscale isn't tunneling correctly.

• "Cheat Code" for App Network Settings: If the HA Companion App's network settings are elusive, you can try setting both the Internal URL and External URL to your Tailscale address (e.g., http://homeassistant.yourtailnetid.ts.net:8123). This forces the app to always use the Tailscale tunnel, simplifying troubleshooting.

• Always-On VPN: For instant access without opening the Tailscale app every time, you can set Tailscale to "Always-on VPN" in your phone's system settings.

• No Port Forwarding: The biggest win here! You don't need to open any ports on your home router, keeping your network much more secure from external threats.

Enjoy your secure, remote Home Assistant access! No more worrying about complex firewall rules or exposing your home network to the internet.