Quick Start

How to (very) quickly start using mirrord

Get mirrord running in under 5 minutes. You'll need:

• Locally: macOS (Intel/Apple Silicon), Linux (x86_64), or Windows (x86_64/WSL). kubectl configured and pointing at your cluster.

• In the cluster: A running workload (deployment, pod, etc.) you want to work with. Linux kernel 4.20+, Docker or containerd runtime.

Install

CLI (macOS/Linux)

brew install metalbear-co/mirrord/mirrord

or:

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

CLI (Windows)

VS Code / Cursor / Windsurf

JetBrains

Try it

CLI

To run a local process in the context of the remote target:

mirrord exec --target <target-path> <command to run locally>

For example, to run a Python app as if it were the remote pod:

mirrord exec --target pod/app-pod-01 python main.py

Or run a local container instead of a native process:

mirrord container --target pod/app-pod-01 -- docker run nginx

Use mirrord exec --help or mirrord container --help for all options.

IDE Extensions

1. VS Code: Click Enable mirrord in the status bar at the bottom of the window.

2. JetBrains: Click the mirrord icon in the navigation toolbar (top right).

Then start a debug session. You'll be prompted to select a pod — pick the one you want to impersonate, and your local process will be plugged into it.

Send a request to your remote target — you should see it arriving at your local process as well!

What just happened?

By default, mirrord does the following:

Feature	Default behavior
Incoming traffic	Mirrored — your local process receives a copy of traffic hitting the remote pod
Outgoing traffic	Tunneled through the remote pod, so your local process can access cluster-internal services
Environment variables	Imported from the remote pod into your local process
File reads	Read from the remote pod's filesystem
DNS	Resolved on the remote pod

Your remote pod continues running normally — nothing is disrupted.

Working with a team? mirrord for Teams adds access control, traffic policies, and concurrent session management so your whole team can use mirrord safely.

Configuration

mirrord reads config from <project-path>/.mirrord/mirrord.json (also supports .toml and .yaml). You can also prefix config files, e.g. my-config.mirrord.json.

Run mirrord wizard to generate a config file interactively, or see the full configuration options.

The IDE extensions provide autocomplete for mirrord config files.

Next Steps

What are you trying to do?

Not sure where to start? Run mirrord wizard to walk through common use cases interactively.

Goal	Guide
Test against live traffic	Steal incoming traffic so your local process responds to real requests instead of the remote pod
Debug a queue consumer	Queue splitting lets your local process consume messages without competing with the deployed service
Run a tool in cluster context	Targetless mode lets you run scripts or tools with cluster network access, without impersonating a specific pod
Use mirrord with an AI agent	Set up Claude Code, Cursor, or Codex to test generated code against your cluster automatically
Set up for your team	Install the mirrord Operator for access control, policies, and multi-user support

Need help or want to share feedback? Join our Slack community