Architecture

kftray and kftui share a config database and port-forwarding code. Each app tracks its own active forwards.

Component structureCopy Anchor Link

The desktop and terminal apps read the same saved configs. The MCP server uses that database too.

Forwarding lifecycleCopy Anchor Link

The tools share a Rust core that handles all Kubernetes interaction. A forward goes through these steps:

For UDP, or when you need to reach external services, kftray deploys a small relay pod in your cluster to do the forwarding. See relay server.

Shared stateCopy Anchor Link

kftray stores configs in configs.db inside the configuration directory. The default location is ~/.kftray/configs.db when no path override is set:

-- Simplified schema
CREATE TABLE configs (
    id INTEGER PRIMARY KEY,
    alias TEXT NOT NULL,
    context TEXT NOT NULL,
    namespace TEXT NOT NULL,
    service TEXT,
    pod TEXT,
    local_port INTEGER NOT NULL,
    remote_port INTEGER NOT NULL,
    protocol TEXT DEFAULT 'tcp',
    -- ... additional fields
);

SQLite locks let both apps read and write configs without corrupting the database. To stop an active forward, use the app that started it.

TCP forwarding architectureCopy Anchor Link

Direct TCP forwarding uses the Kubernetes API's port-forward subprotocol:

This follows the same path as kubectl port-forward, with comparable performance. The kftray-portforward component keeps a WebSocket connection to the Kubernetes API server. It carries multiple TCP connections over that connection.

See port forwarding configuration for examples.

Proxy TCP forwarding architectureCopy Anchor Link

Proxy forwarding adds the kftray-server pod between your local app and the upstream server. The local TCP connection goes to the kftray-server pod, which sends the TCP packets on to the upstream server:

See proxy forwarding for configs and use cases.

UDP forwarding architectureCopy Anchor Link

Kubernetes port-forward only supports TCP. To forward UDP, kftray converts packets to TCP and sends them to an in-cluster proxy:

kftray opens a local UDP socket and connects a local TCP socket to the kftray-server pod. The TCP socket sends the UDP packets over TCP, and the server forwards them to the upstream server.

kftray deploys kftray-server in the target namespace when you create a UDP forward. It removes the deployment when no UDP forwards remain active.

See proxy forwarding for setup details.

Proxy server deploymentCopy Anchor Link

When you create a UDP forward, kftray:

Multiple UDP forwards in a namespace share the proxy pod.

HTTP logging implementationCopy Anchor Link

HTTP logging reads requests and responses from TCP traffic. The kftray-http-logs component:

Each log entry uses this format:

{
  "timestamp": "2026-02-09T10:30:45.123Z",
  "trace_id": "abc123",
  "direction": "request",
  "method": "GET",
  "path": "/api/users",
  "headers": {"Host": "api.example.com"},
  "body": null
}

Parsing adds 1-5 ms per request. Turn off HTTP logging when that delay would affect your work.

Helper componentCopy Anchor Link

The kftray-helper binary handles operations that need elevated permissions:

• Binding ports below 1024 on macOS and Linux.
• Updating /etc/hosts for custom domain mappings.

When you bind a port below 1024, kftray:

Security modelCopy Anchor Link

Credential managementCopy Anchor Link

kftray uses the same kubeconfig files as kubectl:

• The default file is ~/.kube/config.
• Set KUBECONFIG to use a different path.
• Separate multiple paths in KUBECONFIG with colons.

The Kubernetes client library reads credentials from kubeconfig files at runtime. kftray doesn't store those credentials in its database.

For cloud providers, kftray uses the same credential helpers as kubectl:

See CLI reference for environment variables.

Network securityCopy Anchor Link

kftray binds to 127.0.0.1 by default. Only apps on your machine can reach the forward:

{
  "local_address": "127.0.0.1",
  "local_port": 8080
}

Binding to 0.0.0.0 makes the forward available to your network:

{
  "local_address": "0.0.0.0",
  "local_port": 8080
}

MCP serverCopy Anchor Link

The MCP server lets external clients call kftray operations over HTTP:

The server has 16 tools for finding Kubernetes resources, managing port forwards and reading or changing configs. It uses kftray-portforward and kftray-commons, so these operations work the same way as in the desktop and terminal apps.

The server runs inside the desktop app. kftray-tauri starts and stops it based on the MCP settings.

Privilege separationCopy Anchor Link

On macOS, signing and verification protect the helper binary against tampering.

For release verification, SBOMs and vulnerability reporting, see Security.