FAQ · 53 answers · 6 sections
Frequently Asked Questions
Agents, CLI & MCP
Q.01Which coding agents work with Latchkey?
Claude Code, Cursor, Codex and any other MCP client. Each connects with one Latchkey API key, minted in the dashboard under Settings > API keys and agents. Agents can also call the CLI from a shell after npm install -g @latchkeydev/cli: latchkey run runs a command on a fresh Linux VM against your local working tree, shows the logs live and returns the real exit code.
Q.02Can my coding agent read CI failures from Latchkey?
Yes. When self-heal records a failure it did not fix, Latchkey packs it into a failure bundle for your agent, with secrets scrubbed: the root cause, the failing file and the captured logs, where Latchkey kept them. Generate an API key (lk_live_) under Settings > API keys and agents, add the MCP server to Claude Code, Cursor or any MCP client, and the agent can pull failure bundles, check run status and read the logs of any finished job. Keys are read-only by default, so an agent can read that context but never change your code or account. Actions are opt-in per key: pick the Dispatch access to let it start GitHub Actions workflows, or the CLI runner access to let it run commands on fresh VMs, billed per minute like any other job.
Q.03What tools does the Latchkey MCP server give an agent?
Twenty-eight tools. list_failed_runs, get_failure_bundle, get_run_status and tail_run_logs let an agent find and read CI failures, and list_runs finds the runs of a commit or a pull request, and wait_run follows the runs at a commit, or a pull request's runs at its newest commit, to their end, though not a scheduled run that began after the wait. list_heals and get_heal read the self-heal records of the last 90 days, of every outcome. list_findings lists the open AI Insight findings the AI Insight page shows, and get_finding reads one in full, with the evidence it was computed from. dispatch_workflow starts a GitHub Actions workflow. run_workflow starts a Latchkey CI workflow file on a branch or tag, with its inputs. rerun_run re-runs the jobs of a Latchkey CI run that did not pass, and cancel_run cancels a whole run. run_job, list_jobs, get_job_status, get_job_logs and cancel_job let it run a command on a fresh VM, follow it, read the result or cancel it. set_batch_budget sets or lowers the budget of a batch of jobs, and get_batch reads one batch's budget, spend and jobs. plan_migration, apply_migration and get_migration plan a repository's move to Latchkey CI, open the pull request that adds its workflow files, and say where it stands. list_trial_verdicts reads how a repository's trial runs compared with GitHub Actions. list_latchkey_steps lists the Latchkey steps a workflow file can name, with each version's inputs and their rules. list_environments reads which branches each environment of a repository accepts. validate_workflow checks a changed workflow file without starting anything: its first refusal, or its jobs and the most one run of them can cost. dispatch_workflow, run_workflow, rerun_run, cancel_run, the seven job tools, list_runs, wait_run, validate_workflow, list_environments, list_trial_verdicts and apply_migration only work with a key minted with those permissions.
Q.04What does latchkey watch do?
It polls for the CI failures self-heal recorded but did not fix, and hands the first new one of each job (of each run on Latchkey on GH) to a coding agent: Claude Code by default, or any agent command you pass. Failures that were already open when watch started are not handed off. Any API key can run it, because it reads through the mcp:read scope every key carries.
Q.05How are jobs that an agent starts billed?
Per minute, at the rate of the size they run on, from the same free minutes as your Latchkey CI and Latchkey on GH jobs. The CLI and MCP server are on every plan with no separate fee; they need an active subscription or trial. A batch budget caps what a group of agent jobs can spend, and an API key can lower that budget but never raise it.
Q.06Is it safe to give a coding agent a Latchkey API key?
Keys are created in Settings > API keys and agents, and each carries only the scopes chosen when it was minted. Every key carries mcp:read, which lets an agent read CI failures, run status, self-heal records, the log tail of any completed GitHub Actions job in a repository you enabled, the migration plan of any repository connected to Latchkey CI, and your workspace's AI Insight findings. Running jobs needs jobs:run, reading CLI jobs and the logs of Latchkey CI jobs needs jobs:read, and dispatching workflows is a separate opt-in. Scopes cannot be added to an existing key, any key can be revoked, and Latchkey stores only a hash of each key. Each job runs on its own VM, destroyed when the job ends.
Self-Healing
Q.07What is self-healing?
Self-heal is Latchkey's repair loop for failing CI steps. When a step fails for a transient reason, Latchkey detects it, diagnoses the cause and repairs it on the machine while the job is still running, and the job carries on without a human in the loop. It works the same on Latchkey CI and on Latchkey on GH.
Q.08What types of errors does self-healing catch?
Transient and environmental failures: network issues (registry timeouts and 5XXs from npm, Yarn, PyPI, Docker, Terraform), memory errors (OOM kills, SIGKILL), disk-full errors (ENOSPC), missing tools (command-not-found, installed from a vetted allowlist), and environment or config drift (missing variables, toolchain version mismatches, file-handle limits). Self-heal never changes your code, so a bug in it, like a failing test or a compile error, fails with the original logs when it fails on every try.
Q.09Where does self-heal run?
On every Latchkey CI job and every Latchkey on GH job, on every size, with no setup. Self-heal never runs on a pull request from a fork. On Latchkey CI it also never runs on a step written advisory: skip, a step that can publish and writes no advisory:, or any step of a job that writes advisory: hold or names an environment and writes no advisory:, because running such a step again would repeat what it did.
Q.10Is self-healing enabled by default?
Yes, for new workspaces. Owners and admins can turn it off for the whole workspace in Settings > Self-healing.
Q.11Does self-healing cost extra?
No separate fee. Self-heal runs inside the job, so any time it adds is billed at the same per-minute rate as the rest of the job.
Q.12How does self-heal decide what to do?
It works in stages. A failed step's exit code and log are checked against known failure patterns first, and the simple cases are retried or repaired straight away. What those miss goes to an AI agent that can only take a fixed set of actions, such as installing a system package, freeing disk, setting an environment variable or retrying with backoff, within a time limit. A failed step is re-run at most three times by default.
Q.13What data does the AI agent see, and does it touch my code?
The agent receives stderr, stdout, and the exit code so it can reason about the failure, and it can read files in the job's checkout or in the working tree you uploaded with latchkey run: at most four lookups for each diagnosis and the first 8 KiB of a file. What it reads goes to our AI model provider and is kept in the heal record for 90 days. The agent's actions are bounded to a vetted allowlist; it cannot run arbitrary commands or modify your code.
Q.14Can self-healing fix a problem permanently?
Yes, through heal pull requests. When a successful heal traces back to a structural cause, like a setup step missing from the workflow or a too-low job timeout, Latchkey can open a pull request with the durable fix for you to review and merge. Durable changes only ever arrive as reviewable PRs; self-healing never modifies your code during a run.
Q.15Can I see what self-healing did to my build?
Yes. On Latchkey CI the run page marks each healed step Healed, and Open the heal on the job opens the heal's full report: the verdict, what was wrong, the action taken and, for AI-agent heals, the agent's full transcript. On Latchkey on GH the Runs page marks a healed job Healed, and list_heals and get_heal on the MCP server read its record.
Latchkey CI & Runners
Q.16What is Latchkey?
A standalone CI/CD platform, built for coding agents. You commit a workflow file, and Latchkey queues it, runs every job on a fresh Linux VM, heals transient failures mid-run, keeps the logs and run pages, and reports back to your pull request as checks. Your coding agents drive the same CI through a CLI and an MCP server. Teams that want to keep their GitHub Actions workflows can use Latchkey on GH, our managed runners for GitHub Actions.
Q.17How do I set up Latchkey CI?
Sign up, install the Latchkey GitHub App on your account or organization, and turn the repository on in the dashboard. Then commit a workflow file such as .latchkey/workflows/ci.yml and push. Latchkey runs it on every push and pull request and reports back as GitHub checks: Latchkey for the run, and Latchkey / plan for whether the workflow file compiled. The run of a tag push reports them under names that carry its tag, such as Latchkey tag v1.4.0. When a push of the default branch starts a run at a commit less than four days after a push of another branch, a pull request or a merge group started one there, as at a fast-forward or when a merge queue lands, that run reports them under names that carry its branch, such as Latchkey branch main, and Latchkey on that commit shows another run. Each check links to the run page, with live logs.
Q.18What can a Latchkey workflow file do?
It uses the GitHub Actions workflow shape you already know, with each step written as run: or as a Latchkey step (uses: latchkey/<name>@<version>). It supports jobs, needs, matrix with include and exclude, services, env, secrets, environment, if and timeout-minutes, and it runs on push, pull_request, merge_group, a schedule and workflow_dispatch. Each job sets runs-on: to a size: small, medium, large or xlarge. Checkout is automatic, and Node, Python, Go, Rust and Java are on the image. A job that names an environment waits for an owner or admin to approve the run, unless the environment is set to need no approval. A key Latchkey does not support is refused by name, with its line number.
Q.19What does the workflow file not support yet?
Steps that call a GitHub action with uses:. Latchkey runs only its own steps, written uses: latchkey/<name>@<version>, so write any other step as run:. Latchkey does not run marketplace actions, composite actions or reusable workflows. Git LFS, containers and permissions are not supported yet either, and concurrency: takes no cancel-in-progress: true, because Latchkey never cuts off a running job. For caching, use the latchkey/cache-restore and latchkey/cache-save steps, or install the CLI in a step (npm install -g @latchkeydev/cli) and run latchkey cache restore and latchkey cache save. A workflow that needs any of these can stay on GitHub Actions with Latchkey on GH.
Q.20Where do I see my runs and logs?
On the run page in the Latchkey dashboard, which every GitHub check links to. It shows each job with its needs and skips, the matrix legs, services and healed steps, and per-step logs with search that update live while the job runs. Re-run only what failed from GitHub's Re-run button or the dashboard: a job that passed is not run or billed again unless it needs a job that reruns. Job logs are kept 30 days, and agents read the same logs with latchkey logs or the MCP server.
Q.21What happens when Latchkey, not my code, stops a run?
On Latchkey CI, when Latchkey rather than your code stops a run, the Latchkey check concludes neutral and says why. If the stop is our own error, the Latchkey / plan check turns red so it stays visible. In a run whose checks carry its tag or its branch in their names, those checks do this instead, such as Latchkey branch main and Latchkey branch main / plan. Re-run it from GitHub or the dashboard.
Q.22What is Latchkey on GH?
Latchkey on GH, our managed runners for GitHub Actions, keeps your .github/workflows files as they are. Set runs-on: latchkey-small (or latchkey-medium, latchkey-large or latchkey-xlarge) and the same self-healing VMs run your GitHub Actions jobs, actions included. It needs a GitHub organization. Every plan keeps one warm and three parked latchkey-small runners ready for these jobs, and larger sizes start on demand. AI Scan can also build a custom runner for a repository.
Q.23How do I move a GitHub Actions workflow to Latchkey?
For Latchkey CI, Move CI to Latchkey, under Migrate in the dashboard, plans each pipeline, carries its secrets and opens the pull request that adds the files, then runs both side by side until you switch. An agent can plan the same move with the plan_migration tool, which proposes a .latchkey/workflows file for each pipeline and marks what needs a person. Opening the pull request that adds the files, with apply_migration, needs the repository connected to Latchkey CI. By hand, copy the jobs into .latchkey/workflows/<name>.yml, set runs-on: to a size such as small, and rewrite each uses: step as run: or as a Latchkey step (uses: latchkey/<name>@<version>); Latchkey refuses one unsupported key at a time, by name and line, so you can fix them in order. For Latchkey on GH, keep the workflow and replace runs-on: ubuntu-latest with runs-on: latchkey-small.
Q.24Can I migrate many repositories at once?
On Latchkey on GH, yes. The Migrate Runners tool on the Runners page opens one ready-to-review pull request per repository, for up to 20 repositories at a time. Only runs-on lines are changed; every other line in each file is left byte-identical, and Windows and macOS jobs are left untouched. Nothing changes until your team merges. Moving many repositories to Latchkey CI workflow files is not automated yet.
Q.25Can I switch from another runner provider or self-hosted runners?
Yes. If your workflows run on GitHub Actions, the shortest move is Latchkey on GH: point the runs-on: line at a Latchkey label and leave the rest of the workflow as it is. Dependency caches, Docker layer caching and steps that relied on a machine you managed can need their own change, and the migration guides below cover them for each provider. To have Latchkey run the pipeline itself, commit the same jobs as a Latchkey CI workflow file.
Q.26What machines do jobs run on?
Ubuntu 24.04 on x86_64, in AWS us-east-1, in four sizes: small (2 vCPU, 8 GB), medium (4 vCPU, 16 GB), large (8 vCPU, 32 GB) and xlarge (16 vCPU, 64 GB), with the common toolchains preinstalled. Each job gets its own VM, destroyed when the job ends. Windows, macOS, arm64 and GPU machines are not offered, and Migrate Runners leaves Windows and macOS jobs where they are.
Q.27Is every job isolated?
Yes. Every job runs on its own fresh VM that accepts no inbound connection, and the VM and its disk are destroyed when the job ends, so nothing carries over from one job to the next the way it can on a persistent self-hosted runner. On Latchkey CI the VM clones your repository with a short-lived token scoped to that one repository, and nothing registers with GitHub.
Q.28Are there limits on how long or how many jobs I can run?
Each job runs on its own VM. A Latchkey CI job can set timeout-minutes up to 180 (30 by default), a CLI job runs for up to 3 hours, and a Latchkey on GH runner for up to 4 hours from its start, or up to 8 when the job is still running at 4. Each plan sets how many jobs a workspace can run at once: Developer 20, Launch 40, Scale 80; a trial runs at the Launch number, and jobs past the limit wait in the queue. Enterprise limits are set by contract. If your team needs more concurrency, reach out through support.
Q.29How much does a minute cost?
Jobs bill per minute by size, rounded up per job, with no idle fees, the same on Latchkey CI, Latchkey on GH and agent jobs: small (2 vCPU / 8 GB) is $0.0025 per minute, medium (4 vCPU / 16 GB) is $0.005, large (8 vCPU / 32 GB) is $0.01, and xlarge (16 vCPU / 64 GB) is $0.02. Custom runners bill at the xlarge rate. At GitHub's list prices, that is 52 to 58% less per minute than GitHub-hosted runners. Every plan includes free minutes each month (2,000 on Developer, 4,000 on Launch, 6,000 on Scale), and usage beyond your included minutes is billed at the per-minute rate. Free runner minutes are counted in small-equivalent units: a minute on latchkey-small counts as one, medium as two, large as four, and xlarge or a custom runner as eight, and the included allowance on every plan is unchanged.
Q.30Does Latchkey include caching?
Yes. On Latchkey CI, add the latchkey/cache-restore and latchkey/cache-save steps, or install the CLI in a step (npm install -g @latchkeydev/cli) and run latchkey cache restore and latchkey cache save: the cache is scoped to the repository and branch, other branches read the default branch's cache, and a cache miss or a cache proxy error never fails the job. A job of a run Dependabot started restores the default branch's cache and saves nothing. On Latchkey on GH, use latchkey-dev/cache-action@v1 for dependency caches and latchkey-dev/docker-cache-action@v1 for Docker layers; storage and credentials are pre-provisioned, in the same region as the runner. Dependency caches are kept 14 days; Docker layer caches keep the current cache image and drop replaced layers 7 days after they were pushed.
AI & Insights
Q.31What does Insight do?
Insight reads the jobs Latchkey runs for you and finds cost, reliability and security fixes, such as an oversized runner, minutes spent on failing jobs, a flaky job or an unpinned action. Each finding carries a dollar or time number worked out from your own runs, and an AI model writes the short explanation. Where a finding has a fix, approving it opens the change as a pull request.
Q.32Does Latchkey ever change my code without review?
No. Every repository change Latchkey makes, whether an optimization insight, a heal fix, or a runner migration, arrives as a pull request you review and merge. Nothing lands in your repository without your approval.
Billing & Plans
Q.33What plans does Latchkey offer?
Four plans: Developer at $5/month (1 repository, 2,000 free small-equivalent minutes, 1 seat), Launch at $19/month (up to 10 repositories, 4,000 free small-equivalent minutes, 3 seats included and extra seats at $5/month), Scale at $49/month (up to 40 repositories, 6,000 free small-equivalent minutes, 5 seats included), and Enterprise with custom pricing. Every new workspace starts on the Launch plan, and a person's first workspace starts with a 30-day trial of it.
Q.34Do I need a credit card to start the free trial?
No. A new workspace starts a 30-day trial of the Launch plan, with full feature access and no card. Each person gets one free trial, on their first workspace.
Q.35What counts as a repository on my plan?
Each repository you turn on in the dashboard takes one of your plan's repository slots: 1 on Developer, 10 on Launch, 40 on Scale. Latchkey CI and Latchkey on GH share the same slots. Repositories you have not turned on do not count, and turning one off frees its slot.
Q.36Do you charge for the number of workflow executions?
No. There is no charge per run, per workflow or per check. Minutes are the only metered usage: every plan includes free minutes each month, and usage beyond them bills at the per-minute rate of the size you use.
Q.37Do I need to pay for each developer on my team (per-seat pricing)?
Each plan includes seats: Developer is single-seat with no team members, Launch includes 3 seats, and Scale includes 5. On Launch and Scale you can add seats for $5/month each, so your whole engineering team can access the dashboard and insights.
Q.38What happens if I exceed my plan's repository limit?
To turn on more repositories than your plan allows, upgrade to a larger plan from the billing page in the dashboard, then turn the new repositories on. You can upgrade at any time.
Q.39What happens if I run out of free runner minutes?
Free minutes reset on the first of each calendar month and are counted in small-equivalent units, so a minute on a larger runner spends more of the allowance than a minute on latchkey-small. Once they are used, additional runner minutes are metered at the per-minute rate of the runner size you use. On the trial, once the free minutes are used, Latchkey stops starting jobs until you choose a plan or the minutes reset.
Q.40What happens when the 30-day free trial ends?
The trial is not a subscription, so when it ends nothing is charged and no plan starts on its own. Latchkey stops starting jobs for the workspace, and an owner or admin chooses a plan in the dashboard. If the plan holds fewer repositories than you have turned on, you first choose which ones to keep. Stripe Checkout then asks for a card and charges the plan's first month, and the paid plan starts when you finish. Developer needs a workspace with one member. Ending the trial deletes nothing, and subscribing opens the dashboard again.
Q.41What happens to my data if I disable a repository or cancel?
Disabling a repository removes its knowledge base index and file layout scan and keeps its GitHub Actions run records and AI history stored out of your dashboard rather than deleting them. Canceling your subscription retains your data, so you can pick up where you left off if you come back, and you can request full data deletion at any time.
Q.42Are GitHub Actions free?
For public repositories, yes: standard GitHub-hosted runners are free with no minute limit, and self-hosted runners are free on any repository. For private repositories you get a monthly allowance and pay for what you use beyond it, so "free" depends entirely on whether your code is public. Latchkey bills per minute on every repository, with 2,000 to 6,000 free small-equivalent minutes a month depending on plan.
Q.43What does the GitHub Actions free tier include?
GitHub's published monthly allowance for private repositories is 2,000 minutes on Free, 3,000 on Pro and Team, and 50,000 on Enterprise Cloud, alongside 500 MB to 50 GB of artifact storage by plan and a 10 GB Actions cache per repository on every plan. Public repositories are not metered at all. Figures are from GitHub's billing documentation.
Q.44How much does GitHub Actions cost per minute?
GitHub's published list rate for a standard Linux 2-core x64 runner is $0.006 per minute, billed only on private repositories once the plan allowance is used. Larger runners and other operating systems cost more. A small Latchkey job, on a comparable 2 vCPU / 8 GB Linux VM, is $0.0025 per minute.
Q.45How much do self-hosted GitHub Actions runners cost?
GitHub charges nothing for self-hosted runners, so the per-minute line disappears and the cost moves to your cloud bill and your engineers: instances that idle between jobs, AMI patching, autoscaler tuning, and a security review of machines that check out your source. Price the engineer-days alongside the instance-hours; that total is what a managed CI platform competes with, not the zero on the GitHub invoice.
Q.46Can I buy more GitHub Actions minutes?
Yes. Once the plan allowance is used, GitHub bills additional minutes at its published per-minute rate against a spending limit you set, so the bill scales with usage rather than stopping the build. Another option is to run those jobs on Latchkey, from $0.0025 per minute: commit them as a Latchkey CI workflow file, or keep the workflow and change its runs-on: line with Latchkey on GH.
Technical & Security
Q.47Does Latchkey support GitHub personal accounts?
Yes, for Latchkey CI: connect a personal account, select the repository in the dashboard, commit a workflow file under .latchkey/workflows/ and push. Latchkey on GH (Latchkey's managed runners in GitHub Actions) needs a GitHub organization that owns the repositories.
Q.48Does Latchkey store my source code?
Your code passes through Latchkey to run, and some of it is kept. On Latchkey CI each job clones your repository onto its own VM, which is destroyed when the job ends. latchkey run uploads your working tree as the job's context, deleted when the job ends, or by a 2-day expiry if that deletion fails. A cache entry a job saves is kept 14 days, and an artifact a job uploads with latchkey artifact 7 days after upload. The outputs a job records when it succeeds, the values its steps write for the names its workflow file lists, are kept until you delete the workspace. Job logs are kept 30 days. When self-heal writes a heal record for a failing step, the record keeps that step's output, and what self-heal read of your files, for 90 days. From a failed test step, Latchkey keeps the names and files of failing tests for 90 days. For a pull request that runs on Latchkey CI, Latchkey keeps the paths of the files the pull request changes for 90 days. When a workflow fails on Latchkey CI but passes on GitHub Actions at the same commit, while the two run side by side, Latchkey keeps the first line of the failed step's command and the last lines of its output for 180 days. The file contents of proposed fixes are kept 365 days. The GitHub App's only writes to a repository are pull requests that you review and merge.
Q.49How do pull requests from forks run?
On Latchkey CI, a fork's pull request waits until a maintainer approves that exact commit, from the check or the run page, unless its author already has write access. It then runs in a sandbox that can reach only GitHub and the main package registries, with no secrets, no token, no cache and no self-heal. Where the check named Latchkey on its commit reports the jobs of a push to your repository, of a pull request from a branch of it or of a merge group, a fork's pull request shows that check instead and waits for no approval. The workflow file is read from your repository, not from the fork, and forks of private repositories never run. On Latchkey on GH, fork pull requests follow GitHub's own rules.
Q.50How are secrets handled?
On Latchkey CI, add secrets in the dashboard under Settings > Secrets, for the whole workspace, for one repository or for one environment of a repository; an environment value wins over a repository one, and a repository value wins over a workspace one. They are encrypted with a key per workspace and masked in logs, and a step reads one as ${{ secrets.NAME }} in its env:. A job reads an environment's secrets only once its run is approved for that environment, or in a run on its branches when the environment needs no approval. Fork pull requests never receive them. On Latchkey on GH, your GitHub Actions secrets work as they do today.
Q.51Do you support private repositories and GitHub Enterprise?
Yes, Latchkey works with both public and private repositories on GitHub.com. However, on-premise GitHub Enterprise Server instances are not currently supported.
Q.52Can I use the dashboard on mobile?
The Latchkey dashboard is desktop-only for now. Slack and browser push notifications keep you informed away from your desk, but the dashboard itself is built for desktop browsers.
Q.53Do you support GitLab, Azure DevOps, or Bitbucket?
Not yet. Latchkey runs the pipeline itself, and GitHub is the first code host it connects to: your code and pull requests stay where they are, and Latchkey reports back to them. More code hosts are on our roadmap.