KSail + mirrord

mirrord lets you run a local process as if it were inside the cluster: your process inherits the pod’s environment variables, file system reads, and incoming network traffic — without deploying a new image. KSail provisions and configures the cluster; mirrord connects your local process to it.

Layer	Responsibility	Tool
Cluster lifecycle	Create, configure, and delete clusters	KSail
GitOps bootstrap	Install Flux/ArgoCD, push manifests	KSail
Local↔remote bridging	Run local process as in-cluster pod	mirrord

Note

KSail sets the kubeconfig context after ksail cluster create. For context names by distribution, see Companion Tools.

How mirrord Works

mirrord injects a layer into your local process that intercepts system calls and redirects them to a target pod in the cluster:

• Incoming traffic — mirror a copy of pod traffic to your local process (non-destructive), or steal it entirely so only your process responds.
• Outgoing traffic — route your local process’s outbound connections through the cluster network.
• Environment — inherit environment variables from the target pod.
• File system — read remote files from the pod’s file system as if they were local.

This lets you debug a specific service using real cluster traffic without image rebuilds, redeploys, or port-forward gymnastics.

Prerequisites

• KSail CLI installed

• Docker running

• mirrord CLI installed:

  brew install metalbear-co/mirrord/mirrord  # macOS
  # or
  curl -fsSL https://raw.githubusercontent.com/metalbear-co/mirrord/main/scripts/install.sh | bash

Quickstart

1. Create a cluster with KSail

ksail project init --name dev --distribution K3s
ksail cluster create

2. Deploy a workload

kubectl --context k3d-dev create deployment my-app --image=nginx:latest --port=80 \
  --dry-run=client -o yaml | kubectl --context k3d-dev apply -f -
kubectl --context k3d-dev expose deployment my-app --port=80 \
  --dry-run=client -o yaml | kubectl --context k3d-dev apply -f -

3. Configure mirrord

Create a .mirrord/mirrord.json configuration file in your project directory:

{
  "target": {
    "path": "deployment/my-app",
    "namespace": "default"
  },
  "feature": {
    "network": {
      "incoming": "mirror"
    },
    "fs": "read",
    "env": true
  }
}

Note

mirrord uses your default kubeconfig (~/.kube/config) unless you set kube_context or point to a different file. If you have configured a custom kubeconfig path in KSail via spec.cluster.connection.kubeconfig, add "kubeconfig": "<path>" here to match.

Field	Description
target.path	The pod/deployment/statefulset to target
feature.network.incoming	"mirror" (duplicate traffic) or "steal" (redirect all traffic)
feature.fs	"read" (remote reads), "write" (read+write), or false
feature.env	Inherit pod environment variables

4. Run your process through mirrord

mirrord exec --config .mirrord/mirrord.json -- ./my-app

Your local my-app process now receives a copy of all traffic destined for deployment/my-app, and inherits its environment variables and file access.

5. Tear down

# Stop the mirrord session with Ctrl+C
ksail cluster delete

Mirror vs. Steal

mirrord supports two traffic modes:

Mode	Behavior	Use case
"mirror"	Duplicate incoming traffic to both the pod and your local process	Observe and debug without affecting production behavior
"steal"	Redirect all incoming traffic exclusively to your local process	Test responses, verify logic changes with real traffic

Switch modes by updating feature.network.incoming in your .mirrord/mirrord.json.

Danger

"steal" mode takes all traffic away from the in-cluster pod. Avoid using it in shared clusters where other developers or services depend on the deployment being responsive.

Context-Specific Configuration

Use the kubeconfig context for your KSail distribution. Pass it directly on the command line to override the default context:

mirrord exec --context k3d-dev --config .mirrord/mirrord.json -- ./my-app

Or set it in mirrord.json:

{
  "target": {
    "path": "deployment/my-app",
    "namespace": "default"
  },
  "kube_context": "k3d-dev"
}

Replace k3d-dev with the context name for your distribution (see Companion Tools).

IDE Integration

mirrord integrates directly with VS Code and JetBrains IDEs — no CLI needed:

• VS Code: Install the mirrord VS Code extension. A mirrord toggle appears in the status bar; enable it before starting a debug session.
• JetBrains: Install the mirrord JetBrains plugin. A mirrord button appears in the Run toolbar.

Both integrations use your .mirrord/mirrord.json configuration automatically.

Combining KSail + mirrord with Other Tools

You can layer mirrord with other inner-loop tools. For example, use Tilt to rebuild and deploy on file save, and mirrord in a separate terminal to debug a specific service with live traffic:

# Terminal 1 — cluster + build loop
ksail cluster create
tilt up

# Terminal 2 — live debugging with real traffic
mirrord exec --config .mirrord/mirrord.json -- dlv debug ./cmd/server

See Companion Tools for a full comparison of KSail’s companion tool integrations.

Tips

• Start with "mirror" mode — it’s non-destructive and lets you observe real traffic without interrupting the in-cluster service.

• Use ksail cluster info to confirm the cluster is healthy before starting a mirrord session.

• Target specific pods by using pod/<name> instead of deployment/<name> for more precise targeting:

  { "target": { "path": "pod/my-app-abc123", "namespace": "default" } }

• Combine with ksail workload watch for manifest editing: ksail workload watch handles YAML changes at the Kubernetes layer; mirrord connects your local process at the network layer. They operate at different layers and do not conflict.

• Ephemeral clusters work well with mirrord — create a short-lived cluster with ksail cluster create --ttl 1h to isolate your debugging session. See Ephemeral Clusters for details.