Using ngrok With

Here you will find notes on using ngrok with particular technologies. Think we're missing something? Send a note to support@ngrok.com and let us know.

Name Description
CGNAT Use ngrok inside Carrier Grade Network Address Translation (CGNAT) systems like Starlink
Django Add ngrok into your Django application
Docker Learn how to configure ngrok to work with Docker networks
Fast API Add ngrok into your Fast API application
Flask Use ngrok to host your Flask applications
Google Colab Run ngrok inside your Google Colab projects
gRPC ngrok TCP tunnels work great with gRPC
Java Learn how to integrate with your Java projects
Minecraft ngrok can help you and your friends connect for online gaming
NGINX Learn how to configure ngrok when using it with NGINX
Node (npm, node.js) Work with the ngrok agent from your Node application
An outbound proxy Use ngrok through an HTTP or SOCKS5 proxy
Puppet Manage the ngrok Agent using Puppet
Python Learn how to integrate with your Python application
SSH Learn how to SSH to a machine from anywhere in the world
Virtual hosts (MAMP, WAMP, etc.) Rewrite the host header for forwarding to virtual hosts
Visual Studio Leverage ngrok when working in Visual Studio
VSCode ngrok can help speed up your VSCode development
Websockets Use ngrok with Secure Websockets (ws:// or wss://)
Wordpress Learn how to use ngrok to host your Wordpress site

Using ngrok with CGNAT

ngrok is a great solution when you don't have access to open ports on your router. This is the case for Starlink and other systems that use CGNAT or similar software. There is a very useful blog post from Don Simpson about using ngrok with CGNAT. The basic steps are summarized below.

That's really it. There shouldn't be any other changes you need to make to your network or router.

Using ngrok with Django

If you're looking to natively embed the ngrok agent into your Django application, you can leverage the pyngrok project to start a tunnel anytime you start the Django Dev Server.

Using ngrok with Docker

ngrok provides pre-built docker images for the ngrok Agent with instructions for getting started. An example command for starting a tunnel to port 80 on the host machine looks like this:

docker run --net=host -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http 80

Note: for MacOS or Windows users, the --net=host option will not work. You will need to use the special url host.docker.internal as described in the Docker networking documentation.

docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http host.docker.internal:80

Using ngrok with Fast API

If you're looking to natively embed the ngrok agent into your Fast API application, you can leverage the pyngrok project to start a tunnel anytime you start the Fast API Server via uvicorn.

Using ngrok with Flask

To share a local Flask development server with someone else, simply run: ngrok http 5000.

If you're looking to natively embed the ngrok agent into your Flask development flow, you can leverage the pyngrok project so that a tunnel is created each time you type flask run.

Note: For users on the latest MacOS, there is an issue where the default port of 5000 is used by Apple AirPlay Receiver. You can use a different port for your Flask app or see this Stack Overflow post for disabling the AirPlay Receiver service.

Using ngrok with Google Colab

If you're looking to run the ngrok agent into your Google Colab project, you can leverage the pyngrok project to start a tunnel in your project.

Using ngrok with gRPC

As noted by this Stack Overflow user, when forwarding to gRPC services, use proto: tcp.

Using ngrok with Java

If you'd like to programmatically manage your ngrok account and resources (register domains, create edges, configure IP restrictions, etc.), you can use the native ngrok Java API Client in your project.

If you're looking to programmatically start tunnels with the ngrok agent, check out Alex's java-ngrok library.

Using ngrok with Minecraft

Minecraft requires the use of an ngrok TCP tunnel to share your server with others. Use ngrok tcp 25565 to open a TCP tunnel on the default Minecraft port. You can then use the address provided to connect to your Minecraft server.

The free version of ngrok has session limitations, which means you will need to restart the agent and send a new TCP address to your players. Our paid accounts allow you to reserve a TCP Address for reuse. In this case, you would start the TCP tunnel using ngrok tcp --remote-addr TCP_ADDRESS 25565.

CAUTION: The TCP tunnel you open is available to anyone by default. Our paid accounts allow you to restrict access to specific IP Addresses using IP Restrictions.

Using ngrok with NGINX

It's a good idea to get a background on how NGINX processes a request. What that usually means is you need to ensure the --host-header flag is set when tunneling your service.

Using ngrok with Node.js or npm

If you need to manage the ngrok agent for starting tunnels, use bubenshchykov's npm package:

If you'd like to programmatically access the ngrok API for configuring ngrok Edges and modules, use our ngrok Javascript/Typescript Client.

Using ngrok with an outbound proxy

ngrok works correctly through an HTTP or SOCKS5 proxy. ngrok respects the standard unix environment variable http_proxy. You may also set proxy configuration explicitly in the ngrok configuration file:

Using ngrok with Puppet

Use Gabe's puppet module for installing and configuring ngrok resources and ensure the ngrok agent process is running: ngrok module for Puppet

Using ngrok with Python

If you'd like to programmatically manage your ngrok account and resources (register domains, create edges, configure IP restrictions, etc.), you can use the native ngrok Python API Client in your project.

If you're looking to programmatically start tunnels with the ngrok agent, check out Alex's pyngrok library.

Using ngrok with RDP

ngrok's TCP tunnels can be used for RDP traffic but we recommend they only be used in conjunction with restricting access to a specific set of IP addresses using IP restrictions. Start a TCP tunnel to port 3389 and add the --cidr-allow flag with the IP addresses you'll be connecting from.

ngrok tcp 3389 --cidr-allow 0.0.0.0/32

To learn more about the RDP protocol and security best practices, see the Understanding the Remote Desktop Protocol (RDP) documentation from Microsoft.

Using ngrok with SSH

ngrok's TCP tunnels are perfect for SSH traffic. Simply start a TCP tunnel to port 22 and you should be all set.

ngrok tcp 22

When connecting through the ngrok TCP address, make sure you specify the port separately.

ssh -p PORT user@NGROK_TCP_ADDRESS

Using ngrok with Virtual hosts (MAMP, WAMP, etc)

Popular web servers such as MAMP and WAMP rely on a technique popularly referred to as 'Virtual Hosting' which means that they consult the HTTP request's Host header to determine which of their multiple sites they should serve. To expose a site like this it is possible to ask ngrok to rewrite the Host header of all tunneled requests to match what your web server expects. You can do this by using the --host-header option (see: Rewriting the Host header) to pick which virtual host you want to target. For example, to route to your local site myapp.dev, you would run:

ngrok http --host-header=myapp.dev 80

You can also use rewrite to tell ngrok to use the local address hostname.

ngrok http --host-header=rewrite 80

Using ngrok with Visual Studio / IIS Express

Use dproterho's visual studio extension which adds ngrok support directly into Visual Studio: ngrok extension for Visual Studio

Using ngrok with VSCode

Use Phil Nash's VSCode extension which adds ngrok support directly into VSCode: ngrok extension for VSCode

Using ngrok with Websockets

Websocket endpoints work through ngrok's HTTP tunnels without any changes. However, there is currently no support for introspecting websockets beyond the initial 101 Switching Protocols response.

Using ngrok with Wordpress

To make ngrok work properly with Wordpress installations you usually need to do two things:

  1. You must ensure that Wordpress issues relative URLS. You can do so by installing the following plugin:
  2. You must ensure that Wordpress understands that it is meant to serve itself from your tunneled hostname. You can configure Wordpress to do that by modifying your `wp-config` to include the following lines:
    define('WP_SITEURL', 'http://' . $_SERVER['HTTP_HOST']);
    define('WP_HOME', 'http://' . $_SERVER['HTTP_HOST']);
  3. You must also instruct ngrok to rewrite the host header, like so:
    ngrok http --host-header=rewrite https://your-site.dev