Chapter: getting-started (docs/getting-started.md) Copy Section

Getting Started

This guide covers installation and your first steps with kubefwd. By the end, you'll have cluster services accessible locally by name.

Prerequisites Copy Chapter

- kubectl configured with access to a Kubernetes cluster
- Root/sudo access (required for /etc/hosts and network interface modifications)

kubefwd reads your kubeconfig (~/.kube/config or KUBECONFIG environment variable) and connects directly to the Kubernetes API. It does not invoke kubectl.

---

Installation Copy Chapter

=== "macOS"

Using Homebrew:

brew install kubefwd

To upgrade:

brew update && brew upgrade kubefwd

=== "Windows"

Using winget:

winget install txn2.kubefwd

Or using Scoop:

scoop install kubefwd

To upgrade:

winget upgrade txn2.kubefwd
    # or
    scoop update kubefwd

!!! note "Run as Administrator"
kubefwd requires elevated privileges on Windows to modify the hosts file. Right-click your terminal and select "Run as Administrator".

=== "Linux (Debian/Ubuntu)"

Download the .deb package from GitHub Releases:

# Install
    sudo dpkg -i kubefwd_*_amd64.deb
    # Upgrade (same command)
    sudo dpkg -i kubefwd_*_amd64.deb

=== "Linux (RHEL/Fedora)"

Download the .rpm package from GitHub Releases:

# Install
    sudo rpm -i kubefwd_*_amd64.rpm
    # Upgrade
    sudo rpm -U kubefwd_*_amd64.rpm

=== "Linux (Manual)"

Download and extract the tarball from GitHub Releases:

tar -xzf kubefwd_Linux_amd64.tar.gz
    sudo mv kubefwd /usr/local/bin/
    sudo chmod +x /usr/local/bin/kubefwd

=== "Docker"

Run kubefwd in a privileged container:

docker run -it --rm --privileged \
        -v "$HOME/.kube:/root/.kube:ro" \
        txn2/kubefwd --tui

The container needs --privileged to modify network interfaces and the hosts file.

Verify installation:

kubefwd version

---

Operating Modes Copy Chapter

kubefwd supports two operating modes depending on how you want to work.

Idle Mode (Recommended) Copy Section

Start kubefwd without specifying namespaces. Add services interactively via TUI or programmatically via API.

sudo -E kubefwd --tui

In Idle Mode:

- REST API is enabled by default
- Auto-reconnect is enabled by default
- Use the TUI to browse namespaces, select services, and forward them
- Or use the API to add services dynamically

This is the recommended mode for interactive development. You can explore what's available in your cluster and forward exactly what you need.

Classic Mode Copy Section

Specify namespaces upfront. All services in those namespaces are forwarded immediately.

sudo -E kubefwd svc -n default --tui

Or without TUI for scripting:

sudo -E kubefwd svc -n default

Classic mode is backwards-compatible with all previous kubefwd versions. Add --tui, --api, or -a (auto-reconnect) as needed.

---

Your First Forward Copy Chapter

Interactive (Recommended) Copy Section

1. Start kubefwd in Idle Mode:

sudo -E kubefwd --tui

2. Browse namespaces: Press f to open the service browser, then select a namespace.

3. Forward services: Select individual services or press a to forward all services in the namespace.

4. Use your services: They're now accessible by name:

curl http://my-api:8080/health
    psql -h postgres -U admin -d mydb
    redis-cli -h redis ping

5. Quit: Press q to exit. kubefwd cleans up automatically.

Quick Start (Classic Mode) Copy Section

Forward all services in a namespace immediately:

sudo -E kubefwd svc -n my-namespace --tui

You'll see the TUI with all services from my-namespace being forwarded.

---

What Happens Under the Hood Copy Chapter

When kubefwd forwards a service:

1. IP Allocation: Each service gets a unique loopback IP (e.g., 127.1.27.1, 127.1.27.2)

2. Hosts File Update: Service names are added to /etc/hosts:

127.1.27.1    my-api
   127.1.27.2    postgres
   127.1.27.3    redis

3. Port Forwarding: kubefwd creates port forwards to pods backing each service

4. Ready to Use: Your applications can connect using service names, exactly like in-cluster

Your App → postgres:5432
         ↓
/etc/hosts: postgres = 127.1.27.2
         ↓
kubefwd listening on 127.1.27.2:5432
         ↓
Kubernetes API → Pod in cluster

Unique IPs Solve Port Conflicts Copy Section

Unlike kubectl port-forward which binds to a single port, kubefwd assigns each service its own IP address. This means:

- Multiple databases on port 5432? No problem.
- Multiple web services on port 80? Works fine.
- Every service uses its real port, just like in-cluster.

Cleanup Copy Section

When kubefwd exits (via q or Ctrl+C):

- /etc/hosts entries are removed
- Network interface aliases are cleaned up
- All port forward connections are closed

Your original hosts file is backed up to ~/hosts.original for safety.

---

Why sudo -E? Copy Chapter

kubefwd requires root privileges for:

- Modifying /etc/hosts
- Creating loopback IP aliases on the network interface
- Binding to ports below 1024

The -E flag preserves your environment variables, especially KUBECONFIG:

Correct - preserves KUBECONFIG

sudo -E kubefwd --tui
Wrong - may fail to find cluster config

sudo kubefwd --tui

---

Enabling the REST API Copy Chapter

The REST API allows programmatic control of kubefwd and enables AI assistant integration via MCP.

Idle Mode (API enabled by default):

sudo -E kubefwd
sudo -E kubefwd --tui

Classic Mode (add --api flag):

sudo -E kubefwd svc -n default --api

The API is available at:

- http://kubefwd.internal/api - REST endpoints
- http://kubefwd.internal/docs - Interactive API documentation

See REST API Reference for endpoints and MCP Integration for AI assistant setup.

---

Common Commands Copy Chapter

Idle mode with TUI (recommended for interactive use)

sudo -E kubefwd --tui
Forward specific namespace with TUI

sudo -E kubefwd svc -n my-namespace --tui
Forward multiple namespaces

sudo -E kubefwd svc -n frontend,backend,data --tui
Forward with label selector

sudo -E kubefwd svc -n default -l app=myapp --tui
Classic mode (no TUI, for scripts)

sudo -E kubefwd svc -n default
Enable verbose logging

sudo -E kubefwd svc -n default -v

---

Next Steps Copy Chapter

- User Guide - Master the interactive interface
- Configuration - All command-line options
- Advanced Usage - Multi-namespace, selectors, port mapping
- MCP Integration - AI assistant setup

Chapter: index (docs/index.md) Copy Section

---
title: kubefwd
description: Bulk port forward Kubernetes services to unique loopback IPs with /etc/hosts integration. Interactive TUI, REST API, and MCP server for AI assistants.
template: home.html
hide:
- navigation
- toc
- footer
---

Chapter: api-reference (docs/api-reference.md) Copy Section

REST API

kubefwd's REST API enables programmatic control over port forwarding. Build custom tooling, integrate with CI/CD pipelines, or create dashboards that dynamically manage which services are forwarded. Add and remove namespaces or individual services on the fly, query real-time metrics, stream events via SSE, and diagnose connection issues without restarting kubefwd.

Quick Start Copy Chapter

Idle mode - API enabled by default, add namespaces dynamically

sudo -E kubefwd
Or forward a namespace with API enabled

sudo -E kubefwd svc -n default --api
Test the API

curl http://kubefwd.internal/api/health

The API is available at http://kubefwd.internal/api.

Interactive documentation is at http://kubefwd.internal/docs.

Overview Copy Chapter

| Property | Value |
|----------|-------|
| Base URL | http://kubefwd.internal/api |
| Authentication | Bearer token (all endpoints except /api/health) |
| Response Format | JSON |
| OpenAPI Spec | /openapi.yaml |

All responses use this wrapper format:

{
  "success": true,
  "data": { ... },
  "error": null
}

Error responses:

{
  "success": false,
  "data": null,
  "error": {
    "code": "NOT_FOUND",
    "message": "Service not found"
  }
}

---

Authentication Copy Chapter

Every endpoint except /api/health requires a Bearer token. Send it in the
Authorization header:

curl http://kubefwd.internal/api/services \
  -H "Authorization: Bearer $KUBEFWD_API_KEY"

Requests with a missing or invalid key get 401 Unauthorized:

{
  "success": false,
  "data": null,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key required. Pass via Authorization: Bearer <key>"
  }
}

Getting the key Copy Section

kubefwd resolves the key at startup from the KUBEFWD_API_KEY environment
variable. If that variable is unset, it generates a random 32-character hex key
and prints the full key to the console when the server starts (this is the
only way to learn a generated key):

API key (generated): 8f3c2a1b9d4e6f70a1b2c3d4e5f60718
Set KUBEFWD_API_KEY to pin your own key instead.

To pin a known key — recommended for automation, CI, or the MCP bridge —
set the variable before launching:

export KUBEFWD_API_KEY=my-known-key
sudo -E kubefwd --api

When you supply the key this way, kubefwd does not echo it to the console —
it only logs that the key was read from KUBEFWD_API_KEY, since you already
know its value:

API key: using KUBEFWD_API_KEY from environment

The API binds to a loopback address (127.2.27.1) and is only reachable from

localhost, but the token is still required: any local process could otherwise

drive kubefwd against your kubeconfig (it runs as root via sudo -E).

Note: The curl examples below omit the Authorization header for

readability. Add -H "Authorization: Bearer $KUBEFWD_API_KEY" to every

request except /api/health.

---

Health & Info Copy Chapter

GET /api/health Copy Section

Health check endpoint.

curl http://kubefwd.internal/api/health

{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00Z"
}

GET /api/info Copy Section

Server information and version.

curl http://kubefwd.internal/api/info

{
  "version": "1.26.0",
  "uptime": "2h15m30s",
  "startedAt": "2025-01-15T08:15:00Z"
}

---

Services Copy Chapter

GET /api/v1/services Copy Section

List all forwarded services.

Query Parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| namespace | string | Filter by namespace |
| context | string | Filter by context |
| status | string | Filter by status (active, error) |

List all services

curl http://kubefwd.internal/api/v1/services
Filter by namespace

curl http://kubefwd.internal/api/v1/services?namespace=default

GET /api/v1/services/:key Copy Section

Get a specific service. Key format: service-name.namespace.context

curl http://kubefwd.internal/api/v1/services/api-gateway.default.minikube

POST /api/v1/services Copy Section

Add a new service to forward.

curl -X POST http://kubefwd.internal/api/v1/services \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "default",
    "service_name": "my-service",
    "context": "minikube"
  }'

DELETE /api/v1/services/:key Copy Section

Stop forwarding a service.

curl -X DELETE http://kubefwd.internal/api/v1/services/my-service.default.minikube

POST /api/v1/services/:key/reconnect Copy Section

Reconnect a specific service.

curl -X POST http://kubefwd.internal/api/v1/services/api-gateway.default.minikube/reconnect

POST /api/v1/services/:key/sync Copy Section

Sync service with Kubernetes (refresh pods).

curl -X POST http://kubefwd.internal/api/v1/services/api-gateway.default.minikube/sync

POST /api/v1/services/reconnect Copy Section

Reconnect all services (or all errored services).

Reconnect all errored services

curl -X POST http://kubefwd.internal/api/v1/services/reconnect
Force reconnect all services

curl -X POST "http://kubefwd.internal/api/v1/services/reconnect?force=true"

---

Forwards Copy Chapter

Individual port forwards (a service may have multiple forwards for different pods/ports).

GET /api/v1/forwards Copy Section

List all active port forwards.

Query Parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| namespace | string | Filter by namespace |
| service | string | Filter by service name |
| status | string | Filter by status |

curl http://kubefwd.internal/api/v1/forwards

GET /api/v1/forwards/:key Copy Section

Get details for a specific forward.

curl http://kubefwd.internal/api/v1/forwards/api-gateway-pod-abc.default.minikube

GET /api/v1/forwards/:key/http Copy Section

Get HTTP traffic captured for a forward.

Query Parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| count | integer | Number of entries (default: 50) |

curl http://kubefwd.internal/api/v1/forwards/api-gateway.default.minikube/http?count=10

---

Namespaces Copy Chapter

Manage namespace watchers dynamically.

GET /api/v1/namespaces Copy Section

List active namespace watchers.

curl http://kubefwd.internal/api/v1/namespaces

GET /api/v1/namespaces/:key Copy Section

Get details for a namespace watcher. Key format: namespace.context

curl http://kubefwd.internal/api/v1/namespaces/default.minikube

POST /api/v1/namespaces Copy Section

Add a namespace watcher (start forwarding all services in namespace).

curl -X POST http://kubefwd.internal/api/v1/namespaces \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "staging",
    "context": "minikube"
  }'

DELETE /api/v1/namespaces/:key Copy Section

Remove a namespace watcher (stop forwarding all services in namespace).

curl -X DELETE http://kubefwd.internal/api/v1/namespaces/staging.minikube

---

Kubernetes Discovery Copy Chapter

Query the Kubernetes cluster for available resources.

GET /api/v1/kubernetes/contexts Copy Section

List available kubeconfig contexts.

curl http://kubefwd.internal/api/v1/kubernetes/contexts

GET /api/v1/kubernetes/namespaces Copy Section

List namespaces in a context.

Query Parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| context | string | Kubernetes context (uses current if omitted) |

curl http://kubefwd.internal/api/v1/kubernetes/namespaces?context=minikube

GET /api/v1/kubernetes/services Copy Section

List services in a namespace.

Query Parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| namespace | string | Namespace (required) |
| context | string | Kubernetes context |

curl "http://kubefwd.internal/api/v1/kubernetes/services?namespace=default&context=minikube"

GET /api/v1/kubernetes/services/:namespace/:name Copy Section

Get details for a specific Kubernetes service.

curl http://kubefwd.internal/api/v1/kubernetes/services/default/api-gateway

GET /api/v1/kubernetes/pods/:namespace Copy Section

List pods in a namespace with status, ready state, restarts, and age.

Query Parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| context | string | Kubernetes context (uses current if omitted) |
| labelSelector | string | Filter pods by labels (e.g., "app=nginx") |
| serviceName | string | Filter to pods backing this service |

List all pods in namespace

curl http://kubefwd.internal/api/v1/kubernetes/pods/default
Filter by label

curl "http://kubefwd.internal/api/v1/kubernetes/pods/default?labelSelector=app=nginx"
Filter by service

curl "http://kubefwd.internal/api/v1/kubernetes/pods/default?serviceName=api-gateway"

GET /api/v1/kubernetes/pods/:namespace/:podName Copy Section

Get detailed pod information including containers, status, conditions, and resources.

curl http://kubefwd.internal/api/v1/kubernetes/pods/default/api-gateway-7d4f5b6c8-abc12

GET /api/v1/kubernetes/pods/:namespace/:podName/logs Copy Section

Get logs from a pod's container.

Query Parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| context | string | Kubernetes context (uses current if omitted) |
| container | string | Container name (defaults to first container) |
| tailLines | integer | Lines from end (default: 100, max: 1000) |
| sinceTime | string | RFC3339 timestamp to start from |
| previous | boolean | Get logs from previous container instance |
| timestamps | boolean | Include timestamps in output |

Get last 100 lines

curl http://kubefwd.internal/api/v1/kubernetes/pods/default/api-gateway-7d4f5b6c8-abc12/logs
Get last 50 lines with timestamps

curl "http://kubefwd.internal/api/v1/kubernetes/pods/default/api-gateway-7d4f5b6c8-abc12/logs?tailLines=50&timestamps=true"
Get logs from specific container

curl "http://kubefwd.internal/api/v1/kubernetes/pods/default/api-gateway-7d4f5b6c8-abc12/logs?container=sidecar"

GET /api/v1/kubernetes/events/:namespace Copy Section

Get Kubernetes events for debugging. Shows scheduling, pulling, starting, and killing events.

Query Parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| context | string | Kubernetes context (uses current if omitted) |
| resourceKind | string | Filter by kind (Pod, Service, Deployment) |
| resourceName | string | Filter by resource name |
| limit | integer | Max events to return (default: 50) |

Get all events in namespace

curl http://kubefwd.internal/api/v1/kubernetes/events/default
Filter to pod events

curl "http://kubefwd.internal/api/v1/kubernetes/events/default?resourceKind=Pod"
Get events for specific pod

curl "http://kubefwd.internal/api/v1/kubernetes/events/default?resourceKind=Pod&resourceName=api-gateway-7d4f5b6c8-abc12"

GET /api/v1/kubernetes/endpoints/:namespace/:serviceName Copy Section

Get endpoints for a service. Shows which pods are backing the service and their ready state.

curl http://kubefwd.internal/api/v1/kubernetes/endpoints/default/api-gateway

---

Metrics Copy Chapter

Traffic and performance metrics.

GET /api/v1/metrics Copy Section

Summary metrics for all forwards.

curl http://kubefwd.internal/api/v1/metrics

{
  "totalServices": 15,
  "activeForwards": 23,
  "totalBytesIn": 1048576,
  "totalBytesOut": 524288,
  "uptime": "2h15m"
}

GET /api/v1/metrics/services Copy Section

Metrics grouped by service.

curl http://kubefwd.internal/api/v1/metrics/services

GET /api/v1/metrics/services/:key Copy Section

Detailed metrics for a specific service.

curl http://kubefwd.internal/api/v1/metrics/services/api-gateway.default.minikube

GET /api/v1/metrics/services/:key/history Copy Section

Historical metrics for a service (time series data).

Query Parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| duration | string | Time window (e.g., "1h", "30m") |
| interval | string | Bucket interval (e.g., "1m", "5m") |

curl "http://kubefwd.internal/api/v1/metrics/services/api-gateway.default.minikube/history?duration=1h"

---

Diagnostics Copy Chapter

Error analysis and troubleshooting.

GET /api/v1/diagnostics Copy Section

Diagnostics summary.

curl http://kubefwd.internal/api/v1/diagnostics

GET /api/v1/diagnostics/errors Copy Section

List current errors.

curl http://kubefwd.internal/api/v1/diagnostics/errors

GET /api/v1/diagnostics/services/:key Copy Section

Diagnostics for a specific service.

curl http://kubefwd.internal/api/v1/diagnostics/services/api-gateway.default.minikube

GET /api/v1/diagnostics/forwards/:key Copy Section

Diagnostics for a specific forward.

curl http://kubefwd.internal/api/v1/diagnostics/forwards/api-gateway.default.minikube

GET /api/v1/diagnostics/network Copy Section

Network interface diagnostics.

curl http://kubefwd.internal/api/v1/diagnostics/network

---

Analysis Copy Chapter

AI-friendly status and analysis endpoints.

GET /api/v1/status Copy Section

Quick status overview optimized for AI tools.

curl http://kubefwd.internal/api/v1/status

{
  "status": "healthy",
  "message": "All services forwarding normally",
  "totalServices": 15,
  "activeServices": 15,
  "errorCount": 0
}

GET /api/v1/analyze Copy Section

Detailed analysis with recommendations.

curl http://kubefwd.internal/api/v1/analyze

---

History Copy Chapter

Event and error history.

GET /api/v1/history/events Copy Section

Recent events.

Query Parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| count | integer | Number of events (default: 50) |

curl http://kubefwd.internal/api/v1/history/events?count=20

GET /api/v1/history/errors Copy Section

Error history.

curl http://kubefwd.internal/api/v1/history/errors?count=20

GET /api/v1/history/reconnections Copy Section

All reconnection events.

curl http://kubefwd.internal/api/v1/history/reconnections

GET /api/v1/services/:key/history/reconnections Copy Section

Reconnection history for a specific service.

curl http://kubefwd.internal/api/v1/services/api-gateway.default.minikube/history/reconnections

GET /api/v1/history/stats Copy Section

Aggregated history statistics.

curl http://kubefwd.internal/api/v1/history/stats

---

Logs Copy Chapter

Application logs.

GET /api/v1/logs Copy Section

Recent log entries.

Query Parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| count | integer | Number of entries (default: 100) |
| level | string | Filter by level (debug, info, warn, error) |
| service | string | Filter by service |

curl "http://kubefwd.internal/api/v1/logs?count=50&level=error"

GET /api/v1/logs/stream Copy Section

Server-Sent Events (SSE) stream of logs.

curl http://kubefwd.internal/api/v1/logs/stream

GET /api/v1/logs/system Copy Section

System-level logs.

curl http://kubefwd.internal/api/v1/logs/system

DELETE /api/v1/logs/system Copy Section

Clear system logs.

curl -X DELETE http://kubefwd.internal/api/v1/logs/system

---

Events (SSE) Copy Chapter

GET /api/v1/events Copy Section

Server-Sent Events stream for real-time updates.

curl http://kubefwd.internal/api/v1/events

Event types:

- service.added - New service started forwarding
- service.removed - Service stopped forwarding
- service.error - Service encountered an error
- forward.connected - Port forward established
- forward.disconnected - Port forward lost
- pod.added - Pod added to service
- pod.removed - Pod removed from service

Example event:

event: service.added
data: {"key":"api-gateway.default.minikube","namespace":"default","service":"api-gateway"}

---

HTTP Traffic Copy Chapter

HTTP request/response capture for debugging.

GET /api/v1/services/:key/http Copy Section

HTTP traffic for a service.

Query Parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| count | integer | Number of entries (default: 50) |

curl http://kubefwd.internal/api/v1/services/api-gateway.default.minikube/http?count=10

---

Error Codes Copy Chapter

| Code | Description |
|------|-------------|
| NOT_FOUND | Resource not found |
| BAD_REQUEST | Invalid request parameters |
| INTERNAL_ERROR | Server error |
| ALREADY_EXISTS | Resource already exists |
| CONFLICT | Operation conflicts with current state |

---

See Also Copy Chapter

- Getting Started - Installation and basic usage
- MCP Integration - AI assistant integration
- Configuration - CLI flags reference