API Documentation

This part of the documentation covers the interfaces used to develop with pyngrok.

Main ngrok Interface

class pyngrok.ngrok.NgrokTunnel(data=None)[source]

Bases: object

An object containing information about an ngrok tunnel.

Variables:
  • name (string) – The name of the tunnel.
  • proto (string) – A valid tunnel protocol.
  • uri (string) – The tunnel URI, a relative path that can be used to make requests to the ngrok web interface.
  • public_url (string) – The public ngrok URL.
  • config (dict) – The config for the tunnel.
  • metrics (dict) – Metrics for the tunnel.
pyngrok.ngrok.api_request(url, method='GET', data=None, params=None, timeout=4)[source]

Invoke an API request to the given URI, returning JSON data from the response as a dict.

Parameters:
  • url (string) – The request URI.
  • method (string, optional) – The HTTP method, defaults to “GET”.
  • data (dict, optional) – The request body.
  • params (list, optional) – The URL parameters.
  • timeout (float, optional) – The request timeout, in seconds.
Returns:

The response from the request.

Return type:

dict

pyngrok.ngrok.connect(port=80, proto='http', name=None, options=None, ngrok_path=None, config_path=None, timeout=4, auth_token=None, region=None)[source]

Establish a new ngrok tunnel to the given port and protocol, returning the connected public URL that tunnels to the local port.

If ngrok is not installed at the given path, calling this method will first download and install ngrok.

If ngrok is not running, calling this method will start a process for the given path.

Parameters:
  • port (int, optional) – The local port to which to tunnel, defaults to 80.
  • proto (string, optional) – The protocol to tunnel, defaults to “http”.
  • name (string, optional) – A friendly name for the tunnel.
  • options (dict, optional) – Parameters passed to configuration for the ngrok tunnel.
  • ngrok_path (string, optional) – A ngrok binary override (instead of using pyngrok’s).
  • config_path (string, optional) – A config path override. Ignored if ngrok is already running.
  • timeout (float, optional) – The request timeout, in seconds.
  • auth_token (string, optional) – An authtoken override. Ignored if ngrok is already running.
  • region (string, optional) – A region override. Ignored if ngrok is already running.
Returns:

The connected public URL.

Return type:

string

pyngrok.ngrok.disconnect(public_url, ngrok_path=None, config_path=None, timeout=4)[source]

Disconnect the ngrok tunnel for the given URL.

If ngrok is not installed at the given path, calling this method will first download and install ngrok.

If ngrok is not running, calling this method will start a process for the given path.

Parameters:
  • public_url (string) – The public URL of the tunnel to disconnect.
  • ngrok_path (string, optional) – A ngrok binary override (instead of using pyngrok’s).
  • config_path (string, optional) – A config path override.
  • timeout (float, optional) – The request timeout, in seconds.
pyngrok.ngrok.ensure_ngrok_installed(ngrok_path)[source]

Ensure ngrok is installed at the given path, downloading and installing the binary for the current system if not.

Parameters:ngrok_path (string) – The path to the ngrok binary.
pyngrok.ngrok.get_ngrok_process(ngrok_path=None, config_path=None, auth_token=None, region=None)[source]

Retrieve the current ngrok process for the given path.

If ngrok is not installed at the given path, calling this method will first download and install ngrok.

If ngrok is not running, calling this method will start a process for the given path.

Parameters:
  • ngrok_path (string, optional) – A ngrok binary override (instead of using pyngrok’s).
  • config_path (string, optional) – A config path override. Ignored if ngrok is already running.
  • auth_token (string, optional) – An authtoken override. Ignored if ngrok is already running.
  • region (string, optional) – A region override. Ignored if ngrok is already running.
Returns:

The ngrok process.

Return type:

NgrokProcess

pyngrok.ngrok.get_tunnels(ngrok_path=None, timeout=4)[source]

Retrieve a list of all active ngrok tunnels.

If ngrok is not installed at the given path, calling this method will first download and install ngrok.

If ngrok is not running, calling this method will start a process for the given path.

Parameters:
  • ngrok_path (string, optional) – A ngrok binary override (instead of using pyngrok’s).
  • timeout (float, optional) – The request timeout, in seconds.
Returns:

The currently active ngrok tunnels.

Return type:

list[NgrokTunnel]

pyngrok.ngrok.kill(ngrok_path=None)[source]

Terminate the ngrok processes, if running, for the given path. This method will not block, it will just issue a kill request.

Parameters:ngrok_path (string, optional) – A ngrok binary override (instead of using pyngrok’s).
pyngrok.ngrok.main()[source]

Entry point for console_scripts.

pyngrok.ngrok.run(args=None)[source]

Start a blocking ngrok process with the default binary and the system’s command line args.

Parameters:args (list, optional) – Arguments to be passed to the ngrok process.
pyngrok.ngrok.set_auth_token(token, ngrok_path=None, config_path=None)[source]

Set the ngrok auth token in the config file, enabling authenticated features (for instance, more concurrent tunnels, custom subdomains, etc.).

If ngrok is not installed at the given path, calling this method will first download and install ngrok.

Parameters:
  • token (string) – The auth token to set.
  • ngrok_path (string, optional) – A ngrok binary override (instead of using pyngrok’s).
  • config_path (string, optional) – A config path override.

Process

class pyngrok.process.NgrokProcess(ngrok_path, config_path, proc)[source]

Bases: object

An object containing information about the ngrok process.

Variables:
  • ngrok_path (string) – The path to the ngrok binary used to start this process.
  • config_path (string) – The path to the ngrok config used.
  • proc (object) – The child subprocess.Popen that is running ngrok.
  • api_url (string) – The API URL for the ngrok web interface.
  • startup_logs (string) – The ngrok startup logs.
  • startup_error (string) – If ngrok startup failed, this will be the log of the failure.
healthy()[source]
log_boot_line(line)[source]
pyngrok.process.get_process(ngrok_path, config_path=None, auth_token=None, region=None)[source]

Retrieve the current ngrok process for the given path. If ngrok is not currently running for the given path, a new process will be started and returned.

If ngrok is not running, calling this method will start a process for the given path.

Parameters:
  • ngrok_path (string) – The path to the ngrok binary.
  • config_path (string, optional) – A config path override. Ignored if ngrok is already running.
  • auth_token (string, optional) – An authtoken override. Ignored if ngrok is already running.
  • region (string, optional) – A region override. Ignored if ngrok is already running.
Returns:

The ngrok process.

Return type:

NgrokProcess

pyngrok.process.kill_process(ngrok_path)[source]

Terminate the ngrok processes, if running, for the given path. This method will not block, it will just issue a kill request.

Parameters:ngrok_path (string) – The path to the ngrok binary.
pyngrok.process.run_process(ngrok_path, args)[source]

Start a blocking ngrok process with the given args.

Parameters:
  • ngrok_path (string) – The path to the ngrok binary.
  • args (list) – The args to pass to ngrok.
pyngrok.process.set_auth_token(ngrok_path, token, config_path=None)[source]

Set the ngrok auth token in the config file, enabling authenticated features (for instance, more concurrent tunnels, custom subdomains, etc.).

Parameters:
  • ngrok_path (string) – The path to the ngrok binary.
  • token (string) – The auth token to set.
  • config_path (string, optional) – A config path override.

Installer

pyngrok.installer.get_ngrok_bin()[source]

Retrieve the ngrok command for the current system.

Returns:The ngrok command.
Return type:string
pyngrok.installer.install_default_config(config_path, data='')[source]

Install the default ngrok config if one is not already present.

Parameters:
  • config_path (string) – The path to where the ngrok config should be installed.
  • data (string, optional) – A JSON string of things to add to the default config.
pyngrok.installer.install_ngrok(ngrok_path, timeout=None)[source]

Download and install ngrok for the current system in the given location.

Parameters:
  • ngrok_path (string) – The path to where the ngrok binary will be downloaded.
  • timeout (float, optional) – The request timeout, in seconds.

Exceptions

exception pyngrok.exception.PyngrokError[source]

Bases: Exception

Raised when a general pyngrok error has occurred.

exception pyngrok.exception.PyngrokNgrokError(error, ngrok_logs=None, ngrok_error=None)[source]

Bases: pyngrok.exception.PyngrokError

Raised when an error occurs interacting directly with the ngrok binary.

Variables:
  • error (string) – A description of the error being thrown.
  • ngrok_logs (string) – The ngrok logs, which may be useful for debugging the error.
  • ngrok_error (string) – The error that caused the ngrok process to fail.
exception pyngrok.exception.PyngrokNgrokHTTPError(error, url, status_code, message, headers, body)[source]

Bases: pyngrok.exception.PyngrokNgrokError

Raised when an error occurs making a request to the ngrok web interface. The body contains the error response received from ngrok.

Variables:
  • error (string) – A description of the error being thrown.
  • url (string) – The request URL that failed.
  • status_code (int) – The response status code from ngrok.
  • message (string) – The response message from ngrok.
  • headers (dict) – The request headers sent to ngrok.
  • body (string) – The response body from ngrok.
exception pyngrok.exception.PyngrokNgrokInstallError[source]

Bases: pyngrok.exception.PyngrokError

Raised when an error has occurred while downloading and installing the ngrok binary.

exception pyngrok.exception.PyngrokNgrokURLError(error, reason)[source]

Bases: pyngrok.exception.PyngrokNgrokError

Raised when an error occurs when trying to initiate an API request.

Variables:
  • error (string) – A description of the error being thrown.
  • reason (string) – The reason for the URL error.
exception pyngrok.exception.PyngrokSecurityError[source]

Bases: pyngrok.exception.PyngrokError

Raised when a pyngrok security error has occurred.