Skip to main content

TCP Endpoints

Overview​

TCP endpoints enable you to deliver any network service with a TCP-based protocol. They are commonly used to create 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

If you are accepting TLS traffic, you may prefer to create a TLS Endpoint.

Free Plan Usage

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

Quickstart​

Agent Endpoints are the easiest way to get started with ngrok. An agent endpoint is started by a Secure Tunnels agent. The endpoint lives for the lifetime of the process and forwards traffic to a port or URL of your choosing.

This example creates a TCP endpoint on a randomly-assigned URL - e.g. tcp://1.tcp.ngrok.io:12345 and forwards its traffic to a local port.

Loading…

URLs​

URLs are validated differently depending on their binding. Consult the following documentation for details on valid URLs for TCP endpoints:

There is no standard scheme for TCP URLs so ngrok renders them as tcp://.

Static URLs​

If you would like a public TCP endpoint to have a static URL, you must first create a TCP Address. When you create a TCP address, a random hostname and port will be assigned to you, e.g. 1.tcp.ngrok.io:12345.

A TCP address is only needed to make a public TCP endpoint have a static URL. They are not needed for TCP endpoints on other bindings, like internal or kubernetes.

After you have created a TCP Address, specify the address (e.g. 1.tcp.eu.ngrok.io:12345) in the URL when you create the endpoint.

Loading…

Custom domains​

Public TCP endpoints 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.

For example if your TCP address is 5.tcp.ngrok.io:12345, you could create the following CNAME record:

Loading…

And then you can access that TCP endpoint with

Loading…

Traffic Policy​

Attach Traffic Policy to endpoints to route, authenticate and transform the traffic through the endpoint.

Authentication​

When you create public TCP endpoints, you often want to secure them with authentication. You can secure your TCP endpoints with the following Traffic Policy actions. There is a limited set of actions available to authenticate TCP traffic because the TCP protocol is low-level.

Agent Forwarding​

The ngrok agent and Agent SDKs forward traffic that your endpoints receive to upstream services. You specify a URL or port number to instruct the ngrok agent where and how to forward traffic.

Forward to non-local service​

Agents don't just forward to ports on your localhost. You can forward traffic to any address or URL reachable from the agent. For example, if you want to forward traffic to a Postgres server running on your network at 192.168.1.2:5432:

Loading…

PROXY Protocol​

When you forward traffic to an upstream TCP service, becuase traffic is coming from the ngrok agent, it won't know the client's original IP address. You can add the PROXY protocol header on connections to your upstream service to send connection information like the original client IP address to your upstream service. You will need to configure your upstream service to handle the PROXY protocol header.

Loading…

Observability​

Traffic Inspector​

Traffic Inspector does not support TCP endpoints.

Log Export Events​

You can export logs of traffic to TCP endpoints with ngrok's events system. The following events are published for log exporting:

EventWhen
tcp_connection_closed.v0Published when a TCP connection to a TCP endpoint completes.

Limits & Timeouts​

Contact us if you need to configure limits and timeouts on connections to TCP endpoints.

LimitNameNotes
5 minutesClient Idle TimeoutTime since data was last transmitted by the upstream service
5 minutesServer Idle TimeoutTime since data was last transmitted by the upstream service
No limitData transmittedData transmitted by the client or upstream service

Errors​

If an error is encountered while handling connections to a TCP endpoint for any reason (e.g. traffic policy action error, 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.

Use the observability features to understand connection handling errors.

API​

TCP Endpoints can be created programatically. Consult the documentation on Endpoint APIs.

Pricing​

TCP endpoints are available on all plans. Consult the Endpoints Pricing documentation for billing details.

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

See TCP Addresses pricing for details on pricing for fixed TCP Addresses.