On 2026-02-17 Vercel shipped configurable Sandbox snapshot retention, replacing a fixed 7-day expiry with a window that runs from 1 day to never-expire and a new 30-day default. For agent runtimes, the change reframes an auto-managed convenience into a decision: how long to keep a failure state replayable before the snapshot storage meter starts compounding at $0.08/GB-month.
What changed on February 17
The snapshot lifecycle moved from a single hard cap to a configurable window, and the default window got longer. Before the change, snapshots expired after a fixed 7 days. After it, Vercel’s changelog lets you set expiration anywhere from 1 day to infinity, with expiration: 0 meaning a snapshot never expires. The new default is 30 days.
These two defaults are easy to conflate but are different mechanisms. The old 7 days was a fixed expiry you could not tune; the new 30 days is a configurable default you can shorten, lengthen, or remove per snapshot, per sandbox, or via a retention policy. The practical effect is that the thing teams used to assume would clean itself up now requires an explicit stance on how long it should live.
The second-order consequence is that retention posture stops being uniform. Under a fixed 7-day cap, every team had roughly the same snapshot economics and the same debugging window. Under a configurable window, stale-snapshot hygiene becomes an operator responsibility: how long to keep a failure state, how many to keep, and who pays for the ones nobody forks back into. The default is no longer a ceiling everyone shares. It is a starting point each team inherits unless it sets the knobs deliberately.
How do the three retention knobs work?
Retention stacks across three independent layers, and they combine rather than override: a per-snapshot value, a per-sandbox default, and a count-bounding policy. Vercel’s snapshot docs describe each.
The per-call layer is the most granular: pass expiration to snapshot() (or --expiration to the CLI) to set a single snapshot’s TTL, or 0 for no expiration. The per-sandbox layer sets snapshotExpiration, which governs the TTL of automatic snapshots taken on stop. The retention policy, keepLastSnapshots, bounds how many snapshots survive regardless of expiration by keeping only a count of the most recent.
import { Sandbox } from '@vercel/sandbox';import ms from 'ms';
const sandbox = await Sandbox.create();await sandbox.snapshot({ expiration: ms('1d') }); // 1 day; pass 0 to never expire| Layer | What it sets | Scope | Notes |
|---|---|---|---|
Per-call expiration | Single snapshot TTL | One snapshot | 0 = never expire |
Per-sandbox snapshotExpiration | Default TTL | Automatic snapshots taken on stop | Inherited unless overridden |
keepLastSnapshots | Max count kept | All snapshots on the sandbox | Evicts older snapshots past the count cap |
Why do persistent sandboxes quietly inflate your snapshot count?
Because sandboxes are persistent by default and Vercel auto-snapshots every time a session stops, doing nothing still accrues storage. The next session resumes from the most recent snapshot, which is convenient and exactly the behavior that lets count grow without a bound.
This is the trap the retention policy exists to close. With persistent sandboxes snapshotting on each session stop and a 30-day default TTL, a sandbox that runs several sessions a day can accumulate dozens of retained snapshots before any of them age out. keepLastSnapshots is the lever that keeps storage flat by evicting older snapshots past the count cap.
What is the tradeoff for agent runtimes?
Longer retention buys replayable failure states for non-deterministic agent runs; the cost is storage that scales with how many states you keep and for how long. Vercel’s agent framework eve delegates isolated filesystem and command execution to Vercel Sandbox, so a snapshot’s lifetime directly governs how long an agent’s intermediate filesystem and failure state stay replayable after a run ends.
The reproducibility value is specific to agents. A non-deterministic agent loop can fail in a way that depends on the exact filesystem contents, installed package versions, and intermediate state at the moment it broke, conditions that are hard to recreate from scratch. A snapshot captures the filesystem and installed packages for a project (a project-scoped image, not a portable backup), so a retained failure-state snapshot can be forked into a fresh sandbox to reproduce the run. Sandboxes run as Firecracker microVMs, and the same snapshot mechanism powers forking via Sandbox.fork or sandbox fork, which is what makes a retained failure snapshot reusable for reproduction rather than just archived.
The economics are metered. Snapshot storage is $0.08/GB-month on Pro and Enterprise, with Hobby capped at 15 GB lifetime. On Pro, all Sandbox usage draws against a $20/month credit before metered rates apply, and Spend Management can pause a project at a threshold. A team that keeps ten 5 GB failure snapshots around for a month is spending $4 before any compute; a hundred of them is $40, recurring, for state that may never be replayed. The honest question is how many snapshots you will actually fork back into, and how fast. Short retention has its own failure mode: a regression reported days after a run can arrive after the failure snapshot has already aged out, leaving the bug unreproducible. The window has to outlast your reporting latency, not just your debugging cycle.
How does reuse reset the retention timer?
Creating a sandbox from a snapshot resets that snapshot’s expiration clock, so a frequently-reused snapshot stays alive indefinitely while an idle one ages out. Reuse is effectively self-renewing retention.
The lifecycle states reflect this. A snapshot’s status reads created, failed, or deleted; a snapshot that keeps getting forked back into stays created because each create-from-snapshot call resets its timer, while one nobody touches ages toward deleted. The implication for operators is the inverse of the cleanup intuition: you cannot rely on expiration to retire snapshots you are actively using, because using them is exactly what keeps them alive. If you want an actively-reused lineage to actually expire, keepLastSnapshots is the only thing that will evict it past the count cap.
What should you audit first?
Set a keepLastSnapshots policy before anything else, then judge whether the 30-day default is the window you actually need. The retention knobs are permissive enough to let storage grow unbounded, and the defaults are tuned for convenience, not cost control.
- Bound the count. Set
keepLastSnapshotswith a smallcounton every persistent sandbox so session-stop snapshots cannot accumulate without limit. - Review the 30-day default. Decide per sandbox whether 30 days of replayability justifies the storage, and set
snapshotExpirationaccordingly. Failure-state debugging rarely needs a month; golden images you fork repeatedly might. - Pair
expiration: 0with a cap. Never-expire silently waives the only automatic cleanup path. If you need a snapshot to live forever, bound its count too, or expect unbounded growth. - Mind the runtime ceiling. Max Runtime Duration is 45 minutes on Hobby and 5 hours on Pro and Enterprise. Snapshots are how long-running agent work survives across sessions that would otherwise time out, so retention and the runtime ceiling interact: the longer your runs, the more session boundaries cross, and the more snapshots you accrue.
- Set a Spend Management threshold. As a backstop against a misconfigured retention policy, configure Spend Management to alert or pause the project at a dollar threshold rather than discovering the bill on the invoice.
The default window is the thing to audit first because it is the one you get without doing anything. Persistent sandboxes snapshot on every session stop, the default TTL is 30 days, and storage bills for all of it.
Frequently Asked Questions
Does keepLastSnapshots only cap count, or does it carry its own expiry?
The policy keeps the 1 to 10 most recent snapshots and carries its own TTL alongside that count, so the cap is only one of three settings on the knob. A separate deleteEvicted flag controls whether snapshots pushed past the count are deleted or merely dropped from the kept set, which is what determines whether eviction actually reclaims storage.
How is a Vercel Sandbox snapshot different from an EBS snapshot or a container image?
It captures one Firecracker microVM running Amazon Linux 2023, bundling that project’s filesystem and installed packages rather than a block-level disk image or a layered OCI image you can pull into another runtime. Because Sandbox runs only in iad1, the snapshot is region-local and project-scoped, so it will not travel the way an AMI or registry image does.
Do the retention knobs matter on Hobby, or only on paid plans?
They exist on Hobby too, but the constraints differ. Hobby caps snapshot storage at 15 GB for the account lifetime rather than billing per GB-month, and the default runtime is 5 minutes with a 45-minute ceiling, so persistent sandboxes there cross far fewer session boundaries than on Pro. The 30-day default still applies, but against a lifetime storage ceiling, so the real risk is exhausting the 15 GB and losing the ability to snapshot at all.
Is a keepLastSnapshots cap of 10 enough for a high-volume agent loop?
The policy tops out at 10 retained snapshots, so a sandbox that stops more than 10 sessions inside the replay window loses its older failure states regardless of TTL. For an agent loop running many short sessions a day, that hard ceiling forces a choice: widen the TTL and accept that only the 10 newest survive, or move long-term replay state out of Sandbox snapshots into your own object storage.
