Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-0012: mirrord for edit mode, with Skaffold as the fallback

Status: accepted · Date: 2026-10-13 · Decision makers: James Hebden

Context and Problem Statement

Edit mode lets a developer run their local code against a cluster of production-mode services, so a change doesn’t need a container rebuild. Something has to connect the local process to the cluster: its network, its environment, and its files. The original Caproni project evaluated this in its alpha and chose a primary tool and a fallback.

Decision Drivers

  • A change should take effect without rebuilding or redeploying a container
  • The local process should see the same network and filesystem as the pod it stands in for
  • Programs that mirrord can’t support still need a path

Considered Options

  1. mirrord as the primary reloader, Skaffold as the fallback
  2. Skaffold only
  3. Tilt
  4. Telepresence

Decision Outcome

Chosen option: “mirrord first, Skaffold as the fallback”, because mirrord runs the unmodified local process with the pod’s network, environment, and files, which is the fastest loop, while Skaffold covers cases where mirrord doesn’t work, such as programs that use mmap (the original example was Gitaly’s git processes). The original decision log noted that Tilt wasn’t evaluated, and this ADR doesn’t evaluate it or Telepresence either.

Both are reloader types in the configuration (mirror and skaffold), and xianyun run starts every configured reloader concurrently.

Consequences

Good:

  • Two reloader types behind one registry-shaped interface, so a third can be added without changing run
  • run waits for every reloader before returning, using a JoinSet

Bad:

  • The mirror reloader’s processes can’t run yet: the internal process supervisor stops after its preflight checks (GAP-002), and status fails when a Ready cluster has reloaders
  • run doesn’t prepare or clean up mirror deployment copies, and doesn’t check preconditions (GAP-006)
  • Neither reloader is exposed over MCP, since run doesn’t fit a request and response call

Neutral:

  • mirrord’s own agent runs in the cluster and wasn’t reviewed for the threat model

Implementation Location

  • crates/xianyun-deploy/src/reloader/mirror/mod.rs
  • crates/xianyun-deploy/src/reloader/skaffold/mod.rs
  • crates/xianyun-cli/src/commands/run.rs

More Information

  • Recorded on 2026-10-13 from the Go project’s alpha decision log and the Rust reloader code.
  • Related: FR-006, Edit mode.