Security architecture

How Latchkey isolates every CI job: dedicated single-use VMs, no inbound network, ephemeral credentials, encryption at rest and in transit, and the constraints the self-healing agent runs under.

This page is written for a security review. It describes how the runner platform is actually built - the isolation boundary, what leaves the machine, how credentials are handled, and what the self-healing agent is and is not allowed to do. For what the GitHub App can read and write in your repositories, see Security and GitHub permissions.

Isolation: one job, one machine#

Latchkey does not share a machine between jobs. Each job runs on a dedicated EC2 virtual machine (m6a-class, Ubuntu 24.04 LTS) launched for that job. Your job is not a container sharing a kernel with another tenant, and it is not a process on a long-lived shared host.

Single-use is enforced at the GitHub registration layer, not just by convention. Cold-start runners register with a just-in-time configuration, which GitHub accepts for exactly one job. Warm-pool runners register with the --ephemeral flag, which does the same. In both cases the instance is configured to terminate on shutdown, so it cannot be reused even if something goes wrong.

Runner groups are created with visibility: selected and an explicit repository list, so a runner registered for your workspace is only offered jobs from the repositories you enabled.

What runs as root, and why that is contained#

Inside its own VM, your job has full control: the runner user has passwordless sudo and Docker access. That is normal for CI - builds install packages and run containers - and it is safe precisely because the blast radius is one short-lived machine with no inbound network that is destroyed at the end of the job. We would rather state this plainly than imply a sandbox that does not exist.

Network#

Credentials and secrets#

Deploys authenticate to AWS through GitHub OIDC role assumption. There are no long-lived AWS access keys in CI. API keys for the MCP integration are stored as a SHA-256 hash only - the plaintext key is shown once at creation and never persisted.

Encryption#

Build cache isolation#

Cache objects are stored in S3 under a key prefix derived from your organization ID, and the tenant ID is injected by the control plane from the job request - a job cannot claim to be another tenant by setting an environment variable. Objects expire after 14 days.

What leaves the runner#

Two kinds of data leave the machine, and it is worth being precise about the second one.

• Run and job metadata - names, timings, statuses, labels, and the workflow YAML - which powers the analytics and optimization features.
• Failing step output. When a step fails, the self-healing pipeline captures that step's standard output and error (capped at 1 MiB each) and stores it so the failure can be diagnosed and, where relevant, turned into a proposed fix. Retention is 90 days.

How the self-healing agent is constrained#

Self-healing is the part a reviewer should push hardest on, because it is the one component that changes a running job. Here is exactly what it can do.

• It runs as the runner user, not root, as a systemd service.
• It listens on a Unix domain socket with group-restricted permissions. It has no TCP listener and no network surface.
• It is invoked through a shim that only intercepts the runner agent's own step scripts; every other command passes straight through untouched.
• It fails open: if the agent times out, refuses, or errors, the command runs exactly as it would have without Latchkey. A broken healer cannot break your build.

The privileged operations it can perform are allowlisted, not filtered:

What the GitHub App can access#

Every permission below exists to power a specific feature. Grouped by what it is for, rather than as a flat list, so you can see the reason next to the grant.

Changes to your repositories#

Latchkey never pushes to your default branch. Every change is a pull request you review, and the write path is gated three ways:

1. The file path must resolve as editable against a per-repository manifest. Unmatched paths default to not editable - the check fails closed.
2. Pull requests originating from forks are rejected, and a missing fork signal is also rejected rather than assumed safe.
3. A proposed fix must match its failure signature in the captured logs, or it is suppressed.

Operational security#

• Runner images are rebuilt weekly so OS security patches land on the fleet on a schedule.
• The runner instance role is least-privilege, including an explicit deny that narrows an AWS-managed policy's account-wide Parameter Store access down to Latchkey's own runner paths.
• Every mutating administrative action is written to an audit log with operator, action, target, parameters, and result.
• Access to the dashboard and API is authenticated by a JWT authorizer at the API gateway. Workspace roles are Owner, Admin, and Member, with owners protected from removal or demotion.

Data retention#

What Latchkey stores, and for how long.

Disabling a repository stops collection for it. Deleting your workspace removes its data. If you need a specific retention window for your organization, ask and we will talk it through.

Reporting a vulnerability#

Email security@latchkey.dev. Please do not open a public GitHub issue for a security report.