initialize already run) baked into a bootable image. A fresh machine that restores from one skips the clone and setup work entirely and starts where your setup scripts finished.
Restoring from a snapshot takes roughly 1–2 seconds. Without one, every fresh machine pays your full setup time: clone plus however long initialize takes. Building a snapshot adds roughly 10–30 seconds on top of your setup scripts’ own runtime, paid once per build instead of once per machine. If your initialize takes five minutes, snapshots are the difference between an agent that starts working immediately and one that spends its first five minutes installing dependencies, on every thread, every task machine, every review.
Snapshots never gate a fresh boot. Missing, stale, disabled, or failed, the fallback is always the same: a fresh machine runs your full setup. A snapshot is a cache of your dev environment, never a second source of truth: your setup configuration stays in charge, and the snapshot just caches the result of running it.
Turning it on
Enable snapshots in the Snapshots section of your project’s Dev environment page, or ask Capy to do it. Enabling doesn’t start a build by itself; the hourly check picks it up on its next pass. Trigger a build immediately from the same page, or ask Capy to build one now. There’s also a test lane that runs the full build without activating the result, useful for validating setup changes while snapshots stay disabled.When snapshots rebuild
Every hour, Capy compares the frozen build input (the selected repositories at their current commits, the active setup version, the machine size) against what the current snapshot was built from. Anything moved, it rebuilds; nothing moved, it doesn’t. In practice that means:- New commits on a selected repository’s base branch trigger a rebuild within the hour.
- Changing setup scripts or machine size triggers a rebuild within the hour.
- Identical input never rebuilds, so a quiet project builds nothing.
- A failed build leaves the previous snapshot serving and is retried on the next hourly pass. Machines fall back to full setup only when there’s no current snapshot at all.
Choosing what goes in
A snapshot contains a selected subset of the project’s repositories, not necessarily all of them. Repositories outside the selection stay in the catalog and clone on demand when a thread needs them; they just don’t get the instant-boot treatment. Selection is validated against the machine’s disk budget using each repository’s size from GitHub, and an over-budget selection is refused up front with a per-repo breakdown rather than failing halfway through a build. Each repository row on the Dev environment page carries an include-in-snapshot switch. A newly added project repository isn’t snapshotted until you select it.Machine sizes and disk tiers
Disk size bakes into the image, so a snapshot serves one disk tier: 64 GB covers Small through Ultra, 128 GB is Hyper, 256 GB is Big Guy. Within a tier, one snapshot serves equal or smaller machines than it was built at; a thread requesting a bigger machine than the snapshot’s baked size falls back to fresh setup rather than silently booting undersized. If your setup size is on a bigger tier, the also snapshot smaller machine sizes option bakes the smaller tiers too, each built at that tier’s largest size.Secrets
Builds receive shared project variables soinitialize can authenticate private registries, and Capy scrubs and verifies every platform-managed secret path before capture; a build that can’t prove the scrub fails. The one hole Capy can’t close is a setup script that writes a secret into the workspace; details in Environment variables and secrets.