# Update and recover

Speedwave checks for updates and can repair a project's containers on its own. This guide covers how an update reaches you and what to do if one goes wrong.

## How updates arrive

A background check runs on startup and repeats every 24 hours, in the CLI and Desktop alike. Speedwave verifies each version's signature and refuses anything older than what you run. It waits for your approval before installing:

1. Open **Settings** and find the update section, or right-click the system tray icon and choose **Check for Updates**.
2. Once a version is available, select **install & restart**, or **Install Update v\<version\>** from the tray menu.

Speedwave stops running project containers, installs the approved version, and restarts. A failed install brings back the stopped projects and clears the pending state.

Separately, on every startup Speedwave compares a hash of the current app version and container images against the hash it last applied. A mismatch triggers a reconcile: an overlay reads **Rebuilding container images...** while it rebuilds only the changed images and recreates only the projects that were running.

Running `speedwave update` for one [project](/docs/features/multi-project/) while another's containers run skips the shared claude-resources sync, to avoid corrupting live file mounts, and logs `claude-resources sync skipped: another project is running; open Speedwave Desktop to finish applying the update.`

[Update, reconcile, and auto-recovery (architecture)](/docs/under-the-hood/updates-and-recovery/)

## Auto-recovery after sleep or restart

A project's containers can stop working on their own: sleep and resume can leave the VM's file mounts stale while a container still reports itself running, or state can get wiped outright by a containerd reinstall or VM recreation. Speedwave detects both and restores the project the next time you use it, not on a timer.

| Trigger | What Speedwave does |
|---|---|
| Stale mount or missing container, detected before a chat session starts | Force-recreates the container, then probes again to confirm the fix |
| Missing [MCP plugin](/docs/plugins/using-plugins/) image, say after a containerd or VM reset | Rebuilds the plugin image automatically |
| Build fails for lack of VM space | Prunes old bundle images and the BuildKit cache, retries once, then shows an actionable error if it still fails |

## When an update goes wrong
**Caution:** If recovery cannot fix the containers, Speedwave stops and shows an actionable error, and restarting Speedwave clears it:

```text
Container recovery failed: ... Please restart Speedwave.
Containers still broken after recovery: ... Please restart Speedwave.
```

If the images themselves are missing, the message says restarting the app triggers an automatic rebuild instead.

If a session keeps ending, or a container will not stay up, see [Troubleshooting](/docs/guides/troubleshooting/).

## Factory reset

When nothing else works, Settings has a Danger Zone with a factory reset. It stops every container, deletes the VM on macOS, removes the `speedwave` CLI symlink, and deletes the entire `~/.speedwave` data directory, including tokens and installed plugins. Speedwave then restarts and runs the Setup Wizard again, whether the reset succeeded or failed. Treat it as a last resort: it wipes all local Speedwave state, not just the current project.

## Critical releases

Speedwave flags a release as critical when its notes contain `[CRITICAL]` or `[SECURITY]`, and that flag carries through to the update information shown to you.

For the deeper mechanics of image tagging and rebuilds, see [Container topology](/docs/under-the-hood/container-topology/) and [Updates and recovery](/docs/under-the-hood/updates-and-recovery/). To turn integrations on or off, which changes which worker images get built, see [Beta features](/docs/guides/beta-features/).