Model or dataset
metalbear-co/mirrord avatar
metalbear-co/mirrord

mirrord: Running a Local Process as a Kubernetes Pod Without Deploying

Run any process, on your machine or in an AI agent's environment, as if it were a pod in your Kubernetes cluster: real env vars, DNS, network, traffic.

5,412 stars228 forksRustMIT

At a glance

What is it?
mirrord routes a locally running process through a target pod in a live cluster so that environment variables, DNS, files, and traffic behave as if the process were deployed. It is a strong fit for debugging services that only fail inside the cluster, and a poor fit for anyone who cannot grant an agent pod elevated Linux capabilities.
Who is it for?
Adopt mirrord if your service depends on cluster-only state such as internal DNS names, mounted secrets, or a queue you cannot replicate locally, and if you can run an agent pod with CAP_NET_ADMIN, CAP_SYS_PTRACE, and CAP_SYS_ADMIN. Do not adopt it if you cannot satisfy those capabilities, if you need a stable long-running replica rather than an ephemeral impersonation, or if you only need to read cluster state without routing traffic.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Rust, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • metalbear-co/mirrord5,412 ★ · +88
Star history
Repository2026-09-102026-11-15
metalbear-co/mirrord5.3k5.4k

88 Stars in the last 66 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The gap mirrord fills: code that only breaks inside the cluster

A service that runs cleanly on a laptop can fail immediately once deployed, and the cause is usually environmental rather than logical. The process expects an internal DNS name that only resolves inside the cluster, reads a secret mounted from a ConfigMap or Secret, or talks to a queue whose contents exist only in a shared staging namespace. Reproducing that locally means standing up a parallel environment and keeping it in sync, which is exactly the work mirrord tries to remove. The README frames the goal directly: mirrord runs a local process inside a live Kubernetes cluster, so the code executes on your machine while its traffic, files, and environment variables are routed through a target pod. The audience is developers debugging a deployed service, and, per the README, AI coding agents such as Claude Code, Cursor, Codex, Copilot, and Windsurf, which the project treats as first-class users. mirrord ships as a VS Code extension, an IntelliJ plugin, and a CLI, so the entry point depends on whether a human or an agent is driving.

How the agent pod and the impersonated pod split the work

The README describes a two-pod arrangement. When you select a pod to impersonate, mirrord launches a new pod on the same node as the pod you selected. That new pod is the bridge: it mirrors incoming traffic from the impersonated pod to your local process, routes outgoing traffic from your local process through the pod, and does the same for file reads, file writes, and environment variables. So the local process keeps its own filesystem and its own debugger, but its network identity and its view of the environment come from the cluster. Placing the agent pod on the same node is not incidental. Joining the target pod's network namespace and redirecting its traffic with iptables are node-local operations, which is why the same-node constraint appears in the description rather than being an optimisation. The README also notes that mirrord uses your machine's default kubeconfig for API access, so there is no separate credential store to configure.

Linux capabilities the agent pod needs, and how to drop them

This is the part that decides whether mirrord works in your cluster at all. The README lists three capabilities required by the container that mirrord launches: CAP_NET_ADMIN for redirecting the target's incoming traffic with iptables, CAP_SYS_PTRACE for accessing the target's network namespace, files and environment through /proc, and CAP_SYS_ADMIN for joining the target pod's network namespace. Those are broad grants, and clusters running restrictive Pod Security Standards or admission policies that forbid CAP_SYS_ADMIN will block the agent pod before mirrord gets a chance to route anything. The project does provide an escape hatch. The README states you can disable any subset of those capabilities through configuration, with the caveat that doing so may limit mirrord's functionality or make it unusable in some setups. The example given sets agent.disabled_capabilities to ["NET_ADMIN"] in a mirrord.json file and passes it with mirrord exec -f mirrord.json node app.js --target pod/my-pod. Note what that example drops: CAP_NET_ADMIN is the capability the README ties to redirecting the target's incoming traffic with iptables. The trade-off is explicit in the documentation, and it is worth reading the configuration reference before assuming a partial setup is enough.

Getting it running from the CLI

Installation is offered through several channels. Homebrew: brew install metalbear-co/mirrord/mirrord. A shell installer: curl -fsSL https://raw.githubusercontent.com/metalbear-co/mirrord/main/scripts/install.sh | bash. Nix, which the README flags as community maintained rather than official, via nix-env -iA nixpkgs.mirrord or nix profile install nixpkgs#mirrord. And on Windows, choco install --pre mirrord. The execution form is a wrapper around your own command: mirrord exec <process command> --target <target-path>, with the README's example being mirrord exec node app.js --target pod/my-pod. The --target flag takes a target path, and the example uses the pod/ prefix, which implies other target kinds are accepted; the README does not enumerate them, so check the configuration reference if you want to target a deployment rather than a single pod. The IDE route is shorter. In VS Code you install the extension, click Enable mirrord on the status bar, start debugging, and choose the pod to impersonate. In IntelliJ you click the mirrord icon in the Navigation Toolbar, start debugging, and choose a namespace and pod. Both flows end the same way: the debugged process is plugged into the selected pod.

Where mirrord is the wrong tool

The capability requirement is the first hard boundary, but not the only one. Because mirrord launches an agent pod per impersonation and mirrors traffic rather than duplicating a replica, it is a debugging and verification tool, not a way to run a long-lived copy of a service. If what you actually need is a second replica receiving a share of production traffic, a service mesh or a traffic-splitting ingress does that job without granting CAP_SYS_ADMIN to anything. The same-node scheduling constraint is a second boundary: on a cluster where the target pod sits on a node with taints the agent pod cannot tolerate, or where node affinity rules are tight, the agent may not land where it needs to. The README does not describe fallback behaviour for that case, so treat it as unverified until you try it against your own node pool. A third limitation is conceptual rather than technical. mirrord mirrors file reads and writes and environment variables from the target pod, which means your local process can be affected by, and can affect, state that other people share. The README's claim that you get the feedback of a deploy without disrupting the cluster for anyone else is a design intent, not a guarantee, and the blast radius depends on what your process does once it is wired in. Finally, if your only need is to read cluster state while writing code, without running the process against live services, mirrord is more machinery than the problem requires.

Alternatives and the difference in approach

The obvious comparison is Telepresence, which also connects a local process to a Kubernetes cluster. The two take different routes to the same destination. Telepresence installs a cluster-side traffic manager and establishes a tunnel that gives your workstation a presence in the cluster network, so the local machine effectively joins the cluster's network rather than borrowing a specific pod's identity. mirrord's approach, as the README describes it, is narrower and more targeted: you name a pod, mirrord launches an agent pod on that pod's node, and your local process is plugged into that one pod, inheriting its environment, files, and traffic. The practical difference shows up in the failure modes. Telepresence's cluster-wide tunnel needs its own installation and lifecycle management. mirrord's per-impersonation agent pod inherits the Linux capability requirements and the same-node scheduling constraint. A second alternative is simply running a local replica against a staging namespace with port-forwarding and copied secrets. That avoids any cluster-side agent and any elevated capabilities, at the cost of the environment drifting from what is actually deployed, which is the problem mirrord exists to solve.

Maintenance cost, release cadence, and licence

mirrord is MIT licensed, which is permissive and places few obligations on how you use or redistribute it. The repository shows a rapid release cadence: 3.284.0 on 2026-11-03, 3.283.0 on 2026-11-01, and 3.282.0 on 2026-10-30. Frequent minor releases are a signal to plan your upgrade path rather than pinning forever, particularly since the tool sits between your local machine and a live cluster, where a version mismatch between the CLI and the agent pod it launches is a plausible source of confusion. The README does not state a compatibility policy between client and agent versions, so that is something to confirm before you standardise on a pinned version across a team. The project is written in Rust and is not archived. For a tool that injects itself into your debug loop, the maintenance question is less about the codebase and more about the operational surface: every developer who uses mirrord needs kubeconfig access to the cluster and the ability to create pods that request CAP_NET_ADMIN, CAP_SYS_PTRACE, and CAP_SYS_ADMIN. That is a platform-team conversation, not a per-developer install.

Editorial conclusion

Adopt mirrord if your service depends on cluster-only state such as internal DNS names, mounted secrets, or a queue you cannot replicate locally, and if you can run an agent pod with CAP_NET_ADMIN, CAP_SYS_PTRACE, and CAP_SYS_ADMIN. Do not adopt it if you cannot satisfy those capabilities, if you need a stable long-running replica rather than an ephemeral impersonation, or if you only need to read cluster state without routing traffic. Before rolling it out, verify two things against your own cluster: that the agent pod can actually be scheduled onto the same node as your target pod, and that your chosen target path (for example pod/my-pod) resolves to something you are willing to have your local process impersonate.

Frequently asked questions

What does it mean to be mirrored in mirrord?

It means your local process is plugged into a pod you pick, not that a copy of your code runs in the cluster. When you select a pod to impersonate, mirrord launches a pod on the same node and uses it to mirror incoming traffic from the target pod to your process, to route outgoing traffic from your process through it, and to do the same for file reads, file writes, and environment variables.

What does something being mirrored mean in mirrord?

Your code stays on your machine while its traffic, files, and environment variables resolve through a target pod, so you read real env vars, real service responses, and real queue contents. The README frames the payoff as the feedback of a deploy in seconds, without the deploy and without disrupting the cluster for anyone else.

What is the meaning of the word mirrored in mirrord?

The README never expands the name. The verbs it actually uses are impersonate, in the step Choose pod to impersonate for the VS Code extension and Choose a namespace and pod to impersonate for the IntelliJ plugin, and plugged into, in the line saying the debugged process will be plugged into the selected pod by mirrord.

What are the mirrord alternatives?

The README names no alternative. It names the workflow mirrord sits against, described as getting the feedback of a deploy in seconds without the deploy, and three ways to install it: a VS Code extension from the marketplace, an IntelliJ plugin from the JetBrains plugin repository, and a CLI from Homebrew, a piped shell installer, community maintained Nix, or Chocolatey with the prerelease flag on.

Official sources

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

Where developers are discussing it

Posts on Hacker News, dev.to and Lobsters that link to this repository, found by our scan of those communities. 0 in the last 30 days; newest first.

Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/metalbear-co-mirrord.svg)](https://hysenlabs.com/projects/metalbear-co-mirrord)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/metalbear-co-mirrord.svg)](https://hysenlabs.com/projects/metalbear-co-mirrord)

Was this useful?