Documentation menu
Dashboard & analytics
Managed runners
Team & notifications
Billing & plans
Workflow files
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
- AI Scan analyzes your workflows and proposes a right-sized configuration with its own
latchkey-<name>label. - Image builds typically take 10-15 minutes; typical result is 30-50% faster builds, because nothing has to install at job start.
- Jobs targeting the new label queue until its image build completes; you are notified when it is ready.
- Limits: 2 on Developer and Launch, 10 on Scale, unlimited on Enterprise; custom runners bill at the xlarge rate ($0.0200/min).
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.
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.
- 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
- 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#
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:
| Bucket | What it means |
|---|---|
| Already in base AMI | The tool ships on every Latchkey runner image, version pinned. Nothing extra to install. |
| Will be added to your runner | The tool gets baked into your custom image, with an estimated build time in minutes shown. |
| Kept in workflow YAML | Latchkey 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.
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.
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#
| Aspect | Rule |
|---|---|
| Label | latchkey-<name>: lowercase letters, digits, hyphens; must not collide with the preset names |
| Shape | CPU/memory profiles across general, compute, and memory-optimized families |
| Disk | 100 to 500 GB |
| How many | Developer and Launch: 2 custom configurations, Scale: 10, Enterprise: unlimited |
| Billing | Custom 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#
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.