Vercel’s CLI can now attach an expiration date to a project at the moment you deploy it, and per Vercel’s changelog announcement, expired projects are deleted automatically; the changelog says nothing about what that deletion removes. For accounts filling up with demos, prototypes, and test apps spawned by coding agents or CI scripts, this changes where the cleanup burden lives: the platform now carries it for new projects, instead of a human remembering to delete anything. The catch is that it only works at creation time, and it introduces a new failure mode of its own: a prototype that quietly becomes real is deleted on schedule unless somebody runs one command.
That tradeoff is worth understanding before you make the flag a default.
The clutter problem this is aimed at
The reader problem is easy to recognize. An agent session or a CI pipeline runs vercel deploy, a project springs into existence with a generated name, and nobody ever returns to it. Multiply that by a team experimenting with agents, and the project list becomes an archaeological record of abandoned experiments. Until now, the cleanup options were all pull-based: a person, a script, or a periodic audit.
The changelog frames the new feature around exactly this waste, though note what it does and does not say: “You can now set a new project to expire when you deploy it with Vercel CLI. Expired projects are deleted automatically, so prototypes, demos, and test apps don’t need cleaning up by hand.” The named use case is prototypes, demos, and test apps. The changelog never mentions AI agents; that framing is the reader’s situation, not a vendor claim.
How —delete-project-after works, and when it silently does nothing
The mechanics, all from the changelog:
vercel deploy --delete-project-after <duration>sets expiry on the project at deploy time.- “Supported durations are 1h, 1d, 1w, 2w, and 30d, and the CLI prints the date and time when the project expires.”
- “To remove a project’s expiration, run vercel project keep:”
- “Update Vercel CLI to v65.12.0 or later to get started.”
The most important sentence in the announcement is the constraint: “The flag only applies when vercel deploy creates the project. If you deploy to an existing project with the flag, its expiration doesn’t change and the CLI prints a warning.”
That one rule has three consequences worth internalizing.
First, the flag is not retroactive. Nothing about it can clean an account that is already cluttered. Every existing project in your dashboard is invisible to it, forever.
Second, the creation-only binding interacts awkwardly with pipelines that reuse project names. If an agent or script redeploys into a project that already exists, passing the flag does not reset the clock and does not add expiry to a project that lacks it. You get a warning line in the output and no behavioral change. In a CI context where nobody reads warnings, this is close to silent. A pipeline that assumes “we always pass the flag, so everything expires” is wrong about every deploy after the first.
Third, the flip side is protective: redeploying to an expiring project does not extend or reset its timer either. The expiration set at creation is the expiration, until someone explicitly runs vercel project keep.
Picking a duration
The five supported durations run from one hour to thirty days, and the right choice depends on who consumes the deploy and how long a link needs to live.
| Duration | Reasonable fit | Main risk |
|---|---|---|
| 1h | Live demos, pairing sessions, “look at this” links | A demo that runs long dies mid-conversation |
| 1d | Agent-generated spike work, same-day review | Links shared in chat go dead overnight |
| 1w | PR-adjacent prototypes, weekly review cycles | Reviewers who come back after a long weekend find nothing |
| 2w | Sprint-length experiments | Comfortable enough that nobody develops a keep habit |
| 30d | Prototypes awaiting a real go/no-go decision | Long enough to become load-bearing without anyone noticing the timer |
My Read: default to 30d for anything a human might revisit, and 1d or 1w for pure agent churn. The reason is asymmetric cost. A project that expires too early costs someone a redeploy and, potentially, state that is not documented as recoverable. A project that lives a few extra weeks costs nothing but a line in a dashboard. Since the CLI prints the expiry date and time at deploy, a longer window also gives you a concrete artifact to grep for in CI logs if you want to audit what’s about to disappear.
One caution on the 1-hour option: a one-hour expiry on anything with attached state is a bet that deletion behaves the way you hope. Keep the shortest durations for truly stateless demos.
The promotion moment: vercel project keep and what to verify first
Auto-expiry forces a decision that used to happen by default. Previously, a prototype became permanent through inaction: nobody deleted it, so it lived. Now permanence requires an explicit act. If a demo earns a custom domain, real users, or a dependency from another system, somebody must run vercel project keep before the timer fires, or the platform deletes the project on schedule.
This is the sharpest edge of the feature. The cost of forgetting a cleanup command used to be clutter. The cost of forgetting vercel project keep is deletion. I’d argue the trade is still worth it for agent-heavy workflows, because clutter is guaranteed while accidental promotion is rare, but the failure mode deserves a checklist rather than a shrug.
Before running vercel project keep on a project that has graduated from prototype status, verify:
- Custom domains. Confirm whether any are attached, and that the domain configuration is reproducible from your side, before the project becomes load-bearing.
- Environment variables. Prototype env vars are frequently pasted by hand and live nowhere else. If they aren’t in a secrets manager or
.envunder version control, promote them first. - Deployment history and logs. Nothing in the changelog says whether deletion preserves any history. If you need an audit trail, assume you must keep your own.
- Attached data services. The least documented area, and the pattern described next argues for caution.
- Who else depends on the URL. A preview link embedded in a ticket, a demo sent to a customer, a webhook target. These don’t show up in any dashboard.
The checklist is deliberately verification-heavy because “deleted automatically” is a schedule claim, not a completeness claim. The changelog is silent on what happens to domains, env vars, logs, or attached resources when the timer fires.
Attached data runs on its own clock
The nearest documented analogue is Neon’s guide to Vercel branch cleanup, and it covers deployment retention, not project expiry. That distinction matters, so be careful about extrapolating. Still, it is the best available window into how cleanup actually behaves once deletion is scheduled, and it complicates any assumption that “automatic” means “instant and total.”
Neon’s docs explain that in its Vercel-Managed integration, “cleanup is tied to deployment deletion, not Git branch deletion.” Closing a pull request or deleting the Git branch does not remove the database branch behind a preview deployment; the cleanup follows the deployment’s lifecycle on Vercel’s side. While a PR is open, the latest preview deployment for its branch, and the Neon branch behind it, stays protected.
On timing, the same guide reports that “Vercel marks an expired deployment for deletion within about 48 hours,” but if a retention exception still applies, re-evaluation “can take up to 30 days.” Again, those figures describe deployment retention under Vercel’s default pre-production retention policy, which the Neon guide (as of October 2025) lists at 180 days on Pro and Enterprise plans, 30 on Hobby. They say nothing directly about what happens when an expired project is deleted. But they establish a pattern worth carrying over: on this platform, deletion is schedule-bound and exception-aware, not instantaneous. Until Vercel documents expired-project teardown, plan as if attached resources may linger, or behave per their own integration’s rules, after the project itself is gone.
Where expiry overlaps the cleanup you already have
Project expiry does not replace the existing cleanup patterns; it sits alongside them, and the seams matter.
Scripted removal in CI. vercel remove remains the incumbent: it deletes a project and all of its deployments. Its --safe option “can be used to skip the removal of deployments with an active preview URL or production domain when a Vercel Project is provided as the parameter.” That guard is useful but narrower than it looks. It protects deployments with active preview URLs or production domains; it is not a general “this got promoted” detector. A prototype with real users but no custom domain, or one whose preview URL isn’t currently active, gets no protection. Meanwhile --delete-project-after offers no such guard: the changelog documents a single escape, vercel project keep, and no traffic exception in either direction. The two mechanisms answer different questions. remove --safe asks “does this look live right now?”; expiry asks “did anyone explicitly claim this?”
Preview-deployment garbage collection. Vercel already retains pre-production deployments for a default window (180 days on Pro and Enterprise as of October 2025, per the Neon guide; Hobby defaults to 30 days) with protections like the PR-open rule above. That system cleans deployments inside projects; expiry deletes whole projects. They run independently, and neither substitutes for the other.
The backlog. Because the flag binds only at creation, every pre-existing project still needs a pull-based cleanup: vercel remove in a script, or a bulk tool. The community project vercel-wipe describes itself as “a powerful bash script to bulk-delete Vercel projects with filtering, preview, and safety features,” with a --dry-run preview mode and filters targeting projects by linked repository visibility. Those safety features are self-described by a single unvetted repository, so the correct posture is: never run a bulk delete without a dry run first, and treat the preview output as the actual decision point.
Putting it together
The operational shape I’d recommend, given the evidence:
- Default new agent- and CI-spawned deploys to an expiry (30d for anything human-facing, shorter for pure churn) on CLI v65.12.0 or later. This moves the guaranteed-clutter problem to the platform.
- Treat
vercel project keepas a promotion ritual, triggered the moment a project earns a domain, real traffic, or a dependency, and preceded by the verification checklist above. - Keep scripted cleanup for the existing backlog, since the flag can never touch it:
vercel remove --safefor targeted removal, a dry-run-first bulk tool for the long tail. - Assume deletion is scheduled, not instant or total, until Vercel documents what expired-project teardown includes.
The honest limitation sits underneath all of this: every mechanic of the feature rests on one vendor changelog post, and that post is silent on the questions that matter most when a timer fires on something that turned out to matter. The Neon guide shows cleanup on this platform can wait weeks on retention exceptions for deployments, which is reason enough not to assume expired projects vanish cleanly and completely. Expire by default, promote deliberately, and verify teardown before you trust it.
Frequently Asked Questions
What durations are supported for the —delete-project-after flag?
Supported durations are 1h, 1d, 1w, 2w, and 30d, and the CLI prints the date and time when the project expires.
Does the expiration flag work on existing projects?
The flag only applies when vercel deploy creates the project. If you deploy to an existing project with the flag, its expiration doesn’t change and the CLI prints a warning.
How do I stop a project from expiring?
To remove a project’s expiration, run vercel project keep:
Join the discussion
Share a useful perspective or ask a question about this article.