Releases: txn2/kubefwd
kubefwd-v1.25.12
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 --tuiThe 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
kubefwd-v1.25.10
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.txtandllms-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
865b95fto2510918(#387) - fbf95f7 docker: bump ubuntu from
c35e29ctocd1dba6(#381)
kubefwd-v1.25.9
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 claimingdocs/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.jsonconfiguration 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)
kubefwd-v1.25.8
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-pathflag defaulted to/etc/hostson all platforms, causing kubefwd to fail immediately on Windows with "Hosts path does not exist: /etc/hosts". - Windows:
Changes
- Added
runtimeimport to detect OS at runtime - Added
defaultHostsPath()function that returns OS-appropriate path - Updated
--hosts-pathflag 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 PATHmacOS (Homebrew)
brew install txn2/tap/kubefwdLinux
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.gzVerify 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.txtAvailable Signed Artifacts
| Platform | Archive | Signature |
|---|---|---|
| Linux x86_64 | kubefwd_Linux_x86_64.tar.gz |
kubefwd_Linux_x86_64.tar.gz.sigstore.json |
| Linux arm64 | kubefwd_Linux_arm64.tar.gz |
kubefwd_Linux_arm64.tar.gz.sigstore.json |
| Linux armv6 | kubefwd_Linux_armv6.tar.gz |
kubefwd_Linux_armv6.tar.gz.sigstore.json |
| Linux i386 | kubefwd_Linux_i386.tar.gz |
kubefwd_Linux_i386.tar.gz.sigstore.json |
| macOS x86_64 | kubefwd_Darwin_x86_64.tar.gz |
kubefwd_Darwin_x86_64.tar.gz.sigstore.json |
| macOS arm64 | kubefwd_Darwin_arm64.tar.gz |
kubefwd_Darwin_arm64.tar.gz.sigstore.json |
| Windows x86_64 | kubefwd_Windows_x86_64.zip |
kubefwd_Windows_x86_64.zip.sigstore.json |
| Windows i386 | kubefwd_Windows_i386.zip |
kubefwd_Windows_i386.zip.sigstore.json |
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/.*"kubefwd-v1.25.7
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
cto switch Kubernetes contexts
Keyboard Shortcuts
| Key | Action |
|---|---|
f |
Open browse modal |
j / ↓ |
Move down |
k / ↑ |
Move up |
g |
Jump to top |
G |
Jump to bottom |
Enter / → |
Select / Forward service |
Esc / ← / q |
Go back / Close |
c |
Switch Kubernetes context |
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 demandBug 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:
| Package | Before | After |
|---|---|---|
pkg/fwdtui |
4.63% | 74.8% |
pkg/fwdtui/events |
— | 100.0% |
pkg/fwdtui/state |
— | 97.9% |
| Overall | 60.65% | 67.6% |
New test files:
browse_test.go— 1,277 lines covering BrowseModel navigation, loading states, error handlingtui_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-sarifversion 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
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)
kubefwd-v1.25.6
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:
| Tool | Issue | Fix |
|---|---|---|
get_pod_logs |
404 - route not registered | Added /v1/kubernetes/pods/:namespace/:podName/logs |
list_pods |
404 - route not registered | Added /v1/kubernetes/pods/:namespace |
get_pod |
404 - route not registered | Added /v1/kubernetes/pods/:namespace/:podName |
get_events |
404 - route not registered | Added /v1/kubernetes/events/:namespace |
get_endpoints |
404 - route not registered | Added /v1/kubernetes/endpoints/:namespace/:serviceName |
Fixed: Response Format Errors
| Tool | Issue | Fix |
|---|---|---|
list_pods |
JSON unmarshal error | Return array directly, not wrapped in object |
get_events |
JSON unmarshal error | Return array directly, not wrapped in object |
Fixed: get_connection_info Without Namespace
Previously, calling get_connection_info with only a service name (no namespace) would return 404. Now it:
- Searches for services matching the name
- If exactly one match, returns that service's connection info
- 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
Changelog
kubefwd-v1.25.5
MCP Kubernetes Discovery Enhancements
Expands MCP server capabilities with comprehensive Kubernetes read operations for debugging and discovery. Previously, users could not inspect Kubernetes resources beyond forwarded services through the MCP interface.
New MCP Tools (5 tools)
| Tool | Description | Key Parameters |
|---|---|---|
get_pod_logs |
Get container logs from a pod | namespace, pod_name, tail_lines, previous, timestamps |
list_pods |
List pods with status/ready/restarts | namespace, label_selector, service_name |
get_pod |
Detailed pod info (containers, conditions, resources) | namespace, pod_name |
get_events |
K8s events for debugging startup failures | namespace, resource_kind, resource_name, limit |
get_endpoints |
Service endpoints showing backing pods | namespace, service_name |
Use Cases
Claude Desktop (or any MCP client) can now:
-
Debug a failing service:
- "What pods are backing auth-service?" →
list_podswith service_name filter - "Is the pod healthy?" →
get_podfor detailed status - "Why won't it start?" →
get_eventsfor scheduling/pulling/startup events
- "What pods are backing auth-service?" →
-
Investigate pod issues:
- "Show me the logs" →
get_pod_logs - "What was the last error?" →
get_pod_logswith previous=true - "Check container status" →
get_podwith container details
- "Show me the logs" →
-
Verify service routing:
- "Which pods are ready?" →
get_endpointsshows ready vs not-ready addresses
- "Which pods are ready?" →
Complete MCP Tool Inventory (29 tools)
Forwarding Management (7): add_namespace, remove_namespace, add_service, remove_service, reconnect_service, reconnect_all_errors, sync_service
Service Discovery (7): list_services, get_service, find_services, list_k8s_namespaces, list_k8s_services, list_contexts, get_connection_info, list_hostnames
Pod Operations (5) — NEW: list_pods, get_pod, get_pod_logs, get_events, get_endpoints
Monitoring & Diagnostics (10): get_health, get_quick_status, get_metrics, get_http_traffic, get_analysis, diagnose_errors, get_logs, get_history
OpenSSF Scorecard
Added OpenSSF Scorecard workflow for security best practices monitoring. The scorecard analyzes the repository for security posture including branch protection, dependency management, and code review practices.
Changes
- Add MCP Kubernetes discovery tools for pod/event/endpoint inspection (#350)
- Add OpenSSF Scorecard security analysis workflow (#343)
Full Changelog
kubefwd-v1.25.4
This release focuses on MCP tool response, code quality improvements, test reliability, and bug fixes identified by GitHub's security scorecard and code quality analysis tools.
Bug Fixes
MCP Tool Response Format
- Fixed all 24 MCP tool handlers to return complete JSON data instead of text summaries
- AI clients now receive full structured data when using MCP tools like
list_services,add_namespace, etc. - Resolves issue where
add_namespacereported "Discovered 0 services" despite successful forwarding
SLSA Provenance Generation
- Fixed artifact hash generation in release workflow
- Previous implementation failed silently when certain file types (e.g.,
.zip) didn't exist - Now uses
findcommand to reliably locate all artifacts before hashing
Test Improvements
Eliminated Flaky Tests
- Replaced
time.Sleeppatterns with proper synchronization usingwaitForConditionhelper - Affected tests in
pkg/fwdsvcregistrynow poll for conditions instead of arbitrary delays
Race Condition Fixes
- Replaced
sync.Oncewith mutex-protected bool inpkg/fwdapi/manager.goandpkg/fwdapi/logbuffer.go - Tests can now properly reset and restore global state without race conditions
Code Quality
- Replaced confusing
string(rune('0'+i))patterns withfmt.Sprintffor clarity - Fixed invalid port number (99999 → 65535) in network error test
- Replaced custom
containshelper withstrings.Contains - Improved non-string conversion test to verify actual type assertions
Build/CI Improvements
- Pinned GoReleaser version to
~> v2.13in both CI and release workflows - Improved artifact hash generation reliability for SLSA provenance
Full Changelog
Changed Files
.github/workflows/ci.yml- Pin GoReleaser version.github/workflows/release.yml- Pin GoReleaser version, fix hash generationpkg/fwdapi/logbuffer.go- Replace sync.Once with mutex patternpkg/fwdapi/logbuffer_test.go- Improve test reliability and claritypkg/fwdapi/manager.go- Replace sync.Once with mutex patternpkg/fwdapi/manager_test.go- Update for new initialization patternpkg/fwdmcp/httpclient_test.go- Fix invalid port numberpkg/fwdmcp/tools.go- Return nil CallToolResult for proper JSON responsespkg/fwdmcp/tools_test.go- Update tests for new handler behaviorpkg/fwdmetrics/httpsniff_test.go- Replace confusing string expressionspkg/fwdns/manager_test.go- Use strings.Containspkg/fwdsvcregistry/fwdsvcregistry_test.go- Add waitForCondition, eliminate time.Sleep
Changelog
kubefwd-v1.25.3
kubefwd-v1.25.2
This release focuses on security improvements, OpenSSF Scorecard compliance, and MCP bug fixes.
Highlights
Security Fix: IP Parsing Bounds Validation
Fixed CodeQL security alert for incorrect integer conversion in IP parsing. The ipFromString() function now validates that each octet is within 0-255 bounds before casting to byte, preventing potential overflow issues.
MCP Bug Fixes
- Fixed namespace state corruption -
remove_namespaceno longer corrupts state for subsequentadd_servicecalls - Fixed service discovery reporting -
add_namespacenow correctly reports discovered service count via direct K8s API query - Restored parameter hints - All MCP tool descriptions now include required parameter hints (e.g., "Requires key (e.g., 'servicename.namespace.context')")
OpenSSF Scorecard Improvements
- Pinned all workflow dependencies by SHA hash
- Restricted token permissions to job-level scope
- Expected Scorecard improvement: Pinned-Dependencies 8→10/10, Token-Permissions 0→10/10
MCPB Bundle Signing
MCPB bundles are now signed with Cosign and included in SLSA provenance attestation for enhanced supply chain security.
What's New
Security
- Fixed CodeQL alert: bounds validation for IP octet parsing (#339)
- Added fuzz tests for IP parsing to catch edge cases (#336)
- Fixed panic in
ipFromStringfor malformed input (#336)
Bug Fixes
- Fixed
remove_namespacecorrupting state for subsequentadd_servicecalls (#338) - Fixed
add_namespacereporting "Discovered 0 services" (#338) - Restored MCP tool parameter hints that were accidentally removed (#338)
- Added missing switch cases for
StatusPendingandStatusStopping(#338) - Fixed nil pointer panic in
fwdsvcregistry.GetAll()(#338)
Build/CI
- Improved OpenSSF Scorecard compliance (#337)
- Pinned workflow dependencies by SHA hash
- Restricted token permissions to job-level
- Sign MCPB bundles with Cosign (#335)
- Include MCPB bundles in SLSA provenance attestation
- Fix MCPB build script for goreleaser arm64 directory naming (#334)
- Pin mkdocs-material version in docs workflow
- Add fuzz testing to CI workflow
Testing
- Added fuzz tests for IP parsing functions
- Added 11 unit tests for IP octet bounds validation
- Added tests covering values >255, negative values, edge cases
Dependencies
- Bumped
github.com/quic-go/quic-gofrom 0.54.0 to 0.57.0
Installation
Homebrew (macOS/Linux)
brew install txn2/tap/kubefwdClaude Desktop (MCPB)
Download the appropriate .mcpb file for your platform and double-click to install.
Binary Download
Download the appropriate archive for your platform from the release assets.
Docker
docker pull txn2/kubefwd:v1.25.2Package Managers
- APK:
kubefwd_amd64.apk,kubefwd_arm64.apk - DEB:
kubefwd_amd64.deb,kubefwd_arm64.deb - RPM:
kubefwd_amd64.rpm,kubefwd_arm64.rpm
Checksums & Verification
All release artifacts include:
- SHA256 checksums in
kubefwd_checksums.txt - Sigstore signature in
kubefwd_checksums.txt.sigstore.json - SBOM (Software Bill of Materials) for each archive
- SLSA Level 3 provenance attestation
Verify signatures with:
cosign verify-blob \
--bundle kubefwd_checksums.txt.sigstore.json \
--certificate-identity-regexp="https://github.com/txn2/kubefwd/.github/workflows/release.yml@refs/tags/.*" \
--certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
kubefwd_checksums.txtBreaking Changes
None.
Upgrade Notes
This is a drop-in replacement for v1.25.1. No configuration changes required.
Contributors
Thanks to all contributors who made this release possible.
Full Changelog
See the commit log for the complete list of changes.
Changelog
- b4ffd89 Add fuzz testing to CI workflow
- 6345ab0 Add fuzz tests and fix panic in ipFromString
- a7735fa Fix CodeQL autobuild and improve Scorecard compliance
- c762a68 Fix CodeQL security alert (#339)
- 8bbb961 Fix MCPB build script for goreleaser arm64 directory naming
- bdd56dd Improve OpenSSF Scorecard - Pin dependencies and restrict token permissions (#337)
- 64510b0 MCP Bug Fixes and Improvements (#338)
- ce94be8 Pin mkdocs-material version in docs workflow
- cafed0b Sign MCPB bundles with Cosign and include in SLSA provenance
- 56615cf deps: bump github.com/quic-go/quic-go from 0.54.0 to 0.57.0