> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boat.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Versions and upgrades

> Each saved change makes a new environment version. A sandbox moves to it only when you upgrade.

Each time you save a change to an environment, Boat makes a new version.

```
you save a change  ──▶  a new version is created
                            │
                            ├──▶ every sandbox that starts from now on gets it
                            │
                            └──▶ Sandboxes already running: nothing happens
                                     │
                                     └──▶ they move only when you upgrade
```

## Which version a sandbox uses

* A sandbox takes the latest version **at the moment it starts**.
* The sandbox keeps that exact version for the rest of its life.
* A save never changes a running sandbox.
* There is no automatic upgrade, no background rollout and no scheduled window.
* A sandbox moves only when you click **Upgrade** in the dashboard or run `boat env upgrade`.

## Find the version of a sandbox

1. Run `boat info <id>`. It shows the version as `environment` and `environmentVersion`.
2. Run `boat env list`. It shows the latest version of each environment.
3. Compare the two numbers. A sandbox below the latest still runs the older configuration.

This is the usual answer to "I added that secret. Why does my sandbox not have it?"

```bash theme={null}
boat info bx_f7k2q9hd     # env:  prod (v2)
boat env list             # prod  latest v3   -> this sandbox is one upgrade behind
```

## Upgrade

An upgrade applies the new configuration. It also removes every secret that the new version withholds.

| Sandbox state | When the upgrade applies |
| - | - |
| Live | Immediately. Boat cleans and updates it. |
| Stopped | When it resumes |

<Warning>
  You cannot undo an upgrade on the disk of that sandbox. Boat deletes a withheld secret from the machine. It does not hide it. If you pin the sandbox to the older version again, a secret file that the newer version dropped does not come back.
</Warning>

The Versions panel lists every version and the number of sandboxes on each. Use it to find sandboxes that still run an old configuration.

To upgrade only some sandboxes, give `upgradeEnvironment` an optional list of sandbox ids. Without the list, Boat moves every sandbox of yours that is on an older version. For the commands, read [Named environments](/environments/named-environments).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.