Easy-ngrok for EvoControl

Because DZ logo Domoticz is not natively accessible from outside your LAN, we need to install a so-called proxy to enable secure access to your instance from the Amazon cloud.

Our easy-setup procedure deploys a proxy called ngrok to open up a persistent tunnel resulting in a password-protected URL like for your Domoticz instance.

Since initializing the tunnel is an outward process originating in your LAN, there's no need to open any ports in your router  — ngrok also takes care of a valid certificate for SSL.

Alexa [443/https] proxy [8080/http] Domoticz

The skill communicates with your proxy and it is the proxy (perched on the LAN side of your firewall on your local network at home) that actually interacts with Domoticz.

With this approach, cloud control is password-protected while local control within your LAN remains completely unrestricted.

If you are on a recent version of Domoticz (after approx. mid 2022) then you will need to take a few extra steps to enable remote access for Alexa:

  • Enable 'Allow Basic-Auth authentication over plain HTTP (API only)' on the Setup → Settings → Security tab.
  • Visit the Setup → Users tab and create a new user with 'User' rights. Important: Assign the same username and password to this user as you will use with the ngrok tunnel. That way, the basic-auth passes through in the http headers and satisfies both ngrok and Domoticz!

Visit the website (no affiliation) for an explanation of how it works and what plans are available. The free plan[1] works just fine for our purposes so go ahead and Sign Up.

To subsequently authenticate you towards ngrok, you should make a note of your personal authtoken which resides at It will look something like 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p.

Please ignore any download/setup instructions at the ngrok website as they are geared towards setting up access to a web-server on 80 rather than a home automation server on 8080. Our installer will automatically download ngrok for you and configure it for Domoticz.

[1] The easy-setup installer ensures that the skill is updated with the changed tunnel URL whenever you restart ngrok or reboot your machine.

When you are logged in to your smartskills EvoControl account dashboard and have also ticked the 'I have a HGI-80 and DZ logo Domoticz / HA logo Home Assistant' checkbox, the configuration form has a blue button at the bottom labelled ' ngrok script'. Pressing it will launch the form shown above. When filled out, the form allows you to download a bash or pwsh script that will install ngrok for you and pre-configure it with the details you fill out on the form. A script will also be created on your system that will poll ngrok whenever it restarts to determine the allocated url and push those details off to EvoControl's back end. That way, the skill always has your correct ngrok details even after a restart.

You must provide the following 6 pieces of information:

  •  The target operating system under which ngrok will run. If you cannot remember if your Linux distro is 32-bit or 64-bit, the result of uname -mpi will enlighten you. For example, ARMv7 is 32-bit while ARMv8 is 64.
  •  Region. To minimize latency, ngrok will use a cloud server physically near you. You can choose one of eu us ap au sa jp in.
  •  Authtoken. Paste the personal authtoken you copied after ngrok SignUp (e.g. 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p) or else use the light-blue -icon button to visit your ngrok account and retrieve it.
  •  A username to associate with your tunnel to prevent unauthorized cloud-access to Domoticz. Min. 8 chars, no spaces. Valid: A-Z a-z 0-9 .@!#$%&*+-=?^_~
  •  A password to associate with your tunnel to prevent unauthorized cloud-access to Domoticz. Min. 8 chars — at least 1x A-Z, 1x a-z, 1x 0-9, 1x @#$%^&+=_-.*
  •  The local fixed IP address used to access Domoticz inside your LAN. For example, You may omit the http prefix but not the 8080.

When all the entries are completed, press the large blue Download Script button and the script file will be saved by your browser.

Your browser may warn that files sourced from the internet are potentially harmful — it does this based on the .sh or .ps1 file extension, not the actual contents. Some browsers or virus-scanners may even change the extension of the saved file to .txt to render it 'harmless'. If that happens you will need to manually rename with the correct extension before running it.

Follow the appropriate instructions below for the OS under which ngrok will run:

Debian Linuxes
Applies to any Debian-based distro which supports systemd services and bash scripting. Examples include Raspberry Pi OS, Ubuntu and Debian.

  • Open a terminal. Place[1] the downloaded file in your home directory, e.g. /home/pi
  • Run it using sudo bash

If your target machine is a pi there's one more important step to ensure the OS waits for the network to come up at boot time. Issue the command sudo raspi-config. Choose System Options and then S6 Network at Boot and choose <Yes>.

If something does not work and you are wondering if your fetched ngrok binary is the correct version for your architecture, type which ngrok and then use the file command on the result, e.g. file /usr/local/bin/ngrok. The output will include something like ELF 64-bit LSB executable, x86-64 or ELF 64-bit LSB executable, ARM aarch64.

Installs ngrok to /usr/local/bin/ngrok and creates a service file /etc/systemd/system/ngrok.service to run ngrok as a daemon at boot. It also builds a file called ~/.ngrok2/ngrok.yml with your configuration. Finally, it creates the ~/ auto-updater file that refreshes your tunnel details when you reboot.

Place the downloaded script in your normal Downloadsfolder.

  • In the Finder, open the Applications folder and then Utilities. Double-click on Terminal to pop open a terminal.
  • Inside the terminal window, typecd ~/Downloads
  • Run the installer using sudo /bin/bash (you will need to type your Mac password to authorize).

Installs ngrok to /usr/local/bin/ngrok and creates a launchd file /Library/LaunchDaemons/com.ngrok.onstartup.plist to run ngrok as a daemon at boot. It also builds a file called /usr/local/bin/.ngrok2/ngrok.yml with your configuration. Finally, it creates the /usr/local/bin/ auto-updater file that refreshes your tunnel details when you reboot.

Windows 10 / 11

  • Right-click on the downloaded PowerShell file ecsetup.ps1 in your downloads folder and select the option to Run with PowerShell. If that is not allowed on your PC, see the comments in the file for a simple fix.

Installs ngrok to c:\ngrok and creates a config file called c:\ngrok\ngrok_config.yml. In the same directory, you'll see ngrok_autostart.ps1 and a wrapper ngrok_autostart.cmd. A shortcut to ngrok_autostart.cmd is added to Windows' startup apps folder.

[1] If the target system is headless, use ssh or scp via e.g. filezilla, winscp or putty to transfer the script file across.