Skip to content
/
Tier A A8 Cross-runtime harness

mirrord

mirrord · metalbear-co/mirrord · ★ 5.1k · last commit 2026-05-25

Primitive shape 6 total
Skills 6
00

Summary

mirrord — Summary

mirrord is a Kubernetes-native process isolation tool (binary: mirrord, Rust, MIT) that routes a local process's file system, network, DNS, and environment variable access through a target pod in a live Kubernetes cluster — without deploying. It ships as a VS Code extension, IntelliJ plugin, and CLI. For AI coding agents (Claude Code, Cursor, Codex, Copilot, Windsurf), mirrord solves the feedback-loop problem: agents write code against real cluster state (actual env vars, real service responses, live queue contents) and verify code against real cluster services in seconds instead of deploying. The companion metalbear-co/skills repo provides 6 Agent Skills for Claude Code and other agents: mirrord-quickstart, mirrord-config, mirrord-operator, mirrord-ci, mirrord-db-branching, mirrord-kafka. mirrord is not a prompt engineering framework — it is a process-level isolation mechanism that eliminates the need for mock environments when developing against Kubernetes clusters.

Differs from seeds: No seed is architecturally similar — mirrord is a process isolation tool, not a development workflow harness. All 11 seeds modify agent behavior via prompts/hooks; mirrord modifies what the agent's code execution environment can access (real cluster syscalls vs mock). The closest seed by "isolation_mechanism" is none — worktree or container isolation in seeds isolates the agent's file editing, while mirrord isolates the agent's test execution against a live remote environment. The 6 Agent Skills are the only harness-adjacent component; otherwise mirrord is infrastructure.

01

Overview

mirrord — Origin, Philosophy, and Manifesto

Origin

Built by MetalBear, a company focused on developer experience for Kubernetes. Publicly released as open-source (MIT). Version: actively maintained, latest 2026-05-25. 5,089 stars. 30+ contributors. Enterprise mirrord Operator product for team-scale concurrent use.

Problem Statement

From README:

"mirrord runs your local process inside a live Kubernetes cluster. 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."

Core Philosophy

The insight: the feedback loop for Kubernetes development is broken. Developers either:

  1. Deploy to test → 5–8 minute cycle
  2. Mock everything → divergence from production

mirrord eliminates both by making the local process appear to run inside a pod:

  • Incoming traffic mirrored/stolen from target pod to local process
  • Outgoing traffic routed through the target pod
  • File reads/writes go through the pod
  • Environment variables injected from the pod
  • DNS resolved using pod's DNS

AI Agent Value Proposition

From CLAUDE.md:

"mirrord is a tool that lets developers run local processes in the context of their cloud environment."

From README AI agents section:

"Your Kubernetes cluster is full of state that isn't [in the context window]. These skills teach your agent how and when to use mirrord so the code it writes against your live infrastructure stops being informed guessing."

Authorized Adopters

monday.com (350+ engineers on a shared staging cluster), SurveyMonkey, Cadence, CoLab, Daylight Security (cut edit-test cycle from 5–8 min to ~5 sec with Cursor+mirrord), Zooplus.

02

Architecture

mirrord — Architecture, Distribution, and Installation

Distribution

  • CLI binary: mirrord (Rust, MIT)
    • brew install metalbear-co/mirrord/mirrord
    • curl -fsSL .../install.sh | bash
    • Nix, Chocolatey (Windows)
  • VS Code extension: MetalBear.mirrord (VS Code Marketplace)
  • IntelliJ plugin: Plugin ID 19772
  • Agent Skills: metalbear-co/skills repo (separate)
    • claude plugin marketplace add metalbear-co/skills
    • npx skills add metalbear-co/skills

Version analyzed: latest stable (2026-05-25)

Technical Architecture

┌─────────────────────────────────────────────────────────────────┐
│  LOCAL MACHINE                                                  │
│  ┌──────────────────────┐     ┌──────────────────────┐          │
│  │   User Application   │     │      CLI (mirrord)   │          │
│  │  ┌────────────────┐  │     │  - Resolves target   │          │
│  │  │     layer      │  │     │  - Starts intproxy   │          │
│  │  │ (LD/DYLD hook) │◄─┼─────┤  - Provides config   │          │
│  │  └───────┬────────┘  │     └──────────────────────┘          │
│  └──────────┼───────────┘                                       │
│             │ local protocol (TCP/Unix)                         │
│  ┌──────────▼───────────┐                                       │
│  │      intproxy        │  Routes messages between layer/agent  │
│  └──────────┬───────────┘                                       │
└─────────────┼───────────────────────────────────────────────────┘
              │ agent protocol over port-forward/operator tunnel
┌─────────────┼───────────────────────────────────────────────────┐
│  KUBERNETES CLUSTER                                             │
│  ┌──────────▼───────────┐                                       │
│  │        agent         │  Runs in target pod's context         │
│  └──────────────────────┘                                       │
└─────────────────────────────────────────────────────────────────┘

Core Crates (Rust)

  • mirrord-layer: LD_PRELOAD/DYLD_INSERT_LIBRARIES hook, intercepts syscalls (file, socket, DNS, exec), sends to intproxy
  • mirrord-intproxy: routes requests from layer to agent, handles reconnects, per-feature proxy
  • mirrord-agent: runs in Kubernetes cluster, does actual remote work (file ops, network, DNS, env)
  • mirrord-protocol: bincode-serialized ClientMessage/DaemonMessage between components
  • mirrord-config: config types and validation

Agent Skills Repo (metalbear-co/skills)

6 skills for AI coding agents. Separate repo from main mirrord. Each skill is a SKILL.md + optional scripts/ + references/ directory.

Required Runtime

  • kubectl configured with cluster access
  • Linux kernel 4.20+ for the remote agent pod
  • Docker/minikube for local dev (optional)
  • For Operator: Kubernetes RBAC permissions

Config Files

  • mirrord.json — target configuration (feature flags, target pod, namespace)
  • ~/.mirrord/ — user-level config
03

Components

mirrord — Components

CLI Binary: mirrord

mirrord exec <process command> --target <target-path>
mirrord exec node app.js --target pod/my-pod
mirrord ls                          # list available targets
mirrord verify-config /path/to/mirrord.json
mirrord ci start / mirrord ci stop  # CI mode

VS Code Extension

Status bar "Enable mirrord" toggle → start debugging → choose pod to impersonate → debugged process connects to pod via mirrord.

IntelliJ Plugin

Navigation toolbar mirrord icon → start debugging → select namespace and pod.

6 Agent Skills (metalbear-co/skills)

mirrord-quickstart

Zero-to-first-session: install, find target pod, run first mirrord session. Covers CLI, VS Code, IntelliJ installation paths. Security note: never pipe-to-shell installs.

mirrord-config

Generate and validate mirrord.json configuration files. Loads references/schema.json (authoritative JSON Schema) + references/configuration.md at start of each invocation. Schema validation is primary; mirrord verify-config CLI optional extra.

mirrord-operator

Install and configure the mirrord Operator for team-scale concurrent shared-cluster use. RBAC configuration, namespace setup, concurrent session management.

mirrord-ci

Wire mirrord into CI pipelines for testing against real cluster services. Generates GitHub Actions / GitLab CI workflow files. Pre-install mirrord in trusted CI image.

mirrord-db-branching

Per-developer copy-on-write database branches off staging DB. Isolated DB environments without provisioning separate databases.

mirrord-kafka

Kafka queue splitting: each developer consumes a private slice of a real topic. Prevents multiple developers from consuming each other's messages on shared staging topics.

Protocol Layer

mirrord-protocol crate: ClientMessage (layer/intproxy → agent) and DaemonMessage (agent → layer/intproxy) over bincode-serialized TCP. Backward compatibility mandatory (components ship independently).

Operator (Enterprise)

Managed session control, multi-tenant concurrent use, operator-provided connectivity tunnel, RBAC-based access control for who can target which pods.

05

Prompts

mirrord — Prompt Files and Techniques

Prompt 1: mirrord-quickstart SKILL.md — Security-first Install Guidance (Security constraint pattern)

### CLI (recommended for getting started)

**Do not** run remote install scripts that pipe a network download into a shell interpreter. Use only methods your organization approves.

**Official guide:** Follow [mirrord installation documentation](https://mirrord.dev/docs/overview/quick-start/) for supported options (package managers, pinned release binaries with checksum verification, etc.).

**Summary for the agent:**
- **macOS / Linux:** Point the user to the official docs for Homebrew, apt, or pinned binary install steps — do not invent or paste one-liners that fetch and execute remote scripts.
- **Windows:** Point the user to the official docs for supported installers.

> **Security:** Prefer package managers or manually verified binaries from official release artifacts. Never execute installation by piping downloaded content into a shell.

Technique: Explicit security prohibition embedded in install instructions. The skill constrains the agent from generating pipe-to-shell install commands — a common vulnerability in agent-generated setup code. The **Do not** imperative and the > **Security:** callout are high-weight instruction signals. The skill directs the agent to official docs rather than generating install commands, preventing outdated or insecure one-liners.

Prompt 2: mirrord-config SKILL.md — Schema-first Validation (Reference injection pattern)

## Critical First Steps

**Step 1: Load references**
Read BOTH reference files from this skill's `references/` directory:
1. `references/schema.json` - Authoritative JSON Schema
2. `references/configuration.md` - Configuration reference

If using absolute paths, these are located relative to this skill's installation directory. Search for them if needed using patterns like `**/mirrord-config/references/*`.

**Step 2: Check mirrord CLI availability**
If `mirrord` is not available:
- Do NOT run installers, package managers, or remote scripts automatically
- Ask the user to install mirrord themselves via their approved process
- Continue with schema-based validation from `references/schema.json` until CLI validation is possible

Technique: Mandatory reference injection with filesystem search fallback. The skill loads authoritative schema files into context before generating any config. The search pattern (**/mirrord-config/references/*) handles both absolute and relative install paths. CLI unavailability is handled gracefully — schema validation continues without the CLI, preventing the skill from requiring a binary as a hard dependency.

Prompt 3: mirrord-ci SKILL.md — CI Safety Constraints (Environment-aware prohibition)

## Security note for CI examples

- **Do not** use remote pipe-to-shell installs or other unverified script execution in CI to install mirrord.
- Pre-install mirrord in a **trusted CI image**, use your org's **approved** package manager with pinned versions, or follow [official install docs](https://mirrord.dev/docs/overview/quick-start/). The YAML below assumes `mirrord` is already available on the runner unless you add an approved install step.

Technique: Environment-specific security constraint. The CI skill embeds the same security prohibition as quickstart, but scoped to CI environments where unverified script execution has supply-chain implications. The "YAML below assumes mirrord is already available" removes the agent's incentive to generate unsafe install steps.

09

Uniqueness

mirrord — Uniqueness and Positioning

Differs from Seeds

No seed is architecturally similar — mirrord is a Kubernetes process-isolation tool, not a prompt engineering or workflow harness framework. All 11 seeds modify agent behavior via prompts, hooks, or skills; mirrord modifies what the process execution environment can access (real cluster syscalls). The seeds' "isolation_mechanism" dimension (git-branch, git-worktree, container) refers to isolating the agent's file editing workspace; mirrord's isolation refers to routing the agent's test execution through a live cluster environment. Architecturally, the most relevant comparison is with Docker-based isolation in CI pipelines, not with any seed framework. The 6 Agent Skills in metalbear-co/skills are the only harness-adjacent component — and they follow the same SKILL.md format as superpowers (Archetype 1: skills-only), but their purpose is infrastructure setup, not behavioral enforcement.

Positioning

mirrord is unique in this corpus as an infrastructure tool that enables AI coding agents to work against real production-grade environments rather than mocks. The key insight: most AI coding agent frameworks assume the agent generates code that is then tested against a mock or staging environment. mirrord enables testing against the actual running cluster, cutting the feedback cycle from minutes (deploy → test) to seconds (local process in cluster context). The DB branching and Kafka queue splitting capabilities extend this to stateful services that are normally difficult to isolate for individual developer use.

The enterprise Operator product extends single-developer mirroring to team-scale concurrent use, which is the commercial offering on top of the OSS CLI.

Observable Failure Modes

  1. Linux kernel requirement: agent runs on Linux, requires kernel 4.20+. macOS clusters require specific configuration. Windows WSL users must use Linux binary.
  2. RBAC complexity: shared-cluster use requires careful RBAC setup so developers can't access each other's data or disrupt production-bound traffic.
  3. Traffic stealing vs mirroring: stealing traffic from a pod removes it from the pod's processing queue. In team environments without Operator, two developers stealing from the same pod is disruptive.
  4. Protocol compatibility: mirrord-protocol uses bincode serialization; version mismatches between layer/intproxy/agent cause failures. Backward compatibility is "mandatory" per CLAUDE.md — violations cause hard failures.
  5. Not applicable for all workloads: Stateless services benefit most. Stateful services with write side-effects need DB branching or careful scoping.

Explicit Antipatterns

  • Pipe-to-shell installs (security risk; all skills explicitly prohibit this)
  • Testing against production (not staging) without explicit scoping
  • Traffic stealing without Operator in multi-developer teams
04

Workflow

mirrord — Workflow

Developer Workflow

Phase What happens Artifact
1. Configure target mirrord.json specifies target pod, features, namespace mirrord.json
2. Enable mirrord CLI: mirrord exec or IDE: click "Enable mirrord" —
3. Select target Pod picker → choose which pod to impersonate —
4. Process starts mirrord exec node app.js --target pod/my-pod — layer injects, intproxy starts —
5. Local process runs "inside" cluster File reads → remote, network → remote, env vars → from pod, DNS → cluster DNS live cluster context
6. Developer iterates Edit code locally, test against real cluster services immediately —
7. Verify locally Test passes against real services — no deploy needed test results

AI Agent Workflow (with Skills)

Phase What happens
Agent writes code Agent generates code based on task
mirrord-quickstart skill Ensures mirrord installed and target connected
mirrord exec runs code Code executes against live cluster (real env vars, real services)
Real responses received Agent sees actual behavior, not mocked responses
Agent iterates Code adjusted based on real cluster feedback

CI Workflow

Phase What happens
CI job starts Kubernetes access configured
mirrord ci start Connects CI runner to staging cluster
Integration tests run Tests hit real staging services via mirrord
mirrord ci stop Disconnects

Approval Gates

None — mirrord is a transparent proxy. No approval gates; developers control when to enable/disable.

Operator Session Management

Enterprise Operator provides concurrent session management: multiple developers can each impersonate the same pod type simultaneously without traffic conflicts. RBAC controls who can target which pods.

06

Memory Context

mirrord — Memory and Context

Process-level State (not agent state)

mirrord manages network/file/env state at the OS syscall level via LD_PRELOAD/DYLD_INSERT_LIBRARIES. This is not memory in the AI agent sense — it is transparent syscall interception.

mirrord.json Configuration

Persisted project configuration specifying target pod, namespace, feature flags (which syscalls to intercept). Read by CLI and layer at session start.

Skills: References Directory

mirrord-config and mirrord-ci skills load references/schema.json + references/configuration.md into agent context at skill activation. These are static files bundled with each skill — not dynamic memory.

Session State

mirrord-intproxy maintains per-session routing state (fd mappings, socket state, reconnect handling). This exists only for the lifetime of the mirrord exec process.

Cross-session Handoff

No agent-level cross-session handoff. mirrord.json config persists; cluster state (pod content, env vars, queue messages) is live and real — not snapshotted.

Operator Session State (Enterprise)

The mirrord Operator maintains team-level session state for concurrent shared-cluster use — tracking which developers have active sessions targeting which pods.

07

Orchestration

mirrord — Orchestration

Multi-agent

No, for the core mirrord tool. The Agent Skills are single-agent skills (one skill per invocation).

Orchestration Pattern

None for the core tool. mirrord is transparent infrastructure — it doesn't orchestrate agent behavior.

Isolation Mechanism

Process-level isolation via LD_PRELOAD/DYLD_INSERT_LIBRARIES syscall interception. The local process runs in full isolation from the cluster (read-only mirroring by default, traffic stealing for exclusive access). Docker/container isolation is NOT used — mirrord operates at the OS library level.

Multi-model

Not applicable. mirrord is not an LLM framework.

Execution Mode

Event-driven: layer intercepts syscalls; intproxy routes to agent; agent executes in target pod context.

Concurrency

With mirrord Operator (Enterprise): multiple developers can simultaneously connect to the same cluster without traffic conflicts. The Operator manages session coordination.

Without Operator: single user at a time can steal traffic from a given pod (others can mirror, but not steal the same pod).

Kafka Queue Splitting (mirrord-kafka skill)

Each developer gets a private slice of a real Kafka topic. This is explicit partitioning, not isolation in the container/worktree sense — consumers are divided among developers so each sees distinct messages.

08

Ui Cli Surface

mirrord — UI and CLI Surface

Dedicated CLI Binary

Yes. Binary name: mirrord. Written in Rust. Distributed via Homebrew, install script, Nix, Chocolatey.

Key subcommands:

  • mirrord exec <cmd> --target <pod> — run process in cluster context
  • mirrord ls — list available targets
  • mirrord verify-config <path> — validate mirrord.json
  • mirrord ci start / stop — CI mode

VS Code Extension

  • Extension ID: MetalBear.mirrord
  • VS Code Marketplace
  • Status bar "Enable mirrord" toggle
  • Pod picker UI when debugging starts
  • Full debugger integration (breakpoints work in cluster context)

IntelliJ Plugin

  • Plugin ID: 19772
  • JetBrains Plugin Marketplace
  • Navigation toolbar icon
  • Namespace + pod picker dialog

Agent Skills Interface (for AI agents)

The 6 skills in metalbear-co/skills provide the agent-facing surface:

  • Natural language activation (e.g., "I'm new to mirrord" → mirrord-quickstart)
  • Config generation via mirrord-config skill
  • CI setup via mirrord-ci skill

Documentation

Full documentation at metalbear.com/mirrord/docs. CLAUDE.md in main repo provides agent-optimized quick reference for build/test/format commands. mirrord-schema.json in repo root is the authoritative config schema.

Observability

  • TELEMETRY.md documents telemetry data collected (anonymized, opt-out available)
  • mirrord doctor (via quickstart skill) — environment verification
  • mirrord verify-config — config validation

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k
A8 Cross-runtime harness

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k
A8 Cross-runtime harness

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k
A8 Cross-runtime harness

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k
A8 Cross-runtime harness

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k
A8 Cross-runtime harness

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k
A8 Cross-runtime harness

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.