Skip to main content

Home Assistant with ngrok

TL;DR

To put your Home Assistant instance online with ngrok:

  1. Start Home Assistant locally in a Docker container
  2. Add ngrok to the Docker container
  3. Allow trusted proxies in Home Assistant

This guide covers how to set up Home Assistant with ngrok. This combination lets you access your Home Assistant dashboard over the public internet.

Prerequisites:

  • Docker Desktop
  • Docker Compose
  • ngrok installed on your machine
  • Basic familiarity with the command line

Tip: This guide walks through setting up Home Assistant in a Docker container from scratch, but the same principles apply if you already have a Home Assistant instance set up, or if you set it up using one of their other installation methods.

Step 1: Initial setup​

  1. Create a directory called home-assistant

  2. Inside the home-assistant directory:

  • create your Docker Compose file called compose.yaml
  • create a directory called config

Step 2: Run Home Assistant in a Docker container​

  1. Update compose.yaml:
Loading…
  1. In your terminal, start a Docker container with this compose.yaml file:
Loading…
  1. Visit localhost:8123 in your browser. You should see your Home Assistant login page: Home Assistant on localhost

Step 3: Add ngrok​

  1. Add ngrok to your compose.yaml under the services section:
Loading…
  1. In your terminal, restart your Docker container with this compose.yaml file:
Loading…

  1. Visit your ngrok dashboard to see the endpoint URL: ngrok Endpoints

  2. If you visit the ngrok URL, you'll get a 4xx response: ngrok Endpoints

and an error log line your Docker Desktop logs for the Home Assistant container:

Loading…

That's because we still have to update the Home Assistant configuration to allow trusted proxies.

Step 3: Allow trusted proxies in Home Assistant​

  1. In your /home-assistant/config directory, look for the file called configuration.yaml. By default, it should already have these settings:
Loading…

Add this new section to the bottom:

Loading…

  1. Restart the Docker container so the updated Home Assistant configuration can take effect.

  2. Visit your ngrok endpoint URL and see your Home Assistant instance online! ngrok hosting Home Assistant