alexdlaird/pyngrok repository overview

pyngrok⁠ gives Python the complete ngrok agent⁠, with programmatic tunnels for ingress, inspection, webhooks, demos, and APIs. ngrok⁠ is a reverse proxy that opens secure tunnels from public URLs to localhost, and because pyngrok runs the real agent, you get everything it offers, from traffic policies and OAuth to its web inspector and request replay, all callable from Python. This repo provides it in pre-built container images on Docker Hub⁠.

⁠Basic Usage

To launch the container into a Python shell, run:

docker run -e NGROK_AUTHTOKEN=$NGROK_AUTHTOKEN -it alexdlaird/pyngrok

If you want to start in a bash shell instead of Python, you can launch the container with:

docker run -e NGROK_AUTHTOKEN=$NGROK_AUTHTOKEN -it alexdlaird/pyngrok /bin/bash

The pyngrok-example-flask repository⁠ also includes a Dockerfile and make commands to run it, if you would like to see a complete example.

⁠Config File

ngrok will look for its config file in this container at /root/.config/ngrok/ngrok.yml. If you want to provide a custom config file, specify a mount to this file when launching the container.

docker run -v ./ngrok.yml:/root/.config/ngrok/ngrok.yml -it alexdlaird/pyngrok

⁠Web Inspector

If you want to use ngrok's web inspector, be sure to expose its port. Ensure whatever config file you use sets web_addr: 0.0.0.0:4040⁠ (the config provisioned in the pre-built images already does this).

docker run --env-file .env -p 127.0.0.1:4040:4040 -it alexdlaird/pyngrok

⁠Docker Compose

Here is an example of how you could instantiate the container with docker-compose.yml, where you also want a given Python script to run on startup:

services:
  ngrok:
    image: alexdlaird/pyngrok
    env_file: ".env"
    command: [ "python", "/root/my-script.py" ]
    volumes:
      - ./my-script.py:/root/my-script.py
    ports:
      - "127.0.0.1:4040:4040"

Then launch it with:

docker compose up -d

⁠Documentation

For more advanced usage of pyngrok, its official documentation is available on Read the Docs⁠.

⁠Command Line Usage

The pyngrok package puts the default ngrok binary on your path in the container, so all features of ngrok are also available on the command line.

docker run -e NGROK_AUTHTOKEN=$NGROK_AUTHTOKEN -it alexdlaird/pyngrok ngrok http 80

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

⁠Tags & Version Map

Images are multi-architectural, and tagged with the following format:

alexdlaird/pyngrok:py$PYTHON_VERSION-$DISTRO-$VERSION

The following tag variants⁠ are available:

• $PYTHON_VERSION has 3.11 through 3.15
  • If none given, defaults to latest
• $DISTRO has alpine, or Debian flavors of bookworm, slim-bookworm
  • If none given, defaults to slim-bookworm
• $VERSION matches the container version in table below
  • If none given, defaults to latest

The first three numbers of the container version correspond to the version of pyngrok it has installed, and you can just use the pyngrok version to grab the latest tagged image for that release.

This table shows the ngrok version that is published in each image: