Skip to main content

TCP Endpoints

Overview​

ngrok's TCP endpoints enable you to deliver any network service with a TCP-based protocol. For example, it is commonly used to establish connectivity for:

  • Remote access protocols like SSH, VNC and RDP
  • Databases like MySQL, Postgres, MSSQL and SQLite
  • IoT protocols like MQTT
  • Gaming servers like Minecraft
warning

TCP endpoints are only available on a free plan after adding a valid payment method to your account.

If the service you are delivering uses TLS, prefer to create a TLS Endpoint.

Because the TCP protocol is low-level, ngrok offers very little functionality to manipulate TCP traffic beyond restricting access via IP Restrictions.

Example Usage​

Random Address​

Listen on a random TCP address.

Loading…

Fixed Address​

Listen on the TCP Address 1.tcp.eu.ngrok.io:12345. You must create this TCP address ahead of time, see TCP Addresses.

Loading…

Forward to non-local service​

Forward to a non-local Postgres instance listening on your network at 192.168.1.2:5432.

Loading…

PROXY Protocol​

Add a PROXY protocol header on connection to your upstream service. This sends connection information like the original client IP address to your upstream service.

Loading…

Behavior​

Endpoints​

When your TCP endpoint is online, it will be available as an Endpoint resource. Endpoints have URLs, but there is no standard scheme for TCP URLs so ngrok renders them as tcp://.

TCP Addresses​

If you would like your TCP endpoints to be fixed, you must first provision a TCP address. TCP Addresses include a hostname and port component and look like 1.tcp.ngrok.io:12345. When you provision a TCP address, a random address will be assigned to you. If you delete a TCP address, there is no way to provision the same one again. TCP addresses may be managed via the dashboard and via API.

Customization​

TCP Addresses are assigned randomly on an ngrok-controlled hostname with a randomly-assigned port. You may not choose the hostname and you may not select the port.

You may, however, simulate a customized hostname by creating a CNAME record to the hostname of your assigned TCP address. If you do so, be aware that all ports on that hostname, even those provisioned to other accounts will then be available on your domain.

Reference​

Edges​

Edges enable you to centrally manage your endpoints' Module configurations in the ngrok dashboard or API instead of defining them via an Agent or Agent SDK.

  • A TCP Edge is attached to one or more TCP Addresses. For each TCP Address, it creates a TCP Endpoint that it listens for traffic on.
  • When a TCP Address is associated with a TCP Edge, agents may no longer start endpoints on that TCP Address. You can always detach a TCP Address from your Edge if you want to create Endpoints on it from an Agent or Agent SDK.
  • Modules on a TCP Edge are attached directly to the edge itself. There are no Routes.
  • When you create a TCP Edge via the dashboard, it will automatically create a new TCP Address assign it to your Edge.
  • When you create a TCP Edge via the dashboard, it will automatically create a tunnel group backend with a unique label.

Modules​

Use modules to modify the behavior of traffic flowing through your endpoints.

ModuleDescription
IP RestrictionsAllow or deny traffic based on the source IP of connections

Observability​

Use ngrok's events system to capture logs of tcp connections to your endpoints.

When TCP connections to your endpoints are closed, tcp_connection_closed.v0 events are published.

Errors​

If an error is encountered while handling TCP connections to your endpoints for any reason (e.g. no available backends, module rejected a connection or internal server error), the connection will be closed. Because of the low-level nature of the TCP protocol, there is no mechanism used to transmit information about what error code was encountered.

You can use the use the observability primitives to understand the error handling behavior of a connection.

Pricing​

TCP endpoints are available on all plans. TCP endpoints are only available on a free plan after adding a valid payment method to your account.

Fixed TCP Addresses are available on the Pro and Enterprise plans.