---
title: 'Update notice'
description: 'The strip at the top of Studio that says your box runs an older CLI, runtime or SDK than the newest release, what each line asks you to do, and how to close it.'
position: 21
---

# Update notice

> Studio compares the versions your **box** (the container running your
> workspace, or `stackbone dev` on your laptop) reports with the newest Stackbone
> releases. When the box is behind, a strip marked **update** appears at the top
> of Studio with one line per package. It never blocks a screen, and closing it
> hides it until the next release.

## What Studio compares

Studio reads two versions from the box's handshake, `GET /api/contract` (the
payload [`stackbone contract show`](/docs/cli/reference/contract#stackbone-contract-show)
prints):

| Field           | What it is                                                                                                                                                                                                                                    |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `build.version` | The CLI that runs a `stackbone dev` session, or the runtime inside a deployed box's image.                                                                                                                                                    |
| `sdk.version`   | The `@stackbone/sdk` your workflows run. `stackbone dev` reads it when it starts. A deployed box reads it from the [manifest `stackbone package` writes](/docs/cli/reference/package#the-box-reports-the-sdk-version-you-packaged). Optional. |

It compares each one with the newest `@stackbone/cli` and `@stackbone/sdk`
releases on the two channels Stackbone publishes on: `latest` for releases and
`alpha` for prereleases. The control plane reads those from the npm registry.

## When a line appears

A line appears when the box runs a version behind the newest release on its own
channel. Any version behind counts, a patch release included.

| The box runs                          | Studio compares it with              | It shows a line for                                                     |
| ------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------- |
| A release, such as `0.5.4`            | The newest `latest`                  | `0.5.4` while `latest` is `0.5.5`                                       |
| A prerelease, such as `0.6.0-alpha.3` | The newest `alpha`, and `latest` too | `0.6.0-alpha.3` while `alpha` is `0.6.0-alpha.4` or `latest` is `0.6.0` |

A prerelease is behind once the stable line passes it, so it is compared with
`latest` as well. When it is behind both, the line names the newer of the two
releases.

No line appears in these cases:

- The box runs the newest release, or a version ahead of it, such as a build of
  your own.
- The registry has no release on that channel.
- The version is not plain semver (`v0.5.3`, `dev`). Build metadata such as
  `+build.5` does not count in the comparison.
- The box reports no `sdk.version` (no SDK installed, or an image built before
  the box reported it). That box gets no SDK line.

Studio shows no strip at all when the control plane cannot say what the newest
releases are: npm did not answer, or the control plane has no release list to
serve, as on a [`self-host`](/docs/cli/reference/package#self-host-the-agent-and-the-dashboard)
deployment. It also stays hidden while Studio is still reading the handshake,
and while a full-page message has replaced the screen (the box is too old for
this Studio, or Studio cannot reach it), because that message already says what
to do.

The lines need the box's own answer. When the control plane answers the
handshake for a box it could not reach, that answer carries the control plane's
version and no SDK version, so Studio has nothing of your box's to compare and
shows no line.

## What each line asks you to do

Each line names the newest release first and the version your box runs second.

### Update the SDK

```text
A newer SDK is available (0.6.0, your workflows run 0.5.2): pnpm add @stackbone/sdk@latest
```

The command carries the channel of the release the line names: `@latest`, or
`@alpha` for a prerelease. Run it in your project root:

```sh
pnpm add @stackbone/sdk@latest
```

A workspace that [`stackbone init`](/docs/cli/reference/init) scaffolded lists
the SDK in `workflows/package.json` as well, and your workflows run that copy.
Run the same command inside `workflows/` too.

Then put the box on the new version. Stop `stackbone dev` and start it again,
because it reads the SDK version when it starts. For a deployed box, run
`stackbone package` again and redeploy: the version travels in the bundle.

### Update the CLI

```text
A newer CLI is available (0.5.5, you run 0.5.4). Update it.
```

Studio shows this wording for a `stackbone dev` session. Install the newer CLI
with the same command you installed it with:

```sh
pnpm add -g @stackbone/cli@latest
```

Use `@alpha` instead of `@latest` when the release the line names is a
prerelease. Then stop `stackbone dev` and start it again: the session that is
running is still the old CLI.

### Redeploy the box

```text
A newer runtime is available (0.5.5, this box runs 0.5.4). Redeploy the box.
```

Studio shows this wording for a deployed box. The runtime comes from the
published base image your `Dockerfile` starts `FROM`, so rebuild the image on
the current base and redeploy it. From a deploy folder:

```sh
docker compose build --pull
docker compose up -d
```

`--pull` fetches the current base. Without it, Docker reuses the copy it already
holds. On a platform that builds the image for you, start a new deploy. On
Railway, Redeploy rebuilds the image and fetches the current base.

That only works while the `FROM` line names the moving tag (`node24-base`, what
`stackbone package` writes). If you packaged with `--base` pointing at a fixed
tag or a digest, every rebuild gets that same old runtime: run `stackbone
package` again without `--base`, then deploy.

### When Studio does not know where the box runs

```text
A newer CLI is available (0.5.5, this agent runs 0.5.4). Update the CLI, or redeploy the box if it is deployed.
```

Studio shows this wording before it knows whether the box is a `stackbone dev`
session or a deployed box. Follow [Update the CLI](#update-the-cli) for a
`stackbone dev` session and [Redeploy the box](#redeploy-the-box) for a deployed
one.

## Close it

The close button at the end of the strip ("Dismiss update notice") hides every
line on screen. Closing it hides it until the next release: Studio remembers
which release each line named, and a newer one shows the line again. Updating
the box removes the line as well: once it runs the newest release, there is
nothing to show.

Studio keeps the close in this browser's local storage, per box and per line.
It is not saved on your account, so another browser, or a teammate, still sees
the line. When the browser blocks site storage, the line stays closed for this
visit only.

## What's next

- **[Install the CLI](/docs/home/get-started/install)**: the one command that
  installs and updates `stackbone`.
- **[`stackbone package`](/docs/cli/reference/package)**: the deploy folder,
  and the SDK version it writes into the bundle.
- **[Troubleshooting](/docs/home/deployments/troubleshooting#the-box-is-too-old)**:
  what to do when Studio refuses a box that is too old.