Custom runners with AI Scan

Create right-sized runner configurations with their own labels: let the AI scan your workflows and propose the shape, then use the label like any preset.

When the four presets do not fit (a memory-hungry integration suite, a CPU-bound compile), create a custom runner configuration with its own latchkey-<name> label and a shape you choose. The fastest way is the AI Scan on the Runners page.

Preset or custom?#

The deciding factor is shape, not cost tuning. Custom runners bill at the xlarge rate ($0.0200/min) regardless of the shape you choose, so a preset is almost always the cheaper option when one fits. A worked example using the published prices: a test suite that needs 32 GB of memory fits latchkey-large (8 vCPU / 32 GB) at $0.0100/min, while a custom memory-optimized shape with the same 32 GB bills at $0.0200/min. Go custom because no preset ratio works for the job, not to shave a vCPU.

Custom configurations are also a limited resource on most plans (2 on Launch, 10 on Scale, unlimited on Enterprise), so spend them on genuinely distinct workloads rather than minor variants of the same shape. Per-plan counts live in Limits and concurrency.

How AI Scan works#

From the Runners page, click AI Scan Runners and pick one of your monitored repositories; the list is searchable and shows each repo's name, primary language, and whether it is private. Click Scan Repository and progress shows live across three steps (scanning the repository, analyzing the tech stack, generating the configuration) with an elapsed timer.

You do not have to watch it. Run in background closes the modal and the scan keeps running server-side; a progress pill on the Runners page tracks each active scan through Queued, Scanning repository, Optimizing workflows, and Ready for review, with actions to view, review and customize, or approve in one click.

Reading the results#

Results open with the repo name and an overall confidence percentage, the AI's self-assessed certainty about the detection and configuration. The scan is evidence-based: it reads the workflows you actually run, your dependency manifests, and your build steps instead of asking you to guess CPU and memory numbers, and nothing is created until you review and accept. Treat the score as exactly that, a prompt for how closely to look before accepting.

• The Detected Tech Stack section groups findings under languages, frameworks, build tools, and package managers. Each item shows its name, the version when detected, and a confidence badge: High at 80%+ confidence, Medium at 50%+, Low below 50%, each with the exact percentage.
• A monorepo indicator appears when the scan finds one; the runner is sized for the most demanding sub-package.
• Below that is the proposed configuration: a generated runner name, a recommended size, the runtimes and versions to preinstall, caches to configure, environment variables, Docker images to pre-pull, and a plain-English notes summary explaining the choices.

Package resolution#

Before you approve anything, detected packages are sorted into three buckets, so there are no surprises about what the image contains:

Approve and build#

Approve & Build creates the runner and starts building its image; Skip scan results discards the recommendation instead. The runner appears immediately in the Your runners table with a status badge that moves from Pending Build to Building to Ready, and builds typically take 10-15 minutes. If a build fails, the badge shows Failed and you can retry from the runner's detail view. The moment the build completes you get the "AI scan runner is ready" notification, and from then on the label behaves like any preset.

The optimization PR#

Latchkey can also make the workflow change for you. It opens a pull request on your repo that switches workflows to the new runner's label and removes setup steps the image makes redundant, since those tools are already installed when the runner boots. A banner on the Runners page announces the optimized workflows with a View Pull Request button. Typical result after the merge: 30-50% faster builds, because nothing has to install at job start. The PR switches Linux jobs; Windows and macOS jobs are left untouched.

The rules#

One naming suggestion: name the label after the workload, as in latchkey-integration-xl, rather than after the shape. A workload name stays true in the workflow file even if the job's needs change, and it tells the next reader what the runner is for.

Using it#

jobs:
  integration:
    runs-on: latchkey-integration-xl   # your custom label
    steps:
      - uses: actions/checkout@v4
      - run: make integration-test

Everything else behaves like a preset: ephemeral single-job machines, self-healing included, minutes metered against your plan.

Keep the image in sync#

The detail drawer's AI Scan Source card shows the source repository, when it was last scanned, and a Rescan Repository button. Rescan results come back as a diff: packages added, packages removed, and any change to the recommended size. Apply Changes updates the configuration and rebuilds the image; Dismiss leaves everything as it is. If nothing changed, the drawer tells you the runner is already up to date.

Build history and settings#

The detail drawer lists the last 10 image builds with status (pending, building, succeeded, or failed), start time, build duration, and the error message for any failure, so when a build fails you can see why without filing a support ticket.

Each runner can be renamed, given extra labels, capped with a Max Concurrent limit (0 means unlimited), toggled active on or off, or deleted with confirmation. Management actions are available to org roles with manage permissions; everyone else sees the same details read-only.