Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

For detailed instructions on using ngrok with Kubernetes, check out the k8s quickstart.
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: the Docker version of ngrok follows the same convention as the agent, for example: 
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http 80                            # secure public URL for port 80 web server
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http --url baz.ngrok.dev 8080   # port 8080 available at baz.ngrok.dev
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http foo.dev:80                    # tunnel to host:port instead of localhost
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http https://localhost:5001        # expose a local https server running on port 5001
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest tcp 22                             # tunnel arbitrary TCP traffic to port 22
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest tls --url foo.com 443           # TLS traffic for foo.com to port 443
docker run -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest start foo bar baz                  # start tunnels from the configuration file

​
Basic usage

The ngrok docker image wraps the ngrok agent executable. Read the documentation for the ngrok agent CLI docs for all commands.

​
Run an ngrok Agent pointed at localhost:80

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

​
Choose a URL

If you don’t choose a URL, ngrok will assign one for you. 
docker run -it -e NGROK_AUTHTOKEN=your_token ngrok/ngrok http host.docker.internal:80 --url https://your-url-here.ngrok.app

​
Add a Traffic Policy

Traffic Policy is a configuration language that offers you the flexibility to filter, match, manage, and orchestrate traffic to your endpoints. 
docker run -it -v $(pwd)/traffic-policy.yml:/etc/traffic-policy.yml ngrok/ngrok:alpine http host.docker.internal:80 --traffic-policy-file /etc/traffic-policy.yml
traffic-policy.yml
on_http_request:
  - actions:
      - type: basic-auth
        config:
          credentials:
            - user:password123

​
Run in the background

docker run -d --restart unless-stopped -e NGROK_AUTHTOKEN=your_token --name ngrok-agent ngrok/ngrok http host.docker.internal:80

​
Use a configuration file

Run the ngrok agent with the config file ./ngrok.yml from the host machine: 
docker run -it -v $(pwd)/ngrok.yml:/etc/ngrok.yml -e NGROK_CONFIG=/etc/ngrok.yml ngrok/ngrok:alpine http host.docker.internal:80

​
Pull the ngrok container image

docker pull ngrok/ngrok

​
Traffic Inspection

​
Traffic Inspector

Use Traffic Inspector on your ngrok dashboard

​
Local web inspection on localhost:4040 (Legacy)

The agent serves this web interface on port 4040 so you’ll need to publish it as well with -p 4040:4040 
docker run -it -p 4040:4040 ngrok/ngrok http host.docker.internal:80
If you are unable to view the web inspection interface typically available at http://localhost:4040, you may need to map your host port 4040 to port 4040 on the container, for example: 
docker run -p 4040:4040 -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http host.docker.internal:80