Secure remote access to Home Assistant using Tor

Routers and gateways provided by broadband internet providers are very often limited regarding features and configuration possibilities. Most of these limitations affect the opportunities that allow users to set up port-forwarding, DMZ, and DHCP reservations since the suppliers figured that average user does not want (or should not) deal with these. Making your Home Assistant instance available remotely (and securely), in this case, becomes more difficult. Are you one of those unlucky ones?

There are a couple of options available to achieve a remote (and secure) accessible Home Assistant instance. However, almost all of them require you to: open one or more ports on your router, expose a public IP address, and require you to reserve a fixed IP in your DHCP server (or set up a static IP address). Examples of these are:

  • Combination of DuckDNS (or similar), Let’s Encrypt (SSL), DHCP reservation, and forwarding a port to your device running Home Assistant.
  • Setup a VPN, which often requires more hardware and software. Additionally, it also requires port-forwarding, DHCP reservation and most likely DuckDNS (or similar).
  • SSH tunnel-ing. Which still requires port-forwarding, DHCP reservation and most likely (yeah, you’ve guessed it) DuckDNS (or similar).

There is, however, another option available that most people do not realize: Tor. Tor offers a capability that they refer to as Tor’s Hidden Services, which allows you to securely access your Home Assistant installation without the need for all these things. No need to forward and open ports, no need to expose your public IP, no DNS entry, no need for SSL certificates, and you do not have to assign a fixed IP to the device running your Home Assistant.

The most amazing part? It is super easy to set up!

Setting up Tor

Our documentation provides a detailed guide about setting up a Tor’s Hidden Service. The setup is straight-forward:

  1. Install Tor. On a Debian-based system: $ sudo apt-get install tor. On Fedora: $ sudo dnf install tor
  2. Modify Tor’s main configuration file /etc/tor/torrc to include the following lines:

     ############### This section is just for location-hidden services ###
     ## Once you have configured a hidden service, you can look at the
     ## contents of the file ".../hidden_service/hostname" for the address
     ## to tell people.
     HiddenServiceDir /var/lib/tor/homeassistant/
     HiddenServicePort 80
  3. Restart Tor: $ sudo systemctl restart tor
  4. The Tor-generated hostname file contains the hostname you need to access your installation.

     $ sudo cat /var/lib/tor/homeassistant/hostname

Tor add-on for

Franck Nijhof (@frenck) created the Tor add-on for This add-on makes the installation and the setup extremely simple. Go to the panel, then to the Store, copy into the text box of Add-On Repositories and save it.

A new entry Tor will show-up in the list of add-ons. Click on it to install it. The configuration is done in Options. Please refer to the Configuration documentation for further details. A possible configuration could look like the sample below (which is the default configuration).

  "log_level": "info",
  "socks": false,
  "hidden_services": true,
  "stealth": false,
  "client_names": [],
  "ports": [

When you are done, press Save and then Start. In the Logs section, you can see what the add-on is doing. Watch out for an entry like the one below, which will tell you your hostname on the Tor network.

INFO: -----------------------------------------------------------
INFO: Your Home Assistant instance is available on Tor!
INFO: Address: abcdef1234567890.onion
INFO: -----------------------------------------------------------

Don’t worry if you missed it, restarting the add-on will display it again. The details are also stored and available in the /ssl/tor/hidden_service/hostname file.

Tor clients

To access you Home Assistant via the Tor Hidden Service, you will need a Tor client. There are multiple clients, for different devices and platforms, available. The Tor Browser is by far the simplest option, which is available for Windows, MacOS & Linux.

Simply download and install the Tor Browser, start it, and enter the “dot onion” address you’ve gained from the earlier steps (abcdef1234567890.onion in this case). Voila!

Some other clients:

Cranking up security

The setup described in this blog post is easy and relatively secure, but anyone who knows your .onion address can still connect to your Home Assistant instance (Remember to use passwords!). With all of the discussion about putting your IoT on the Tor Network, maybe you want to add an extra layer of defense, especially if you’re going to be the only one that uses it. Tor offers an additional layer of security, called “Hidden Service Authentication”, usually referred to as “Stealth”-mode.

This “Stealth”-mode adds an extra layer of security to your Hidden Service by only responding to a client that passes a unique secret cookie as it connects. Obviously, this requires additional configuration on the Tor client applications.

Additional information can be found in the Tor documentation and the Tor add-on repository, including how to setup the “Stealth”-mode. The Tor Project itself provides details about a variaty of topics in their documentation.

This is a companion discussion topic for the original entry at

In the blog-post list of other clients Onion Browser for iOS is mentioned. I tried to setup Tor on my installation and that was really easy. On MacOS Tor Browser displays as it should, but on my iPhone the recommended Onion Browser cannot connect. All other (free) browsers for iOS have the same problem. As far as I can find out this is due to javascript which is not permitted in these browsers but essential for the working of home assistant.
Is there a iOS browser available (can be paid, but I didn’t test them so far) that works? If not maybe it would be better not to recommend Tor for iOS but report it as not working.

It may seem a stupid question, but I really can’t see it:
Does the above setup allow you to connect to your home assistant instance from outside your network?

Yes it does. You get a unique link to your home assistant instance which you reach via the tor network.

1 Like

Hi @breinonline

How were you able to add custom torrc entries on Onion Browser, Red Onion or TOBY browser ?

I can’t find a way to do that and by searching the community I see other members are writing the same problem…

EDIT: I can’t find TOBY browser on App Store…

I didn’t add anything. Just typed in the union address the add-on for gave me. But that didn’t work on the iPhone.

1 Like

I think I’ve installed the TOR client on my rasp3 from this log, but when I try the dot.onion address on the TOR browser on my PC or ipad they are unable to connect to home assistant - what am I doing wrong or (not doing) ?
INFO: -----------------------------------------------------------
[cont-init.d] exited 0.
[cont-init.d] done.
[services.d] starting services
starting version 3.2.4
[services.d] done.
May 08 16:28:17.609 [notice] Tor (git-727d3f1b5e6eeda7) running on Linux with Libevent 2.1.8-stable, OpenSSL LibreSSL 2.6.3, Zlib 1.2.11, Liblzma N/A, and Libzstd N/A.
May 08 16:28:17.609 [notice] Tor can’t help you if you use it wrong! Learn how to be safe at
May 08 16:28:17.610 [notice] Read configuration file “/etc/tor/torrc”.
May 08 16:28:17.000 [notice] Parsing GEOIP IPv4 file /usr/share/tor/geoip.
May 08 16:28:19.000 [notice] Parsing GEOIP IPv6 file /usr/share/tor/geoip6.
May 08 16:28:20.000 [warn] You are running Tor as root. You don’t need to, and you probably shouldn’t.
May 08 16:28:36.000 [notice] Bootstrapped 0%: Starting
May 08 16:28:42.000 [notice] Starting with guard context “default”
May 08 16:28:42.000 [notice] Bootstrapped 80%: Connecting to the Tor network
May 08 16:28:43.000 [notice] Bootstrapped 85%: Finishing handshake with first hop
May 08 16:28:43.000 [notice] Bootstrapped 90%: Establishing a Tor circuit
May 08 16:28:43.000 [notice] Tor has successfully opened a circuit. Looks like client functionality is working.
May 08 16:28:43.000 [notice] Bootstrapped 100%: Done

Any updates on this topic? Is there any ios browser which can access HA through tor?

@ShoePac did you try out red onion or any other pay app?

Yes, I tried every available and as for now I think there is still no solution for iOS. But the guy from TOR are planning to develop something like Androids Orbot in order to have ability to edit torrc file… For now, as I now, only for Android. Someone correct me if I am wrong, I would be happy to be wrong :slight_smile:

Nice idea.

Why not run an OpenVPN server at home and connect to that?

You then get all the access you need. Benefits are it’s encrypted, can be hardened and use 2FA

I’ve installed the add on and got a .onion address.

I can connect to Home assistant, but if I try to open Hass the page remains blank.

So Hass only works on chrome. It’s now working with Tor chrome extension.

If certificates are not used (for SSL/TLS), aren’t the connections to the TOR network in the clear. Can someone snoop on the traffic between the TOR browser and HA and if so, what can they do?

So I have the Tor Addon working :slight_smile: I really like it so far. This is my config:

“log_level”: “info”,
“socks”: true,
“hidden_services”: true,
“stealth”: false,
“client_names”: [],
“ports”: [

I’d like to be able to access node red http://hassio.local:7681/
and the terminal app http://hassio.local:1880 over it too.

What would be the correct syntax for the config to add these ports so that I can access them over Tor?

I tried a search but couldn’t find anything, and I tried experimenting and made my device unavailable on :8123. I’ve restored from backup, but keen to find the right syntax.

I tried

but that broke it.

I tried

but that broke it too.

@frenck any suggestion?

Please read the documentation, since your answer is in there.

I’ve also tried


Then accessing http://uygrewgfxxxx.onion:7681

But the browser just hung and didn’t load the page

The ports on the outside end must be unique. Applications cannot share ports (not a tor issue btw, just the way the internet works).

I also tried


Then accessing http://yugfrheriepogr.onion:7681

But that didn’t work, and also made my device inaccessible.

1 Like