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 |
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.
ngrok config --add-authtoken TOKEN
ngrok http 80
That's really it. There shouldn't be any other changes you need to make to your network or router.
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.
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
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.
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.
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.
As noted by this
Stack Overflow user, when forwarding to gRPC services, use proto: tcp.
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.
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.
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.
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.
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:
Use Gabe's puppet module for installing and configuring ngrok resources and ensure the ngrok agent process is running: ngrok module for Puppet
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.
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/32To learn more about the RDP protocol and security best practices, see the Understanding the Remote Desktop Protocol (RDP) documentation from Microsoft.
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 22When connecting through the ngrok TCP address, make sure you specify the port separately.
ssh -p PORT user@NGROK_TCP_ADDRESS
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 80Use dproterho's visual studio extension which adds ngrok support directly into Visual Studio: ngrok extension for Visual Studio
Use Phil Nash's VSCode extension which adds ngrok support directly into VSCode: ngrok extension for VSCode
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.
To make ngrok work properly with Wordpress installations you usually need to do two things:
define('WP_SITEURL', 'http://' . $_SERVER['HTTP_HOST']);
define('WP_HOME', 'http://' . $_SERVER['HTTP_HOST']);ngrok http --host-header=rewrite https://your-site.dev