Your First Gefyra Bridge
Important: This getting started guide for Minikube requires Gefyra in version >=2.0.0+.
Prerequisites
Creating a local Kubernetes cluster with Minikube

1. Create a local Kubernetes cluster with Minikube by running:
minikube start
Important: the following example does not fully work with --driver=qemu since minikube service is not currently
implemented with the qemu2 driver. See this GitHub issue for details.
Tested drivers are: docker, kvm2, kvm, virtualbox. Others are potentially working, but are not tested.
After some time of downloading the required resources, the cluster will be running. You may enable the required
addons based on your requirements. The kubectl context is immediately set to this cluster. You can check if
kubectl config current-context is set to minikube.
kubectl config current-context
2. Apply some workload, for example from the testing directory from Gefyra:
kubectl apply -f https://raw.githubusercontent.com/gefyrahq/gefyra/main/testing/workloads/hello.yaml
3. Check the output of the deployed app with:
kubectl expose deployment hello-nginxdemo --type=NodePort --port=80
minikube service hello-nginxdemo
Running Gefyra
1. Set up Gefyra with your Minikube cluster:
gefyra up --minikube
Important: The --minikube switch detects all required connection parameters from your local cluster. The connection won't work
if this switch is missing when working with Minikube.
2. Run a local container with Gefyra (Zero Image Build)
No custom Dockerfile or image build is required. Run an official lightweight Python container from Docker Hub:
# 1. Create a local response file
mkdir -p /tmp/local-server
echo "<h1>Hello from Gefyra. Live local code served directly into Minikube!</h1>" > /tmp/local-server/index.html
# 2. Run the local container in Gefyra
gefyra run \
-i python:3.12-alpine \
-N mypyserver \
-v /tmp/local-server:/app \
-c "python3 -m http.server 8000 -d /app" \
-d
Important: gefyra run joins your local container directly to the Kubernetes network fabric with CoreDNS and internal service access. Check out the docs for gefyra run.
3. Exec into the running container and verify cluster access:
docker exec -it mypyserver sh
wget -O- hello-nginx
exit
will print out the website of the cluster service hello-nginx from within the cluster. 🚀
4. Mount the workload and create a bridge to redirect cluster traffic to your local container:
In Gefyra 2.5+, workload mounting is decoupled from traffic bridging to support multi-developer workflows without collisions.
First, mount the cluster deployment:
gefyra mount create --target deployment/hello-nginxdemo/hello-nginx --name mymount
Next, create the bridge connecting your local container to the mount:
gefyra bridge create --mount mymount -p 80:8000 -t mypyserver --match-path-prefix /
Check out the locally running server serving the cluster by refreshing the address from:
minikube service hello-nginxdemo
It shows you a different message: Hello from Gefyra. It is .... Yes, that is really coming from your local container! 😎
5. List all active mounts and bridges:
You can inspect all active mounts and bridges with:
gefyra bridge list
gefyra mount list
You will see your local container linked to the cluster workload and intercepting requests.
6. Remove the bridge and restore the cluster:
# Delete the bridge (use the ID from gefyra bridge list)
gefyra bridge delete <bridge-id>
# Remove the mount and restore the original pod image
gefyra mount delete mymount
Check out the original response from:
minikube service hello-nginxdemo
The cluster is now reset to its initial state again.
Cleaning up
Remove Gefyra's components from the cluster and your local Docker host with:
gefyra down
Deleting the Minikube cluster
minikube delete
Installation
Install the Gefyra CLI on macOS, Linux, or Windows via binary, Homebrew, or package managers — then connect to any Kubernetes cluster.
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.