mirrord: run a local process as if it were a pod in your Kubernetes cluster

The gap mirrord fills between a local run and a real deploy

A service that passes locally can still fail in the cluster because of what surrounds it: a ConfigMap value, a service DNS name that only resolves inside the cluster, a queue that actually has messages in it. The README frames the problem in two halves. First, read live cluster context while writing the code, so the change is grounded in what is deployed. Second, run the same code against those services and data to confirm it works end to end. mirrord's pitch is that you get the feedback of a deploy in seconds, without the deploy, and without disrupting the cluster for anyone else.

The intended audience is the developer running a debugger, and increasingly an AI coding agent. The README lists Claude Code, Cursor, Codex CLI and Gemini CLI among the agents it works with, and points to a separate repository, metalbear-co/skills, for setup guides. The same mechanism serves both: a process on a laptop that needs to behave as if it were scheduled in the cluster.

How the agent pod mirrors traffic, files and environment variables

The mechanism is worth understanding before you install anything, because it explains both the value and the operational cost. When you select a pod to impersonate, mirrord launches a new pod on the same node as the pod you selected, according to the README. That new pod is the bridge. It connects your local process to the impersonated pod: it mirrors incoming traffic from the pod to your process, routes outgoing traffic from your process through the pod, and does the same for file reads, file writes and environment variables.

Two consequences follow. Because the agent pod must land on the same node, scheduling constraints on that node apply to mirrord too. And because the agent manipulates routing tables, joins a network namespace and reads the target's environment, its container needs extra Linux capabilities. The README names four: CAP_NET_ADMIN and CAP_NET_RAW for modifying routing tables, CAP_SYS_PTRACE for reading the target pod environment, and CAP_SYS_ADMIN for joining the target pod network namespace.

Those capabilities are the part most likely to collide with your cluster's policy. The README is explicit that you can disable any subset through configuration, but it also warns that doing so will possibly limit mirrord functionalities or even make it unusable in some setups. That is an honest trade-off statement rather than a guarantee, and it is the first thing to test in a locked-down environment.

Installing the mirrord CLI and running a first process against a pod

The CLI installs through Homebrew, a shell script, Nix (community maintained, not official) or Chocolatey on Windows. The Homebrew tap is the shortest path on macOS or Linux:

brew install metalbear-co/mirrord/mirrord

If you prefer not to use Homebrew, the README also gives a curl-to-bash installer:

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

mirrord uses your machine's default kubeconfig for access to the Kubernetes API. There is no separate login step in the README; whatever context kubectl already uses is what mirrord uses. Confirm that with `kubectl config current-context` before you run anything, and make sure the context points at the cluster you mean to touch.

The first real use is a single command. You give it the process to run and a target to impersonate:

mirrord exec node app.js --target pod/my-pod

The target takes the form `pod/my-pod` in the README example. What you should see is your process starting locally while its environment variables, DNS resolution and network traffic come from the selected pod. If the agent pod cannot be created, or the capabilities it requests are rejected, the command fails rather than silently falling back to a purely local run.

If your cluster forbids some capabilities, the README shows an environment variable for dropping them. This example disables CAP_NET_RAW and CAP_SYS_PTRACE:

MIRRORD_AGENT_DISABLED_CAPABILITIES=CAP_NET_RAW,CAP_SYS_PTRACE mirrord exec node app.js --target pod/my-pod

Expect reduced behaviour: with CAP_SYS_PTRACE disabled, reading the target pod's environment is the capability you gave up, so anything depending on that will not work. Test the subset you actually need rather than copying this line.

The editor plugins change the workflow, not the mechanism

If you would rather not manage a CLI invocation, the VS Code extension and the IntelliJ plugin wrap the same machinery. In VS Code you install the extension from the Marketplace, click Enable mirrord on the status bar, start debugging your project and then choose the pod to impersonate. The debugged process is plugged into the selected pod by mirrord. In IntelliJ you install the plugin from the JetBrains Marketplace, click the mirrord icon in the Navigation Toolbar, start debugging, and choose a namespace and pod.

The IntelliJ flow is the one that asks for a namespace explicitly; the VS Code flow as documented goes straight to pod selection. Neither plugin is described in the README as offering a different feature set from the CLI, so treat the choice as ergonomic. The CLI is what you will script, what you will put in front of an AI agent, and what you will use when the debugger is not the point.

Where mirrord is the wrong tool

mirrord assumes there is a long-lived pod worth impersonating. If your workload is a CronJob, a one-shot migration or a batch job, there is no stable target to attach to and the model does not fit. The README does not describe support for attaching to completed or short-lived workloads.

The capability requirement is the harder constraint. In clusters where Pod Security Admission is set to restricted, or where an admission controller rejects CAP_SYS_ADMIN and CAP_SYS_PTRACE, the default agent pod will not be admitted. Disabling capabilities can get you past policy, but the README's own wording is that this will possibly limit functionality or make mirrord unusable in some setups. That is not a guarantee that a reduced set works for your service.

There is also a blast-radius question the README does not answer. Because incoming traffic to the impersonated pod is mirrored to your machine, running mirrord against a production pod routes a copy of that traffic to a laptop. The README says mirrord does not disrupt the cluster for anyone else, which addresses the other developers, not the question of whether production traffic should reach your machine at all. Choose your target accordingly, and prefer a staging pod when the service handles anything sensitive.

Finally, if your local docker-compose stack already reproduces the bug, mirrord adds a cluster dependency and a capability negotiation for no gain.

Alternatives and what actually differs

The obvious alternative is Telepresence, which also connects a local process to a Kubernetes cluster. The difference is architectural. Telepresence installs a cluster-wide traffic manager and intercepts traffic at the cluster level, replacing or intercepting a workload's traffic so that requests reach your machine. mirrord instead launches a per-session agent pod on the same node as the target and mirrors traffic, files and environment variables through it. The practical consequences: mirrord's footprint is scoped to the node of the pod you pick and to the lifetime of your session, while Telepresence's model involves a cluster-side component that persists. mirrord's per-session agent is also why the four Linux capabilities are requested at all.

A second alternative is simply port-forwarding plus a copied environment. That gets you network reachability to one port and nothing else: no mirrored file reads, no environment variables from the target, no incoming traffic. It is the right answer when all you need is to hit a database from your laptop.

A third is running the whole thing with Skaffold or Tilt, which build and deploy on every change. That gives you a real pod rather than a mirrored one, at the cost of a build and deploy cycle per iteration. mirrord's claim is that it removes that cycle; the trade is that your local process now depends on a cluster session being alive.

Licence, release cadence and the cost of staying current

mirrord is MIT licensed, which places few restrictions on internal or commercial use. The licence text is in the repository root. Nothing in the README suggests a separate commercial tier or a licence key requirement for the CLI, the VS Code extension or the IntelliJ plugin. This is a description of what the repository states, not legal advice; if you redistribute mirrord or embed it in a product, read the MIT terms yourself.

The release cadence is fast. The recent releases listed for the project are 3.256.0 on 2026-09-10, 3.255.0 on 2026-09-09 and 3.254.0 on 2026-09-03, and the last push to the default branch was on 2026-09-10. Version numbers in the 3.2xx range with releases days apart mean the project ships often. For a tool that runs inside your cluster, that cadence has a cost: the agent pod image your session creates is tied to the version of the tool you run, so a team on mixed versions is running mixed agents. Pin the version in CI and in any shared developer setup rather than tracking latest.

Telemetry is worth checking before rollout. The repository contains a TELEMETRY.md file, which is where the project documents what it collects. The README itself does not describe telemetry behaviour, so read that file rather than assuming.

Editorial conclusion

Adopt mirrord if you debug services that only misbehave against real cluster dependencies, and you can grant the agent pod CAP_NET_ADMIN, CAP_NET_RAW, CAP_SYS_PTRACE and CAP_SYS_ADMIN or a deliberate subset of them. Do not reach for it when the target workload is a one-off job, when you have no rights to create pods, or when a local compose stack already reproduces the failure. Before rolling it out to a team, verify two things in your own cluster: that the agent pod schedules onto the same node as the target, and that your admission policies accept the capabilities the default configuration requests.

Frequently asked questions

Official sources

1. License: MIT
2. metalbear-co/mirrord on GitHub
3. Project website
4. README
5. Releases