mirrord — Run Local Code in Kubernetes Cloud Conditions

Introduction

mirrord lets developers test local code against a remote Kubernetes environment without building images, pushing to a registry, or waiting for deployments. It intercepts traffic, environment variables, and file access from a target pod and redirects them to your local process, giving you production-like conditions on your laptop.

What mirrord Does

• Mirrors or intercepts incoming network traffic from a target Kubernetes pod to your local process
• Proxies environment variables and mounted config from the remote pod
• Forwards DNS resolution through the cluster so local code resolves service names
• Provides remote file system access so your process reads files from the pod
• Works with any language or framework since it operates at the OS level

Architecture Overview

mirrord injects a lightweight agent as an ephemeral container into the target pod. The agent captures network traffic using eBPF hooks and forwards it over a secure connection to the mirrord client running on the developer's machine. The client hooks the local process using LD_PRELOAD (Linux) or DYLD_INSERT_LIBRARIES (macOS), intercepting system calls for networking, file I/O, and environment access.

Self-Hosting & Configuration

• Install via brew, curl script, or as a VS Code / JetBrains IDE extension
• No cluster-side installation required; the agent is injected on-demand as an ephemeral container
• Configure target pod, namespace, and traffic mode (mirror or steal) via a JSON config file
• Restrict which paths are read remotely versus locally using file filter patterns
• RBAC: the user needs permissions to create ephemeral containers in the target namespace

Key Features

• Zero cluster-side setup with on-demand ephemeral agent injection
• Traffic mirroring for read-only observation or stealing for full interception
• IDE integration with one-click debug for VS Code and JetBrains
• Works with any language, framework, or runtime — no SDK required
• Configurable filters for network ports, file paths, and environment variables

Comparison with Similar Tools

• Telepresence — Requires a cluster-side traffic manager; mirrord uses ephemeral containers with no persistent install
• kubectl port-forward — Only forwards ports; mirrord also proxies env vars, DNS, and files
• Skaffold dev — Redeploys on changes; mirrord avoids the build/push/deploy cycle entirely
• Eclipse Che — Full cloud IDE; mirrord keeps you in your local IDE

FAQ

Q: Does mirrord modify the target pod? A: It adds a temporary ephemeral container that is removed when the session ends. The original containers are untouched.

Q: Can multiple developers use mirrord on the same pod? A: Yes. In mirror mode, multiple developers can observe the same traffic. Steal mode is typically one-at-a-time per port.

Q: Does mirrord work on macOS? A: Yes. It supports macOS (x86_64 and ARM64) and Linux.

Q: Is mirrord free? A: The open-source CLI and IDE extensions are free. MetalBear offers mirrord for Teams with additional features.

Sources

• https://github.com/metalbear-co/mirrord
• https://mirrord.dev/docs