pyngrok 1.3.1

A Python wrapper for Ngrok.

pyngrok - a Python wrapper for ngrok

pyngrok is a Python wrapper for ngrok that manages its own binary and puts it on our path, making ngrok readily available from anywhere on the command line and via a convenient Python API.

install

pyngrok is available on PyPI and can be installed using pip.

pip install pyngrok

That's it! pyngrok is now available as a package to our Python projects, and ngrok is now available from the command line.

open a tunnel

To open a tunnel, use the connect() method, which returns the public URL generated by ngrok.

from pyngrok import ngrok

# Open a tunnel on the default port 80
public_url = ngrok.connect()

The connect() method can also take an options parameter, which allows us to pass additional options that are supported by ngrok.

get active tunnels

It can be useful to ask the ngrok client what tunnels are currently open. This can be accomplished with the get_tunnels() method, which returns a list of NgrokTunnel objects.

from pyngrok import ngrok

tunnels = ngrok.get_tunnels()
# A public ngrok URL that tunnels to port 80 (ex. http://<public_sub>.ngrok.io)
public_url = tunnels[0].public_url

closing a tunnel

All open tunnels will automatically be closed when the Python process terminates, but we can also close them manually.

from pyngrok import ngrok

public_url = "http://<public_sub>.ngrok.io"

ngrok.disconnect(public_url)

the ngrok process

Opening a tunnel will start the ngrok process. This process will remain alive, and the tunnels open, until ngrok.kill() is invoked, or until the Python process terminates.

If we are building a short-lived app, for instance a CLI, we may want to block on the ngrok process so tunnels stay open until the user intervenes. We can do that by accessing the NgrokProcess.

from pyngrok import ngrok

ngrok_process = ngrok.get_ngrok_process()
# Block until CTRL-C or some other terminating event
ngrok_process.process.wait()

The NgrokProcess also contains an api_url variable, usually initialized to http://127.0.0.1:4040, from which we can access the ngrok client API.

If some feature we need is not available in this package, the client API is accessible to us via the api_request() method. Additionally, the NgrokTunnel objects expose a uri variable, which contains the relative path used to manipulate that resource against the client API. This package also gives us access to ngrok from the command line, as shown below.

other useful configuration

authtoken

Running ngrok with an auth token enables additional features available on our account (for instance, the ability to open more tunnels concurrently). We can obtain our auth token from the ngrok dashboard and install it like this:

from pyngrok import ngrok

ngrok.set_auth_token("<NGROK_AUTH_TOKEN>")

# Once an auth token is set, we are able to open multiple tunnels at the same time
ngrok.connect()
ngrok.connect(8000)

This will set the auth token in the config file. We can also set it in a one-off fashion by setting it for the "auth" key of the options parameter passed to connect().

config file

The default ngrok config file lives in the home directory's .ngrok2 folder. We can change this in one of two ways. Either pass the config_path parameter to methods:

from pyngrok import ngrok

CONFIG_PATH = "/opt/ngrok/config.yml"

ngrok.connect(config_path=CONFIG_PATH)

or override the DEFAULT_CONFIG_PATH variable:

from pyngrok import ngrok

ngrok.DEFAULT_CONFIG_PATH = "/opt/ngrok/config.yml"

ngrok.set_auth_token("<NGROK_AUTH_TOKEN>")

binary path

The pyngrok package manages its own ngrok binary. However, we can use our ngrok binary if we want in one of two ways. Either pass the ngrok_path parameter to methods:

from pyngrok import ngrok

NGROK_PATH = "/usr/local/bin/ngrok"

ngrok.get_tunnels(ngrok_path=NGROK_PATH)

or override the DEFAULT_NGROK_PATH variable:

from pyngrok import ngrok

ngrok.DEFAULT_NGROK_PATH = "/usr/local/bin/ngrok"

ngrok.connect()

command line usage

This package puts the default ngrok binary on our path, so all features of ngrok are also available on the command line.

ngrok http 80

For details on how to fully leverage command line usage, see ngrok's official documentation.

contributing

If you find issues, report them on GitHub. Pull requests for fixes and features are also warmly welcomed.