Install ngrok on Linux

ngrok allows you to create secure ingress to any app, device, or service without spending hours learning arcane networking technologies. You can get started with a single command or a single line of code. What is ngrok? ngrok is an all-in-one cloud networking platform that secures, transforms, and routes traffic to services running anywhere. In this guide, you’ll walk through the process of installing the ngrok agent on a remote Linux device, ensuring the agent runs integrated into your operating system, restricting traffic to trusted origins, and preparing to scale from a single device to a full fleet.

1. Install the ngrok Agent

To download and install the ngrok agent on your remote Linux device, follow these steps:

Open a terminal into your remote Linux device.
Download the latest ngrok binary for your Linux distribution. You can find the correct binary on the ngrok download page: Select your operating system, select the version, and copy the link that appears in the Download button. Below is an example for x86-64:

wget https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-linux-amd64.tgz

Equinox is fully owned by ngrok and used exclusively for building and distributing ngrok binaries. See the FAQ page for more details.

Unzip the downloaded file and move it to a directory in your PATH. Below is an example for /usr/local/bin:

sudo tar xvzf ./ngrok-v3-stable-linux-amd64.tgz -C /usr/local/bin

Now that you have installed ngrok on your Linux device, link it to your ngrok account by using your authtoken:

ngrok authtoken NGROK_AUTHTOKEN

Note: Replace NGROK_AUTHTOKEN with your unique ngrok authtoken found in the ngrok dashboard.

2. Enable SSH access

To enable remote SSH access to your device via ngrok:

Test that the ngrok agent is configured correctly by starting a TCP tunnel on your remote device.

TCP endpoints are only available on a free plan after adding a valid payment method to your account. If you get a different error, ensure your authtoken is configured correctly.

ngrok tcp 22

The ngrok agent assigns you a TCP address and port. Use these values to test the SSH access via ngrok by running the following command from another server or from a desktop.

ssh -p NGROK_PORT USER@NGROK_TCP_ADDRESS

Note: Replace the variables in the command line with the following:

NGROK_PORT: The port number of the ngrok agent (that is, if the agent shows tcp://1.tcp.ngrok.io:12345, your port number is 12345.
USER: A valid ssh login to access your remote device’s operating system.
NGROK_TCP_ADDRESS: The address of the ngrok agent (that is, if the agent shows tcp://1.tcp.ngrok.io:12345, your TCP address is 1.tcp.ngrok.io.

3. Adding IP restrictions

Once you confirmed that you have connectivity to the device, add some security so that you are the only one who can access it. Note: This capability requires ngrok’s IP Restrictions feature, which is only available with a paid subscription.

On the remote Linux device terminal, stop the ngrok process using the ctrl+c command.
Add an allow rule to restrict access to your Linux device to an IP address or a range of IP addresses.

ngrok tcp 22 --cidr-allow ALLOWED_IP_ADDRESS_CIDR

Note: Replace ALLOWED_IP_ADDRESS_CIDR with the CIDR notation for the allowed IP Address(es) (that is, 123.123.123.0/24).

Alternatively, you can create an IP policy in the ngrok dashboard (under Security > IP Restrictions), and leverage the same policy to control access to your entire device fleet.

4. Run ngrok as a service so you don’t need to manually restart

Read more about the ngrok servicecommand which allows you to run and control an ngrok service on the operating system. Run ngrok as a service.). The ngrok agent works with native OS services like systemd. This helps you ensure that the ngrok service is available even after the machine restarts. Before doing this, it’s useful to reserve a TCP address in the ngrok dashboard which allows you to reuse the same address each time the device is restarted.

Navigate to the ngrok Dashboard and access Gateway > TCP Addresses. Create a new TCP address with a description and click Save. Your new TCP address will look something like 1.tcp.ngrok.io:12345.

Update the ngrok config file in your Linux device to start the ngrok agent using this TCP address.

Open the ngrok config file:

ngrok config edit

Add the following to the end of the file and then save it:

endpoints:
  - name: device-ssh
    url: tcp://NGROK_TCP_ADDRESS
    upstream:
      url: 22
    traffic_policy:
      on_tcp_connect:
        - actions:
            - type: restrict-ips
              config:
                allow:
                  - ALLOWED_IP_ADDRESS_CIDR

Note: Make sure to replace NGROK_TCP_ADDRESS with the address you reserved earlier in the ngrok dashboard (that is, 1.tcp.ngrok.io:12345) and ALLOWED_IP_ADDRESS_CIDR with the CIDR notation of the allowed IP Address(es) (that is, 123.123.123.0/24). Note: Make note of the location of the ngrok.yml file.

Enable ngrok in service mode:

ngrok service install --config $HOME/.config/ngrok/ngrok.yml

You may need to run this command using sudo depending on your system

Run the following command to ensure your operating system launches ngrok with the ssh ingress whenever your device starts:

ngrok service start

You may need to run this command using sudo depending on your system

With ngrok running on your device, you should be able to SSH into the device using the reserved address from the dashboard.

ssh -p NGROK_PORT user@NGROK_TCP_ADDRESS

What’s next?

You’ve connected one device. The next step is understanding how ngrok works when that one device becomes ten, a hundred, or ten thousand.

Learn the device gateway model

The Device Gateway guide walks through the full picture: giving every device a secure, addressable endpoint, keeping access policy in the cloud so you can update it without firmware pushes or truck rolls, and managing your entire fleet programmatically through the ngrok API.

Scaling from one device to a fleet

When your devices live in networks you don’t own—kiosks in stores, POS terminals, medical devices in clinics, industrial controllers on factory floors—ngrok is a better fit than a mesh VPN. Enrolling each device into a VPN mesh means placing your network inside someone else’s, at fleet scale. ngrok’s model avoids that entirely:

A lightweight agent on each device dials out, so it traverses CGNAT and hostile firewalls by default—no inbound ports or firewall changes on networks you don’t control.
Each device gets one named endpoint, addressable by your cloud, technicians, and customers.
Each device gets its own credentials, which you can revoke individually without touching the rest of the fleet.
Everything is automatable via the API across thousands of units, including remote health checks, stop, start, and updates for every agent in your fleet.

For a deeper comparison of the two models, see ngrok vs. Tailscale.

Talk to us about fleet pricing

Running ngrok across a fleet doesn’t have to mean list pricing. Contact our sales team to discuss per-device and fleet pricing for your deployment.

Use cases

The ngrok platform

Installation Guides

1. Install the ngrok Agent

2. Enable SSH access

3. Adding IP restrictions

4. Run ngrok as a service so you don’t need to manually restart

What’s next?

Learn the device gateway model

Scaling from one device to a fleet

Talk to us about fleet pricing

​1. Install the ngrok Agent

​2. Enable SSH access

​3. Adding IP restrictions

​4. Run ngrok as a service so you don’t need to manually restart

​What’s next?

​Learn the device gateway model

​Scaling from one device to a fleet

​Talk to us about fleet pricing

1. Install the ngrok Agent

2. Enable SSH access

3. Adding IP restrictions

4. Run ngrok as a service so you don’t need to manually restart

What’s next?

Learn the device gateway model

Scaling from one device to a fleet

Talk to us about fleet pricing