# 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.

## 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.

## Share a preview link

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-server.md)). 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](agent-releases.md) covers it.
