kubefwd

https://kubefwd.com
Admin
kubefwd is a Kubernetes port forwarding tool that makes cluster services locally accessible by name...
Tokens:40,845
Snippets:606
Trust Score:6.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### MCP Environment Setup Example

Source: https://kubefwd.com/mcp-integration

Shows how an AI assistant, using MCP, can discover and configure local environment variables for development services based on user requests.

```bash
You: I'm starting work on the checkout service, set up my environment
AI: Your environment is ready. These services are available locally:
  * cart-service:8080
  * payment-service:443
  * inventory-service:8080
  * user-db:5432

Add to your .env: `CART_URL=http://cart-service:8080 PAYMENT_URL=https://payment-service:443`
```

--------------------------------

### Install kubefwd on Windows

Source: https://kubefwd.com/getting-started

Install kubefwd on Windows using winget or Scoop. Upgrading follows a similar pattern.

```bash
winget install txn2.kubefwd

```

```bash
scoop install kubefwd

```

```bash
winget upgrade txn2.kubefwd
# or
scoop update kubefwd

```

--------------------------------

### Start kubefwd with Pre-forwarded Namespace and API

Source: https://kubefwd.com/mcp-integration?q=

Starts kubefwd, pre-forwarding a specified namespace and enabling the API for MCP communication.

```bash
sudo -E kubefwd svc -n default --api
```

--------------------------------

### Install and Run kubefwd in TUI Mode

Source: https://kubefwd.com/

Install kubefwd using a package manager and run it to access services via the interactive TUI. Services can then be accessed using their names.

```bash
$ brew install kubefwd
$ sudo -E kubefwd svc -n my-namespace --tui
  press ? for help, q to quit

# in another terminal, services resolve by name:
$ curl http://api-gateway:8080
$ redis-cli -h cache -p 6379
$ mysql -h database -P 3306
```

--------------------------------

### Install kubefwd on RHEL/Fedora

Source: https://kubefwd.com/getting-started

Install or upgrade the .rpm package for kubefwd on RHEL-based systems. Requires root privileges.

```bash
# Install
sudo rpm -i kubefwd_*_amd64.rpm

# Upgrade
sudo rpm -U kubefwd_*_amd64.rpm

```

--------------------------------

### Start kubefwd with API Enabled for Tunneling

Source: https://kubefwd.com/mcp-integration?q=

Starts kubefwd with the API enabled, necessary for exposing the REST API through a tunnel for remote MCP servers like ChatGPT.

```bash
sudo -E kubefwd --api
```

--------------------------------

### Install kubefwd on Debian/Ubuntu

Source: https://kubefwd.com/getting-started

Install or upgrade the .deb package for kubefwd on Debian-based systems. Requires root privileges.

```bash
# Install
sudo dpkg -i kubefwd_*_amd64.deb

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

```

--------------------------------

### Start kubefwd for Remote MCP with ChatGPT

Source: https://kubefwd.com/mcp-integration

Start kubefwd with the API enabled to expose its REST API for remote connections, typically used with ChatGPT.

```bash
sudo -E kubefwd --api

```

--------------------------------

### Start kubefwd with API Enabled

Source: https://kubefwd.com/mcp-integration

Start kubefwd in idle mode with the API enabled to allow MCP commands. Use `--tui` to monitor activity or pre-forward a namespace.

```bash
sudo -E kubefwd

```

```bash
sudo -E kubefwd --tui

```

```bash
sudo -E kubefwd svc -n default --api

```

--------------------------------

### Verify kubefwd Installation

Source: https://kubefwd.com/getting-started

Check if kubefwd is installed correctly by running the version command.

```bash
kubefwd version

```

--------------------------------

### Start Kubefwd in Idle Mode

Source: https://kubefwd.com/user-guide

Use this command to start kubefwd in idle mode, allowing you to add services as needed instead of forwarding everything upfront.

```bash
sudo -E kubefwd --tui
```

--------------------------------

### Install kubefwd on macOS

Source: https://kubefwd.com/getting-started

Use Homebrew to install kubefwd on macOS. To upgrade, run the update and upgrade commands.

```bash
brew install kubefwd

```

```bash
brew update && brew upgrade kubefwd

```

--------------------------------

### Start kubefwd in Idle Mode with API

Source: https://kubefwd.com/mcp-integration?q=

Starts kubefwd in idle mode, waiting for MCP commands. The API must be enabled for MCP communication.

```bash
sudo -E kubefwd
```

--------------------------------

### Metrics response example

Source: https://kubefwd.com/api-reference

Example JSON response for the summary metrics endpoint.

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

--------------------------------

### Quick Start: Forward Services in a Namespace

Source: https://kubefwd.com/getting-started

Use Classic Mode with the TUI to quickly forward all services within a specific namespace.

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

```

--------------------------------

### Hosts File Example

Source: https://kubefwd.com/getting-started

Illustrates how service names are mapped to unique loopback IP addresses in the /etc/hosts file when kubefwd is active.

```text
127.1.27.1    my-api
127.1.27.2    postgres
127.1.27.3    redis

```

--------------------------------

### Install kubefwd Manually on Linux

Source: https://kubefwd.com/getting-started

Download, extract, and move the kubefwd binary to your PATH. Ensure it has execute permissions.

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

```

--------------------------------

### Hosts File Management Example

Source: https://kubefwd.com/architecture?q=

Shows the structure of the /etc/hosts file before and after kubefwd modifies it to map service names to allocated IPs.

```text
# Before kubefwd
127.0.0.1       localhost

# After kubefwd starts
127.0.0.1       localhost
127.1.27.1      api-service
127.1.27.2      database
127.1.27.3      cache
```

--------------------------------

### GET /api/v1/logs/system

Source: https://kubefwd.com/api-reference

Retrieves system-level logs.

```APIDOC
## GET /api/v1/logs/system

### Description
System-level logs.

### Method
GET

### Endpoint
/api/v1/logs/system

### Request Example
```bash
curl http://kubefwd.internal/api/v1/logs/system
```
```

--------------------------------

### Start kubefwd in Classic Mode with TUI

Source: https://kubefwd.com/getting-started

Run kubefwd in Classic Mode to forward all services in specified namespaces immediately. Includes the TUI for interaction.

```bash
sudo -E kubefwd svc -n default --tui

```

--------------------------------

### Access Services by Name

Source: https://kubefwd.com/getting-started

Examples of accessing forwarded services using their names, similar to how they are accessed within the cluster.

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

```

--------------------------------

### API Info Response

Source: https://kubefwd.com/api-reference

Example response from the /api/info endpoint, providing server details.

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

--------------------------------

### Use IP Reservation Configuration File

Source: https://kubefwd.com/configuration

Use a YAML configuration file for complex IP reservation setups. This allows defining multiple reservations and a base IP for auto-allocation.

```bash
sudo -E kubefwd svc -n default -z config.yml --tui

```

--------------------------------

### Example Event Data

Source: https://kubefwd.com/api-reference

Illustrates the format of an event pushed through the SSE stream, specifically for a 'service.added' event.

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

```

--------------------------------

### Get Detailed Analysis

Source: https://kubefwd.com/api-reference

Retrieves a detailed analysis of kubefwd's operation, including recommendations.

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

--------------------------------

### Get Quick Status Overview

Source: https://kubefwd.com/api-reference

Provides a quick status overview of kubefwd, optimized for automated tools.

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

--------------------------------

### Get Diagnostics Summary

Source: https://kubefwd.com/api-reference

Retrieves a summary of the current diagnostics for kubefwd.

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

--------------------------------

### Get System-Level Logs

Source: https://kubefwd.com/api-reference

Retrieves logs generated at the system level.

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

--------------------------------

### Start kubefwd in Idle Mode with TUI

Source: https://kubefwd.com/getting-started

Launch kubefwd in recommended Idle Mode, enabling the REST API and auto-reconnect. Use the TUI to interactively manage services.

```bash
sudo -E kubefwd --tui

```

--------------------------------

### IP Reservation Configuration File Format

Source: https://kubefwd.com/configuration?q=

Example YAML structure for the IP reservation configuration file. It allows defining specific service-to-IP mappings and an optional base IP for auto-allocation.

```yaml
# config.yml
reservations:
  # Reserve specific IPs for services
  - service: api-gateway
    namespace: default
    ip: 127.3.3.1

  - service: database
    namespace: default
    ip: 127.3.3.2

  - service: cache
    namespace: default
    ip: 127.3.3.3

# Optional: base IP for auto-allocation
baseIP: 127.1.27.1

```

--------------------------------

### Check kubefwd Version

Source: https://kubefwd.com/troubleshooting?q=

Display the currently installed version of kubefwd. This is useful for reporting issues and ensuring you are using the latest version.

```bash
kubefwd version
```

--------------------------------

### Verify kubefwd Installation Path

Source: https://kubefwd.com/mcp-integration?q=

Check if the kubefwd executable is in your system's PATH.

```bash
which kubefwd

```

--------------------------------

### Get Detailed Analysis

Source: https://kubefwd.com/api-reference?q=

Retrieves a detailed analysis of the system, including recommendations. This endpoint is useful for in-depth troubleshooting.

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

```

--------------------------------

### Add Namespace

Source: https://kubefwd.com/api-reference?q=

Add a namespace watcher to start forwarding all services within that namespace.

```APIDOC
## POST /api/v1/namespaces

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

### Method
POST

### Endpoint
/api/v1/namespaces

### Request Body
- **namespace** (string) - Required - The namespace to watch.
- **context** (string) - Required - The Kubernetes context.

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

--------------------------------

### Get API Server Information

Source: https://kubefwd.com/api-reference

Retrieves information about the kubefwd server, including version and uptime.

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

--------------------------------

### Get Kubernetes events for debugging

Source: https://kubefwd.com/api-reference

Retrieves Kubernetes events for debugging purposes, including scheduling, pulling, starting, and killing events. Supports filtering by resource kind and name.

```APIDOC
## GET /api/v1/kubernetes/events/:namespace

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

### Method
GET

### Endpoint
/api/v1/kubernetes/events/:namespace

### Parameters
#### Query Parameters
- **context** (string) - Optional - Kubernetes context (uses current if omitted)
- **resourceKind** (string) - Optional - Filter by kind (Pod, Service, Deployment)
- **resourceName** (string) - Optional - Filter by resource name
- **limit** (integer) - Optional - Max events to return (default: 50)

### Request Example
```bash
# 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 Kubernetes events

Source: https://kubefwd.com/api-reference

Retrieve Kubernetes events for debugging purposes, including scheduling, pulling, starting, and killing events. Supports filtering by resource kind and name, and limiting the number of events.

```bash
# Get all events in namespace
curl http://kubefwd.internal/api/v1/kubernetes/events/default
```

```bash
# Filter to pod events
curl "http://kubefwd.internal/api/v1/kubernetes/events/default?resourceKind=Pod"
```

```bash
# Get events for specific pod
curl "http://kubefwd.internal/api/v1/kubernetes/events/default?resourceKind=Pod&resourceName=api-gateway-7d4f5b6c8-abc12"
```

--------------------------------

### Get metrics grouped by service

Source: https://kubefwd.com/api-reference

Retrieve performance metrics for kubefwd, grouped by individual services.

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

--------------------------------

### Get Namespace Details

Source: https://kubefwd.com/api-reference

Retrieve details for a specific namespace watcher. The key format is `namespace.context`.

```APIDOC
## GET /api/v1/namespaces/:key

### Description
Get details for a namespace watcher. Key format: `namespace.context`

### Method
GET

### Endpoint
/api/v1/namespaces/:key

### Parameters
#### Path Parameters
- **key** (string) - Required - The key of the namespace watcher (format: `namespace.context`).

### Request Example
```bash
curl http://kubefwd.internal/api/v1/namespaces/default.minikube
```
```

--------------------------------

### Real Workflow: Building a Notification Service with MCP

Source: https://kubefwd.com/mcp-integration

A detailed scenario of using MCP to discover available services, forward necessary ones, and generate configuration for a new service.

```bash
You: I'm building a notification service that needs to send emails and store records in the database. What services are available in the dev namespace?
AI: _queries cluster_ "I found these services in dev:
  * postgres:5432 (database)
  * smtp:2525 (mail server)
  * redis:6379 (cache)
  * api-gateway:8080

Want me to forward postgres and smtp for your notification service?"
You: Yes, forward those
AI: _forwards services_ "Done. Here's your configuration:
```
# config.py
DATABASE_URL = 'postgresql://dev:dev123@postgres:5432/notifications'
SMTP_HOST = 'smtp'
SMTP_PORT = 2525

```

These hostnames work exactly like they would in-cluster."
```

--------------------------------

### Enable Verbose Logging in kubefwd

Source: https://kubefwd.com/troubleshooting?q=

Enable verbose logging to get detailed information about service discovery, pod selection, IP allocation, and connection lifecycle events.

```bash
sudo -E kubefwd svc -n default -v --tui
```

--------------------------------

### Get Real-time Event Stream

Source: https://kubefwd.com/api-reference

Connects to a Server-Sent Events (SSE) stream for real-time updates on kubefwd events.

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

--------------------------------

### Get Quick Status Overview

Source: https://kubefwd.com/api-reference?q=

Provides a concise status overview optimized for AI tools. Includes health status, message, and service counts.

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

```

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

```

--------------------------------

### Get Specific Service Diagnostics

Source: https://kubefwd.com/api-reference

Retrieves detailed diagnostics for a particular service. Replace 'api-gateway.default.minikube' with the target service key.

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

--------------------------------

### Configure IP reservations with a file

Source: https://kubefwd.com/troubleshooting?q=

Configure IP reservations using a YAML file, specifying the base IP and individual service reservations.

```yaml
# fwdconf.yml
baseIP: 127.50.50.1
reservations:
  - service: api
    namespace: default
    ip: 127.50.50.1
```

--------------------------------

### Get detailed pod information

Source: https://kubefwd.com/api-reference

Retrieve comprehensive details for a specific pod, including its containers, status, conditions, and resource utilization.

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

--------------------------------

### AI-driven Service Discovery and Configuration

Source: https://kubefwd.com/mcp-integration?q=

Shows how an AI assistant can discover available services in a Kubernetes namespace and provide ready-to-use configuration for development.

```python
# config.py
DATABASE_URL = 'postgresql://dev:dev123@postgres:5432/notifications'
SMTP_HOST = 'smtp'
SMTP_PORT = 2525
```

--------------------------------

### Get summary metrics for all forwards

Source: https://kubefwd.com/api-reference

Retrieve summary metrics for all active forwards, including total services, active forwards, total bytes in/out, and uptime.

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

--------------------------------

### Forward Services from All Namespaces

Source: https://kubefwd.com/configuration?q=

Use the -A flag to forward services from all available namespaces. This is a convenient option for a comprehensive view.

```bash
sudo -E kubefwd svc -A --tui
```

--------------------------------

### MCP-based Kubernetes Port Forwarding Workflow

Source: https://kubefwd.com/mcp-integration?q=

Demonstrates how MCP simplifies Kubernetes port forwarding, allowing AI to handle infrastructure tasks seamlessly.

```shell
You: I need the staging database
AI: Connected. Your connection: psql -h postgres -U admin -d mydb
```

--------------------------------

### GET /api/v1/diagnostics/network

Source: https://kubefwd.com/api-reference

Provides diagnostics for the network interfaces.

```APIDOC
## GET /api/v1/diagnostics/network

### Description
Network interface diagnostics.

### Method
GET

### Endpoint
/api/v1/diagnostics/network

### Request Example
```bash
curl http://kubefwd.internal/api/v1/diagnostics/network
```
```

--------------------------------

### GET /api/v1/history/stats

Source: https://kubefwd.com/api-reference

Retrieves aggregated statistics from the event history.

```APIDOC
## GET /api/v1/history/stats

### Description
Aggregated history statistics.

### Method
GET

### Endpoint
/api/v1/history/stats

### Request Example
```bash
curl http://kubefwd.internal/api/v1/history/stats
```
```

--------------------------------

### Configure kubefwd MCP Server for Zed

Source: https://kubefwd.com/mcp-integration

Add kubefwd as a custom context server in Zed's `settings.json` file.

```json
{
  "context_servers": {
    "kubefwd": {
      "source": "custom",
      "command": "kubefwd",
      "args": ["mcp"]
    }
  }
}

```

--------------------------------

### GET /api/v1/history/reconnections

Source: https://kubefwd.com/api-reference

Retrieves a list of all past reconnection events.

```APIDOC
## GET /api/v1/history/reconnections

### Description
All reconnection events.

### Method
GET

### Endpoint
/api/v1/history/reconnections

### Request Example
```bash
curl http://kubefwd.internal/api/v1/history/reconnections
```
```

--------------------------------

### GET /api/v1/diagnostics/errors

Source: https://kubefwd.com/api-reference

Lists all current errors within the system.

```APIDOC
## GET /api/v1/diagnostics/errors

### Description
List current errors.

### Method
GET

### Endpoint
/api/v1/diagnostics/errors

### Request Example
```bash
curl http://kubefwd.internal/api/v1/diagnostics/errors
```
```

--------------------------------

### GET /api/v1/diagnostics

Source: https://kubefwd.com/api-reference

Retrieves a summary of the system's diagnostics.

```APIDOC
## GET /api/v1/diagnostics

### Description
Diagnostics summary.

### Method
GET

### Endpoint
/api/v1/diagnostics

### Request Example
```bash
curl http://kubefwd.internal/api/v1/diagnostics
```
```

--------------------------------

### Get Specific Namespace

Source: https://kubefwd.com/api-reference?q=

Retrieve details for a specific namespace watcher.

```APIDOC
## GET /api/v1/namespaces/:key

### Description
Get details for a namespace watcher. Key format: `namespace.context`

### Method
GET

### Endpoint
/api/v1/namespaces/:key

### Request Example
```bash
curl http://kubefwd.internal/api/v1/namespaces/default.minikube
```
```

--------------------------------

### GET /api/v1/services/:key/history/reconnections

Source: https://kubefwd.com/api-reference

Retrieves reconnection history for a specific service.

```APIDOC
## GET /api/v1/services/:key/history/reconnections

### Description
Reconnection history for a specific service.

### Method
GET

### Endpoint
/api/v1/services/:key/history/reconnections

### Parameters
#### Path Parameters
- **key** (string) - Required - The key of the service to get reconnection history for.

### Request Example
```bash
curl http://kubefwd.internal/api/v1/services/api-gateway.default.minikube/history/reconnections
```
```

--------------------------------

### Use IP Reservation Configuration File

Source: https://kubefwd.com/configuration?q=

Specify a YAML configuration file using the -z flag for complex IP reservation setups. This allows for defining multiple reservations and a base IP for auto-allocation.

```bash
sudo -E kubefwd svc -n default -z config.yml --tui
```

--------------------------------

### Launch kubefwd for Multiple Namespaces

Source: https://kubefwd.com/user-guide

Forward services from multiple specified namespaces simultaneously. This is useful for microservice architectures with distinct service groups.

```bash
sudo -E kubefwd svc -n frontend,backend,data --tui

```

--------------------------------

### GET /api/v1/analyze

Source: https://kubefwd.com/api-reference

Performs a detailed analysis of the system and provides recommendations.

```APIDOC
## GET /api/v1/analyze

### Description
Detailed analysis with recommendations.

### Method
GET

### Endpoint
/api/v1/analyze

### Request Example
```bash
curl http://kubefwd.internal/api/v1/analyze
```
```

--------------------------------

### Integrate kubefwd with Tilt

Source: https://kubefwd.com/advanced-usage

Incorporate kubefwd into your Tilt development environment by defining it as a local resource in your Tiltfile. This ensures kubefwd is managed alongside your application.

```python
local_resource(
  'kubefwd',
  serve_cmd='sudo -E kubefwd svc -n default',
  deps=[]
)
```

--------------------------------

### Check RBAC permissions for listing resources

Source: https://kubefwd.com/troubleshooting?q=

Verify your RBAC permissions to list services and pods in a given namespace.

```bash
# Can you list services?
kubectl auth can-i list services -n default

# Can you list/get/watch pods?
kubectl auth can-i list pods -n default
kubectl auth can-i get pods -n default
kubectl auth can-i watch pods -n default
```

--------------------------------

### Get All Reconnection Events

Source: https://kubefwd.com/api-reference

Fetches a list of all recorded reconnection events.

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

--------------------------------

### Get Specific Forward

Source: https://kubefwd.com/api-reference?q=

Retrieve detailed information for a specific port forward.

```APIDOC
## GET /api/v1/forwards/:key

### Description
Get details for a specific forward.

### Method
GET

### Endpoint
/api/v1/forwards/:key

### Request Example
```bash
curl http://kubefwd.internal/api/v1/forwards/api-gateway-pod-abc.default.minikube
```
```

--------------------------------

### GET /api/v1/logs/stream

Source: https://kubefwd.com/api-reference

Provides a Server-Sent Events (SSE) stream of application logs.

```APIDOC
## GET /api/v1/logs/stream

### Description
Server-Sent Events (SSE) stream of logs.

### Method
GET

### Endpoint
/api/v1/logs/stream

### Request Example
```bash
curl http://kubefwd.internal/api/v1/logs/stream
```
```

--------------------------------

### Traditional Kubernetes Port Forwarding Workflow

Source: https://kubefwd.com/mcp-integration?q=

Illustrates the manual steps involved in port forwarding and retrieving connection information in a traditional Kubernetes workflow.

```shell
You: How do I forward postgres from kft1?
AI: Run sudo -E kubefwd svc -n kft1 -l app=postgres
You: *runs command*
You: What's the connection string?
AI: psql -h postgres -U user -d dbname
```

--------------------------------

### GET /api/v1/history/errors

Source: https://kubefwd.com/api-reference

Retrieves a list of historical errors. Supports filtering by count.

```APIDOC
## GET /api/v1/history/errors

### Description
Error history.

### Method
GET

### Endpoint
/api/v1/history/errors

### Parameters
#### Query Parameters
- **count** (integer) - Optional - Number of errors to retrieve (default: 50).

### Request Example
```bash
curl http://kubefwd.internal/api/v1/history/errors?count=20
```
```

--------------------------------

### GET /api/v1/history/events

Source: https://kubefwd.com/api-reference

Retrieves a list of recent events. Supports filtering by count.

```APIDOC
## GET /api/v1/history/events

### Description
Recent events.

### Method
GET

### Endpoint
/api/v1/history/events

### Parameters
#### Query Parameters
- **count** (integer) - Optional - Number of events to retrieve (default: 50).

### Request Example
```bash
curl http://kubefwd.internal/api/v1/history/events?count=20
```
```

--------------------------------

### List services in a namespace

Source: https://kubefwd.com/api-reference

Retrieve a list of services within a specified namespace and context. The namespace parameter is required.

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

--------------------------------

### Running Applications with mirrord

Source: https://kubefwd.com/comparison?q=

When using process-injection tools like mirrord, launch each application through the tool to grant it cluster access. Only the process executed via mirrord will see cluster services.

```bash
mirrord exec -- curl http://api-service:8080  # Only this curl sees cluster
```

```bash
mirrord exec -- your-app                        # Only this process sees cluster
```

--------------------------------

### GET /api/v1/diagnostics/services/:key

Source: https://kubefwd.com/api-reference

Retrieves diagnostics for a specific service identified by its key.

```APIDOC
## GET /api/v1/diagnostics/services/:key

### Description
Diagnostics for a specific service.

### Method
GET

### Endpoint
/api/v1/diagnostics/services/:key

### Parameters
#### Path Parameters
- **key** (string) - Required - The key of the service to get diagnostics for.

### Request Example
```bash
curl http://kubefwd.internal/api/v1/diagnostics/services/api-gateway.default.minikube
```
```

--------------------------------

### Run kubefwd in Classic Mode (Scripting)

Source: https://kubefwd.com/getting-started

Execute kubefwd in Classic Mode without the TUI, suitable for scripting and automated forwarding of services in specified namespaces.

```bash
sudo -E kubefwd svc -n default

```

--------------------------------

### GET /api/v1/status

Source: https://kubefwd.com/api-reference

Provides a quick status overview of the system, optimized for AI tools.

```APIDOC
## GET /api/v1/status

### Description
Quick status overview optimized for AI tools.

### Method
GET

### Endpoint
/api/v1/status

### Response
#### Success Response (200)
- **status** (string) - The overall health status of the system.
- **message** (string) - A human-readable message describing the current status.
- **totalServices** (integer) - The total number of services being managed.
- **activeServices** (integer) - The number of currently active services.
- **errorCount** (integer) - The number of errors encountered.

### Response Example
```json
{
  "status": "healthy",
  "message": "All services forwarding normally",
  "totalServices": 15,
  "activeServices": 15,
  "errorCount": 0
}
```
```

--------------------------------

### GET /api/v1/diagnostics/forwards/:key

Source: https://kubefwd.com/api-reference

Retrieves diagnostics for a specific port forward identified by its key.

```APIDOC
## GET /api/v1/diagnostics/forwards/:key

### Description
Diagnostics for a specific forward.

### Method
GET

### Endpoint
/api/v1/diagnostics/forwards/:key

### Parameters
#### Path Parameters
- **key** (string) - Required - The key of the forward to get diagnostics for.

### Request Example
```bash
curl http://kubefwd.internal/api/v1/diagnostics/forwards/api-gateway.default.minikube
```
```

--------------------------------

### Get Aggregated History Statistics

Source: https://kubefwd.com/api-reference

Fetches aggregated statistics based on historical data.

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

--------------------------------

### Run Kubefwd in Background with Logging

Source: https://kubefwd.com/mcp-integration?q=

Alternative mode for running kubefwd in the background with verbose logging captured to a file for debugging purposes. Requires sudo privileges.

```bash
sudo -E kubefwd -v 2>&1 | tee kubefwd.log &
```

--------------------------------

### Get Service

Source: https://kubefwd.com/api-reference

Retrieve details for a specific forwarded service using its unique key.

```APIDOC
## GET /api/v1/services/:key

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

### Method
GET

### Endpoint
/api/v1/services/:key

### Parameters
#### Path Parameters
- **key** (string) - Required - The unique key of the service (format: `service-name.namespace.context`).

### Request Example
```bash
curl http://kubefwd.internal/api/v1/services/api-gateway.default.minikube
```
```

--------------------------------

### Get System-Level Logs

Source: https://kubefwd.com/api-reference?q=

Retrieves logs generated at the system level. This can be useful for debugging kubefwd itself.

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

```

--------------------------------

### Restore hosts file from backup

Source: https://kubefwd.com/troubleshooting?q=

Restore the hosts file to a previous state by copying a backup file.

```bash
sudo cp ~/hosts.original /etc/hosts
```

--------------------------------

### Get Forward HTTP Traffic

Source: https://kubefwd.com/api-reference?q=

Retrieve captured HTTP traffic for a specific port forward.

```APIDOC
## GET /api/v1/forwards/:key/http

### Description
Get HTTP traffic captured for a forward.

### Method
GET

### Endpoint
/api/v1/forwards/:key/http

### Query Parameters
#### Query Parameters
- **count** (integer) - Optional - Number of entries to retrieve (default: 50).

### Request Example
```bash
curl http://kubefwd.internal/api/v1/forwards/api-gateway.default.minikube/http?count=10
```
```

--------------------------------

### Launching kubefwd for Service Access

Source: https://kubefwd.com/comparison?q=

Use this command to forward all services in a specific namespace with an interactive TUI. This method provides unique IPs for each service, preventing port conflicts and enabling service name resolution.

```bash
sudo -E kubefwd svc -n dev --tui
```

--------------------------------

### GET /api/v1/logs

Source: https://kubefwd.com/api-reference

Retrieves recent log entries. Supports filtering by count, level, and service.

```APIDOC
## GET /api/v1/logs

### Description
Recent log entries.

### Method
GET

### Endpoint
/api/v1/logs

### Parameters
#### Query Parameters
- **count** (integer) - Optional - Number of entries to retrieve (default: 100).
- **level** (string) - Optional - Filter by log level (e.g., debug, info, warn, error).
- **service** (string) - Optional - Filter by service name.

### Request Example
```bash
curl "http://kubefwd.internal/api/v1/logs?count=50&level=error"
```
```

--------------------------------

### Refresh hosts file backup with kubefwd

Source: https://kubefwd.com/troubleshooting?q=

Use the `-b` flag with kubefwd to create a fresh backup of your hosts file.

```bash
sudo -E kubefwd svc -n default -b --tui
```

--------------------------------

### Get Specific Service

Source: https://kubefwd.com/api-reference?q=

Retrieve details for a specific forwarded service using its unique key.

```APIDOC
## GET /api/v1/services/:key

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

### Method
GET

### Endpoint
/api/v1/services/:key

### Request Example
```bash
curl http://kubefwd.internal/api/v1/services/api-gateway.default.minikube
```
```

--------------------------------

### Get Network Interface Diagnostics

Source: https://kubefwd.com/api-reference

Fetches diagnostics related to the network interfaces used by kubefwd.

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

--------------------------------

### Forward Services from Specific Namespaces

Source: https://kubefwd.com/configuration

Specify one or more namespaces to forward services from. Use comma-separated values for multiple namespaces.

```bash
# Single namespace
sudo -E kubefwd svc -n default --tui

# Multiple namespaces (comma-separated)
sudo -E kubefwd svc -n default,staging,production --tui

# All namespaces
sudo -E kubefwd svc -A --tui

```

--------------------------------

### Get details for a specific Kubernetes service

Source: https://kubefwd.com/api-reference

Retrieves detailed information about a specific Kubernetes service.

```APIDOC
## GET /api/v1/kubernetes/services/:namespace/:name

### Description
Get details for a specific Kubernetes service.

### Method
GET

### Endpoint
/api/v1/kubernetes/services/:namespace/:name

### Request Example
```bash
curl http://kubefwd.internal/api/v1/kubernetes/services/default/api-gateway
```
```

--------------------------------

### Accessing Cluster Services with kubefwd

Source: https://kubefwd.com/comparison?q=

Demonstrates how applications can access cluster services using their service names after kubefwd updates the /etc/hosts file. This enables direct access from web browsers, database clients, and CLI tools.

```shell
# Your web browser can access cluster UIs
open http://grafana:3000
open http://kibana:5601

# Database clients (DBeaver, DataGrip, pgAdmin) connect directly
# Just use: host=postgres port=5432

# Any CLI tool works
curl http://api-service:8080/health
redis-cli -h redis -p 6379
psql -h postgres -U admin
mongo --host mongodb:27017

```

--------------------------------

### Verify Kubernetes context

Source: https://kubefwd.com/troubleshooting?q=

Ensure you are using the correct Kubernetes context by checking the current context and listing available contexts.

```bash
kubectl config current-context
kubectl config get-contexts
```

--------------------------------

### Execute kubefwd with Sudo

Source: https://kubefwd.com/mcp-integration?q=

Kubefwd requires elevated privileges for network operations. Use `sudo -E` to preserve environment variables.

```bash
# Wrong
kubefwd svc -n default

# Right
sudo -E kubefwd svc -n default

```

--------------------------------

### List Configured MCP Servers

Source: https://kubefwd.com/mcp-integration?q=

Verifies the MCP server configuration, listing all currently configured MCP servers, including kubefwd.

```bash
claude mcp list
```

--------------------------------

### Get Forward Details

Source: https://kubefwd.com/api-reference

Retrieve detailed information for a specific port forward using its key.

```APIDOC
## GET /api/v1/forwards/:key

### Description
Get details for a specific forward.

### Method
GET

### Endpoint
/api/v1/forwards/:key

### Parameters
#### Path Parameters
- **key** (string) - Required - The unique key of the forward.

### Request Example
```bash
curl http://kubefwd.internal/api/v1/forwards/api-gateway-pod-abc.default.minikube
```
```

--------------------------------

### List Configured MCP Servers

Source: https://kubefwd.com/mcp-integration

Verify that kubefwd has been successfully added to the list of MCP servers for your AI client.

```bash
claude mcp list

```

--------------------------------

### Kubefwd Status Response

Source: https://kubefwd.com/api-reference

Example JSON response for the /api/v1/status endpoint, indicating the health and operational status.

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

--------------------------------

### Check service endpoints and deployment

Source: https://kubefwd.com/troubleshooting?q=

Verify that a service has endpoints and that its associated deployment is healthy if no pods are found.

```bash
# Check pods for a service
kubectl get endpoints my-service -n default

# If empty, check deployment
kubectl get deployment -n default
kubectl describe deployment <deployment-name> -n default
```

--------------------------------

### Configure kubefwd MCP Server for Cursor

Source: https://kubefwd.com/mcp-integration

Add kubefwd as an MCP server by modifying the global or project-specific `mcp.json` file in Cursor.

```json
{
  "mcpServers": {
    "kubefwd": {
      "command": "kubefwd",
      "args": ["mcp"]
    }
  }
}

```

--------------------------------

### GET /api/v1/services/:key/http

Source: https://kubefwd.com/api-reference

Captures and retrieves HTTP traffic for a specific service. Supports filtering by count.

```APIDOC
## GET /api/v1/services/:key/http

### Description
HTTP traffic for a service.

### Method
GET

### Endpoint
/api/v1/services/:key/http

### Parameters
#### Path Parameters
- **key** (string) - Required - The key of the service to get HTTP traffic for.
#### Query Parameters
- **count** (integer) - Optional - Number of entries to retrieve (default: 50).

### Request Example
```bash
curl http://kubefwd.internal/api/v1/services/api-gateway.default.minikube/http?count=10
```
```

--------------------------------

### List pods in a namespace

Source: https://kubefwd.com/api-reference

List pods within a namespace, including their status, ready state, restarts, and age. Supports filtering by context, label selector, and service name.

```bash
# List all pods in namespace
curl http://kubefwd.internal/api/v1/kubernetes/pods/default
```

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

```bash
# Filter by service
curl "http://kubefwd.internal/api/v1/kubernetes/pods/default?serviceName=api-gateway"
```

--------------------------------

### GET /api/v1/events

Source: https://kubefwd.com/api-reference

Provides a Server-Sent Events (SSE) stream for real-time updates on various system events.

```APIDOC
## GET /api/v1/events

### Description
Server-Sent Events stream for real-time updates.

### Method
GET

### Endpoint
/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"}
```

### Request Example
```bash
curl http://kubefwd.internal/api/v1/events
```
```

--------------------------------

### Get service endpoints

Source: https://kubefwd.com/api-reference

Retrieve the endpoints for a specific service, showing the backing pods and their ready status.

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

--------------------------------

### List kubeconfig contexts

Source: https://kubefwd.com/api-reference

Use this endpoint to retrieve a list of available kubeconfig contexts.

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

--------------------------------

### Get Specific Forward Details

Source: https://kubefwd.com/api-reference

Retrieves detailed information about a specific port forward using its key.

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