Skip to documentation
MMirageDocs

Execution

Local Mac execution

Learn how Mirage reserves capacity and creates disposable runner VMs.

Execution flow

  1. 1
    GitHub queues attempt 1

    The job enters its repository-scoped mirage-* scale set.

  2. 2
    Mirage validates policy

    Repository, installation, event trust, and immutable job identity are checked.

  3. 3
    The fleet reserves a slot

    One owner-scoped scheduler atomically chooses an eligible targeted Mac.

  4. 4
    The Mac boots a guest

    A one-time JIT configuration starts the official Actions runner inside a fresh VM.

  5. 5
    GitHub assigns the job

    Logs, artifacts, caches, secrets, and results flow directly through GitHub.

Guest boundary

  • Linux jobs run through Apple Containerization in a disposable APFS-cloned VM.
  • Native macOS jobs run in a checksum-verified Tart guest.
  • Guests receive NAT networking and no host workspace or arbitrary filesystem mounts.
  • The exact writable guest is deleted on every terminal path.
  • A cleanup failure sets advertised capacity to zero until recovery succeeds.

Capacity

Linux and macOS profiles share one slot pool. The Mac advertises the lowest safe value derived from its configured VM cap, CPU, memory, disk, power, thermal state, verified assets, and readiness checks.

min(configured cap, CPU budget, memory budget, disk budget)

Policy changes stop new advertisements; an already running job is allowed to finish.

Failure semantics

OutcomeWhat Mirage does
Test command failsAccepts the clean GitHub completion. No replay.
No eligible slotCreates a replay lock and requests attempt 2.
VM or runner failsWaits 30 seconds for a late completion, then replays once.
Mac disconnectsWaits 90 seconds for reconnect, then replays once.
Runner is never assignedFails as infrastructure after two minutes.