Mirrord Config

Mirrord Configuration Skill

Purpose

Generate and validate mirrord.json configuration files:

• Generate valid configs from natural language descriptions
• Validate user-provided configs against schema
• Fix invalid configurations with explanations
• Explain configuration options and patterns

Security (must follow)

• Never instruct or generate remote pipe-to-shell installs (downloading a script and executing it via the shell) or similar patterns to install mirrord.
• Never embed Homebrew tap install one-liners as mandatory steps; if the user needs the CLI, point them to the official mirrord installation docs and their org’s approved install path.
• Schema validation (references/schema.json) is sufficient; mirrord verify-config is an optional extra when the CLI is already installed locally.

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

# Check if installed
which mirrord

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

Step 3: Validate before presenting After generating any config:

• Validate against references/schema.json first (required)
• Optional: If mirrord is already installed locally, the user may run mirrord verify-config /path/to/config.json for an extra check. Do not treat the CLI as a prerequisite for this skill.
• If validation fails, fix the config and re-validate
• Only present configs that pass schema validation
• Include CLI validation output only when CLI validation was run

Your code is local by default — do not "fix" this with fs.mode

The single most common wrong config. An agent reasons "the app must run my local source, so I need a local filesystem mode" and sets fs.mode to local or localwithoverrides. This is backwards. mirrord already reads your code locally in every fs mode, including the default read.

A built-in local-by-default list applies in all modes (mirrord/layer-lib/src/file/unix/read_local_by_default.rs) and covers:

• The process's current working directory — your entire project tree
• The executable being run
• Runtime and package-manager paths: /node_modules, /package.json, .yarnrc*, .tool-versions
• Source and build artifacts by extension: .js, .py, .pyc, .rb, .jar, .class, .so, .dll, .pdb
• System paths: /usr, /lib, /bin, /etc, /home, /opt, /tmp, /proc, /sys, /dev
• Hidden files under $HOME

So ts-node, nodemon, python -m, go run, dotnet watch etc. all load local source under the default config. No fs setting is needed for that. What fs.mode: "read" gives you on top is the pod's config files, secrets and mounted volumes — which is usually the entire reason to use mirrord.

Consequences of getting this wrong: setting local or localwithoverrides silently cuts the app off from the remote pod's ConfigMaps, mounted Secrets, TLS certs and volumes. The app often still starts, then fails later in a way that looks unrelated to mirrord.

Correct reasons to reach for these modes — all of them are about the remote FS, never about local code:

localwithoverrides reads only /etc/resolv.conf, /etc/hosts and /etc/hostname remotely by default (read_remote_by_default.rs) — plus whatever you add to fs.read_only / fs.read_write. It is a rescue for local mode, not an upgrade to read. If you did not already need local, you do not need localwithoverrides.

Do not add config speculatively

Every key in a generated config must be traceable to something the user actually asked for or a failure they actually reported. Do not add options because they seem prudent, and never present a change as required when it is a guess.

• If a setting is a hypothesis about an unexplained failure (a timeout, a hang, a connection error), say so plainly and say what result would confirm or refute it. Do not write it up as "Needed: Yes."
• Prefer changing one thing at a time over shipping a bundle of plausible-looking settings — a bundle makes it impossible to tell which key mattered.
• Outgoing traffic is already remote by default (network.outgoing.tcp/udp default to true). An outgoing.filter is only correct when the user has stated that a specific destination must be reached from their machine, e.g. a service on their VPN that the cluster cannot route to. Adding a filter does not fix cluster-side timeouts.
• When you cannot justify a key, leave it out. Minimal configs are a hard requirement of this skill, not a stylistic preference.

Request Types

Generate new config

User describes what they want without providing JSON.

• Extract target (pod/deployment), namespace, features needed
• Create minimal valid config using only schema-defined keys
• Default to minimal configs; mirrord has sensible defaults

Validate existing config

User provides JSON to check.

• Parse strictly (catch trailing commas, comments, invalid syntax)
• Validate against schema
• List issues by severity: Errors → Warnings → Suggestions
• Provide corrected version

Modify existing config

User wants changes to their config.

• Validate first, then apply requested changes
• Ensure modifications maintain schema conformance

Response Format