Agent Packaging and Distribution

The ngrok agent is a standalone native executable with zero runtime dependencies. It runs on all major operating systems and architectures, and is distributed through multiple channels to fit your deployment environment.

Installing the ngrok agent

The ngrok agent is available on many platforms and through many popular package managers. Visit the ngrok download page for specific installation instructions based on your setup.

Standalone binary

The ngrok agent is available as a standalone binary with no runtime dependencies. Download it directly from the ngrok download page. The agent supports the following platforms:

OS	Supported architectures
Windows	64-bit, 32-bit (`x86-64`, `x86`)
macOS	Intel, Apple Silicon (`x86-64`, `arm64`)
Linux	`x86-64`, `x86`, `arm`, `arm64`, `mips`, `mips64`, `mips64le`, `mipsle`, `ppc64`, `ppc64le`, `s390x`
FreeBSD	`x86-64`, `x86`, `arm`

The agent can update itself with the ngrok update command, even if you didn’t install it with a package manager.

Docker

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.

Debian Linux
Windows or Mac

docker run --net=host -it -e NGROK_AUTHTOKEN=xyz ngrok/ngrok:latest http 80

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

For MacOS and Windows, you must use the special URL host.docker.internal as described in the Docker networking documentation.This also applies to the upstream.url endpoint property in your ngrok config file. For example:

endpoints:
  - name: example
    url: https://example.ngrok.app
    upstream:
      url: http://host.docker.internal: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

For more details, see the Using ngrok with Docker documentation.

Docker Desktop extension

The ngrok Docker Desktop Extension lets you forward traffic from internet-accessible endpoint URLs to your local Docker containers directly from the Docker Desktop UI. Install the ngrok Docker Desktop Extension to get started. For more details, see the Docker Desktop documentation.

Kubernetes

The ngrok Kubernetes Operator lets you manage ngrok resources natively from within your Kubernetes cluster using Helm. Install the Operator with Helm:

helm install ngrok-operator ngrok/ngrok-operator \
  --namespace ngrok-operator \
  --create-namespace \
  --set credentials.apiKey=$NGROK_API_KEY \
  --set credentials.authtoken=$NGROK_AUTHTOKEN

For more details, see the Kubernetes Operator documentation.

Security

Reliability

Private addressability

Production ready

Installing the ngrok agent

Standalone binary

Docker

Basic usage

Run an ngrok Agent pointed at localhost:80

Choose a URL

Add a Traffic Policy

`traffic-policy.yml`

Run in the background

Use a configuration file

Pull the ngrok container image

Traffic Inspection

Traffic Inspector

Local web inspection on localhost:4040 (Legacy)

Docker Desktop extension

Kubernetes

​Installing the ngrok agent

​Standalone binary

​Docker

​Basic usage

​Run an ngrok Agent pointed at localhost:80

​Choose a URL

​Add a Traffic Policy

traffic-policy.yml

​Run in the background

​Use a configuration file

​Pull the ngrok container image

​Traffic Inspection

​Traffic Inspector

​Local web inspection on localhost:4040 (Legacy)

​Docker Desktop extension

​Kubernetes

Installing the ngrok agent

Standalone binary

Docker

Basic usage

Run an ngrok Agent pointed at localhost:80

Choose a URL

Add a Traffic Policy

`traffic-policy.yml`

Run in the background

Use a configuration file

Pull the ngrok container image

Traffic Inspection

Traffic Inspector

Local web inspection on localhost:4040 (Legacy)

Docker Desktop extension

Kubernetes