# Kubeshark: cluster-wide traffic indexing with eBPF, TLS decryption and an MCP server for AI agents

> Kubeshark is an Apache-2.0 Go project that indexes Kubernetes L4/L7 traffic at the kernel level and exposes it through a dashboard, a CEL-based query language and an MCP endpoint. It is a strong fit for packet-level incident work, and a poor fit if you need a long-running capture on every cluster or cannot tolerate privileged eBPF pods.

**kubeshark/kubeshark** — eBPF-powered network observability for Kubernetes. Indexes L4/L7 traffic with full K8s context, decrypts TLS without keys. Queryable by AI agents via MCP and humans via dashboard.

- Repository: https://github.com/kubeshark/kubeshark
- Website: https://kubeshark.com
- Stars: 12,089 · Forks: 550
- Language: Go
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/kubeshark-kubeshark

## The gap Kubeshark fills between metrics, logs and packet capture

Metrics tell you a service started returning errors at 14:15. Logs tell you what the application decided to write down. Neither tells you what actually crossed the wire: which pod talked to which, which HTTP status came back, whether a TCP retransmission preceded the timeout, or what a gRPC call carried. The usual answer is a sidecar proxy, an agent with code instrumentation, or a tcpdump session on one node that you then have to correlate by hand.

Kubeshark takes the third path and removes the manual correlation. It indexes cluster-wide network traffic at the kernel level using eBPF, then attaches Kubernetes context to each request: namespace, pod, workload, node, IP. The README describes the result as "instant answers to any query using network, API, and Kubernetes semantics." The audience it names is SREs and AI agents, which is an accurate description of the two interfaces it ships: a dashboard for humans and an MCP server for agents.

The project is written in Go and licensed Apache-2.0. The last push to master was on 2026-09-09, and the most recent release listed is v53.4.0 from 2026-08-13. That version numbering is worth noting before you plan upgrades: the major number is high and the minor releases are not frequent, so pinning a version in your Helm values is cheaper than tracking latest.

## How the eBPF capture, L7 dissection and KFL query layer fit together

The pipeline has three visible stages. First, eBPF programs in the kernel capture packets on the nodes where Kubeshark is deployed. Second, those packets are parsed according to protocol specifications. The README lists HTTP, gRPC, GraphQL, Redis, Kafka and DNS, with request/response matching and full payloads, and calls the result L7 indexing. Third, the indexed records are queryable through KFL, described as a CEL-based query language that can combine Kubernetes identity, API context and network attributes in a single expression.

TLS decryption happens in the capture stage rather than through a proxy. The README states that Kubeshark decrypts TLS and mTLS traffic using eBPF "with no key management or sidecars required," and that decrypted traffic is included in snapshots. That is the design decision that separates it from service-mesh approaches: nothing is inserted into the request path, so the application does not change and no certificate has to be distributed. The trade-off is symmetric. You are not proxying traffic, so you are also not enforcing anything, and you depend entirely on what the kernel-level capture can see and reassemble.

Retention is handled by traffic snapshots. A snapshot is a point-in-time capture that can be scoped by time range, nodes, workloads and IPs, exported as PCAP for Wireshark or any PCAP-compatible tool, and stored in S3, Azure Blob or GCS for long-term retention and cross-cluster sharing. The repository layout reflects this split between the CLI and the cluster side: cmd/, internal/, helm-chart/, manifests/, kubernetes/, mcp/ and skills/ sit alongside a kubeshark.go entry point. The mcp/ directory is the server that the CLI starts, and skills/ holds the two published AI skills, network-rca and kfl.

## Installing Kubeshark with Helm and capturing your first traffic

The README gives Helm as the primary install path. Adding the repository and installing the chart creates the cluster-side components, and a port-forward exposes the dashboard on port 8899.

```bash
helm repo add kubeshark https://helm.kubeshark.com
helm install kubeshark kubeshark/kubeshark
kubectl port-forward svc/kubeshark-front 8899:80
```

After the port-forward is running, opening http://localhost:8899 in a browser should show the dashboard already capturing traffic. The README notes that for production use an ingress controller is recommended instead of port-forward, and links to an ingress guide rather than documenting the values inline.

There is a second, CLI-first path for local machines. Homebrew installs the binary, and kubeshark tap starts a capture.

```bash
brew install kubeshark
kubeshark tap
```

The README's install table also lists a direct binary download from the releases page. If you are working from a source checkout instead, the Makefile defines the build targets: make build sets CGO_ENABLED=0 and produces bin/kubeshark_$(GOOS)_$(GOARCH) plus a .sha256 file, while make build-debug and make build-race switch CGO on for debugging and race detection. The version string is injected at link time through the misc.Ver variable, so a locally built binary reports whatever VER you export.

## Connecting an AI agent over MCP, and what the skills actually do

The MCP integration is the part of Kubeshark that has no direct equivalent in the tools it usually gets compared to. The README shows two commands: installing the CLI with Homebrew and registering the MCP server with Claude.

```bash
brew install kubeshark
claude mcp add kubeshark -- kubeshark mcp
```

The README states that this works with Claude Code, Cursor and any MCP-compatible AI, and gives the kind of question the agent is expected to answer: why a checkout failed at a specific time, which services have error rates above one percent, TCP retransmission rates across node-to-node paths, or tracing one request identifier through all services. Those are queries over indexed traffic, not over metrics, which is why the MCP server can answer them at all.

The skills directory holds reusable workflow definitions rather than data. Network RCA covers retrospective root cause analysis through snapshots, dissection, PCAP extraction and trend comparison. KFL covers writing, debugging and optimizing traffic filters. They can be installed as a Claude Code plugin through the marketplace commands in the README, or cloned and used directly, in which case the README says they trigger automatically based on conversation context. Treat the skills as prompt scaffolding: they shape how an agent sequences Kubeshark's MCP tools, and they are only as good as the queries the agent ends up issuing.

## Where Kubeshark is the wrong tool

Kubeshark is not a metrics store and does not try to be. If your question is whether p99 latency has drifted over the last quarter, you want a time-series system, not indexed packets. The project gives you traffic and the ability to query it; it does not give you retention curves, alerting rules or SLO evaluation.

The deployment model is the sharper constraint. Capture happens in the kernel on the nodes you deploy to, which means privileged pods and a node-level footprint. The README does not document a per-node overhead figure, and it does not describe a sampling mode that would let you trade fidelity for cost. On a large cluster, the honest planning assumption is that you are running capture on every node you want visibility into, and that the cost scales with node count and traffic volume rather than with the number of services you care about.

TLS decryption deserves the same skepticism. Capturing plaintext without keys is exactly what makes the tool useful for debugging and exactly what makes it a data-protection question. Anyone who can reach the dashboard or the MCP endpoint is looking at request and response payloads, including credentials in headers and bodies. The README does not document per-user access control on the dashboard, and it does not describe redaction rules for indexed payloads. If your cluster carries regulated data, that gap is something you have to close at the network and identity layer yourself, not something the chart closes for you.

Finally, the documentation is thin in places where operators need detail. The Helm install is a two-line example, and the README points to the docs site for values, ingress and air-gapped deployment rather than reproducing them. There is no rollback guidance in the README, and no documented compatibility matrix between CLI versions and cluster-side versions. Check those pages before you assume an upgrade is a single helm upgrade.

## Kubeshark against the service-mesh and sidecar approach

The closest alternative is a service mesh with an observability add-on, or a sidecar-based capture agent. Both give you L7 request data with Kubernetes context, and both do it by putting something in the request path. A mesh sidecar terminates or intercepts connections, which is why it can decrypt TLS, enforce policy and emit per-request telemetry. It also means every workload has to be injected, every certificate has to be rotated, and the mesh itself becomes a component you operate.

Kubeshark inverts that. Nothing is injected into the workload, no keys are managed, and the capture is external to the application. The cost is that it observes rather than controls. It cannot block a request, cannot rewrite a header, and cannot enforce mutual TLS policy. It also sees what the kernel sees, which is a different and generally lower-level view than a proxy's view of a request: the README explicitly frames the output as PCAPs and indexed packets that you can open in Wireshark, which is a packet-tool workflow, not a mesh-dashboard workflow.

For teams already running a mesh, the interesting question is not replacement but overlap. The mesh answers questions about policy and service-to-service identity. Kubeshark answers questions about what was on the wire, including traffic that never went through the mesh. Those are different failure modes, and the second one is the one you reach for when a mesh-instrumented service still fails and you cannot explain why.

## Licence, upgrade cadence and the cost of running capture

Kubeshark is Apache-2.0. That permits commercial use, modification and redistribution, and it includes a patent grant. It also means there is no open-core boundary documented in the README: the MCP server, the skills and the cluster components are all in the same repository under the same licence. The README does not describe a paid tier, and the questions people ask about whether Kubeshark is free are answered by the licence file rather than by a pricing page. This is not legal advice; if you redistribute a modified build, read the licence text and your own obligations.

Upgrade cost is dominated by two things. The first is the release cadence. The listed releases are v53.4.0 in August 2026, v53.3.0 in May 2026 and v53.2.5 in May 2026, with the last push to master on 2026-09-09. Releases are not weekly, but the version numbers move in large steps, so reading the release notes between your pinned version and the target is not optional. The second is the cluster-side footprint. Because capture runs per node, the resource cost of an upgrade is a function of your node count, and the README does not publish a sizing table you can plan against.

Two operational details are worth pinning down before rollout. Snapshots can be written to S3, Azure Blob or GCS, so retention has a storage cost and a credentials story that the README leaves to the cloud storage guide. And air-gapped deployment is listed as a supported feature under the 100 percent on-premises entry, which matters if your cluster cannot reach helm.kubeshark.com at install time.

## Conclusion

Adopt Kubeshark if you debug Kubernetes networking at the packet and API level, or if you want an MCP server so an AI agent can answer questions like which services exceed an error threshold. Do not adopt it as a general metrics or log backend: it indexes traffic, not time series, and it needs privileged eBPF pods on the nodes you want to see. Verify first that your cluster admits those pods under your own policy, that the Helm release matches the v53.4.0 line you intend to run, and that the traffic snapshots land in the storage backend you actually operate.

## FAQ

### How do I install Kubeshark?

The README gives Helm as the main path: add the kubeshark Helm repository, install the kubeshark/kubeshark chart, then port-forward svc/kubeshark-front on 8899 to reach the dashboard. Homebrew is the alternative for the CLI, followed by kubeshark tap, and a direct binary download is listed as a third option.

### What is Kubeshark?

It is a network observability tool for Kubernetes that indexes cluster-wide L4/L7 traffic at the kernel level using eBPF, attaches Kubernetes context to each request, and makes the result queryable through a dashboard, the KFL query language and an MCP server for AI agents. It is written in Go and licensed Apache-2.0.

### Is Kubeshark free?

The repository is licensed Apache-2.0, which permits commercial use and modification. The README does not describe a paid tier or a pricing page, and the MCP server, skills and cluster components all live in the same repository.

### How do I use Kubeshark?

Install the CLI with Homebrew and register the MCP server with claude mcp add kubeshark -- kubeshark mcp, or install the Helm chart and open the dashboard on port 8899. From there you query indexed traffic with KFL, which combines Kubernetes, API and network semantics in one expression, and export snapshots as PCAP for Wireshark.

### How do I install Kubeshark?

The README lists three methods: the Helm chart from https://helm.kubeshark.com, Homebrew followed by kubeshark tap, or a direct binary download from the latest release. The Helm path also needs a port-forward on svc/kubeshark-front to reach the dashboard.

## Sources

- [kubeshark/kubeshark on GitHub](https://github.com/kubeshark/kubeshark)
- [License: Apache-2.0](https://github.com/kubeshark/kubeshark/blob/master/LICENSE)
- [Project website](https://kubeshark.com)
- [README](https://github.com/kubeshark/kubeshark/blob/master/README.md)
- [Releases](https://github.com/kubeshark/kubeshark/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kubeshark-kubeshark