mirrord Documentation

1. Project Overview & Quickstart (metalbear-co/mirrord) Copy Chapter

File: README.md Copy Chapter

mirrord runs your local process inside a live Kubernetes cluster.
It works the same way for developers and for AI coding agents (Claude Code, Cursor, Codex, Copilot, Windsurf):
your code runs on your machine, but mirrord routes its traffic, files, and environment variables through a target pod in the cluster.

That covers both halves of the software development loop. Read live cluster context while writing the code (real env vars, real service responses, real queue contents)
so the change is grounded in what's actually deployed. Then run the code against those same services and data to confirm it works end-to-end.

You get the feedback of a deploy in seconds, without the deploy, and without disrupting the cluster for anyone else.
mirrord ships as a VS Code extension, IntelliJ plugin, and CLI tool. Read more.

Adopted by: monday.com, SurveyMonkey, Cadence, CoLab, Daylight Security, Zooplus, and others.

Contents

• Contents
  • Getting Started
  • VS Code Extension
    • Installation
    • How To Use
  • IntelliJ Plugin
    • Installation
    • How To Use
  • CLI Tool
    • Installation
    • How To Use
  • How It Works
    • Additional capabilities
  • Using mirrord with AI coding agents
  • FAQ
  • Contributing
  • Help and Community
  • Code of Conduct
  • License

Getting Started Copy Chapter

• VS Code Extension
• IntelliJ Plugin
• CLI Tool

mirrord uses your machine's default kubeconfig for access to the Kubernetes API.

VS Code Extension Copy Chapter

Installation Copy Section

Get the extension here.

How To Use Copy Section

• Click "Enable mirrord" on the status bar
• Start debugging your project
• Choose pod to impersonate
• The debugged process will be plugged into the selected pod by mirrord

IntelliJ Plugin Copy Chapter

Installation Copy Section

Get the plugin here.

How To Use Copy Section

• Click the mirrord icon in the Navigation Toolbar
• Start debugging your project
• Choose a namespace and pod to impersonate
• The debugged process will be plugged into the selected pod by mirrord

CLI Tool Copy Chapter

Installation Copy Section

You can use either

brew install metalbear-co/mirrord/mirrord

or

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

or using Nix (not official, community maintained):

# Using nix-env (legacy)
nix-env -iA nixpkgs.mirrord

# Using nix profile (recommended)
nix profile install nixpkgs#mirrord

or on Windows using Chocolatey:

choco install --pre mirrord

How To Use Copy Section

mirrord exec  --target <target-path>

e.g.

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

How It Works Copy Chapter

When you select a pod to impersonate, mirrord launches a pod on the same node as the pod you selected.
The new pod is then used to connect your local process and 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.
You can read more about it here.

Additional capabilities Copy Section

Container run inside the pod launched by mirrord requires additional Linux capabilities:

• CAP_NET_ADMIN and CAP_NET_RAW - for modifying routing tables
• CAP_SYS_PTRACE - for reading target pod environment
• CAP_SYS_ADMIN - for joining target pod network namespace

However, you can disable any subset of those in the configuration.
This will possibly limit mirrord functionalities or even make it unusable in some setups.

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

Using mirrord with AI coding agents Copy Chapter

mirrord works first-class with Claude Code, Cursor, Codex CLI, Gemini CLI, and other AI coding agents,
letting them run and verify generated code against real cluster services without deploying.

For setup guides and ready-made workflow skills,
see metalbear-co/skills or the mirrord for AI Agents page.

FAQ Copy Chapter

Our FAQ is available here.
If you have a question that's not on there, feel free to ask in our Discussions
or on Slack.

Contributing Copy Chapter

Contributions are very welcome.
Start by checking out our open issues, and by going through our contributing guide.
We're available on Slack for any questions.

Help and Community Copy Chapter

Join our Slack for questions, support and fun.

We always appreciate hearing how mirrord has made a difference for our users.
Check out our ADOPTERS.md to see how others are using mirrord —
and open a pull request to add your organization if you’d like to share how mirrord has been useful to you.

Code of Conduct Copy Chapter

We take our community seriously and we are dedicated to providing a safe and welcoming environment for everyone.
Please take a few minutes to review our Code of Conduct.

License Copy Chapter

MIT

File: medschool/readme.md Copy Chapter

medschool

It's what makes docs MD.

• Tal

Generates a markdown file from a Rust crate's documentation.

medschool will extract the docs from the current directory, and build a nice
configuration.md file.

To use it simply run medschool on the directory you want to get docs from, for example:

cd rust-project

medschool

It'll look into rust-project/src and produce rust-project/configuration.md.

Usage Copy Chapter

To generate the configuration.md that you see in the
docs page we use the medschool tool as such:

cargo run -p medschool -- --input ./mirrord/config/src --output ./mirrord/config/configuration.md

You can also use the --prepend arg to include a file at the start of the generated markdown file.

cargo run -p medschool -- --prepend ./header.txt --input ./mirrord/config/src --output [path to metalbear.co/mirrord docs page]

File: mirrord/protocol/README.md Copy Chapter

mirrord-protocol

This is a cargo library that implements the mirrord-protocol between the agent and client.

File: mirrord/layer/README.md Copy Chapter

mirrord-layer

This part of mirrord is preloaded into a process and hooks libc functions, making them work with mirrord-agent rather than locally.

To preload mirrord-layer into a process:

• On Linux, run LD_PRELOAD=/mirrord-layer.so
• On macOS, run DYLD_INSERT_LIBRARIES=/mirrord-layer.dylib

File: mirrord/config/derive/README.md Copy Chapter

Mirrord Config Derive

This crate implements the derive macro MirrordConfig, which introduces the config attribute:

• On a struct:

  • map_to = &str set the name of the new generated struct (defaults to format!("File{}", <struct name>)).
  • derive = &str extend derive statement with extra values.
  • generator = &str set the type Generator for FromMirrordConfig.

• On struct fields:

  • nested to use a value of a type that itself implement MirrordConfig. The value used is its Generated type.
  • toggleable wrap field with ToggleableConfig so will be allowed to pass bool instead of entire field
  • env = &str to load the value from the specified environment variable, if it's populated.
  • default = &str to set a default value to the field. This also implicitly unwraps it.
  • unstable mark field as unstable and print an error message to the user.
  • deprecated | deprecated = &str mark field as deprecated and print either a default message or a custom one.
  • rename = &str pass #[serde(rename = &str)] to generated struct.

Example

/// MyConfig Comments
#[derive(MirrordConfig, Default)]
#[config(map_to = "MyFileConfig", derive = "Eq,PartialEq")] // If map_to isn't given, it will default to FileMyConfig
pub struct MyConfig {
    /// Value 1 Comment
    #[config(env = "VALUE_1")]
    pub value_1: Option<String>,

    /// Value 2 Comment
    #[config(env = "VALUE_2", default = "2")]
    pub value_2: i32,

    /// Value 3 Comment
    #[config(env = "VALUE_3", rename = "foobar")]
    pub value_3: String,

    /// Value 4 Comment
    #[config(nested)]
    pub value_4: OtherConfig,
}

The following struct will be generated:

/// MyConfig Comments
#[derive(Clone, Debug, Default, serde::Deserialize, Eq, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct MyFileConfig {
    /// Value 1 Comment
    pub value_1: Option<String>,

    /// Value 2 Comment
    pub value_2: Option,

    /// Value 3 Comment
    #[serde(rename = "foobar")]
    pub value_3: Option<String>,

    /// Value 4 Comment
    pub value_4: Option<<OtherConfig as FromMirrordConfig>::Generator>,
}

File: mirrord/cli/README.md Copy Chapter

mirrord-cli

mirrord-cli is the actual binary that users use to run mirrord. The client helps you execute processes with mirrord injected to it.
Right now injection is done using LD_PRELOAD on Linux and DYLD_INSERT_LIBRARIES on macOS.

Usage Copy Chapter

mirrord exec --pod-name [BINARY_ARGS..]

Compatibility Copy Chapter

Linux Copy Section

LD_PRELOAD works only on dynamically linked binaries, so static binaries won't work. Most development use cases are dynamic binaries, so it should be okay.
We do have plan to support static binaries, so let us know if you encountered a use case that isn't covered.

macOS Copy Section

DYLD_INSERT_LIBRARIES works on "unprotected" binaries, which are most development binaries anyway. To be more specific, the following use cases won't work:

• setuid and/or setgid bits are set
• restricted by entitlements
• restricted segment

Source

Please let us know if you encountered a use case where it doesn't work for you, of whether it's documented that it isn't supported, so we know there's demand to implement that use case.

Diagrams Copy Chapter

`mirrord exec` Copy Section

%%{init: {'theme': 'neutral', 'themeVariables': {'lineColor': '#f00'}}}%%
flowchart TB
    %% Nodes
    Start((Start))
    CLI[mirrord CLI]
    Config[Parse & Verify Config]
    Target[Target Resolution]
    Init[Initialize]
    CreateAgent[Create Agent]
    Connect[Create & Connect]
    ProxyStart[Start Internal Proxy]
    Patch[Patch Binary macOS]
    Exec[Execute User Binary]
    IntProxy[Internal Proxy]
    Agent[mirrord Agent]
    Operator[mirrord Operator]

    %% Styles
    classDef default fill:#f9f9f9,stroke:#333,stroke-width:2px
    classDef proxy fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    classDef agent fill:#e6ffe6,stroke:#006600,stroke-width:2px
    classDef operator fill:#ffe6e6,stroke:#cc0000,stroke-width:2px,stroke-dasharray: 5 5
    classDef init fill:#f9f9f9,stroke:#333,stroke-width:4px

    %% Apply styles
    class IntProxy proxy
    class Agent agent
    class Operator operator
    class Init init

    %% Flow
    Start --> CLI
    CLI --> Config
    Config --> Target
    Target --> |If operator enabled| Operator
    Operator --> |Create agent| Agent
    Target --> |If no operator| CreateAgent
    CreateAgent --> |Create via k8s API| Agent
    Target --> |Extract library| Init
    Init --> Connect
    Connect --> ProxyStart
    ProxyStart --> |macOS only| Patch
    Patch --> Exec
    Exec --> |Communicates via| IntProxy
    IntProxy --> |Forwards messages| Agent

    %% Note: Create Agent, mirrord Operator, and Initialize steps happen in parallel
    subgraph Parallel
        direction LR
        CreateAgent
        Operator
        Init
    end

`mirrord exec` (Sequence Diagram) Copy Section

%%{init: {'theme': 'neutral', 'themeVariables': {'lineColor': '#f00'}}}%%
sequenceDiagram
    participant CLI as mirrord CLI
    participant Config as Config Parser
    participant Target as Target Resolution
    participant Operator as mirrord Operator
    participant Agent as mirrord Agent
    participant Init as Initializer
    participant Proxy as Internal Proxy
    participant Binary as User Binary

    CLI->>Config: Parse & Verify Config
    Config->>Target: Resolve Target

    alt Operator Enabled
        Target->>Operator: Request Agent
        Operator->>Agent: Create Agent
    else No Operator
        Target->>Agent: Create via k8s API
    end

    Target->>Init: Extract Library
    Init->>Proxy: Initialize & Connect
    Proxy->>Agent: Establish Connection

    Note over Binary: On macOS Only
    Init->>Binary: Patch Binary

    Binary->>Proxy: Execute & Communicate
    Proxy->>Agent: Forward Messages
    Agent->>Operator: Report Status (if enabled)

File: mirrord/agent/README.md Copy Chapter

mirrord-agent

Agent part of mirrord responsible for running on the same node as the debuggee, entering it's namespace and collecting traffic.

mirrord-agent is written in Rust for safety, low memory consumption and performance.

mirrord-agent is distributed as a container image (currently only x86) that is published on GitHub Packages publicly.

Enabling prometheus metrics Copy Chapter

To start the metrics server, you'll need to add this config to your mirrord.json:

{
  "agent": {
    "metrics": "0.0.0.0:9000",
    "annotations": {
      "prometheus.io/scrape": "true",
      "prometheus.io/port": "9000"
    }
}

Remember to change the port in both metrics and annotations, they have to match,
otherwise prometheus will try to scrape on port: 80 or other commonly used ports.

Installing prometheus Copy Section

Run kubectl apply -f {file-name}.yaml on these sequences of yaml files and you should
get prometheus running in your cluster. You can access the dashboard from your browser at
http://{cluster-ip}:30909, if you're using minikube it might be
http://192.168.49.2:30909.

You'll get prometheus running under the monitoring namespace, but it'll be able to look
into resources from all namespaces. The config in configmap.yaml sets prometheus to look
at pods only, if you want to use it to scrape other stuff, check
this example.

1. create-namespace.yaml

apiVersion: v1
kind: Namespace
metadata:
  name: monitoring

2. cluster-role.yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: prometheus
rules:
- apiGroups: [""]
  resources:
  - nodes
  - services
  - endpoints
  - pods
  verbs: ["get", "list", "watch"]
- apiGroups:
  - extensions
  resources:
  - ingresses
  verbs: ["get", "list", "watch"]

3. service-account.yaml

apiVersion: v1
kind: ServiceAccount
metadata:
  name: prometheus
  namespace: monitoring

4. cluster-role-binding.yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: prometheus
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: prometheus
subjects:
- kind: ServiceAccount
  name: prometheus
  namespace: monitoring

5. configmap.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: prometheus-config
  namespace: monitoring
data:
  prometheus.yml: |
    global:
      keep_dropped_targets: 100

    scrape_configs:
      - job_name: "kubernetes-pods"

        kubernetes_sd_configs:
          - role: pod

        relabel_configs:
          - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
            action: replace
            regex: ([^:]+)(?::\d+)?;(\d+)
            replacement: $1:$2
            target_label: __address__
          - action: labelmap
            regex: __meta_kubernetes_pod_label_(.+)
          - source_labels: [__meta_kubernetes_namespace]
            action: replace
            target_label: namespace
          - source_labels: [__meta_kubernetes_pod_name]
            action: replace
            target_label: pod

• If you make any changes to the 5-configmap.yaml file, remember to kubectl apply it
  before restarting the prometheus deployment.

6. deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: prometheus
  namespace: monitoring
  labels:
    app: prometheus
spec:
  replicas: 1
  strategy:
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 1
    type: RollingUpdate
  selector:
    matchLabels:
      app: prometheus
  template:
    metadata:
      labels:
        app: prometheus
      annotations:
        prometheus.io/scrape: "true"
        prometheus.io/port: "9090"
    spec:
      serviceAccountName: prometheus
      containers:
      - name: prometheus
        image: prom/prometheus
        args:
          - '--config.file=/etc/prometheus/prometheus.yml'
        ports:
        - name: web
          containerPort: 9090
        volumeMounts:
        - name: prometheus-config-volume
          mountPath: /etc/prometheus
      restartPolicy: Always
      volumes:
      - name: prometheus-config-volume
        configMap:
            defaultMode: 420
            name: prometheus-config

7. service.yaml

apiVersion: v1
kind: Service
metadata:
    name: prometheus-service
    namespace: monitoring
    annotations:
        prometheus.io/scrape: 'true'
        prometheus.io/port:   '9090'
spec:
    selector:
        app: prometheus
    type: NodePort
    ports:
    - port: 8080
      targetPort: 9090
      nodePort: 30909

2. Official Technical Reference & Guides (metalbear-co/docs) Copy Chapter

File: README.md Copy Chapter

mirrord docs

This repo contains the source for the mirrord docs site Documentation tab. It uses GitBook to generate documentation from markdown.

NOTE that the mirrord docs' Configuration tab is not governed by this repo, but by the mirrord repo docs branch and is updated automatically by mirrord's release workflow.

The Changelog tab also has a separate repo, and is also updated automatically by CI.

Structure Copy Section

The root of the GitBook docs is ./docs, as defined in .gitbook.yaml. See the GitBook docs for more info.

Development Copy Section

When you open a PR with changes, GitBook will publish a preview and display the link under the Checks section at the bottom of the page that will show your changes - it does so via the GitBook bot installed in this repo. Use the preview labeled "GitBook - metalbear.com".

Changes to content and basic structure are possible in the repo, and other changes must be made via the GitBook platform. To do so, you will need access to the MetalBear organisation.

When changing the structure of the docs, like creating a new page, you must update ./docs/SUMMARY.md to reflect this. New folders should have a README.md as their overview page.

GitBook Copy Section

Each tab on the docs site corresponds to a GitBook "space". Adding a space is done through GitBook, and GitHub sync must be set up to sync changes between the space's repo and the website. Note that changes made in GitBook may be live.

File: docs/faq/comparisons.md Copy Chapter

title: "Comparisons"
date: 2020-11-16T13:59:39+01:00
lastmod: 2020-11-16T13:59:39+01:00
draft: false
images: []
menu:
docs:
parent: "faq"
weight: 130
toc: true

tags: ["oss", "team", "enterprise"] Copy Chapter

Why not just use a remote debugger? Copy Chapter

When you use a remote debugger, you still have to deploy new code to the cluster. When you plug local code into the cloud with mirrord, you don't have to wait for cloud deployment. Using mirrord is also less disruptive to the cluster, since the stable version of the code is still running and handling requests.

Why not just run a copy of the cluster on my machine with e.g. minikube? Copy Chapter

Our assumption is that some environments are too complex to run wholly on your local machine (or their components are just not virtualizable). If that's the case with your environment, you can only run the microservice you're currently working on locally, but connect it to your cloud environment with mirrord. Note that mirrord can also be used to connect your non-containerized process to your local Kubernetes cluster.

How is mirrord different from Telepresence? Copy Chapter

mirrord can be a great alternative to Telepresence. The main differences are:

• mirrord works on the process level, meaning it doesn't require you to run a "daemon" locally and it doesn't change your local machine settings. For example, if you run another process, it won't be affected by mirrord.
• This means that you can run multiple services at the same time, each in a different context and without needing to containerize them.
• mirrord doesn't require you to install anything on the cluster.
• mirrord duplicates traffic and doesn't intercept/steal it by default.
• mirrord can be run through one of our IDE extensions: we support JetBrains IDEs and VS Code.

More details can be found in this GitHub discussion.

File: docs/faq/general.md Copy Chapter

title: General
date: 2020-11-16T12:59:39.000Z
lastmod: 2020-11-16T12:59:39.000Z
draft: false
images: []
menu:
docs:
parent: faq
weight: 110
toc: true
tags:

• oss
• team
• enterprise

What does mirrord actually do? Copy Chapter

First and most important, mirrord doesn't just mirror traffic. It does that, but also a lot more.

mirrord lets you connect a process on your development machine to your Kubernetes cluster. It does this by injecting itself into the local process (no code changes needed!), intercepting all of the input and output points of the process - network traffic, file access, and environment variables - and proxying them to the cluster. This mechanism is discussed in more detail here.

When you run mirrord, you select a Target - this is the Kubernetes Pod or Deployment whose context you want your local code to run in. For example, if you have a staging cluster running the latest stable version of all of your microservices, and you're now coding the next version of one of these microservices, you'd select as your Target the Pod or Deployment running the stable version of that microservice in staging. The following things will then happen:

• The Target's environment variables will be made available to the local process.
• When the local process tries to read a file, it will be read from the Target's filesystem instead.
• Traffic reaching the remote Target will reach your locally running process (this incoming traffic can either be mirrored, intercepted entirely, or intercepted based on a filter you define).
• Traffic sent out from your local process will be sent out from the Target instead, letting it reach any endpoint that's accessible to the Target, and the response will be sent back to your local process.

By proxying all of your local process' input and output points in this way, mirrord makes it "think" it's running in the cloud, which lets you test it in cloud conditions:

1. Without having to run your entire architecture locally
2. Without going through lengthy CI and deployment processes
3. Without deploying untested code to the cloud environment - the stable version of the code is still running in the cluster and handling requests - letting multiple users test on the same cluster without queueing to use it or breaking the cluster for everyone else.

Ready to try it? Get started in under 2 minutes with the Quick Start guide.

Is mirrord free? Copy Chapter

mirrord is free and open source (MIT License). Our paid offering, mirrord for Teams, includes a Kubernetes operator that acts as a control plane for mirrord. You can read more about it here.

Can I intercept traffic instead of duplicating it? Copy Chapter

Yes, you can use the --steal flag to intercept traffic instead of duplicating it.

Does mirrord install anything on the cluster? Copy Chapter

No, mirrord doesn't install anything on the cluster, nor does it have any persistent state. It does spawn a short-living pod/container to run the proxy, which is automatically removed when mirrord exits. mirrord works using the Kubernetes API, and so the only prerequisite to start using mirrord is to have kubectl configured for your cluster.

If you have any restrictions for pulling external images inside your cluster, you have to allow pulling of ghcr.io/metalbear-co/mirrord image.

How does mirrord protect against disrupting my shared environment with my local code? Copy Chapter

• By letting you mirror traffic rather than intercept it, the stable version of the code can still run in the cluster and handle requests.
• By letting you control which functionality runs locally and which runs in the cloud, you can configure mirrord in the way that's safest for your architecture. For example, you can configure mirrord to read files and receive incoming traffic from the cloud, but write files and send outgoing traffic locally. Our main goal in future versions of mirrord is to reduce the risk of disruption of the shared environment when using mirrord. This will be achieved by providing more granular configuration options (for example, filtering traffic by hostname or protocol), and advanced functionality like copy-on-write for databases.

Can I use mirrord to run a local container, rather than a local process, in the context of the remote Kubernetes cluster? Copy Chapter

Yes! You can use the mirrord container command to run a local container in the context of the remote Kubernetes cluster. You can read more about it here.

What if I can't create containers with the capabilities mirrord requires in my cluster? Copy Chapter

mirrord works by creating an agent on a privileged pod in the remote cluster that accesses another pod's namespaces (read more about it here). If you can't give your end users permissions to create pods with the capabilities mirrord needs, we suggest trying out mirrord for Teams. It adds a Kubernetes operator that acts as a control plane for mirrord clients, and lets them work with mirrord without creating pods themselves. If mirrord for Teams doesn't work for you either, let us know and we'll try to figure a solution that matches your security policies.

What kinds of Kubernetes objects can I use as a remote target? Copy Chapter

mirrord OSS supports the following Kubernetes objects as targets:

• Pods
• Deployments
• Argo Rollouts

In mirrord OSS, mirrord will always target a random pod when a workload with multiple pods is used as the remote target.

mirrord for Teams adds support for the following workloads:

• Jobs
• CronJobs
• StatefulSets

mirrord for Teams also supports targeting:

• Services
• Labels

In mirrord for Teams, mirrord will always target all pods when a workload with multiple pods is used as the remote target.

Both in mirrord OSS and mirrord for Teams, if you don't name any specific container to be targeted, mirrord will pick the first container from the pod spec. Some containers, like service mesh proxies, will be automatically ignored.

If the target deployment restarts or is recreated in Kubernetes, will mirrord’s traffic stealing stop working? Copy Chapter

No, everything will continue working as expected if you’re using the mirrord Operator. When the target deployment is redeployed or scaled, mirrord reconnects to the new pods, so you don’t need to restart anything. If you’re not using the Operator in your cluster, you’ll need to restart your local app with mirrord to reconnect to the new pods.

How mirrord Handles Secrets and In-Memory Application State Copy Section

mirrord mirrors environmental inputs of your Kubernetes workload, such as environment variables, mounted files, and network access, but it does not copy or replicate the in-memory state of a running pod. This means any data your application loads and caches during runtime (including secrets fetched from external providers like AWS) is not transferred to your local process.

When you run your service locally with mirrord, your application starts from the same inputs as the in-cluster version. If your application’s startup logic fetches secrets from AWS and then caches them in memory, the local version will run that same logic and fetch the secrets again. mirrord’s job is to provide your local process with the same environment and the same access paths, not to copy running state from the remote process.

If you prefer to avoid calling external secret providers during local development, you will need to mock or override that behavior within your application. mirrord does not intercept or alter application logic related to secret retrieval, and it does not supply cached in-memory data from remote pods.

File: docs/faq/limitations.md Copy Chapter

title: Limitations
date: 2020-11-16T12:59:39.000Z
lastmod: 2020-11-16T12:59:39.000Z
draft: false
images: []
menu:
docs:
parent: faq
weight: 120
toc: true
tags:

• oss
• team
• enterprise

What frameworks/languages does mirrord support?

mirrord works by hooking libc, so it should work with any language/framework that uses libc (vast majority).

This includes: Rust, Node, Python, Java, Kotlin, Ruby, and others (most languages use libc).

mirrord also supports Go, which doesn't use libc

Does mirrord support clusters with a service mesh like Istio or Linkerd?

Yes, mirrord works exactly the same way with and without a service mesh installed.

Does mirrord support OpenShift?

Yes, mirrord works with OpenShift. However, OpenShift usually ships with a default security policy that doesn't let mirrord create pods. To fix this, you would need to tweak your scc settings - more information here. If you'd rather keep the default security policies, we recommend trying out mirrord for Teams.

Does mirrord support Teleport, Tailscale, or other secure cluster access tools?

Yes, and there's nothing to configure.

mirrord reaches your cluster entirely through the Kubernetes API, using the same kubeconfig kubectl uses. That covers everything it does: the mirrord Operator is exposed as a Kubernetes APIService, and the connection to the mirrord agent runs over Kubernetes port forwarding. mirrord never opens a network path of its own.

If kubectl works through your access provider, mirrord works through it too. Customers run mirrord behind Teleport and Tailscale today.

Does mirrord support binaries that are statically compiled? (Linux)

No, mirrord needs to be able to leverage dynamic linking in order to work. This means static binaries are not supported.

To check a binary, you can use the file <FILE_NAME> command - dynamically linked binaries will look like this:

marvin@heart-of-gold:~$ file /usr/bin/ls
/usr/bin/ls: ELF 64-bit LSB pie executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, BuildID[sha1]=36b86f957a1be53733633d184c3a3354f3fc7b12, for GNU/Linux 3.2.0, stripped

And static binaries will look like this:

marvin@heart-of-gold:~/MetalBear$ file some_static_binary 
some_static_binary: ELF 64-bit LSB executable, x86-64, version 1 (GNU/Linux), statically linked, BuildID[sha1]=2e1eda62d5f755377435c009e856cd7b9836734e, for GNU/Linux 3.2.0, not stripped

Sometimes, Go is statically compiled by default, so it's important to check and compile dynamically if necessary. See this section in Common Issues for more info.

File: docs/getting-started/onboarding-wizard.md Copy Chapter

title: Onboarding wizard
date: 2026-01-05T12:00:00.000Z
lastmod: 2026-01-05T12:00:00.000Z
draft: false
toc: true
tags:

• oss
• team
• enterprise

Onboarding Wizard

The mirrord onboarding wizard is designed to make getting started with mirrord easier and faster. It does this by taking you through the basics of mirrord and some commonly used features, and then lets you create and download your first mirrord configuration file via the UI.

{% hint style="info" %}
This feature is available in mirrord version 3.178.0 and onwards.
{% endhint %}

Launching the wizard Copy Section

Starting the wizard will open a locally hosted webapp in your browser. To launch the wizard, install mirrord and run the following command:

mirrord wizard

Make sure that you are connected (and if necessary signed in) to your cluster and that if you are using the operator, it is set up properly. If you do not, the wizard will not be able to list targets or suggest ports for network configuration.

Learning overview

As a new user, you may want to learn some mirrord basics before jumping into creating a configuration file. You can do this from the wizard landing page, by leafing through the overview before getting to the configuration options.

Creating a configuration Copy Section

There are four parts to configuration creation:

1. Boilerplate selection
2. Target configuration
3. Network configuration
4. Export

Boilerplate selection

There are three options for boilerplate configurations that you can choose between. The differences between them are explained in more detail in the overview steps.

Note that using "Replace" mode requires the operator (not available in OSS).

Target configuration

Select a target from a given namespace in your cluster, optionally filtering by specific types (this can be helpful if there are a lot of resources in your cluster). Target selection is required in the wizard (targetless configurations are not yet supported).

If there are namespaces or resources missing, it could be that there is an issue with your connection to the cluster, or that the resources require the operator and you are using OSS.

Network configuration

Optionally configure traffic filters and/or ports.

Traffic filters

Here, you can set header or path filters for traffic. Strings are RegEx by default, but selecting "Exact" matching from the dropdown will enable exact matching instead.

If you set multiple filters, you can choose how to combine them: "Any" will filter traffic that matches one or more of the filters (logical OR), whereas "All" will filter traffic that matches every filter (logical AND).

Ports

Here, you can configure specific ports that you are interested in mirroring or stealing. Ports that are exposed in the resource definition of your target will be added automatically, but you can remove these or add your own.

Additionally, if you wish to map ports that differ on the local and remote, you can do so by editing the remote port for the corresponding entry in the list.

Export

Preview and download (or copy to clipboard) the configuration file according to the options you have set in the previous steps. To use a configuration file in the CLI, use the -f <CONFIG_PATH> flag. Or if using VSCode Extension or JetBrains plugin, simply create a .mirrord/mirrord.json file or use the UI.

File: docs/getting-started/quick-start.md Copy Chapter

title: Quick Start
date: 2020-11-16T12:59:39.000Z
lastmod: 2020-11-16T12:59:39.000Z
draft: false
images: []
menu:
docs:
parent: overview
weight: 105
toc: true
tags:

• oss
• team
• enterprise
  shallowToc: true

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 Copy Chapter

{% tabs %}
{% tab title="CLI (macOS/Linux)" %}

brew install metalbear-co/mirrord/mirrord

or:

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

{% endtab %}

{% tab title="CLI (Windows)" %}

choco install mirrord

{% endtab %}

{% tab title="VS Code / Cursor / Windsurf" %}

Extensions → search mirrord → Install.

Works with all VS Code forks (Cursor, Windsurf, Antigravity, PearAI, Trae).

You can also download it from the VS Code Marketplace.

{% endtab %}

{% tab title="JetBrains" %}

Preferences → Plugins → search mirrord → Install.

Works with IntelliJ, GoLand, PyCharm, and other JetBrains IDEs.

You can also download it from the JetBrains Marketplace.

{% endtab %}
{% endtabs %}

Try it Copy Chapter

CLI Copy Section

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 Copy Section

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.

{% hint style="success" %}
Send a request to your remote target — you should see it arriving at your local process as well!
{% endhint %}

What just happened? Copy Chapter

By default, mirrord does the following:

Your remote pod continues running normally — nothing is disrupted.

{% hint style="info" %}
Working with a team? mirrord for Teams adds access control, traffic policies, and concurrent session management so your whole team can use mirrord safely.
{% endhint %}

Configuration Copy Chapter

mirrord reads config from /.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.

{% hint style="info" %}
The IDE extensions provide autocomplete for mirrord config files.
{% endhint %}

Next Steps Copy Chapter

What are you trying to do?

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

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

File: docs/getting-started/what-is-mirrord.md Copy Chapter

title: What is mirrord? Copy Chapter

What is mirrord?

mirrord lets developers (or AI agents) run local code in the context of their cloud environment. Your code runs on your machine, but talks to real cloud services - databases, queues, APIs - as if it were deployed in the cluster.

When you start your process with mirrord, it overrides low-level system calls to:

• Receive incoming traffic from a remote pod (mirrored or stolen)
• Send outgoing traffic through the remote pod, reaching cluster-internal services
• Read and write files on the remote file system
• Import environment variables from the remote pod

mirrord runs in two places: a thin layer injected into your local process (mirrord-layer), and an agent pod in the cluster (mirrord-agent) that handles the remote side.

No VPN, no root access, no deployment. Your local process behaves as if it's running inside the cluster, but you keep your local tools, debugger, and IDE.

For the full architecture, see the Architecture reference.

Try mirrord now — it takes less than 2 minutes. Follow the Quick Start guide to run your first local process in a cloud context.

{% hint style="info" %}
Using an AI coding agent? See Using mirrord with AI agents to set up autonomous testing against your cluster with Claude Code, Cursor, Codex, and more.
{% endhint %}

The same model powers mirrord for CI — running integration and end-to-end tests against a shared staging cluster without spinning up a dedicated test environment. See mirrord for CI.

mirrord for Teams Copy Section

mirrord's core functionality is free and open source. Individual developers can install it and start using it immediately.

mirrord for Teams adds the mirrord Operator - a Kubernetes operator that runs in your cluster and acts as a centralized control plane. It enables:

• Concurrent usage - Multiple developers can work on the same cluster without conflicts
• Traffic filtering - Route only specific HTTP requests to your local process using header, path, or method filters
• Queue splitting - Split message queue traffic so each developer gets their own messages
• DB branching - Ephemeral database branches per developer session
• Policies and profiles - Admins can define rules and standardize mirrord configuration across the team
• Session management - View and manage all active mirrord sessions in the cluster

Features marked with [Teams] in these docs require a mirrord for Teams license.

mirrord for Enterprise Copy Section

The Enterprise plan adds:

• Preview Environments - Deploy isolated, ephemeral pods in the cluster for async review and QA
• mirrord for CI - Run integration and end-to-end tests against a shared staging cluster without spinning up a dedicated test environment
• Multi-cluster - Intercept traffic across multiple clusters in a single mirrord session
• Air-gapped operation - Run the License Server on-prem to manage seats without sending telemetry to MetalBear
• High availability - Run the Operator in HA mode
• Premium support

See pricing for details.

File: docs/installing-mirrord/cli.md Copy Chapter

title: CLI Copy Chapter

The mirrord CLI is the core tool for running mirrord from the command line.

Installation Copy Chapter

{% tabs %}
{% tab title="MacOS/Linux" %}

To install the CLI, run:

brew install metalbear-co/mirrord/mirrord

or

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

{% endtab %}

{% tab title="Windows" %}
To install the CLI, run:

choco install --pre mirrord

{% endtab %}
{% endtabs %}

Usage Copy Chapter

To use mirrord to plug a local process into a pod/deployment in the cluster configured with kubectl, run:

mirrord exec --target <target-path> <command used to run the local process>

For example:

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

Use mirrord --help to see all available commands.

Configuration Copy Chapter

mirrord is configured using a JSON or YAML configuration file. The CLI reads its configuration from this file — by default, it looks for .mirrord/mirrord.json in the current directory. You can specify a different configuration file with the -f flag:

mirrord exec -f my-config.json --target pod/app-pod python main.py

Configuration options are documented in the configuration reference.

Interactive Setup Copy Chapter

You can use mirrord wizard to generate a mirrord.json configuration file interactively. This walks you through common use cases and helps you create a configuration tailored to your needs. See the Onboarding Wizard for more information.

Listing Targets Copy Chapter

To see available targets in your cluster:

mirrord ls

This will list all pods, deployments, and other resources that mirrord can target.

Verifying Installation Copy Chapter

To verify mirrord is installed correctly:

mirrord --version

To check connectivity to your cluster and the mirrord Operator (if using mirrord for Teams):

mirrord operator status

{% hint style="info" %}
Got it working? Stuck? Either way, come say hi in Slack
{% endhint %}

File: docs/installing-mirrord/intellij.md Copy Chapter

title: JetBrains IDEs Copy Chapter

JetBrains IDEs

If you develop your application in one of the JetBrains' IDEs (e.g PyCharm, IntelliJ or GoLand), you can debug it with mirrord using our JetBrains Marketplace plugin. Simply:

1. Download the plugin
2. Enable mirrord using the toolbar button (next to "mirrord" popup menu)
3. Run or debug your application as you usually do

{% hint style="info" %}
The plugin runs natively on Windows since mirrord-intellij 3.73.0 for these scenarios: Rider Run + Debug, IntelliJ IDEA Build-System Run + Debug, and IDEA Gradle/Maven Build-System Run + Debug. Other run configurations on Windows still require WSL.
{% endhint %}

When you start a debugging session with mirrord enabled, you'll be prompted with a target selection dialog. This dialog will allow you to select the target in your Kubernetes cluster that you want to impersonate.

Note: For some projects, the plugin might not be able to present the target selection dialog.

When this happens, you'll see a warning notification and the execution will be cancelled. You can still use mirrord, but you'll have to specify the target in mirrord config.

This is known to happen with Java projects using the IntelliJ build system.

The toolbar button enables/disables mirrord for all run and debug sessions.

mirrord's initial state on startup can be configured in the plugin settings (Settings -> Tools -> mirrord -> Enable mirrord on startup)

Enabling/disabling mirrord for a specific run configuration Copy Section

mirrord can be persistently enabled or disabled for a specific run configuration, regardless of the toolbar button state. This is controlled via the MIRRORD_ACTIVE environment variable in your run configuration.

To have mirrord always enabled for the given run configuration, set MIRRORD_ACTIVE=1 in the run configuration's environment variables. To have mirrord always disabled, set MIRRORD_ACTIVE=0.

In some cases, mirrord will not run for a specific run configuration regardless of if it is enabled or not. This may occur when the run configuration is a build task, a Tomcat task, or a Gradle task with "build" in the name. If required, this behaviour can be overridden by setting MIRRORD_FORCE_RUN=true in the run configuration's env vars. Note that mirrord must still be enabled to run, with either MIRRORD_ACTIVE or the toolbar button.

Selecting session target Copy Section

mirrord's target can be specified in two ways:

1. with the target selection dialog
   • The dialog will only appear if the mirrord config does not specify the target.
   • The dialog will initially show targets in the namespace specified in the mirrord config (.target.namespace). If the namespace is not specified, your Kubernetes user's default namespace will be used.
   • If you want to see targets in a different namespace, there is a dropdown to choose between namespaces.
2. in the mirrord config's target section

Using the mirrord config Copy Section

The plugin allows for using the mirrord config. For any run/debug session, the mirrord config to be used can be specified in multiple ways:

Active config

The toolbar dropdown menu allows for specifying a temporary mirrord config override. This config will be used for all run/debug sessions.

To specify the override, use Select Active Config action.

You will be prompted with a dialog where you can select a mirrord config from your project files. For the file to be present in the dialog, its path must contain mirrord and end with either .json, .yaml or .toml.

You can remove the override using the same action.

Config for run configuration

If no active config is specified, the plugin will try to read the config file path from the MIRRORD_CONFIG_FILE environment variable specified in the run configuration.

This path should be absolute.

Config from default path

If the config file path is not specified in the run configuration environment, the plugin will try to find a default config.

The default config is the lexicographically first file in /.mirrord directory that ends with either .json, .yaml or .toml.

Managing the mirrord binary Copy Section

The plugin relies on the standard mirrord CLI binary.

By default, the plugin checks the latest release version and downloads the most up-to-date binary in the background. You can disable this behavior in the plugin settings (Settings -> Tools -> mirrord -> Auto update mirrord binary).

You can also pin the binary version in the plugin settings (Settings -> Tools -> mirrord -> mirrord binary version).

WSL Copy Section

The guide on how to use the plugin with remote development on WSL can be found here.

File: docs/installing-mirrord/README.md Copy Chapter

title: Installing mirrord Copy Chapter

mirrord can be installed and used in several ways depending on your development workflow:

• CLI - Install the mirrord command-line tool directly
• VS Code - Install the mirrord extension for Visual Studio Code and compatible editors (Cursor, Windsurf, etc.)
• JetBrains IDEs - Install the mirrord plugin for JetBrains IDEs (IntelliJ, PyCharm, GoLand, etc.)

mirrord runs natively on Windows — no WSL needed. If you still prefer to use WSL, see our WSL setup guide.

Local Requirements Copy Chapter

For your local machine, you may use any of:

• MacOS (Intel, Apple Silicon)
• Linux (x86_64)
• Windows (x86_64), WSL (x86_64)

kubectl needs to be configured on the local machine.

mirrord Operator Copy Chapter

If you're planning to use mirrord for Teams, you'll also need to install the mirrord Operator in your cluster. See the mirrord Operator page for installation instructions.