# What is Mirage?

Choose where your CI jobs run, compare providers, and control fallback.

Mirage is a router for CI jobs. It connects your GitHub Actions workflows to execution
providers, so you can choose where each job runs, compare providers, and configure fallback.

Your workflows define the builds and tests. Mirage manages their execution routes across
GitHub-hosted runners, your own machines, Cloudflare and Blacksmith. You keep using GitHub Actions for triggers,
pull request checks, logs, artifacts, and secrets.

## One workflow, multiple providers

Choose an execution provider for each job. A workflow can keep some jobs on GitHub-hosted
runners while routing others to your own machines or Cloudflare.

Mirage shows the provider, result, and available timing information for each job. The
[routing guide](https://mirageci.com/docs/routing.md) explains how providers, runner labels, and fallback fit
together.

## Choose, compare, and fall back

- **Choose where a job runs.** Set its runner in the workflow, or onboard an eligible job
  so you can manage its default provider through Mirage.
- **Compare before switching.** Run an extra copy of a completed job on the same commit
  across providers. Review the results and timings, then promote a supported provider
  through a pull request.
- **Configure a fallback.** Try your machines first and use GitHub-hosted runners when local
  capacity or infrastructure is unavailable. Failed tests still fail the check.

Provider support varies. Cloudflare supports direct Linux x64 workflows and comparisons;
it currently has no promotion action or automatic hosted fallback. See
[provider capabilities](https://mirageci.com/docs/routing.md#providers) before choosing a route.

## Choose a starting point

- **Understand the routing model:** start with [Routing and providers](https://mirageci.com/docs/routing.md).
- **Evaluate providers for an existing job:** [compare CI providers](https://mirageci.com/docs/ci-providers.md)
  while keeping the current GitHub-hosted default.
- **Get measured workflow improvements:** [set up automatic CI improvements](https://mirageci.com/docs/ci-improvements.md)
  and optionally use your Claude Code or ChatGPT subscription to generate proposals.
- **Try routing with a Mac and hosted fallback:** follow [Route your first job](https://mirageci.com/docs/quick-start.md).
- **Use a dedicated Linux host:** follow [Set up a Linux host](https://mirageci.com/docs/linux-host.md).
- **Keep a Linux or macOS VM for agent work:** use [Agent VMs on a Mac](https://mirageci.com/docs/agent-vms.md) alongside CI.
- **Use your Proxmox cluster:** [connect Proxmox runners](https://mirageci.com/docs/proxmox.md) for disposable
  Linux QEMU VMs.
- **Use Cloudflare compute:** [connect Cloudflare runners](https://mirageci.com/docs/cloudflare.md) and run a
  compatible Linux x64 job.
- **Manage Mirage from a terminal:** use the [CLI guide](https://mirageci.com/docs/cli.md).

## What you need

Start with a private GitHub repository and permission to install the Mirage GitHub App and
review workflow changes. [Connect GitHub](https://mirageci.com/docs/connect-github.md), then set up the providers
you want to use. Your team may already have shared capacity available.

- **GitHub-hosted runners** use your repository’s GitHub Actions access and billing.
- **Local infrastructure** uses a paired Mirage connector with a ready runner profile for
  the job’s operating system and architecture. The guided setup uses an Apple-silicon Mac.
- **Cloudflare** uses available shared capacity or your own Cloudflare account, without
  requiring a paired Mac.

For a dedicated Linux machine, [install the signed Linux agent](https://mirageci.com/docs/linux-host.md). For a
separate VM per job, use the [Proxmox connector](https://mirageci.com/docs/proxmox.md). See
[the differences in job isolation](https://mirageci.com/docs/security.md) before choosing a host.

Use the hosted router at [mirageci.com](https://mirageci.com). Provider setup and workflow
changes happen in your accounts; Mirage’s server is managed for you.