Hello, this article will be a step-by-step tutorial of how to setup secure Home Assistant remote access using NGINX reverse proxy & DuckDNS.
In other words you will be able to access your Home Assistant via encrypted connection with a legit, trusted certificate when you are outside your local network, but at the same time when you are connected to your local home network you will still be able to use the regular non-encrypted HTTP connection giving you the best possible speed, without any latencies and delays. The best of all – it is all totally free.
Home Assistant Remote Access using reverse proxy DuckDNS & NGINX – prerequisites
For this tutorial you will need a working Home Assistant with Supervisor & Add-ons store. That means, your installation type should be either Home Assistant OS or Home Assistant Supervised.
Quick Tip: If you want to know more about the different official and not so official Home Assistant installation types, then you can check my free Webinar available at https://automatelike.pro/webinar. Go watch that Webinar and you will become a Home Assistant installation type expert.
Back to the requirements for our Home Assistant remote access using NGINX reverse proxy & DuckDNS project. The next and final requirement is: access to your router interface as we will do one quick port forward rule, but more on that later, because now we will continue with DuckDNS domain creation.
How to create DuckDNS sub-domain?
Creating a DuckDNS is free and easy. All you have to do is the following:
- Go to https:///duckdns.org and login with any of the available options (I used Twitter)
- Type a unique domain of your choice and click on Add Domain. I will use smash-the-like.duckdns.org domain for the rest of this demo.
- After that, if it is needed, update the current ip field with your real IP address (usually duckdns auto detect that field, so you don’t have to do anything).
- Then copy somewhere safe the generated token.
What is your favorite?
DuckDNS domain is created, but can you share what is your favorite Dynamic DNS service? Is it a DuckDNS, or it is a No-IP or FreeDNS or maybe something completely different. Let me know in the comments section below.
How to install Home Assistant DuckDNS add-on?
Next step is to install and configure the Home Assistant DuckDNS add-on. This is very easy and fast.
Open your Home Assistant:
- Press the “c” button to invoke the search bar and start typing Add-ons, select Navigate Add-ons > search for DuckDNS add-on > click Install. Alternatively, click the My Home Assistant link below:
- After the DuckDNS Home Assistant add-on installation is completed. Go to the Configuration tab of the add-on and add:
- Your DuckDNS sub-domain under
- Your DuckDNS sub-domain under
- At the end your Home Assistant DuckDNS Add-on configuration should look similar to the one below:
aliases:  domains: - YOUR_DOMAIN.duckdns.org lets_encrypt: accept_terms: true algo: secp384r1 certfile: fullchain.pem keyfile: privkey.pem seconds: 300 token: YOUR_DUCKDNS_TOKEN
- Save the changes and start the Home Assistant DuckDNS Add-on from the Info tab.
What is a reverse proxy?
I’m ready with DuckDNS installation and configuration. It is time for NGINX reverse proxy. But first, Let’s clear what a reverse proxy is?
The purpose of a reverse proxy setup in our case NGINX is to only encrypt the traffic for certain entry points, such as your DuckDNS domain name.
What is NGINX?
If you are wondering what NGINX is? Here is a simple explanation: it is lightweight open source web server that is within the Top 3 of the most popular web servers around the world.
How to install NGINX Home Assistant Add-on?
Fortunately, there is a ready to use Home Assistant NGINX add-on that we will use to reverse proxy the Internet traffic securely to our Home Assistant installation. Let’s install that Home Assistant NGINX add-on:
- Press the “c” button to invoke the search bar and start typing Add-ons, select Navigate Add-ons > search for NGINX add-on > click Install. Alternatively, click the My Home Assistant link below:
- After the NGINX Home Assistant add-on installation is completed. Go to the Configuration tab of the add-on and add your DuckDNS domain next to the domain section and Save the changes.
- Your NGINX configuration should look similar to the picture below (of course, you should change smash-the-lke sub-domain with your own).
When using a reverse proxy, you will need to enable the
trusted_proxies options in your Home Assistant configuration. Requests from reverse proxies will be blocked if these options are not set. To add them open your
configuration.yaml file with your favourite editor and add the following section:
# configuration.yaml entry http: use_x_forwarded_for: true trusted_proxies: - 172.30.33.0/24
Exposing your Home Assistant installation to the outside world is a moderate security risk. To make this risk very low you can add few more lines (last two lines from the example below), so you can protect yourself further and if someone tries to login three times with wrong credentials it will be automatically banned.
The next lines (last two lines below) are optional, but highly recommended.
# configuration.yaml entry http: use_x_forwarded_for: true trusted_proxies: - 172.30.33.0/24 ip_ban_enabled: true # use this to enable auto IP ban login_attempts_threshold: 3 # set the number of allowed login attempts
After you are finish editing the configuration.yaml file. Save the changes and restart your Home Assistant.
Port Forwarding rule
The final step of the Home Assistant Remote Access using NGINX Reverse Proxy & DuckDNS is to do some port forwarding in your home router. This part is easy, but the exact steps depends of your router brand and model.
The port forwarding rule should do the following: Forward any 443 port income traffic towards your Router WAN IP (Or DuckDNS domain) to port 443 of your local IP where Home Assistant is installed.
If you don’t know how to do it type in YouTube the following:
your_router_brand port forward
For example: linksys port forward
Below is a screen of how I configured this port forwarding rule in Unifi Dream Machine router.
Testing the Home Assistant Remote Access using NGINX Reverse Proxy & DuckDNS
Time to test our Home Assistant Remote Access using NGINX Reverse Proxy & DuckDNS setup.
- If I try to open the https://smash-the-like.duckdns.org it will work! And I will have a trusted certificate from Let’s Encrypt Certificate Authority (CA) that will auto renew from now on.
- If I try to open http://smash-the-like.duckdns.org the request will be converted to secure https connection and I will open my Home Assistant. This is very convenient as it will not matter whether you type http or https when you try to reach your Home Assistant from the outside.
- If from my local network I type https://MY_HA_LOCAL_IP:8123 it will not work, but this result is wanted and expected.
- And if I try non-encrypted http://MY_HA_LOCAL_IP:8123 connection it will work just fine. Exactly as I wanted.
If some of the abbreviations and acronyms that I’m using are not so clear for you, download my free Smart Home Glossary which is available at https://automatelike.pro/glossary.
I’m Kiril and I’m done writing. Bye!
vcents · 28/05/2022 at 8:25 pm
Hi – I’ve heard/read other instructions which also set up port forwarding for port 80 to make sure a browser will redirect an http request for the domain to https. Is it advisable to follow this as well or can it cause other issues?
Kat81inTX · 24/07/2022 at 4:38 pm
I have a problem with my router that means I can’t use port forwarding on 443 (if I do, I lose the ability to use the router’s admin interface).
For folks like me, having instructions for using a port other than 443 would be great. Is as simple as using some other port (maybe 8443) and using https://:8443 as my external address?
John · 31/08/2022 at 4:40 pm
Hey @Kat81inTX, you pretty much have it. So the instructions vary depending on your router, but essentially you want to tell it to listen on a particular port, like https://:8443 and “divert” (route) those to the local IP address of your Home Assistant device, like: 192.168.0.123:443
John · 31/08/2022 at 4:34 pm
I am a noob to homelab and just trying to get a few things working. I got Nginx working in docker already and I want to use that to secure my new Home Assistant I just setup, and these instructions I can’t translate into working. I have setup the subdomain and when I try to access it via a web browser I get a 400 error, when I try to connect the iOS app it says 400 error Shared.WebhookError 2. I have tried turning websockets and tried all the various options on the ssl tab but I’m guessing it’s going to need something custom or specific in the Advanced tab, but I don’t know what. Any pointers/help would be appreciated.
Justin · 21/10/2022 at 10:39 pm
Where do you get 172.30.33.0/24 as the trusted proxy? Should mine be set to the same IP?
KIril Peyanski · 22/10/2022 at 9:51 am
Yes, you should said the same. These are the internal IPs of Home Assistant add-ons/containers/modules.
Scott · 23/11/2022 at 7:55 pm
I am a NOOB here as well. I followed the instructions above and appear to have NGINX working with my Duck DNS URL. I have had Duck DNS running for a couple years ago but recently (like a few weeks ago) came across this thread and installed NGINX.
I am seeing a handful of errors in the Home Assistant log for the NGINX SSL Proxy. Any suggestions on what is going on? Things seem to be working despite the errors:
1) connect() failed (111: Connection refused) while connecting to upstream, client: , server: .duckdns.org, request: “GET /api/websocket HTTP/1.1”, upstream: “http://172.30.32.1:8123/api/websocket”, host: “.duckdns.org”
2) connect() failed (111: Connection refused) while connecting to upstream, client: , server: .duckdns.org, request: “POST /api/webhook/ HTTP/2.0”, upstream: “http://172.30.32.1:8123/api/webhook/”, host: “.duckdns.org”
3) SSL_do_handshake() failed (SSL: error:141CF06C:SSL routines:tls_parse_ctos_key_share:bad key share) while SSL handshaking, client: 18.104.22.168, server: 0.0.0.0:443
For errors 1 and 2 above I added “172.30.32.0/24” to the trusted proxies list in my HA config file. This is in addition to what the directions show above which is to include 172.30.33.0/24. I think that may have removed the error… but why?
For error 3 there are several different IPs that this shows up with (in addition to “22.214.171.124”). I don’t recognize any of them.
Any help would be greatly appreciated!
Scott · 23/11/2022 at 7:56 pm
I excluded my Duck DNS and external IP address from the errors…
Ari · 31/01/2023 at 11:05 am
Hi. After using this kind of setup for some time, I got an error “NSURLErrorDomain -1200” in companion app. To my understanding this was due to renewed certificate (by DuckDNS/Let’s Encrypt add-on), but it looks like NGINX did not notice that and continued serving the old one. Restart of NGINX add-on solved the problem.
Do you know how I could get NGINX to notice the renewal so that this kind of situation would not happen again?