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.

ngrok is a universal gateway, which means it allows you to connect to any app, IoT device, or service without networking expertise. This guide walks you through an example scenario using ngrok to set up a secure, controlled remote access solution for IoT devices. The solution enables you to grant trusted parties access to critical systems without exposing those systems to the public internet or relying on complex VPN setups.

​
Example scenario

Consider a situation where a network of smart factories is coming online, each with IoT-connected controllers, security cameras, and machine sensors. In this scenario, each factory’s network blocks inbound connections. However, your technicians need to do remote maintenance on these cameras via SSH, and your SaaS platform’s cloud software needs access to device data via a web app for mission-critical operations.

​
Architectural reference

Architecture diagram: one ngrok agent per factory routing cloud traffic to internal devices

​
Why only one ngrok agent per factory?

Traditionally, you might assume that every device inside the factory needs its own ngrok agent, but this isn’t necessary. A single ngrok agent is installed on a network-accessible machine inside the factory. The agent acts as a central gateway (jumpbox) that can reach any machine on the local network, eliminating the need for multiple agents.

​
What you’ll need

  • An ngrok account. If you don’t have one, sign up.
  • An ngrok agent configured in a remote IoT-based network. See the getting started guide for instructions on how to install the ngrok agent.

​
1. Create a service user and authtoken for isolated network access

First, create a service user and an associated authtoken for each of your factories. A service user is intended for automated systems that programmatically interact with your ngrok account (other platforms sometimes call this concept a Service Account). Create a separate service user and associated authtoken for each of your factories so that:
  • Their usage of your ngrok account is isolated and scoped with a specific permission set
  • If an agent is compromised, you can revoke its access independently
  • Agent start/stop audit events are properly attributed to each customer
  • Your ngrok agents don’t stop working if the human user who set them up leaves your ngrok account
Navigate to the Service Users section of your dashboard and click New Service User. Service Users page with New Service User button Next, create an authtoken assigned to this specific service user. Authtokens page showing a new authtoken assigned to a service user

​
2. Install the ngrok agent within your remote network and configure internal Agent Endpoints in ngrok.yml

Configure the agent to create internal Agent Endpoints that point to the devices you want to remotely access. This connects the devices to your ngrok account, but nothing can connect to them until you complete the subsequent steps. The configuration to achieve this is shown in the example agent configuration file below. Internal Agent Endpoints are private endpoints that only receive traffic when forwarded through the forward-internal Traffic Policy action. This allows you to route traffic to an application through ngrok without making it publicly addressable. Internal Agent Endpoint URL hostnames must end with .internal. After installing the ngrok agent, define internal Agent Endpoints for each service you want to remotely access inside the ngrok configuration file. You can install ngrok and its configuration file at /path/to/ngrok/ngrok.yml and the executable at /path/to/ngrok/ngrok. 
version: 3

agent:
  authtoken: AUTHTOKEN_CREATED_IN_STEP_1

endpoints:
  - name: Internal Endpoint for Controller
    url: https://controller.internal
    upstream:
      url: 8080 
  - name: Internal Endpoint for Sensor
    url: https://sensor.internal
    upstream:
      url: 8081 
  - name: Internal Endpoint for Security Camera
    url: tcp://camera.internal:22
    upstream:
      url: 22

​
3. Reserve a TCP address for security camera connectivity

You need to reserve a TCP address to create a TCP Cloud Endpoint, which you’ll do in the next step. Reserving the address holds it exclusively for your ngrok account. Reserved TCP addresses page with a newly reserved address

​
4. Create your Cloud Endpoints and attach a Traffic Policy

Cloud Endpoints are persistent, always-on endpoints whose creation, deletion, and configuration is managed centrally via the dashboard or API. They exist permanently until explicitly deleted. Cloud Endpoints don’t forward their traffic to an agent by default—they only use their attached Traffic Policy to handle connections. Create a public Cloud Endpoint in the ngrok dashboard by navigating to Endpoints and clicking New. Endpoints page with New button to create a Cloud Endpoint Additionally, create Cloud Endpoints for the sensor and camera: https://sensor.acme.com and tcp://1.tcp.ngrok.io:12345 (using your reserved TCP address). Click on your newly created controller Cloud Endpoint and replace the default Traffic Policy with: 
on_http_request:
  - actions:
      - type: forward-internal
        config:
          url: https://controller.internal
Click on your newly created sensor Cloud Endpoint and replace the default Traffic Policy with: 
on_http_request:
  - actions:
      - type: forward-internal
        config:
          url: https://sensor.internal
Click on your newly created camera Cloud Endpoint and replace the default Traffic Policy with: 
on_tcp_connect:
  - actions:
      - type: forward-internal
        config:
          url: tcp://camera.internal:22

​
5. Secure your Cloud Endpoints with OAuth, TLS version control, and IP restrictions

Navigate to your newly created Cloud Endpoints in the Endpoints tab on your ngrok dashboard, and apply a Traffic Policy action to each. For this example, apply OAuth to your controller endpoint, enforce a minimum TLS version for your sensor endpoint, and enable IP restrictions for your camera endpoint. Browse the full list of Traffic Policy actions. You can add each action directly to the Cloud Endpoint’s YAML configuration. The final Traffic Policy config for each endpoint is shown below. https://controller.acme.com 
on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google
          client_id: '{your app's oauth client id}'
          client_secret: '{your app's oauth client secret}'
          scopes:
            - https://www.googleapis.com/auth/userinfo.email
  - actions:
      - type: forward-internal
        config:
          url: https://controller.internal
https://sensor.acme.com 
on_tcp_connect:
  - actions:
      - type: terminate-tls
        config:
          min_version: '1.3'
on_http_request: 
  - actions:
      - type: forward-internal
        config:
          url: https://sensor.internal
tcp://1.tcp.ngrok.io:12345 
on_tcp_connect:
  - actions:
      - type: restrict-ips
        config:
          allow:
            - <your source IPs>
  - actions:
      - type: forward-internal
        config:
          url: tcp://camera.internal:22

​
What’s next