[{"data":1,"prerenderedAt":523},["ShallowReactive",2],{"navigation_docs_en":3,"-en-ai-agents-cluster-ground-truth":225,"-en-ai-agents-cluster-ground-truth-surround":518},[4,25,41,66,85,140,167,181,195],{"title":5,"path":6,"stem":7,"children":8,"icon":10},"Quickstart","\u002Fen\u002Fquickstart","en\u002F1.quickstart\u002F1.index",[9,11,16,20],{"title":5,"path":6,"stem":7,"icon":10},"i-lucide-rocket",{"title":12,"path":13,"stem":14,"icon":15},"Installation","\u002Fen\u002Fquickstart\u002Finstallation","en\u002F1.quickstart\u002F2.installation","i-lucide-download",{"title":17,"path":18,"stem":19,"icon":10},"First Bridge","\u002Fen\u002Fquickstart\u002Ffirst-bridge","en\u002F1.quickstart\u002F3.first-bridge",{"title":21,"path":22,"stem":23,"icon":24},"Docker Desktop Extension","\u002Fen\u002Fquickstart\u002Fdocker-desktop-extension","en\u002F1.quickstart\u002F4.docker-desktop-extension","i-simple-icons-docker",{"title":26,"path":27,"stem":28,"children":29,"page":40},"Ai Agents","\u002Fen\u002Fai-agents","en\u002F2.ai-agents",[30,35],{"title":31,"path":32,"stem":33,"icon":34},"Cluster Ground Truth","\u002Fen\u002Fai-agents\u002Fcluster-ground-truth","en\u002F2.ai-agents\u002F1.cluster-ground-truth","i-lucide-bot",{"title":36,"path":37,"stem":38,"icon":39},"Agent Workflows","\u002Fen\u002Fai-agents\u002Fagent-workflows","en\u002F2.ai-agents\u002F2.agent-workflows","i-lucide-workflow",false,{"title":42,"path":43,"stem":44,"children":45,"page":40},"Developer Workflows","\u002Fen\u002Fdeveloper-workflows","en\u002F3.developer-workflows",[46,51,56,61],{"title":47,"path":48,"stem":49,"icon":50},"Hot Reloading","\u002Fen\u002Fdeveloper-workflows\u002Fhot-reloading","en\u002F3.developer-workflows\u002F1.hot-reloading","i-lucide-zap",{"title":52,"path":53,"stem":54,"icon":55},"IDE Debugging","\u002Fen\u002Fdeveloper-workflows\u002Fide-debugging","en\u002F3.developer-workflows\u002F2.ide-debugging","i-lucide-bug",{"title":57,"path":58,"stem":59,"icon":60},"Run vs. Bridge","\u002Fen\u002Fdeveloper-workflows\u002Fbridge-vs-run","en\u002F3.developer-workflows\u002F3.bridge-vs-run","i-lucide-git-compare-arrows",{"title":62,"path":63,"stem":64,"icon":65},"Database and DNS","\u002Fen\u002Fdeveloper-workflows\u002Fdatabase-and-dns","en\u002F3.developer-workflows\u002F4.database-and-dns","i-lucide-database",{"title":67,"path":68,"stem":69,"children":70,"page":40},"Team And Enterprise","\u002Fen\u002Fteam-and-enterprise","en\u002F4.team-and-enterprise",[71,75,80],{"title":72,"path":73,"stem":74,"icon":10},"Getting Started","\u002Fen\u002Fteam-and-enterprise\u002Fshared-staging-clusters","en\u002F4.team-and-enterprise\u002F1.shared-staging-clusters",{"title":76,"path":77,"stem":78,"icon":79},"Managing Gefyra Clients","\u002Fen\u002Fteam-and-enterprise\u002Frbac-and-security","en\u002F4.team-and-enterprise\u002F2.rbac-and-security","i-lucide-computer",{"title":81,"path":82,"stem":83,"icon":84},"CI Cost Reduction","\u002Fen\u002Fteam-and-enterprise\u002Fci-cost-reduction","en\u002F4.team-and-enterprise\u002F3.ci-cost-reduction","i-lucide-trending-down",{"title":86,"path":87,"stem":88,"children":89,"page":40},"Cluster Guides","\u002Fen\u002Fcluster-guides","en\u002F5.cluster-guides",[90,116,121],{"title":91,"path":92,"stem":93,"children":94,"page":40},"Local Clusters","\u002Fen\u002Fcluster-guides\u002Flocal-clusters","en\u002F5.cluster-guides\u002F1.local-clusters",[95,100,104,108,112],{"title":96,"path":97,"stem":98,"icon":99},"Colima Kubernetes","\u002Fen\u002Fcluster-guides\u002Flocal-clusters\u002Fcolima","en\u002F5.cluster-guides\u002F1.local-clusters\u002F1.colima","i-simple-icons-kubernetes",{"title":101,"path":102,"stem":103,"icon":24},"Docker Desktop Kubernetes (OSX)","\u002Fen\u002Fcluster-guides\u002Flocal-clusters\u002Fdocker-desktop","en\u002F5.cluster-guides\u002F1.local-clusters\u002F2.docker-desktop",{"title":105,"path":106,"stem":107},"k3d","\u002Fen\u002Fcluster-guides\u002Flocal-clusters\u002Fk3d","en\u002F5.cluster-guides\u002F1.local-clusters\u002F3.k3d",{"title":109,"path":110,"stem":111},"kind","\u002Fen\u002Fcluster-guides\u002Flocal-clusters\u002Fkind","en\u002F5.cluster-guides\u002F1.local-clusters\u002F4.kind",{"title":113,"path":114,"stem":115,"icon":99},"minikube","\u002Fen\u002Fcluster-guides\u002Flocal-clusters\u002Fminikube","en\u002F5.cluster-guides\u002F1.local-clusters\u002F5.minikube",{"title":117,"path":118,"stem":119,"icon":120},"Overview","\u002Fen\u002Fcluster-guides\u002Foverview","en\u002F5.cluster-guides\u002F1.overview","i-lucide-network",{"title":122,"path":123,"stem":124,"children":125,"page":40},"Remote Clouds","\u002Fen\u002Fcluster-guides\u002Fremote-clouds","en\u002F5.cluster-guides\u002F2.remote-clouds",[126,131,136],{"title":127,"path":128,"stem":129,"icon":130},"Google Cloud Platform (GCP)","\u002Fen\u002Fcluster-guides\u002Fremote-clouds\u002Fgke","en\u002F5.cluster-guides\u002F2.remote-clouds\u002F1.gke","i-material-icon-theme:gcp",{"title":132,"path":133,"stem":134,"icon":135},"Elastic Kubernetes Service (EKS)","\u002Fen\u002Fcluster-guides\u002Fremote-clouds\u002Feks","en\u002F5.cluster-guides\u002F2.remote-clouds\u002F2.eks","i-simple-icons-amazoneks",{"title":137,"path":138,"stem":139,"icon":99},"SysEleven MetaKube","\u002Fen\u002Fcluster-guides\u002Fremote-clouds\u002Fsyseleven","en\u002F5.cluster-guides\u002F2.remote-clouds\u002F3.syseleven",{"title":141,"path":142,"stem":143,"children":144,"page":40},"Use Cases and Demos","\u002Fen\u002Fusecases-and-demos","en\u002F5.usecases-and-demos",[145,148,153,158,162],{"title":72,"path":146,"stem":147,"icon":10},"\u002Fen\u002Fusecases-and-demos\u002Fgetting-started","en\u002F5.usecases-and-demos\u002F1.getting-started",{"title":149,"path":150,"stem":151,"icon":152},"Developing Go Applications with Gefyra","\u002Fen\u002Fusecases-and-demos\u002Fgolang","en\u002F5.usecases-and-demos\u002F2.golang","i-simple-icons-go",{"title":154,"path":155,"stem":156,"icon":157},"OAuth2 Demo with a Sidecar","\u002Fen\u002Fusecases-and-demos\u002Foauth2-demo","en\u002F5.usecases-and-demos\u002F3.oauth2-demo","i-devicon-plain:oauth",{"title":159,"path":160,"stem":161,"icon":130},"Remote Development on Google Kubernetes Engine","\u002Fen\u002Fusecases-and-demos\u002Fremote-gke","en\u002F5.usecases-and-demos\u002F4.remote-gke",{"title":163,"path":164,"stem":165,"icon":166},"Run an Ubuntu Container instance","\u002Fen\u002Fusecases-and-demos\u002Fubuntu-in-namespace","en\u002F5.usecases-and-demos\u002F5.ubuntu-in-namespace","i-simple-icons-ubuntu",{"title":168,"path":169,"stem":170,"children":171,"page":40},"Architecture","\u002Fen\u002Farchitecture","en\u002F6.architecture",[172,176],{"title":168,"path":173,"stem":174,"icon":175},"\u002Fen\u002Farchitecture\u002Fhow-gefyra-works","en\u002F6.architecture\u002F1.how-gefyra-works","i-lucide-square-chevron-right",{"title":177,"path":178,"stem":179,"icon":180},"Gefyra Components","\u002Fen\u002Farchitecture\u002Fcomponents","en\u002F6.architecture\u002F2.components","i-lucide-circle-question-mark",{"title":182,"path":183,"stem":184,"children":185,"page":40},"Comparisons","\u002Fen\u002Fcomparisons","en\u002F7.comparisons",[186,191],{"title":187,"path":188,"stem":189,"icon":190},"Gefyra vs. Telepresence","\u002Fen\u002Fcomparisons\u002Fgefyra-vs-telepresence","en\u002F7.comparisons\u002F1.gefyra-vs-telepresence","i-lucide-git-compare",{"title":192,"path":193,"stem":194,"icon":190},"Gefyra vs. mirrord","\u002Fen\u002Fcomparisons\u002Fgefyra-vs-mirrord","en\u002F7.comparisons\u002F2.gefyra-vs-mirrord",{"title":196,"path":197,"stem":198,"children":199,"page":40},"Reference","\u002Fen\u002Freference","en\u002F8.reference",[200,205,210,215,220],{"title":201,"path":202,"stem":203,"icon":204},"CLI","\u002Fen\u002Freference\u002Fcli","en\u002F8.reference\u002F1.cli","i-lucide-square-terminal",{"title":206,"path":207,"stem":208,"icon":209},"CRD Reference","\u002Fen\u002Freference\u002Fcrd-reference","en\u002F8.reference\u002F2.crd-reference","i-lucide-file-code",{"title":211,"path":212,"stem":213,"icon":214},"What changed in Gefyra 2?","\u002Fen\u002Freference\u002Fv1-vs-v2","en\u002F8.reference\u002F3.v1-vs-v2","i-lucide-history",{"title":216,"path":217,"stem":218,"icon":219},"Media","\u002Fen\u002Freference\u002Fmedia","en\u002F8.reference\u002F4.media","i-lucide-play",{"title":221,"path":222,"stem":223,"icon":224},"About","\u002Fen\u002Freference\u002Fabout","en\u002F8.reference\u002F5.about","i-lucide-info",{"id":226,"title":227,"body":228,"description":511,"extension":512,"links":513,"meta":514,"navigation":515,"path":32,"seo":516,"stem":33,"__hash__":517},"docs_en\u002Fen\u002F2.ai-agents\u002F1.cluster-ground-truth.md","Giving AI Agents Live Cluster Context",{"type":229,"value":230,"toc":500},"minimark",[231,240,245,248,251,255,262,267,272,276,280,283,306,310,313,456,460,463,468,490,496],[232,233,234,235,239],"p",{},"Modern developers build with local AI agents (Cursor, Claude Code, Gemini CLI, Aider, Devin). However, ",[236,237,238],"strong",{},"local AI agents operate blind to runtime cluster state",".",[241,242,244],"h2",{"id":243},"the-context-blind-spot","The Context Blind Spot",[232,246,247],{},"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.",[232,249,250],{},"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.",[241,252,254],{"id":253},"the-gefyra-solution","The Gefyra Solution",[232,256,257,258,261],{},"Gefyra bridges the local workspace directly into the Kubernetes network fabric. It provides local AI agents with ",[236,259,260],{},"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.",[263,264,266],"h3",{"id":265},"the-agent-workflow","The Agent Workflow",[268,269],"content-mermaid-transport",{":page-data":270,"code":271},"runtimeData","sequenceDiagram%0A%20%20%20%20autonumber%0A%20%20%20%20actor%20Dev%20as%20Engineer%20%2F%20AI%20Agent%20(Cursor%20%2F%20Claude%20Code)%0A%20%20%20%20participant%20Local%20as%20Local%20Workspace%20(Docker%20%2F%20Port%208000)%0A%20%20%20%20participant%20Bridge%20as%20Gefyra%20WireGuard%20Tunnel%0A%20%20%20%20participant%20Cluster%20as%20Remote%20Staging%20Microservices%0A%20%20%20%20participant%20DB%20as%20Live%20Staging%20Database%0A%0A%20%20%20%20Dev-%3E%3ELocal%3A%20Agent%20writes%20endpoint%20logic%20%26%20triggers%20integration%20test%0A%20%20%20%20Local-%3E%3EBridge%3A%20HTTP%20request%20to%20%60http%3A%2F%2Fauth-service.staging.svc%60%0A%20%20%20%20Bridge-%3E%3ECluster%3A%20Resolves%20cluster-internal%20DNS%20%26%20forwards%20to%20Auth%20Service%0A%20%20%20%20Cluster--%3E%3ELocal%3A%20Live%20Auth%20token%20returned%0A%20%20%20%20Local-%3E%3EBridge%3A%20Query%20customer%20records%20on%20%60postgres.staging.svc%3A5432%60%0A%20%20%20%20Bridge-%3E%3EDB%3A%20Direct%20SQL%20query%20executed%0A%20%20%20%20DB--%3E%3ELocal%3A%20Live%20production-schema%20dataset%20returned%0A%20%20%20%20Local--%3E%3EDev%3A%20Test%20Passed%20in%202.8s%20(Zero%20hallucinations%2C%20zero%20brittle%20mocks)",[241,273,275],{"id":274},"setup-walkthrough","Setup Walkthrough",[263,277,279],{"id":278},"_1-initialize-gefyra-connection","1. Initialize Gefyra Connection",[232,281,282],{},"First, connect your local machine to the target staging cluster:",[284,285,290],"pre",{"className":286,"code":287,"language":288,"meta":289,"style":289},"language-bash shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","gefyra up\n","bash","",[291,292,293],"code",{"__ignoreMap":289},[294,295,298,302],"span",{"class":296,"line":297},"line",1,[294,299,301],{"class":300},"sBMFI","gefyra",[294,303,305],{"class":304},"sfazB"," up\n",[263,307,309],{"id":308},"_2-run-local-container-mount-and-bridge","2. Run Local Container, Mount, and Bridge",[232,311,312],{},"Launch your local development container inside the Gefyra network fabric, mount the target cluster deployment with Carrier2, and establish the bridge:",[284,314,316],{"className":286,"code":315,"language":288,"meta":289,"style":289},"# 1. Run your local container connected to cluster DNS and databases\ngefyra run -i my-image:dev -N local-container -v $(pwd):\u002Fapp -c \"python main.py\" -d\n\n# 2. Mount the target deployment\ngefyra mount create --target deployment\u002Fmy-service\u002Fapp --name my-service-mount\n\n# 3. Bridge incoming cluster traffic to your local container\ngefyra bridge create --mount my-service-mount -p 8080:8080 -t local-container --match-path-prefix \u002F\n",[291,317,318,324,376,383,389,412,417,423],{"__ignoreMap":289},[294,319,320],{"class":296,"line":297},[294,321,323],{"class":322},"sHwdD","# 1. Run your local container connected to cluster DNS and databases\n",[294,325,327,329,332,335,338,341,344,347,351,355,358,361,364,367,370,373],{"class":296,"line":326},2,[294,328,301],{"class":300},[294,330,331],{"class":304}," run",[294,333,334],{"class":304}," -i",[294,336,337],{"class":304}," my-image:dev",[294,339,340],{"class":304}," -N",[294,342,343],{"class":304}," local-container",[294,345,346],{"class":304}," -v",[294,348,350],{"class":349},"sMK4o"," $(",[294,352,354],{"class":353},"s2Zo4","pwd",[294,356,357],{"class":349},")",[294,359,360],{"class":304},":\u002Fapp",[294,362,363],{"class":304}," -c",[294,365,366],{"class":349}," \"",[294,368,369],{"class":304},"python main.py",[294,371,372],{"class":349},"\"",[294,374,375],{"class":304}," -d\n",[294,377,379],{"class":296,"line":378},3,[294,380,382],{"emptyLinePlaceholder":381},true,"\n",[294,384,386],{"class":296,"line":385},4,[294,387,388],{"class":322},"# 2. Mount the target deployment\n",[294,390,392,394,397,400,403,406,409],{"class":296,"line":391},5,[294,393,301],{"class":300},[294,395,396],{"class":304}," mount",[294,398,399],{"class":304}," create",[294,401,402],{"class":304}," --target",[294,404,405],{"class":304}," deployment\u002Fmy-service\u002Fapp",[294,407,408],{"class":304}," --name",[294,410,411],{"class":304}," my-service-mount\n",[294,413,415],{"class":296,"line":414},6,[294,416,382],{"emptyLinePlaceholder":381},[294,418,420],{"class":296,"line":419},7,[294,421,422],{"class":322},"# 3. Bridge incoming cluster traffic to your local container\n",[294,424,426,428,431,433,436,439,442,445,448,450,453],{"class":296,"line":425},8,[294,427,301],{"class":300},[294,429,430],{"class":304}," bridge",[294,432,399],{"class":304},[294,434,435],{"class":304}," --mount",[294,437,438],{"class":304}," my-service-mount",[294,440,441],{"class":304}," -p",[294,443,444],{"class":304}," 8080:8080",[294,446,447],{"class":304}," -t",[294,449,343],{"class":304},[294,451,452],{"class":304}," --match-path-prefix",[294,454,455],{"class":304}," \u002F\n",[263,457,459],{"id":458},"_3-prompting-your-ai-agent","3. Prompting Your AI Agent",[232,461,462],{},"Now that your local container is running in the context of the cluster, you can prompt your AI agent with real cluster endpoints.",[232,464,465],{},[236,466,467],{},"Example Prompt in Cursor\u002FClaude Code:",[469,470,471],"blockquote",{},[232,472,473,474,477,478,481,482,485,486,489],{},"\"I am getting a 500 error from the staging API at ",[291,475,476],{},"http:\u002F\u002Fauth-service.staging.svc.cluster.local\u002Fv1\u002Fverify",". Here is the endpoint logic in ",[291,479,480],{},"auth.py",". Please run a ",[291,483,484],{},"curl"," request against that URL, analyze the response, and fix the payload structure. You can test your fix live against the staging database at ",[291,487,488],{},"postgresql:\u002F\u002Fadmin:secret@db.staging.svc:5432\u002Fmain",".\"",[232,491,492,495],{},[236,493,494],{},"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.",[497,498,499],"style",{},"html pre.shiki code .sBMFI, html code.shiki .sBMFI{--shiki-light:#E2931D;--shiki-default:#FFCB6B;--shiki-dark:#FFCB6B}html pre.shiki code .sfazB, html code.shiki .sfazB{--shiki-light:#91B859;--shiki-default:#C3E88D;--shiki-dark:#C3E88D}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sHwdD, html code.shiki .sHwdD{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#546E7A;--shiki-default-font-style:italic;--shiki-dark:#676E95;--shiki-dark-font-style:italic}html pre.shiki code .sMK4o, html code.shiki .sMK4o{--shiki-light:#39ADB5;--shiki-default:#89DDFF;--shiki-dark:#89DDFF}html pre.shiki code .s2Zo4, html code.shiki .s2Zo4{--shiki-light:#6182B8;--shiki-default:#82AAFF;--shiki-dark:#82AAFF}",{"title":289,"searchDepth":326,"depth":326,"links":501},[502,503,506],{"id":243,"depth":326,"text":244},{"id":253,"depth":326,"text":254,"children":504},[505],{"id":265,"depth":378,"text":266},{"id":274,"depth":326,"text":275,"children":507},[508,509,510],{"id":278,"depth":378,"text":279},{"id":308,"depth":378,"text":309},{"id":458,"depth":378,"text":459},"Learn how to provide local AI coding agents like Cursor, Claude Code, and Gemini CLI with real-time Kubernetes cluster state using Gefyra.","md",null,{},{"title":31,"icon":34},{"title":227,"description":511},"xvYin67_lRZmGwiIQii8IH-cHUsTjeOEfl1v17sQrAo",[519,521],{"title":21,"path":22,"stem":23,"description":520,"icon":24,"children":-1},"Install the Gefyra Docker Desktop Extension to bridge local containers into Kubernetes from a GUI — ideal for testing services without the CLI.",{"title":36,"path":37,"stem":38,"description":522,"icon":39,"children":-1},"Supercharge autonomous AI coding agents with live Kubernetes cluster context. Eliminate hallucinations and test AI-generated code against real cluster services in seconds.",1795114692427]