# Quick Start

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.](/mirrord/docs/reference/targets.md)) you want to work with. Linux kernel 4.20+, Docker or containerd runtime.

## Install

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

```bash
brew install metalbear-co/mirrord/mirrord
```

or:

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

{% endtab %}

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

```powershell
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](https://marketplace.visualstudio.com/items?itemName=MetalBear.mirrord).
{% 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](https://plugins.jetbrains.com/plugin/19772-mirrord).
{% endtab %}
{% endtabs %}

## Try it

### CLI

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

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

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

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

Or run a local container instead of a native process:

```bash
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.

{% 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?

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.

{% hint style="info" %}
**Working with a team?** [mirrord for Teams](https://app.metalbear.com) adds access control, traffic policies, and concurrent session management so your whole team can use mirrord safely.
{% endhint %}

## 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](https://metalbear.com/mirrord/docs/config).

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

## 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](/mirrord/docs/using-mirrord/incoming-traffic/filter-incoming-traffic.md) so your local process responds to real requests instead of the remote pod |
| **Debug a queue consumer**        | [Queue splitting](/mirrord/docs/sharing-the-cluster/queue-splitting.md) lets your local process consume messages without competing with the deployed service                |
| **Run a tool in cluster context** | [Targetless mode](/mirrord/docs/using-mirrord/targetless.md) 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](/mirrord/docs/use-cases/using-mirrord-with-ai.md) to test generated code against your cluster automatically                          |
| **Set up for your team**          | Install the [mirrord Operator](/mirrord/docs/getting-started/installing-mirrord/operator.md) for access control, policies, and multi-user support                           |

Need help or want to share feedback? [Join our Slack community](https://metalbear.com/slack)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://metalbear.com/mirrord/docs/getting-started/quick-start.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.