KubeVPN

KubeVPN bridges a local machine to a remote Kubernetes cluster network. Core workflows: connect (VPN tunnel), proxy (traffic interception), run (local pod simulation), sync (local code → cluster clone).

Installation

brew install kubevpn                              # macOS
curl -fsSL https://kubevpn.dev/install.sh | sh   # Linux/macOS
kubectl krew install kubevpn/kubevpn              # kubectl plugin
scoop bucket add extras && scoop install kubevpn  # Windows

Core Workflows

1. Connect — Access cluster network

kubevpn connect
kubevpn connect -n \x3Cnamespace>
kubevpn connect --context \x3Ccontext-name>
kubevpn disconnect --all

After connecting, access cluster resources directly:

ping \x3Cpod-ip>
curl \x3Cservice-name>:\x3Cport>
curl \x3Cservice-name>.\x3Cnamespace>.svc.cluster.local:\x3Cport>

2. Proxy — Intercept inbound traffic

Intercepts inbound cluster traffic for a workload and forwards to local machine. proxy also auto-connects to the cluster if not already connected.

kubevpn proxy deployment/\x3Cname>
kubevpn proxy deployment/\x3Cname> -n \x3Cnamespace>

# Mesh mode: only requests with matching headers go to local
kubevpn proxy deployment/\x3Cname> --headers foo=bar
kubevpn proxy deployment/\x3Cname> --headers foo=bar --headers env=dev  # AND logic

# Port mapping
kubevpn proxy deployment/\x3Cname> --portmap 9080:8080
kubevpn proxy deployment/\x3Cname> --portmap udp/9080:5000

# Multiple workloads at once
kubevpn proxy deployment/authors deployment/productpage

kubevpn leave deployment/\x3Cname>   # stop proxying, restore workload

3. Run — Simulate pod locally in Docker

Runs a workload in a local Docker container with identical env vars, volumes, and network.

kubevpn run deployment/\x3Cname>
kubevpn run deployment/\x3Cname> --entrypoint /bin/bash   # interactive shell
kubevpn run deployment/\x3Cname> --no-proxy               # no traffic interception
kubevpn run deployment/\x3Cname> --dev-image golang:1.21 --entrypoint bash
kubevpn run deployment/\x3Cname> --headers foo=bar        # mesh mode

4. Sync — Hot-reload local code in cluster

Clones the workload inside the cluster and syncs a local directory into the clone. The clone has the same env/volumes/network as the original. Supports mesh routing via --headers.

kubevpn sync deployment/\x3Cname> --sync ~/code:/app/code
kubevpn sync deployment/\x3Cname> --sync ~/code:/app/code --headers foo=bar

kubevpn unsync deployment/\x3Cname>-sync-xxxxx   # remove sync resource

5. Alias — Named config shortcuts

Define named aliases in ~/.kubevpn/config.yaml to avoid repeating long flags. Supports Needs dependency chains (connect to cluster A before cluster B).

kubevpn alias dev       # runs the flags defined under "dev" in config
kubevpn alias jumper    # connect to jumper cluster only

See commands.md for config file format.

Via SSH Bastion / Jump Host

All connect/proxy/run/sync commands support SSH jump:

kubevpn connect --ssh-addr 192.168.1.100:22 --ssh-username root --ssh-keyfile ~/.ssh/id_rsa
kubevpn connect --ssh-alias dev                           # uses ~/.ssh/config alias
kubevpn proxy deployment/\x3Cname> --ssh-alias dev --headers foo=bar

Reference Files

• commands.md — Full flag reference for all kubevpn commands (including alias, connection, route, ssh, image, logs, quit)
• architecture.md — How connect/proxy/mesh modes work internally

Common Patterns

Notes

• proxy, run, and sync auto-connect to the cluster if not already connected
• Multiple clusters can be connected simultaneously; use kubevpn status or kubevpn connection list to inspect
• disconnect cleans up DNS/hosts; quit also stops the daemon gRPC server entirely
• Server components are auto-deployed on first use (or pre-install: helm install kubevpn kubevpn/kubevpn)
• Supports HTTP, gRPC, Thrift, WebSocket, TCP, UDP, ICMP
• Use kubevpn reset deployment/\x3Cname> if a workload gets stuck with injected containers
• Use kubevpn image copy to mirror images to a private registry when ghcr.io is not accessible