Developer Guide
Note
CortexBrain is currently in active development. Resources on eBPF and the Aya Rust framework are sparse across the internet, and existing references such as ebpf.io and aya-rs.dev only cover the top of the iceberg. This Developer Guide aims to flatten the learning curve so that newcomers can easily learn, contribute and become maintainers of the project.
Why this section exists
The project has a very steep curve because of the combination of eBPF and Rust at the same time. This section consolidates the architecture, the Agent API surface, the integrated metrics, and the contribution workflow into a single, detailed reference so that you don't have to guess what the codebase does to get started.
What you'll find here
| Page | What it covers |
|---|---|
| Glossary | Definitions for eBPF, kernel, Kubernetes, networking, observability, GPU, and MCP terms used across the docs |
| Architecture Overview | Covers kernel instrumentation, maps pinning, aggregation and consumption |
| Development Workflow | Covers the complete developer workflow: Fork, development branch and PR flow, CI pipeline, commit and branch conventions |
| Agent API Overview | The Cortexflow agent service. Covers the RPC methods, the BPF maps the agent reads, and the data flow from eBPF kernel programs to cfcli |
| Integrated Metrics | Covers the live metrics and the OpenTelemetry metric format from metrics-patch |
| MCP Server | The MCP server that exposes CortexBrain metrics to AI assistants via Prometheus queries |
| GPU Metrics (Upcoming) | The complete CUDA observability roadmap |
| Troubleshooting | Common issues (BPF fs not mounted, pinned map path mismatch, port-forward, permissions) and their fixes |
| Development Goals & Discussions | Milestones, roadmap, GitHub Discussions, labels, and how to propose new features |
Prerequisites
Make sure you have the development environment set up. The guided setup (Rust nightly, eBPF toolchain, Minikube/Kind, Calico CNI, Docker setup) is documented in the Getting Started for developers section of the installation page.
The core build requirements (kernel >= 5.15, bpftool, bcc, clang, llvm, libbpf-dev, rustc >= 1.85.0 nightly) are also listed there.
External resources
CortexBrain sits at the intersection of Rust and eBPF no single resource covers everything at the same time, in the same repository. The following are the best starting points beyond this guide:
- Linux Kernel docs - Linux Kernel the complete linux kernel reference divided by version
- eBPF - ebpf.io (concept overview), the Cilium eBPF documentation (practical kernel hook reference), and the BPF and XDP reference guide in the Linux kernel docs.
- Aya (Rust eBPF) - aya-rs.dev (the framework CortexBrain uses to load and pin BPF maps), the Aya book, and the Aya examples.
- gRPC / tonic - the tonic Rust gRPC stack documentation, which powers the
agent.Agentservice. - Kubernetes networking - the Kubernetes CNI documentation and the Calico docs, since CortexBrain attaches eBPF programs to veth interfaces created by Calico.
- Docker docs - Docker docs
Contributing
CortexBrain is open source under Apache 2.0. We actively look for contributors and collaborators. If you have knowledge in DevOps,GPUs, Kubernetes,Docker or networking.