Giving AI Agents Live Cluster Context
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
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 inauth.py. Please run acurlrequest against that URL, analyze the response, and fix the payload structure. You can test your fix live against the staging database atpostgresql://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.
Docker Desktop Extension
Install the Gefyra Docker Desktop Extension to bridge local containers into Kubernetes from a GUI — ideal for testing services without the CLI.
Agent Workflows
Supercharge autonomous AI coding agents with live Kubernetes cluster context. Eliminate hallucinations and test AI-generated code against real cluster services in seconds.