The 2-Minute Quickstart
Ship verified code directly inside a live Kubernetes environment in under two minutes. Zero external dependencies, zero image builds, and zero registry pushes.
All you need is Docker or Podman running on your laptop.
Step 1: Install the Gefyra CLI (15 Seconds)
Install the standalone Gefyra binary:
curl -sSL https://raw.githubusercontent.com/gefyrahq/gefyra/main/install.sh | sh
brew tap gefyrahq/gefyra
brew install gefyra
iwr -useb https://raw.githubusercontent.com/gefyrahq/gefyra/main/install.ps1 | iex
Verify the CLI is ready:
gefyra version
Step 2: Spin Up a Local Cluster (30 Seconds)
If you already have a Kubernetes cluster running, make sure your kubectl context is set and proceed to Step 3.
If you don't have a cluster yet, spin one up in seconds with k3d or minikube:
# 1. Install k3d (if not already installed)
curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash
# 2. Create a lightweight cluster with the Gefyra WireGuard port exposed
k3d cluster create gefyra --agents 1 -p 8080:80@agent:0 -p 31820:31820/UDP@agent:0
# 1. Start minikube
minikube start
Confirm your cluster is ready:
kubectl get nodes
Step 3: Deploy a Sample Workload (15 Seconds)
Deploy an off-the-shelf Nginx service from Docker Hub into your cluster. No custom manifests or builds required:
# Deploy sample Nginx workload
kubectl create deployment hello-nginx --image=nginxdemos/hello --port=80
# Expose as a ClusterIP service
kubectl expose deployment hello-nginx --port=80 --target-port=80
Verify that the sample pod is running:
kubectl get pods -l app=hello-nginx
Step 4: Connect Gefyra (15 Seconds)
Initialize Gefyra against your cluster:
gefyra up
Gefyra automatically:
- Deploys the lightweight Gefyra Operator and Stowaway gateway to the cluster.
- Spins up the local Cargo WireGuard sidecar on your workstation.
- Establishes an encrypted, bidirectional network tunnel.
Step 5: Run Your Local Container (15 Seconds)
Create a sample HTML file on your machine and run an official Python container in Gefyra. Zero Dockerfile writing, zero image building:
# 1. Create a local response file
mkdir -p ./quickstart-app
echo "<h1>⚡ Hello from Gefyra Local Bridge!</h1>" > ./quickstart-app/index.html
# 2. Run the local container in Gefyra
gefyra run \
-i python:3.12-alpine \
-N local-hello \
-v $(pwd)/quickstart-app:/app \
-c "python3 -m http.server 8080 -d /app" \
-d
Your local container is now attached to the cluster network with direct access to all internal Kubernetes services and CoreDNS (.svc.cluster.local).
Step 6: Mount & Bridge the Workload (15 Seconds)
Gefyra 2.5+ decouples workload mounting from traffic routing:
# 1. Mount the deployment with Carrier2 proxy
gefyra mount create --target deployment/hello-nginx/hello-nginx --name hello-mount
# 2. Bridge cluster traffic on port 80 to your local container on port 8080
gefyra bridge create \
--mount hello-mount \
-p 80:8080 \
-t local-hello \
--match-path-prefix /
Step 7: Verify Live Interception & Hot-Reloading
Test that cluster traffic is intercepted and routed directly to your local file:
kubectl run test-curl --rm -it --restart=Never --image=curlimages/curl -- curl -s http://hello-nginx
Output:
<h1>⚡ Hello from Gefyra Local Bridge!</h1>
See Hot-Reloading in Action
Edit your local file:
echo "<h1>🚀 Live Code Change Synced Instantly!</h1>" > ./quickstart-app/index.html
Run the curl verification command again:
kubectl run test-curl --rm -it --restart=Never --image=curlimages/curl -- curl -s http://hello-nginx
Output:
<h1>🚀 Live Code Change Synced Instantly!</h1>
Your changes are live in the cluster immediately. No image builds, no container registry pushes, and no CI pipelines.
Step 8: Clean Exit
When you are finished developing, restore the cluster and remove all local sidecars:
# 1. List and remove active bridges
gefyra bridge list
gefyra bridge delete <bridge-id>
# 2. Unmount the workload and restore original pod image
gefyra mount delete hello-mount
# 3. Stop Gefyra components
gefyra down
(Optional) Tear down the local test cluster:
k3d cluster delete gefyra