Skip to main content
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:
OSSupported architectures
Windows64-bit, 32-bit (x86-64, x86)
macOSIntel, Apple Silicon (x86-64, arm64)
Linuxx86-64, x86, arm, arm64, mips, mips64, mips64le, mipsle, ppc64, ppc64le, s390x
FreeBSDx86-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. 
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
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.