Ai Agents

Giving AI Agents Live Cluster Context

Learn how to provide local AI coding agents like Cursor, Claude Code, and Gemini CLI with real-time Kubernetes cluster state using Gefyra.

Modern developers build with local AI agents (Cursor, Claude Code, Gemini CLI, Aider, Devin). However, local AI agents operate blind to runtime cluster state.

The Context Blind Spot

Local AI agents can inspect source code, but they cannot query internal cluster services, private staging databases, gRPC endpoints, or in-cluster Kafka topics. Because they lack access to the actual runtime environment, they hallucinate assumptions about network state, data shapes, and environment variables.

Engineers waste hours creating brittle mocks and Docker Compose replicas that drift from Kubernetes production manifests, just to give their AI agents a "fake" playground.

The Gefyra Solution

Gefyra bridges the local workspace directly into the Kubernetes network fabric. It provides local AI agents with real-time runtime grounding—allowing the agent to run, test, and debug live API calls against real cluster services without requiring an image build, registry push, or remote deployment.

The Agent Workflow

mermaid
sequenceDiagram
    autonumber
    actor Dev as Engineer / AI Agent (Cursor / Claude Code)
    participant Local as Local Workspace (Docker / Port 8000)
    participant Bridge as Gefyra WireGuard Tunnel
    participant Cluster as Remote Staging Microservices
    participant DB as Live Staging Database

    Dev->>Local: Agent writes endpoint logic & triggers integration test
    Local->>Bridge: HTTP request to `http://auth-service.staging.svc`
    Bridge->>Cluster: Resolves cluster-internal DNS & forwards to Auth Service
    Cluster-->>Local: Live Auth token returned
    Local->>Bridge: Query customer records on `postgres.staging.svc:5432`
    Bridge->>DB: Direct SQL query executed
    DB-->>Local: Live production-schema dataset returned
    Local-->>Dev: Test Passed in 2.8s (Zero hallucinations, zero brittle mocks)

Setup Walkthrough

1. Initialize Gefyra Connection

First, connect your local machine to the target staging cluster:

gefyra up

2. Run Local Container, Mount, and Bridge

Launch your local development container inside the Gefyra network fabric, mount the target cluster deployment with Carrier2, and establish the bridge:

# 1. Run your local container connected to cluster DNS and databases
gefyra run -i my-image:dev -N local-container -v $(pwd):/app -c "python main.py" -d

# 2. Mount the target deployment
gefyra mount create --target deployment/my-service/app --name my-service-mount

# 3. Bridge incoming cluster traffic to your local container
gefyra bridge create --mount my-service-mount -p 8080:8080 -t local-container --match-path-prefix /

3. Prompting Your AI Agent

Now that your local container is running in the context of the cluster, you can prompt your AI agent with real cluster endpoints.

Example Prompt in Cursor/Claude Code:

"I am getting a 500 error from the staging API at http://auth-service.staging.svc.cluster.local/v1/verify. Here is the endpoint logic in auth.py. Please run a curl request against that URL, analyze the response, and fix the payload structure. You can test your fix live against the staging database at postgresql://admin:secret@db.staging.svc:5432/main."

The Result: The AI agent directly queries the live staging service, reads the real error response, refactors the code, and verifies the fix instantly against the live database—all without a single Docker build or remote deployment.