Gefyra bridges a local container into a live Kubernetes cluster

One service local, the rest of the stack in the cluster

Gefyra describes itself as a completely new way of writing and testing applications for Kubernetes developers. The target is the gap between two bad options: running the whole application locally with custom docker-compose setups, Vagrants and ad hoc scripts, or deploying everything to a cluster to test a small change.

The offer is a third option. You run the service you are working on locally, in a container, and the rest of the application stays in the cluster. The bullet list in the README is explicit about what that buys: services running locally on your machine, feature branches operating in a production-like Kubernetes environment with all adjacent services present, code written in the IDE you already use, and the usual development features such as a debugger, code hot reloading and overriding environment variables. On top of that, high level integration tests can run against all dependent services, and you keep peace of mind when pushing new code to the integration environment.

The last two points are the ones that distinguish it from a tunnel. A bridge is only useful if the local process genuinely behaves as if it were deployed, which is what makes the integration test claim possible.

The project is Python, the homepage is gefyra.dev, and the topics name docker, kubernetes, containers, tunnel and developer-tool.

A WireGuard tunnel, local DNS and an Nginx proxy

The built-with section explains the mechanism better than any marketing line would.

Docker manages the local container based development setup, including the host, networking and container management procedures. Wireguard establishes the connection tunnel between the two ends, encrypting the UDP based traffic so a site-to-site network can be created for Gefyra. The result is that the local development setup becomes part of the cluster, and containers running locally can actually reach cluster based resources such as databases and other microservices.

CoreDNS provides the local DNS functionality that lets you resolve those cluster resources by name, and Nginx does the proxying and reverse proxying, including the interceptions of containers already running in the cluster.

The composition explains the design. A tunnel alone gives you network reachability but not name resolution, and reachability without names is not much use to a service that expects to talk to a database by its service name. CoreDNS is what turns the tunnel into something a Kubernetes application can use unchanged, and Nginx is what lets the local container be slotted in front of an existing deployment without changing it.

These are the same components a hand rolled setup would need, which is the point of the project rather than a criticism of it.

Installing the CLI, then running and bridging

The CLI install has platform specific routes. On Linux and macOS a script is piped to a shell:

curl -sSL https://raw.githubusercontent.com/gefyrahq/gefyra/main/install.sh | sh -

on macOS there is also a Homebrew tap:

brew tap gefyrahq/gefyra
brew install gefyra

and on Windows the instruction is to download the latest binary from the releases page.

Two commands do the actual work. The first runs a local image with Gefyra, taking the image name, the container name and the namespace:

gefyra run -i <image_name> -N <container_name> -n default

The second creates the bridge, pointing at the target workload in the cluster with the namespace and the deployment and container inside it:

gefyra bridge -N <container_name> -n <k8s_namespace> --target deployment/<k8s_deployment>/<k8s_deployment_container>

The placeholders are documented in the README, and the full set of bridge flags is linked in the CLI reference. Before either command, Gefyra has to be installed on the cluster itself with gefyra up, and some details of that installation depend on the Kubernetes platform, which is why the documentation is the reference rather than the README.

A local k3d cluster is the quickest way to try it

The getting started section recommends a local cluster rather than a real one, and it uses k3d with one agent. There are two command forms because k3d changed its port syntax between versions:

# < v5
k3d cluster create mycluster --agents 1 -p 8080:80@agent[0] -p 31820:31820/UDP@agent[0]
# >= v5
k3d cluster create mycluster --agents 1 -p 8080:80@agent:0 -p 31820:31820/UDP@agent:0

The older form addresses the agent as agent[0] and the newer one as agent:0. The cluster binds port 8080 and port 31820 over UDP to localhost, and the kubectl context is set to it immediately, so there is no separate context switching step.

Port 31820 over UDP is the Wireguard side of the arrangement, and 8080 is the port the application is exposed on. The mapping matters: the local Gefyra instance and the cluster agent have to agree on those ports for the tunnel to come up, which is the kind of detail that produces a confusing failure when it is wrong.

To apply a workload, the README points at the testing directory in the repository itself:

kubectl apply -f testing/workloads/hello.yaml

The repository tree confirms the shape of the project: a client directory, an operator directory, a rewritten carrier2 directory, a stowaway directory, a cargo directory, a testing directory, an install.sh script and a version.py.

Version 2.4 rewrote the carrier

The warning at the top of the README is the single most important line for anyone who has used the project before. Gefyra release 2.4 contains major breaking changes, big parts of the operator have been refactored, and the carrier has been completely rewritten to support user specific bridges.

The deprecated version can be found in the branch deprecation-main-march-2026, which tells you the shape of the change: this was a rewrite in March 2026, with the old tree kept on a branch rather than deleted.

That combination, a rewritten component and a preserved old branch, is a pattern worth taking seriously. The carrier is the part that carries traffic between the local and cluster sides, so a rewrite there touches the network path that everything else depends on, and the user specific bridge support means the bridge is no longer a single shared object. A team that pins to 2.3 can keep working on the old branch, but the documentation on the main site describes the new architecture.

The release history shows steady work since the rewrite, with 2.5.6 on 2026-10-06, 2.5.5 on 2026-09-14 and 2.5.4 on 2026-07-20, and the last push was on 2026-10-22.

What it costs you to run

Gefyra needs a Kubernetes cluster, a local Docker daemon, and the pieces that make the tunnel work. The k3d path in the getting started section is a way to reduce the first requirement to something you can create on a laptop, and the rest is Docker, which most developers already have.

The real operational cost is not the install, it is the mental model. A bridged container is not a local process that happens to talk to a cluster. It is a container that has been slotted into the cluster's network through an Nginx proxy, with cluster DNS resolving names for it, running over an encrypted tunnel. That is what makes the integration testing claim work, and it is also what makes debugging awkward, because a request that fails may be failing in your code, in the proxy, in DNS, or in the tunnel.

There is also a security dimension that a developer tool inherits from its infrastructure. The tunnel is site-to-site and encrypted, and the point of it is that a local process can reach cluster resources. That is a deliberate grant, and in a shared cluster it is worth checking what the bridge's account is allowed to reach before connecting it to a namespace with production data in it.

The README is also honest about what the project is not trying to be, in the sense that it is a development environment tool and says nothing about deploying with it.

Editorial conclusion

Gefyra suits a developer who writes one service of a Kubernetes application locally and needs the rest of the stack to stay in the cluster, because the tunnel and the DNS arrangement make the local container a genuine cluster member rather than an isolated process. It is the wrong tool if you need to run the whole application locally, or if you do not have a cluster, a Docker daemon available. Before adopting it, read the 2.4 migration notes, because the carrier was rewritten and the deprecated tree lives on a separate branch, and check that your cluster platform is covered by the installation instructions.

Frequently asked questions

Official sources

1. gefyrahq/gefyra on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases