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 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) The internals: build hashes, the reconcile id, and the reconcile phases.

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 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:

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.

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 and Updates and recovery. To turn integrations on or off, which changes which worker images get built, see Beta features.