Skip to content
Latchkey home
Documentation menu

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.

In short

  1. AI Scan analyzes your workflows and proposes a right-sized configuration with its own latchkey-<name> label.
  2. Image builds typically take 10-15 minutes; typical result is 30-50% faster builds, because nothing has to install at job start.
  3. Jobs targeting the new label queue until its image build completes; you are notified when it is ready.
  4. Limits: 2 on Developer and Launch, 10 on Scale, unlimited on Enterprise; custom runners bill at the xlarge rate ($0.0200/min).
app.latchkey.dev / acme / runners

The Runners page shows Your runners with 5 configurations. AI scan runners opens the Select repository dialog: Select a monitored repository to scan. AI will analyze the tech stack and generate an optimized runner configuration. acme/web is picked and Scan repository is pressed. The dialog becomes Scanning repository for acme/web and checks off its three stages, Scanning repository, Analyzing tech stack and Generating configuration, as Elapsed reads 4s, then 1m 12s, then 3m 40s, with Run in background below. Scan results follow with Confidence: 87%: the detected tech stack (TypeScript, JavaScript, Node.js, Vitest, tsc, Playwright and npm, each with its confidence), the runner configuration web · AI scan at size medium, and the package resolution: node, git and jq already in the base AMI, playwright-chromium, libnss3 and build-essential to be added (about 6 min to build), and wasm-pack kept in the workflow YAML. Approve & build is pressed and reads Approving. The dialog closes and Your runners shows 6 configurations, the new web · AI scan row (latchkey-web-ai) first Pending build, then Building.

FIG. 3.7-ANothing is created until you press Approve & build. The scan itself takes minutes (the figure skips ahead, as its Elapsed line shows), and jobs on the new latchkey-web-ai label wait until its image goes from Building to Ready.

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.

Stay on a preset
  • A preset's CPU/memory ratio covers the job
  • You want the lowest rate: each preset bills at its own price
  • You are on Launch and want to keep your 2 custom slots free
Go custom
  • No preset ratio fits: for example, high memory with modest CPU
  • The job needs more disk than any preset offers (custom goes to 500 GB)
  • You want a dedicated label for one workload, with its own controls

Custom configurations are also a limited resource on most plans (2 on Developer and 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#

01
Scan
Pick a monitored repo; the AI reads workflows, manifests, and build steps
02
Proposal
A right-sized configuration comes back with a confidence score
03
Approve & build
One click creates the runner and starts the image build
04
Ready
You are notified ("AI scan runner is ready"); the label is live

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 row for each active scan, under Latchkey on GH on the Runners page, tracks it through Queued, Scanning repository, Optimizing workflows, and Ready for review, with View, Review & customize, or, for owners and admins, Approve & build in one press.

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 (Runner configuration): a generated runner name, a recommended size (instance type), the runtimes and versions to preinstall, caches to configure, whether Docker and GPU are enabled, 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:

BucketWhat it means
Already in base AMIThe tool ships on every Latchkey runner image, version pinned. Nothing extra to install.
Will be added to your runnerThe tool gets baked into your custom image, with an estimated build time in minutes shown.
Kept in workflow YAMLLatchkey cannot pre-bake this tool, so it stays as an install step at CI runtime.

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 the runner's detail view lists the failed build under Image builds. The moment the build completes you get the "AI scan runner is ready" notification, and from then on the label behaves like any preset.

app.latchkey.dev / acme / runners

The Your runners panel on the Runners page lists 4 configurations: api · AI scan with a Ready image, and the presets ci-small, ci-medium and release-large, with the foot 3 active, 0 images building. Below it, the scan of acme/web is Ready for review. Approve & build shows a loader and reads Building; the scan row leaves and Your runners lists 5 configurations, the new web · AI scan, latchkey-web-ai, AI scan · 4 vCPU, second, its image Pending build. The image changes to Building and the foot reads 4 active, 1 image building; then the image reads Ready, the foot 0 images building, and a notification says AI scan runner is ready: web · AI scan finished building. You can start using it in your workflows now, with View.

FIG. 3.7-BApproving a scan adds the runner at once, and its Image column shows the build: Pending build, then Building, then Ready. A real build takes 10 to 15 minutes, shortened here; until it is Ready, jobs that name the new label wait in the queue.

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. The AI Scan modal then says so, "Your optimized workflows are ready.", with a View pull request link. 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#

AspectRule
Labellatchkey-<name>: lowercase letters, digits, hyphens; must not collide with the preset names
ShapeCPU/memory profiles across general, compute, and memory-optimized families
Disk100 to 500 GB
How manyDeveloper and Launch: 2 custom configurations, Scale: 10, Enterprise: unlimited
BillingCustom runners bill at the xlarge rate ($0.0200/min)

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#

.github/workflows/integration.yml
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#

When Latchkey releases a new base image, it rebuilds each enabled custom runner with a Ready image on it, keeping the runner's packages, pinned runtime versions, size and settings. The runner keeps serving jobs from its current image until the new one is ready, and the build appears under Image builds. If a rebuild fails, the current image keeps serving and Latchkey tries again, up to three attempts for that base image. Pinned runtime versions change only when you apply a Rescan.

The detail drawer's AI scan source card shows the source repository, when it was last scanned, and a Rescan button. Rescan results come back as a diff: packages added, packages removed, and any change to the recommended size. Apply 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 runner's image builds under Image builds, 10 to a page, with status (Pending, Building, Ready, or Failed), start time, build duration (in Pro), and a line on a rebuild Latchkey started.

Each runner can be renamed, given extra labels, capped with a Max at once 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.

Q.01What does AI Scan do?

It analyses your workflows and proposes a right-sized runner configuration with its own latchkey-<name> label, preinstalling what your jobs actually use. Because nothing installs at job start, the typical result is a 30 to 50 percent faster build.

Q.02How long does a custom runner image take to build?

Usually 10 to 15 minutes. Jobs targeting the new label queue until the build finishes rather than failing, and you are notified when the image is ready, so it is safe to merge the workflow change before the build completes.

Q.03How many custom runners can I have, and what do they cost?

Two on Developer and Launch, ten on Scale, unlimited on Enterprise. Custom runners bill at the xlarge rate of $0.0200 per minute regardless of the size you configure, so the saving comes from shorter jobs, not a lower rate.