kubefwd v1.25.16

This release modernizes the interactive Terminal UI by moving it onto the Charm v2 library line, hardens API-key startup logging, and rolls up routine dependency and CI maintenance.

Highlights

TUI migrated to Charm v2 (#527, closes #517)

The entire interactive TUI (--tui) has been migrated from the v1 Charm libraries to their v2 equivalents under the charm.land/... module path:

These are distinct, incompatible type systems, so this was a full API migration rather than a version bump. Notable changes handled under the hood:

• View() returns tea.View - alt-screen and mouse capture moved from the removed tea.WithAltScreen() / tea.WithMouseCellMotion() program options to the AltScreen / MouseMode fields on the returned view, applied on every render path.
• Keys - tea.KeyMsg is now an interface; all handlers (services, logs, detail, browse, and help) dispatch on the concrete tea.KeyPressMsg.
• Mouse - tea.MouseMsg split into tea.MouseWheelMsg / tea.MouseClickMsg, with renamed button constants; all wheel-scroll and click-to-focus behavior preserved.
• Styling - lipgloss.Color is now a function returning image/color.Color; viewport sizing moved to SetWidth() / SetHeight() and option-based construction.

No user-facing behavior changes. All keyboard shortcuts (j/k, Enter, Tab, /, r, b, ?, q), traffic metrics, log streaming, theme switching, and auto-reconnect work exactly as before. The dark/light theme workaround was re-validated under lipgloss v2. Verified on ubuntu + macOS with go build, go vet, golangci-lint (0 issues), and the full test suite.

API-key authentication: docs and safer startup logging (#526)

Follow-up to the API-key auth feature (#508):

• Security: the API key is now only printed at startup when kubefwd generated it. A user-supplied KUBEFWD_API_KEY is referenced by name and never echoed to logs.
• Docs: the Authentication sections of openapi.yaml, api-reference.md, and mcp-integration.md were rewritten to cover the Bearer header, KUBEFWD_API_KEY / kubefwd mcp --api-key, the /api/health exemption, and the 401 response.

Dependency updates

• k8s.io/streaming 0.36.1 -> 0.36.2 (#523)
• k8s.io/kubectl 0.36.1 -> 0.36.2 (#525)
• k8s.io/cli-runtime 0.36.1 -> 0.36.2 (#522)
• golang.org/x/sys 0.45.0 -> 0.46.0 (#518)
• github.com/txn2/txeh 1.8.0 -> 1.8.1 (#516)
• github.com/quic-go/quic-go bump (#511)

CI / build

• codecov/codecov-action 6.0.1 -> 7.0.0 (#521)
• github/codeql-action 4.36.0 -> 4.36.1 -> 4.36.2 (#512, #520)
• actions/checkout 6.0.2 -> 6.0.3 (#514)
• docker/setup-qemu-action 4.0.0 -> 4.1.0 (#513)

Install / upgrade

# Homebrew (macOS / Linux)
brew install txn2/tap/kubefwd
brew upgrade kubefwd

# Or download a binary for your platform from the assets below.

Run it (requires root for /etc/hosts and loopback aliases):

sudo -E kubefwd svc -n <namespace> --tui

Full changelog: v1.25.15...v1.25.16

kubefwd v1.25.15

Highlights

🔒 REST API now requires authentication (security)

The optional REST API (--api) and the HTTP MCP bridge previously served every endpoint — Kubernetes context enumeration, pod log reads, and port-forward creation — with no authentication. Because kubefwd runs as root via sudo -E, any local process could drive it against your kubeconfig. This release adds Bearer-token authentication, addressing advisory GHSA-vwjh-p4vp-9rp2 (#507, #508).

• The API key is resolved from KUBEFWD_API_KEY; if unset, a random 32-character hex key is generated and only its last 4 characters are logged on startup.
• All endpoints require Authorization: Bearer <key> except /api/health, which stays open for liveness probes.
• Token comparison uses crypto/subtle.ConstantTimeCompare to avoid timing side channels.
• kubefwd mcp reads KUBEFWD_API_KEY automatically; a new --api-key flag overrides it.

export KUBEFWD_API_KEY=my-known-key
sudo -E kubefwd svc -n my-namespace --api

🐛 Multi-port services recover after a single port is reset (#509)

Fixed an unrecoverable zombie state in which a multi-port service that lost one port's connection — e.g. the TCP RST behavior of kubernetes/kubernetes#111825 — would never re-establish that port or restore its /etc/hosts entries. Auto-reconnect (-a, on by default in --tui) found the pod but did nothing, and only a full kubefwd restart recovered the service.

syncNormalService now reasons in terms of the pod being forwarded rather than a single port: it keeps every port of that pod and re-establishes any that were torn down independently. This also fixes a related regression where a healthy multi-port service could drop all but one port on the periodic resync. (#509, #510)

Dependencies

• golang.org/x/sys → 0.45.0 (#502)
• github.com/modelcontextprotocol/go-sdk → 1.6.1 (#501)

CI / Build

• goreleaser/goreleaser-action → 7.2.2 (#500)
• github/codeql-action → 4.36.0 (#504, #499)
• golangci/golangci-lint-action → 9.2.1 (#506)
• docker/setup-buildx-action → 4.1.0 (#505)
• docker/login-action → 4.2.0 (#503)
• codecov/codecov-action → 6.0.1 (#498)

Full changelog: v1.25.14...v1.25.15

What's New

MCP Registry Publish Fix (#470)

Fixes the Publish to MCP Registry step in the release workflow that had been failing on every release since v1.25.1. server.json used the snake_case key file_sha256, but the MCP registry schema requires camelCase fileSha256. The workflow now also validates server.json against the official MCP schema (plus an explicit MCPB contract check for fileSha256) before publishing, preventing the class of bug that caused the v1.25.13 homebrew formula SHA drift.

Dependency Updates

Kubernetes

• k8s.io/cli-runtime 0.35.2 → 0.35.3
• k8s.io/kubectl 0.35.2 → 0.35.3

Go Modules

• github.com/moby/spdystream 0.5.0 → 0.5.1 (header-size/count limits, 24-bit frame length enforcement)
• github.com/modelcontextprotocol/go-sdk 1.4.1 → 1.5.0
• golang.org/x/sys 0.42.0 → 0.43.0

CI

• actions/setup-go 6.3.0 → 6.4.0
• actions/upload-artifact 7.0.0 → 7.0.1
• actions/upload-pages-artifact 4.0.0 → 5.0.0
• actions/deploy-pages 4.0.5 → 5.0.0
• docker/login-action 4.0.0 → 4.1.0
• github/codeql-action 4.34.1 → 4.35.1
• sigstore/cosign-installer 4.1.0 → 4.1.1

Docker

• Ubuntu base image digest bump (186072b → 84e77de)

Changelog

• 5eab2dc ci: fix MCP Registry publish step (fileSha256 field name) (#470)
• 8cfcbd9 deps: bump github.com/moby/spdystream from 0.5.0 to 0.5.1 (#460)
• af76b37 ci: bump actions/upload-pages-artifact from 4.0.0 to 5.0.0 (#459)
• 337d352 ci: bump actions/upload-artifact from 7.0.0 to 7.0.1 (#458)
• eaffc2a deps: bump golang.org/x/sys from 0.42.0 to 0.43.0 (#457)
• 0ab9d85 docker: bump ubuntu from 186072b to 84e77de (#456)
• bd6e739 ci: bump docker/login-action from 4.0.0 to 4.1.0 (#455)
• a2469b1 deps: bump github.com/modelcontextprotocol/go-sdk from 1.4.1 to 1.5.0 (#454)
• 1f8cd06 ci: bump CI dependencies (combined) (#453)
• ac6b038 deps: bump k8s.io/cli-runtime and k8s.io/kubectl from 0.35.2 to 0.35.3 (#447)

What's New

Wayland Clipboard Support (#446)

The TUI copy feature now supports Wayland environments via wl-copy, in addition to existing X11 (xclip/xsel) and macOS (pbcopy) support. Clipboard detection order: wl-copy → xclip → xsel.

Release Process Fix (#395)

Releases are now created as drafts so MCPB bundles can be uploaded before publishing.

Dependency Updates

Kubernetes

• k8s.io/api 0.35.0 → 0.35.1
• k8s.io/apimachinery 0.35.2 → 0.35.3
• k8s.io/cli-runtime 0.35.0 → 0.35.2
• k8s.io/client-go 0.35.0 → 0.35.3
• k8s.io/kubectl 0.35.0 → 0.35.2
• k8s.io/klog/v2 2.130.1 → 2.140.0

Go Modules

• github.com/charmbracelet/bubbles 0.21.1 → 1.0.0
• github.com/gin-gonic/gin 1.11.0 → 1.12.0
• github.com/modelcontextprotocol/go-sdk 1.2.0 → 1.4.1
• github.com/txn2/txeh 1.7.0 → 1.8.0
• golang.org/x/sys 0.40.0 → 0.42.0

CI

• actions/setup-go 6.2.0 → 6.3.0
• actions/upload-artifact 6.0.0 → 7.0.0
• anchore/sbom-action 0.22.1 → 0.24.0
• codecov/codecov-action 5.5.2 → 5.5.3
• docker/login-action 3.7.0 → 4.0.0
• docker/setup-buildx-action 3.12.0 → 4.0.0
• docker/setup-qemu-action 3.7.0 → 4.0.0
• github/codeql-action 4.32.1 → 4.34.1
• goreleaser/goreleaser-action 6.4.0 → 7.0.0
• sigstore/cosign-installer 4.0.0 → 4.1.0

Docker

• Ubuntu base image updated (4 digest bumps)

What's New

TUI Light/Dark Theme Support (#393)

The TUI now supports light terminal backgrounds with a new --theme flag and KUBEFWD_THEME environment variable.

# CLI flag
sudo -E kubefwd svc -n default --tui --theme light

# Environment variable
KUBEFWD_THEME=light sudo -E kubefwd svc -n default --tui

The light palette uses darker color variants (dark gold, dark green, dark teal, black text) optimized for readability on light terminal backgrounds. The default remains the dark theme.

Bug Fixes

• Fix MCPB build script for Windows (#394): Corrected the goreleaser dist directory path for Windows CGO cross-compilation builds.

Changelog

• TUI: add light/dark theme support (#393)
• fix: use correct goreleaser build ID for Windows MCPB bundles (#394)

v1.25.10

Bug Fixes

• Windows VPN DNS resolution fixed (#390): Windows users with VPN connections can now connect to clusters when the API server hostname requires VPN-specific DNS resolution. The Go 1.24 upgrade in v1.23.0 broke this because Go's pure-Go DNS resolver doesn't respect Windows per-adapter DNS settings.

Changes

• Windows builds now use CGO (CGO_ENABLED=1) with MinGW cross-compilation to use the native Windows DNS API
• Linux and macOS builds remain static (CGO_ENABLED=0) for Alpine compatibility

Changelog

• 33c0ab8 Add attributions page and CNCF Landscape badge to documentation (#374)
• 516d002 Add kubefwd documentation files (llms.txt and llms-full.txt) detailing features, installation, usage, and REST API. (#373)
• f2ad8b7 Bump urllib3 in /.github in the pip group across 1 directory (#371)
• c08d613 Enable Windows CGO cross-compilation in release workflow (#391)
• cdf18db Update Installation Documentation for Official Package Managers (#379)
• f31c27d ci: bump actions/checkout from 6.0.1 to 6.0.2 (#384)
• fe0291d ci: bump actions/setup-go from 6.1.0 to 6.2.0 (#376)
• 92e88ef ci: bump actions/setup-python from 6.1.0 to 6.2.0 (#385)
• 7a8adef ci: bump anchore/sbom-action from 0.21.0 to 0.21.1 (#377)
• ff3286d ci: bump anchore/sbom-action from 0.21.1 to 0.22.1 (#383)
• b40fa9d ci: bump docker/login-action from 3.6.0 to 3.7.0 (#389)
• e5ee353 ci: bump github/codeql-action from 4.31.10 to 4.32.0 (#382)
• 22b2b83 ci: bump github/codeql-action from 4.31.9 to 4.31.10 (#378)
• 0fd5f36 ci: bump github/codeql-action from 4.32.0 to 4.32.1 (#388)
• 7bd7d10 deps: bump github.com/charmbracelet/bubbles from 0.21.0 to 0.21.1 (#386)
• 15d300e deps: bump github.com/sirupsen/logrus from 1.9.3 to 1.9.4 (#380)
• 4b472ca deps: bump golang.org/x/sys from 0.39.0 to 0.40.0 (#375)
• 143c055 docker: bump alpine from 865b95f to 2510918 (#387)
• fbf95f7 docker: bump ubuntu from c35e29c to cd1dba6 (#381)

MCP Server Improvements

Graceful Startup Without API Connection

The MCP server now starts and registers all tools even when the kubefwd API is unavailable. This enables:

• Registry Discovery: Smithery, Glama.ai, and other MCP registries can now introspect kubefwd's tool definitions without requiring kubefwd to be running
• Better Developer Experience: Tools return helpful, structured error messages guiding users to start kubefwd when the API isn't available

Consistent Error Handling

All MCP tool handlers now return structured ProviderUnavailableError responses with:

• Clear diagnosis explaining the issue
• Suggested actions to resolve
• Retry recommendations

Example error response:

{
  "code": "provider_unavailable",
  "message": "State reader not available",
  "diagnosis": "kubefwd may not be running. Start it with: sudo -E kubefwd",
  "suggested_actions": [{"action": "get_health", "hint": "Check kubefwd status"}],
  "retry_recommended": true
}

New Files

• glama.json: Configuration for Glama.ai MCP registry claiming
• docs/images/kubefwd-logo.svg: Logo asset for documentation

Testing

• Added unit tests for MCP command package (cmd/kubefwd/mcp/mcp_test.go)
• Test coverage for cmd/kubefwd/mcp: 0% → 13.5%
• All existing tests pass
• Lint clean

Upgrade Notes

This is a non-breaking change. The MCP server behavior is improved but maintains backward compatibility. Users who previously ran kubefwd mcp without the API available will now see the server start (with warnings) instead of immediately exiting.

Full Changelog

• Improve MCP server initialization and API connection handling
• Replace generic error messages with structured NewProviderUnavailableError
• Add unit tests for MCP command flags and API connection validation
• Add glama.json configuration file for registry claiming
• Add kubefwd logo SVG for documentation

Changelog

• 7881c5a Fix gofmt -s simplification issues
• 6efedb9 MCP server improvements (#372)
• dd8a3d2 Quality/gocyclo (#363)
• cd084ca Quality/housekeeping (#369)
• 080853c Replace outdated TUI guide with revamped User Guide (#360)
• bdacb6d Revert "Fix gofmt -s simplification issues"
• 6ad2509 Tests/coverage (#362)
• b96ea6d ci: bump actions/checkout from 4.2.2 to 6.0.1 (#370)
• a961053 ci: bump actions/setup-go from 5.2.0 to 6.1.0 (#368)
• a84426d ci: bump codecov/codecov-action from 5.4.3 to 5.5.2 (#365)
• 9e9da2d ci: bump github/codeql-action from 3.27.9 to 4.31.9 (#367)
• f265619 ci: bump golangci/golangci-lint-action from 6.1.1 to 9.2.0 (#366)
• e8b851f ci: bump ossf/scorecard-action from 2.4.1 to 2.4.3 (#364)

Bug Fixes

• fix: Windows hosts path auto-detection (#359) - kubefwd now automatically detects the correct hosts file path based on the operating system:

  • Windows: C:\Windows\System32\drivers\etc\hosts
  • Linux/macOS: /etc/hosts

  Previously, the --hosts-path flag defaulted to /etc/hosts on all platforms, causing kubefwd to fail immediately on Windows with "Hosts path does not exist: /etc/hosts".

Changes

• Added runtime import to detect OS at runtime
• Added defaultHostsPath() function that returns OS-appropriate path
• Updated --hosts-path flag to use dynamic default

Windows Support

This release fixes a critical issue that prevented kubefwd from running on Windows without manually specifying the --hosts-path flag. Windows users can now run kubefwd without any additional configuration:

Before (Windows):

kubefwd svc -n mynamespace
FATA[12:34:18] Hosts path does not exist: /etc/hosts

After (Windows):

kubefwd --help | findstr hosts-path
--hosts-path string          Hosts file path. (default "C:\Windows\System32\drivers\etc\hosts")

Installation

Windows

Download from GitHub Releases and extract to your PATH.

# Download and extract (PowerShell)
Invoke-WebRequest -Uri "https://github.com/txn2/kubefwd/releases/download/v1.25.8/kubefwd_Windows_x86_64.zip" -OutFile kubefwd.zip
Expand-Archive kubefwd.zip -DestinationPath C:\kubefwd
# Add C:\kubefwd to your PATH

macOS (Homebrew)

brew install txn2/tap/kubefwd

Linux

Download from GitHub Releases or use your package manager.

Verifying This Release

All release artifacts are signed with Sigstore for supply chain security. Each binary archive has its own .sigstore.json signature bundle.

Verify Individual Binaries

# Example: Verify the Linux x86_64 binary
curl -LO https://github.com/txn2/kubefwd/releases/download/v1.25.8/kubefwd_Linux_x86_64.tar.gz
curl -LO https://github.com/txn2/kubefwd/releases/download/v1.25.8/kubefwd_Linux_x86_64.tar.gz.sigstore.json

cosign verify-blob \
  --bundle kubefwd_Linux_x86_64.tar.gz.sigstore.json \
  --certificate-identity-regexp="https://github.com/txn2/kubefwd/.*" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  kubefwd_Linux_x86_64.tar.gz

Verify Checksums File

curl -LO https://github.com/txn2/kubefwd/releases/download/v1.25.8/kubefwd_checksums.txt
curl -LO https://github.com/txn2/kubefwd/releases/download/v1.25.8/kubefwd_checksums.txt.sigstore.json

cosign verify-blob \
  --bundle kubefwd_checksums.txt.sigstore.json \
  --certificate-identity-regexp="https://github.com/txn2/kubefwd/.*" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  kubefwd_checksums.txt

Available Signed Artifacts

Docker Image Verification

cosign verify txn2/kubefwd:v1.25.8 \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  --certificate-identity-regexp="https://github.com/txn2/kubefwd/.*"

TUI Browse Modal

Introduces an interactive Browse Modal for discovering and forwarding Kubernetes services directly from the TUI. Press f to open a hierarchical browser that navigates through contexts, namespaces, and services - then forward individual services or entire namespaces without leaving the interface.

Browse Modal Features

• Three-level navigation: Contexts → Namespaces → Services
• Forward services on demand: Select any service and press Enter to start forwarding
• Bulk forwarding: "Forward All" option forwards every service in a namespace
• Visual indicators: Already-forwarded services show a checkmark (✓)
• Port display: See service ports before forwarding
• Context switching: Press c to switch Kubernetes contexts

Keyboard Shortcuts

Use Case

Start kubefwd with minimal namespaces, then dynamically add services as needed:

# Start with one namespace
sudo -E kubefwd svc -n default --tui

# Press 'f' to browse, navigate to another namespace,
# and forward additional services on demand

Bug Fixes

Pod Logs Streamer Reliability

Fixed nil interface issues with clientSet initialization in the TUI pod logs streamer. Improved namespace manager integration ensures reliable log streaming.

Log Spam Prevention

ServiceFWD now tracks "no pods" warnings with a flag to prevent repeated log messages. The flag resets when pods become available, allowing future warnings if pods disappear again.

Test Coverage Improvements

Significant expansion of TUI test coverage:

New test files:

• browse_test.go — 1,277 lines covering BrowseModel navigation, loading states, error handling
• tui_test.go — 1,712 lines covering RootModel, event handling, and UI components

Documentation

Updated API reference and OpenAPI specification with documentation for Kubernetes pod debugging and event endpoints (no new code, documentation only).

CI Updates

• Updated GitHub Actions dependencies for security and compatibility
• Pinned codeql-action/upload-sarif version in Scorecard workflow

No MCP/API Code Changes

This release contains no changes to the MCP server or REST API functionality. All MCP tools (29 total) continue to work as documented in v1.25.6.

Changes

• Add TUI Browse Modal for interactive service discovery (#358)
• Add API documentation for Kubernetes pod/event endpoints (#357)
• Code quality improvements (#353, #354, #355)
• Documentation housekeeping (#356)
• CI dependency updates (#345, #346, #347, #348, #349)

Full Changelog

v1.25.6...v1.25.7

Changelog

• 269f550 Add Kubernetes pod debugging and event APIs (#357)
• 3f0f812 Documentation and badge housekeepin (#352)
• f259e34 Housekeeping/documentation (#356)
• addd289 Potential fixes for 2 code quality findings (#353)
• fc2215f Potential fixes for 3 code quality findings (#354)
• 56ad479 Potential fixes for 3 code quality findings (#355)
• 1351ad1 TUI Browse Modal & Tests (#358)
• ebe298b ci: bump actions/setup-python from 5.3.0 to 6.1.0 (#349)
• 76a9fad ci: bump actions/upload-artifact from 4.6.1 to 6.0.0 (#345)
• 118f9de ci: bump anchore/sbom-action from 0.18.0 to 0.21.0 (#347)
• a15b5f1 ci: bump docker/setup-buildx-action from 3.7.1 to 3.12.0 (#348)
• 49b7db3 ci: bump sigstore/cosign-installer from 3.7.0 to 4.0.0 (#346)

Fixes critical issues with the Kubernetes discovery MCP tools introduced in v1.25.5. The tools were defined but their HTTP API routes were not registered, causing 404 errors.

Fixed: Missing API Routes

The following MCP tools now work correctly:

Fixed: Response Format Errors

Fixed: get_connection_info Without Namespace

Previously, calling get_connection_info with only a service name (no namespace) would return 404. Now it:

1. Searches for services matching the name
2. If exactly one match, returns that service's connection info
3. If multiple matches, returns an error listing namespaces to disambiguate

# Now works:
get_connection_info(service_name="postgres")

# If ambiguous, helpful error:
"multiple services found with name 'postgres' in namespaces: [staging, production]. Please specify namespace"

Changes

• Fix missing HTTP routes for 5 MCP Kubernetes discovery tools
• Fix response format for list_pods and get_events
• Fix get_connection_info to work without namespace parameter

Full Changelog

v1.25.5...v1.25.6

Changelog

• 516bdc3 Fix Missing Kubernetes API Routes for MCP (#351)
• 60238c7 deps: bump github.com/bep/debounce from 1.2.0 to 1.2.1 (#344)