Build a reliable Kubernetes port-forwarding workflow, verify it locally, and make the resulting TCP endpoint available remotely
kftray and its terminal companion, kftui, help developers manage Kubernetes port forwards across contexts without repeatedly running individual kubectl commands. This guide explains how to choose an interface, install the project using its official distribution path, create and validate a forward, and troubleshoot common connection problems. Once the local listener is working, we show how to connect it to a Localtonet TCP tunnel without requiring inbound router port forwarding, firewall changes, a VPN, or a public IP address. Because the exact installer, local address, local port, and Kubernetes target depend on your environment, this guide clearly identifies the values you must obtain from your own configuration instead of inventing defaults.
📋 What's in this guide
How kftray and Localtonet fit together
Kubernetes services and pods normally live behind cluster networking. A developer who needs to inspect an internal web application, query a database, call an API, or connect a debugging tool can use port forwarding to create a listener on a local machine. Traffic sent to that local listener is carried through the configured Kubernetes connection to the selected workload.
kftray is a desktop application with system tray integration for managing these forwards. kftui provides a terminal interface, along with CLI functionality intended for scripts and headless use. The two applications share configurations and a Rust backend. The project supports multiple forwards across Kubernetes contexts, forwards to services or pods, TCP and UDP traffic, configuration sharing, and reconnection when pods restart or connections drop.
Localtonet enters the workflow only after kftray has created a working local endpoint. Our client establishes an outbound connection to a Localtonet relay server. A TCP tunnel can then provide a public host and port that sends incoming TCP connections to the address and port on which the kftray forward is listening. No inbound router port forwarding, public IP address, VPN setup, or inbound firewall change is required for this tunnel workflow.
The complete traffic path is:
Remote client → Localtonet public host and port → Localtonet client → kftray local listener → Kubernetes service or pod.
kftray includes reverse-tunneling and public-exposure capabilities of its own. Localtonet is therefore an optional integration rather than a requirement for using kftray. Use the approach that matches your operational and security requirements. The workflow below is useful when you want the working local kftray endpoint to be published and managed through our tunnel platform.
Prerequisites and values to collect
Before installing anything, separate the Kubernetes side of the workflow from the public-access side. kftray must first be able to reach the cluster and create a functional local listener. Localtonet does not repair cluster authentication, Kubernetes authorization, workload selection, or an invalid forwarding configuration.
Prepare a machine from which you can access the intended Kubernetes cluster. Your Kubernetes identity must have permission to perform the operations required by the forwarding workflow. The supplied project evidence does not establish one universal operating-system prerequisite list, package-manager requirement, kubeconfig location, or authentication method. Those details vary by the installation artifact and the way your cluster is administered.
You also need to know which Kubernetes target should receive the traffic. kftray can forward to services or pods, but the correct workload type, namespace, resource, remote port, context, and any other configuration fields are specific to your cluster. Confirm these with the workload owner or your existing Kubernetes configuration.
Record the following values as you configure the forward:
- The Kubernetes context that reaches the intended cluster.
- The target service or pod and its namespace.
- The target port exposed by the selected Kubernetes workload.
- The local listening address selected by the kftray configuration.
- The local listening port selected by the kftray configuration.
- Whether the application protocol uses TCP or UDP.
- The application-level authentication and encryption requirements.
There is no evidence-backed universal kftray port or listening address that should be copied into every setup. The local endpoint comes from your own forwarding configuration. Do not assume a sample port from another guide is correct for your workload.
| Component | Responsibility | Value you must verify |
|---|---|---|
| Kubernetes access | Authenticates to the cluster and authorizes the forwarding operation | Working context, identity, and required permissions |
| kftray or kftui | Creates the local listener and forwards traffic to the workload | Target resource, target port, protocol, local address, and local port |
| Local application test | Confirms that the workload responds through the forward | A protocol-appropriate client and an expected response |
| Localtonet | Connects a public endpoint to the verified local listener | Device token, current relay selection, tunnel type, and local target |
Install kftray or kftui
Start by choosing the interface that fits the machine where the forward will run. kftray is the graphical desktop application with system tray integration. kftui runs in a terminal and includes CLI functionality for scripts and headless use. Both applications share configurations and the same Rust backend, so the choice is primarily about how you want to operate the forwards.
The project currently directs users to its Downloads page and installation guide rather than publishing a single universal installation command in the evidence available for this article. That matters because a guessed package-manager command, filename, operating-system package, or binary path could be incorrect. Use the official kftray website and download path to select the artifact and instructions for your platform.
Choose kftray or kftui
Select kftray when you want a desktop system tray interface. Select kftui when the forward will be managed from a terminal, used in scripts, or run on a headless machine. Install the application on the machine that can already reach and authenticate to the Kubernetes cluster.
Download the platform-appropriate release
Follow the project’s official Downloads and installation path. Match the artifact to your actual operating system and architecture. The supplied evidence does not provide a complete supported-platform matrix or universal package-manager commands, so this guide does not invent them.
Complete the documented installation
Apply the installation steps associated with the downloaded artifact. If your environment requires execution approval, package verification, or an administrator-managed installation process, follow your organization’s policy and the project’s security guidance.
After installation, launch kftray or kftui and confirm that its interface opens successfully. This is only an installation check. It does not yet prove that the application can authenticate to the cluster or that a particular forward works.
Installer names and package-manager instructions can change between releases and platforms. Obtain the application through the official project download path, check that the artifact matches your platform, and use the project’s release-verification guidance where required. This article intentionally avoids presenting an installation command that is not established by the supplied official evidence.
Create the Kubernetes port-forward configuration
Once the application opens, create your first port-forward configuration using the project’s documented configuration interface. The exact field names and screen layout are not established in the supplied evidence, so they should be taken from the installed version rather than inferred from screenshots or older tutorials.
At a conceptual level, the configuration must identify a Kubernetes context, a target service or pod, the remote workload port, the transport protocol, and the desired local endpoint. Depending on the installed release and selected forwarding mode, additional options may be available. Only enable options whose behavior you understand and whose values are confirmed for your cluster.
Choose the target carefully
A service is generally the stable Kubernetes abstraction through which an application is reached, while a pod is an individual workload instance. kftray supports forwarding to either type. The correct choice depends on why you need access and how the application is deployed. If the target pod is replaced, a configuration aimed at a stable service can represent a different operational intention than one aimed at a specific pod.
Do not guess the remote port from the application name. A web interface might use a nonstandard TCP port, and a database may have been configured differently from its common default. Confirm the target port from the workload configuration or the administrator responsible for the cluster.
Select TCP or UDP
kftray supports both TCP and UDP forwarding. TCP is the appropriate general choice for typical web applications, APIs, databases, administrative consoles, and other connection-oriented services when those workloads actually listen on TCP. UDP should be selected only when the destination service and client genuinely communicate over UDP.
This protocol selection must remain consistent throughout the complete path. A Kubernetes UDP workload forwarded to a local UDP listener should not be placed behind a Localtonet TCP tunnel. Likewise, a TCP workload should use an end-to-end TCP path unless you intentionally introduce an application-aware intermediary.
Record the resulting local endpoint
The two most important values for the later Localtonet configuration are the local listening address and local listening port. Record them exactly as configured or displayed by kftray. Do not confuse the local port with the Kubernetes target port. They can be related, but they are distinct points in the connection.
Start the forward and observe its status in kftray or kftui. The project is designed to reconnect forwards when pods restart or connections drop, but automatic recovery does not make an incorrect target valid. A persistent failure still requires investigation of cluster access, workload state, resource selection, and local port availability.
kftray can import and export configurations as JSON and can store or synchronize port-forward configurations through Git. This can help teams keep setups aligned. Review shared configuration before using it because a teammate’s Kubernetes context, namespace, target, or local port may not be valid or appropriate on your machine.
Verify the forward locally before exposing it
Local verification is the most important diagnostic boundary in this workflow. If the application does not respond through the kftray listener from the same machine, adding a public tunnel will not solve the underlying problem. It will only add another network segment to troubleshoot.
Keep the forward running, then connect to the recorded local address and port with a client appropriate for the application protocol. For a web application, that may be a browser or HTTP client. For a database, use the corresponding database client. For another TCP protocol, use its normal client and perform a harmless operation that demonstrates a valid application response.
A successful transport connection is useful, but an application-level response is stronger evidence. For example, an authentication prompt, a health response, a protocol banner, or a successful read-only query can confirm that traffic reached the intended workload. The exact test depends on the application, so this guide does not prescribe a universal command.
Verify the following before proceeding:
- kftray or kftui reports the forward as active.
- The selected local address and port accept the expected protocol.
- The response comes from the intended Kubernetes application.
- Application authentication behaves as expected.
- Stopping the forward causes the local test to stop working.
- Restarting the forward restores local access.
The stop-and-start check confirms that you are actually testing the kftray listener rather than another process that happens to be using a similar endpoint. If the forward cannot start because the local port is busy, choose an appropriate unused local port in the kftray configuration or stop the conflicting process. Do not terminate an unknown process without first determining what it is.
Interpreting common local failures
A connection-refused result usually indicates that no process is accepting connections at the tested address and port, or that the forward stopped. A timeout can indicate a cluster connectivity problem, an unreachable workload, a network policy, or a target that is not responding. An immediate application error may mean the transport path works but the protocol, hostname, credentials, or request is wrong.
If kftray cannot establish the forward, confirm that the intended Kubernetes context is active and usable, the target resource exists, the selected namespace is correct, and the workload is ready. Also verify that your Kubernetes identity is authorized for the operation. Avoid broadening cluster permissions merely to make a test pass. Ask the cluster administrator for the narrow access required by the workflow.
Expose the verified local TCP endpoint with Localtonet
After the local test succeeds, you can make the endpoint remotely reachable with a Localtonet TCP tunnel. The Localtonet client must run on the same machine as kftray or on another device that can reach the configured local listener. Running both applications on the same machine is often the simplest topology because it removes an additional LAN path, but the correct arrangement depends on your environment.
Use a TCP tunnel only when the local kftray endpoint uses TCP. For a browser-oriented application, an HTTP tunnel may be more appropriate when you specifically want a public HTTPS address and HTTP-oriented behavior. For a genuine UDP workload, use a UDP tunnel instead. This guide focuses on TCP because it is suitable for many Kubernetes web applications, APIs, databases, and other TCP services without assuming the application is HTTP.
Install and run the Localtonet client
Run our client on the device that can reach the verified kftray listener. The client establishes the outbound connection used by the tunnel, so the public endpoint is available only while the selected device is connected and the tunnel is running.
Authenticate or select the device
Use the device-specific authentication token associated with the client that will run the tunnel. Treat the token as a secret. Do not place it in screenshots, shell history, shared configuration files, source control, or documentation.
Select a current relay server
Choose an available relay server or region from the current Localtonet dashboard. Available server codes and regions can vary, so this guide does not hardcode a value.
Create the TCP tunnel
Select a TCP tunnel and enter the exact local IP address and port used by the working kftray forward. Do not enter the Kubernetes service address, pod address, cluster port, or Localtonet public port as the local target. The target must be the listener that you already verified from the Localtonet client device.
Start and test the tunnel
Creating a tunnel does not start it. Press Start, then connect with the application’s normal client using the public host and port assigned by Localtonet. Verify an application-level response rather than relying only on the tunnel status.
Stop or delete access when it is no longer needed
Stop the tunnel to remove active public access while retaining the configuration, or delete it when the configuration is no longer required. Also stop the kftray forward if local access is not needed.
The public host and port are not substitutes for the application’s own connection settings. A database client, for example, still needs the correct protocol options, database name, username, password, and any required transport security. Localtonet carries the connection to the local target, while the destination application remains responsible for its own authentication and authorization.
| Local workload | Likely tunnel family | Selection guidance |
|---|---|---|
| Database or other raw TCP service | TCP | Use the verified kftray TCP listening address and port as the local target. |
| Web application or HTTP API | HTTP or TCP | Choose HTTP when you need an HTTP-oriented public HTTPS address, or TCP when the client should connect through a raw TCP endpoint. |
| UDP application | UDP | Use UDP only when kftray and the Kubernetes workload are also configured for UDP. |
| Mixed or uncertain protocol | Confirm before exposing | Inspect the workload configuration and client requirements rather than guessing from the application name. |
Security practices for remote Kubernetes access
A working public tunnel changes the exposure boundary. A service that was previously reachable only through your cluster connection and local machine can now receive traffic through the assigned public endpoint. Treat this as a deliberate access-control decision rather than a convenience setting.
Do not expose an unauthenticated administrative interface, development console, database, metrics endpoint, or debugging service merely because the tunnel is easy to create. Require suitable application authentication, use least-privilege accounts, limit the duration of exposure, and stop the tunnel immediately after the remote-access task is complete.
Keep Kubernetes and application permissions narrow. A remote user should receive only the application-level permissions needed for the task. The Kubernetes identity used by kftray should likewise have only the cluster permissions required for the forwarding workflow. Do not compensate for a configuration problem by granting broad cluster roles or disabling application controls.
Protect the Localtonet device token. It identifies the client device that runs the tunnel and must never be guessed, published, or committed to a repository. Shared kftray configuration should also be reviewed before distribution. Even when a configuration contains no secret, it can reveal namespaces, service names, port choices, or internal workflow details that your organization may consider sensitive.
Match transport security to the application. A raw TCP tunnel forwards TCP traffic, but this article does not claim that every target protocol automatically gains end-to-end application encryption. If the application requires TLS, configure and verify TLS according to that application’s own documentation. Do not disable certificate validation simply to get a remote test working.
Finally, minimize the exposure window. Start the Kubernetes forward and Localtonet tunnel only when needed, monitor the operation, and stop both layers afterward. If a public endpoint or credential was shared more broadly than intended, stop the tunnel and rotate affected application credentials according to your incident process.
Routine operations and troubleshooting
Starting a normal session
Begin by checking that the intended Kubernetes context is available. Start the required kftray forward and repeat a local application-level test. Then run or confirm the Localtonet client, start the corresponding tunnel, and test through the assigned public host and port. This order isolates failures and prevents a stale public tunnel configuration from hiding a broken local forward.
Stopping a normal session
Stop the Localtonet tunnel first so new public connections cannot arrive. Then stop the kftray forward if it is no longer required locally. If the configuration was temporary, delete it from the appropriate system. Stopping a Localtonet tunnel and deleting it are different lifecycle actions.
The kftray forward will not start
Confirm the Kubernetes context, namespace, workload type, resource name, and target port. Check whether the selected local port is already occupied. Verify that the target workload exists and is ready, and that the Kubernetes identity has the required permissions. If the project reports a specific error, use that error to narrow the investigation instead of repeatedly recreating the forward.
The local endpoint opens but the application fails
This usually means the network path is at least partially functional. Check that the client uses the correct protocol and application settings. Validate credentials, expected hostname behavior, database selection, request path, and any required TLS settings. Confirm that the response belongs to the intended workload rather than another service bound to the same local port.
Local access works but remote access fails
First verify that the Localtonet client remains connected and that the tunnel was explicitly started. Confirm that the selected device is the one that can reach the kftray listener. Compare the Localtonet local target character for character with the verified kftray address and port. Also confirm that the tunnel family matches the local transport protocol.
If Localtonet runs on another device, test whether that device can reach the kftray listener directly. A listener that is reachable only from its own machine may not be reachable across the LAN. Do not widen the binding or local firewall access without evaluating the resulting exposure. Running both components on the same machine can avoid that additional network boundary.
The connection breaks after a pod restart
kftray’s shared backend is designed to reconnect forwards when pods restart or connections drop. Allow the application to perform its recovery, then repeat the local test. If recovery does not succeed, inspect whether the Kubernetes target still exists, whether the workload is ready, and whether the configuration points to the intended resource. The Localtonet tunnel can remain running while the local target is unavailable, but remote requests will not produce a valid application connection until the kftray endpoint recovers.
A configuration works for one teammate but not another
Shared JSON or Git-synchronized configurations can align forwarding definitions, but they do not guarantee identical local environments. Compare Kubernetes contexts, credentials, namespace access, local port availability, operating-system behavior, and application client settings. Review imported configurations before starting them, particularly when they select a local port or a production workload.
Choosing between kftray’s exposure features and Localtonet
kftray includes its own reverse-tunneling and public-exposure capabilities. If those capabilities already satisfy the workflow, adding Localtonet may be unnecessary. Choose Localtonet when you specifically want the verified local endpoint to use our outbound client, relay selection, dashboard-managed tunnel lifecycle, and assigned public endpoint. Avoid running multiple public-exposure methods for the same service unless there is a documented operational reason.
Frequently asked questions
What is the difference between kftray and kftui?
kftray is a desktop application with system tray integration. kftui runs in a terminal and includes CLI functionality for scripts and headless use. They share configurations and a Rust backend, so both can participate in the same general Kubernetes port-forward management workflow.
Does kftray require kubectl for every forward?
The project describes kftray and kftui as managing multiple forwards across Kubernetes contexts without requiring users to run individual kubectl port-forward commands. You still need valid Kubernetes access and sufficient authorization for the selected workload.
Which local port should I enter in Localtonet?
Enter the local listening port created by your working kftray configuration. There is no universal port for this integration. Do not substitute the Kubernetes target port unless it is also explicitly the configured local port. Verify the endpoint locally before creating the tunnel.
Should I use a Localtonet TCP tunnel or HTTP tunnel?
Use TCP for a raw TCP service such as a database or another non-HTTP protocol. An HTTP tunnel may be more appropriate for a web application or HTTP API when you want an HTTP-oriented public HTTPS address. The tunnel type must match the application and the kftray listener. Use UDP for an actual UDP workload.
Must Localtonet run on the same machine as kftray?
No. Our client can run on another device that can reach the local endpoint. However, running both on the same machine is often simpler because it avoids an additional LAN route, listener-binding issue, and local firewall boundary. Whichever device runs our client must be able to connect to the exact configured address and port.
Will Localtonet fix a broken Kubernetes port forward?
No. The kftray endpoint must work locally first. Localtonet carries connections to that local target, but it does not correct Kubernetes authentication, authorization, resource selection, workload readiness, local port conflicts, or application configuration.
Is the public endpoint available after I create the tunnel?
Not automatically. Creating a Localtonet tunnel does not mean it is running. You must press Start, and the selected Localtonet client device must remain connected. The kftray forward and target Kubernetes workload must also remain available for end-to-end access.
Does this workflow replace application authentication?
No. Keep the destination application’s authentication, authorization, and required transport security enabled. Use least-privilege credentials and expose the endpoint only for as long as needed. A public host and port should never be treated as an access-control mechanism.
Connect your verified kftray endpoint with Localtonet
First confirm that the Kubernetes workload responds through the local kftray listener. Then run our client on a device that can reach that listener, create the matching TCP, HTTP, or UDP tunnel, and start remote access without configuring inbound router port forwarding.
Get Started Free →
