Try changes in a preview

Try each new version on a copy of your data before anyone using your app sees it. Your live app keeps running as it is until you choose Go live, so a broken change or a risky migration never reaches your users by surprise.

Last updated

AI agent? Start with llms.txt.

Choose what happens when you push

Every Project has a When you push setting. You pick it when you create the Project, and you can change it at the top of the Project page or on its Settings tab.

Option What happens
Go live automatically Tokay deploys each change once it's ready.
Try it in a preview first Changes run on a copy of your data until you go live.
Wait for me Changes wait until you press Deploy all.

Choosing Go live automatically or Try it in a preview first needs permission to deploy the Project, since both run new code with your real Secrets. Wait for me needs only permission to change the Project. A Project's first version goes live on its own, since nothing is live yet to protect. Every push after that runs in a preview first.

Try your new version

When you push, we copy the Project's databases, run your migrations on the copy, and start the new version there. This usually takes about a minute, and the card at the top of the Project page shows each step.

Once the preview is ready, the card offers an Open button for each web app and a Run button for each scheduled job. Anything you change in the preview stays in the copy. Your live app and its data stay as they are until you go live.

A scheduled job never runs on its schedule in a preview. Run it once from the card, or with Run in preview on the job's page. Background workers do run there, and they can pick up jobs that were waiting in the copied data.

Your code can tell when it runs in a preview. Every app and job there gets the environment variable TOKAY_PREVIEW=1, which is never set live. Use it to hold back side effects you don't want from a trial, such as outgoing email.

Each web app in the preview has its own address, listed under Links on the Project's Preview tab while the preview is ready. Anyone with a link can open that app in the preview, with your real values and a copy of your data. Private services still ask people to sign in.

Treat a link like a password. Each preview opens at the same addresses, so a link keeps working in the next one. If a link reaches someone it shouldn't, including someone you removed from the Project, choose Rotate links. Your services get new addresses and the old links stop working.

Decide what the preview runs with

A preview runs with your live Config and Secrets unless you give it values of its own. On the Preview tab, What it runs with shows each value as Same as live or the preview's own. Choose Set preview value to give the preview something like a test API key, so trying a change can't charge or email anyone for real. Use live value switches it back. Your live app never sees a preview value.

Control what the preview can reach

A preview can call your Project's own services and the host names you allow, like api.stripe.com, and nothing else. It never reaches your live app. Add names under What it can reach on the Preview tab.

A call to an allowed name is real. The preview holds your real Secrets unless you gave it its own, so a payment or email service charges and sends for real. When your pages try to reach a site the preview blocks, browsers report it under Blocked requests, where you can allow it. We can't check those reports, so only allow host names you recognize.

Go live or discard

Go live on the Project's card ships the waiting version and ends the preview. Deploy all and a service's own Deploy do the same. If a migration needs your review, the card says so, and the service keeps its current version until you confirm.

Discard closes the preview and leaves your live app as it is. Your next push starts a fresh preview.

Anyone who can see the Project can try a ready preview. Opening it again, going live, discarding, and changing what it can reach need permission to deploy.

When a preview closes

A ready preview closes after an hour with no visits, when your server stops, or when your server runs low on memory. Previews stop first when memory runs low, so your live apps keep running (Your server). Your new version keeps waiting after a preview closes. Choose Open preview to start it again on a fresh copy of your data.

Your workspace runs one preview at a time. If another Project's preview is open, yours waits and starts as soon as that one closes.

Limits

Limit Value
Previews running at once One per workspace
Closes after An hour with no visits
Databases Postgres and MySQL. Projects that use MongoDB or Redis can't preview yet.
Scheduled jobs Run only when you start them
Allowed host names Up to 100 exact names, with no wildcards or IP addresses

Your AI agent can do all of this through Tokay MCP. Releases and migration safety for agents covers it.