Expose a Service with the ngrok Agent

Each example below starts an endpoint and forwards its traffic to a service you’re already running. They are all the same shape: ngrok <protocol> <what to forward to>, with flags for anything you want to change about the endpoint. Before you begin, install the CLI and add your authtoken.

HTTP endpoint

The common case: a web app on a local port, reachable at your account’s dev domain. Every ngrok account, including free accounts, gets a dev domain like your-assigned-name.ngrok-free.dev. When you don’t pass --url, the agent uses it automatically, and it doesn’t change when you restart the agent. Serve your web app listening at port 8080 on your dev domain

ngrok http 8080

Pre-defined domain

Pass --url to serve on a domain you choose instead of your dev domain, such as an ngrok subdomain like example.ngrok.app (Hobbyist and Pay-as-you-go plans) or your own domain (Pay-as-you-go plan). Serve a web app on example.ngrok.app

ngrok http 8080 --url https://example.ngrok.app

Basic Auth

Put a username and password in front of the service without changing the service itself. Secure your web app with a username + password

ngrok http 80 --traffic-policy-file traffic-policy.yml

traffic-policy.yml

on_http_request:
  - actions:
      - type: basic-auth
        config:
          credentials:
            - username1:password1
            - username2:password2

Forward to non-local

Point the agent at another host on the network, not just localhost. Forward to a service not listening on localhost

ngrok http 192.168.1.2:80

Local HTTPS server

Forward to an upstream that already speaks HTTPS, rather than plain HTTP. Forward to an upstream service listening for https

ngrok http https://localhost:8443

Forwarding to an IPv6 address

Forward to an upstream reachable only over IPv6. The ngrok agent can also forward to IPv6 addresses

ngrok http '[::1]:80' --url https://ipv6.example.com

ngrok http 'https://[2001:db8::123.123.123.123]:8443' --url https://ipv6.example.com

TCP endpoint

Expose anything that isn’t HTTP, such as a database, SSH, or RDP. Accept traffic to a non-HTTP service.

ngrok tcp 22

TLS endpoint

Accept TLS traffic and pass it through, for protocols wrapped in TLS that aren’t HTTPS. Listen on your-name.ngrok.app for TLS traffic. It could be HTTPS, but any protocol wrapped in TLS is accepted.

ngrok tls 80 \
  --url tls://your-name.ngrok.app \
  --traffic-policy-file traffic-policy.yml

traffic-policy.yml

on_tcp_connect:
  - actions:
      - type: terminate-tls

Multiple endpoints

Run several services from one agent by naming them in a configuration file. Start multiple endpoints defined in the configuration file.

ngrok start foo bar baz

Getting Started

Use Cases

Examples

Connectivity

Traffic Policy

Observability

Network

Resources

Identity & Access

Expose a Service with the ngrok Agent

HTTP endpoint

Pre-defined domain

Basic Auth

Forward to non-local

Local HTTPS server

Forwarding to an IPv6 address

TCP endpoint

TLS endpoint

Multiple endpoints

​HTTP endpoint

​Pre-defined domain

​Basic Auth

​Forward to non-local

​Local HTTPS server

​Forwarding to an IPv6 address

​TCP endpoint

​TLS endpoint

​Multiple endpoints

HTTP endpoint

Pre-defined domain

Basic Auth

Forward to non-local

Local HTTPS server

Forwarding to an IPv6 address

TCP endpoint

TLS endpoint

Multiple endpoints