Skip to main content

​
Running ngrok in the background

ngrok includes commands to run itself in the background as a native operating system service, that is, as a daemon. When it runs as an operating system service it:
  • Starts when the machine boots
  • Automatically restarts after crashes
  • Can be managed via native OS service tooling
  • Sends logs to the OS’s native logging service
  • Starts all endpoints defined in the configuration file, the equivalent of running ngrok start --all
In most cases, installing ngrok as a service requires administrator privileges.

​
Try it out

Create an ngrok configuration file. For this example, assume it’s C:\ngrok\ngrok.yml. In your configuration file, make sure you include the authtoken property and define all of the endpoints you want to start. Then run:
This command validates that the configuration file is valid, and if so, installs ngrok as a service using the given configuration file. The service installation includes the location of the ngrok executable and the configuration file, so don’t move or delete either after you’ve installed the service. You can then start the ngrok agent service with:
You can manage the agent with your OS’s normal service tooling, but the agent also includes the ngrok service commands to manage the installed service:
  • ngrok service start
  • ngrok service stop
  • ngrok service restart
  • ngrok service uninstall
If you see an exit code 5 or Input/output error, ngrok usually can’t find the config file, or doesn’t have permission to read it. Make sure you have installed the ngrok service with a valid config file and that when the service is run (either as you or an administrator) it has access to that same config file.

​
Why is ngrok running in the background?

An administrator or a vendor may have installed ngrok as a service so an integration survives logout and reboot. Check the service’s executable path, account, and arguments to find its owner and config file. If you don’t recognize it, see what to check before you change or remove it.

​
Remote management

You can stop, restart, or upgrade the ngrok agent remotely using the Tunnel Sessions API. You can also perform these actions from the ngrok dashboard. On Windows, the Tunnel Sessions restart operation isn’t supported. If the agent is installed as a Windows service, use the Tunnel Sessions stop operation and rely on your Windows service recovery policy to start the service again after it stops.
Use this with caution if you have made changes to the config file. If ngrok can’t restart for any reason, you may lose access to the agent completely.