Skip to main content

Download & Install

The fastest way to put anything on the internet.

DockerAgent

1

Install the ngrok agent

docker pull ngrok/ngrok
2

Start an endpoint

docker run -it \  -e NGROK_AUTHTOKEN="<YOUR_AUTHTOKEN>" ngrok/ngrok:latest \  http host.docker.internal:80
docker run --net=host -it -e NGROK_AUTHTOKEN="<YOUR_AUTHTOKEN>" ngrok/ngrok:latest http 80

Don’t have an authtoken? for a free account.

Open your ngrok URL in a browser to see it working!

Watch

Expose any container with ngrok

You’re all set. What’s next?

Copy the policy below into a local policy.yaml file.

docker run -it \  -v $(pwd)/policy.yaml:/etc/traffic-policy.yml \  -e NGROK_AUTHTOKEN="<YOUR_AUTHTOKEN>" ngrok/ngrok:latest \  http host.docker.internal:80 \  --traffic-policy-file /etc/traffic-policy.yml
contents of policy.yaml
on_http_request:  # redirect users to Google to log in  - actions:    - type: oauth      config:        provider: google   # allow logins *only* from acme.com  - expressions:    - "!actions.ngrok.oauth.identity.email.endsWith('@acme.com')"    actions:    - type: deny

Copy the policy below into a local policy.yaml file.

docker run -it \  -v $(pwd)/policy.yaml:/etc/traffic-policy.yml \  -e NGROK_AUTHTOKEN="<YOUR_AUTHTOKEN>" ngrok/ngrok:latest \  http host.docker.internal:80 \  --traffic-policy-file /etc/traffic-policy.yml
contents of policy.yaml
on_http_request:  # verify webhook signatures from your provider  - actions:    - type: verify-webhook      config:        provider: github        # access your signing key from a secure ngrok vault        # no cleartext secrets in your policy, friend        secret: ${secrets.get('webhook-vault', 'github-secret')}

Copy the policy below into a local policy.yaml file.

docker run -it \  -v $(pwd)/policy.yaml:/etc/traffic-policy.yml \  -e NGROK_AUTHTOKEN="<YOUR_AUTHTOKEN>" ngrok/ngrok:latest \  http host.docker.internal:80 \  --traffic-policy-file /etc/traffic-policy.yml
contents of policy.yaml
on_http_request:  # redirect users to your OpenID provider to log in  - actions:    - type: openid-connect      config:        issuer_url: https://accounts.google.com        # access your OIDC details from a secure ngrok vault        client_id: ${secrets.get('auth-vault', 'oidc-client-id')}        client_secret: ${secrets.get('auth-vault', 'oidc-client-secret')}        scopes:          - openid          - email

Copy the policy below into a local policy.yaml file.

docker run -it \  -v $(pwd)/policy.yaml:/etc/traffic-policy.yml \  -e NGROK_AUTHTOKEN="<YOUR_AUTHTOKEN>" ngrok/ngrok:latest \  http host.docker.internal:80 \  --traffic-policy-file /etc/traffic-policy.yml
contents of policy.yaml
on_http_request:  - actions:    - type: basic-auth      config:        credentials:          # add up to 10 username:password pairs, all stored safely in a vault          - user01:${secrets.get('basic-auth-vault', 'password01')}          - user02:${secrets.get('basic-auth-vault', 'password02')}

Inspect every detail of your traffic

Watch the flow in real time, then dig into the headers, body, latency, response, and more for every request.

Configure your agent

Configure settings like multiple endpoints, load balancing, and traffic transformation with Traffic Policy.

Bring your own domain

Paid feature

Create a DNS CNAME record to use your own domain name for your endpoint URL.

docker run -it \  -e NGROK_AUTHTOKEN="<YOUR_AUTHTOKEN>" ngrok/ngrok:latest \  http host.docker.internal:80 --url https://app.acme.com

Run as background service

Recover connectivity after unexpected software or hardware failures.

docker run -d --restart unless-stopped \  -e NGROK_AUTHTOKEN="<YOUR_AUTHTOKEN>" ngrok/ngrok:latest \  http host.docker.internal:80