Run & Scale
TCP Proxy

TCP Proxy

TCP Proxy lets you expose the TCP ports of your Services to the Internet, enabling direct TCP connections such as SSH or connections to databases.

When enabled, Koyeb provisions a unique domain and port that forward traffic directly to your Service's TCP port.

Note: TCP Proxy is currently in private preview, request access to the feature here (opens in a new tab).

This feature is ideal for use cases that require native TCP communication beyond HTTP, WebSocket, HTTP/2, or gRPC protocols.

TCP Proxy is available in the Koyeb control panel (opens in a new tab) and the CLI and API.

Enabling TCP Proxy

To expose a TCP port, you must explicitly enable TCP Proxy for that port in your Service configuration.

Once enabled, a new Deployment will be triggered. During the Deployment, Koyeb provisions:

  • A proxy host – A Koyeb-managed domain used to proxy external traffic.
  • A proxy port – A dynamically assigned TCP port that forwards traffic to your internal port.
Once TCP Proxy is enabled on a port, the assigned proxy port is randomly generated and not predictable ahead of time. However, once assigned, it persists across Deployments—unless you disable and re-enable TCP Proxy for that port, in which case a new port may be generated.

Example

Suppose your Service listens on TCP port 22 (e.g., for SSH access). After enabling TCP Proxy on port 22, your Deployment will be assigned a proxy like:

01.proxy.koyeb.app:2222

You can then connect using a TCP client like nc:

nc 01.proxy.koyeb.app 2222

Or, for SSH:

ssh -p 2222 user@01.proxy.koyeb.app

Things to know

  • A port with TCP Proxy enabled persists across Deployments and Service Pause/Resume operations, meaning the dynamically assigned proxy port will remain unchanged unless TCP Proxy is disabled and re-enabled.
  • Incoming TCP traffic is distributed across all healthy instances of your Service.
  • TCP Proxy is not compatible with Scale to zero at the moment and using them together may lead to unexpected behavior.
  • You can combine HTTP and TCP Proxy on the same Service port.
DomainsMetrics