Quickstart

The 2-Minute Quickstart

Zero-dependency quickstart for Gefyra. Spin up a local cluster, connect Gefyra, and bridge a live Kubernetes service to your local code in 120 seconds.

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

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

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

Next Steps

Connect Your AI Coding Agent

Give Cursor, Claude Code, or Gemini CLI live cluster ground truth to test generated code without mocks.

IDE Breakpoint Debugging

Set step-through breakpoints in VS Code or PyCharm triggered by live cluster traffic.

Hot-Reloading Workflows

Configure instant hot-reloading for Django, FastAPI, Next.js, and Go Air.