Update and auto-recovery
Speedwave includes built-in update verification and automated container recovery mechanisms to maintain workspace availability and image consistency across system reboots and sleep states.
Application updates
Section titled “Application updates”Speedwave checks for signed software releases on launch and every 24 hours in the background across both Desktop and CLI interfaces. Signature verification ensures binaries match official releases, and downgrades are rejected. Updates require explicit user authorization:
- Navigate to Settings → Updates or right-click the Desktop tray icon and select Check for Updates.
- When a release is available, select Install & Restart or choose Install Update v<version> from the tray menu.
During the update process, Speedwave stops active containers, applies the verified binary release, and restarts the environment. If an update fails, previously running workspaces are restored to their prior operational state. On Windows, the installer also removes files the previous version left in the installation folder, so they cannot end up in container image builds.
Update files are downloaded through the GitHub API, which serves about 60 anonymous requests per hour to one IP address. When many computers share one public address, some of them may need to retry the download later.
Image reconciliation
Section titled “Image reconciliation”On every startup, Speedwave compares a cryptographic hash of current application binaries and container templates against previously compiled images. Any configuration drift triggers automatic reconciliation: a diagnostic overlay displays Rebuilding container images… while modified layers are recompiled and active workspaces recreated.
Executing speedwave update from the CLI while another project is active avoids interrupting active workspace mounts by deferring global resource synchronization.
Automated recovery mechanisms
Section titled “Automated recovery mechanisms”Containers can encounter broken state following operating system sleep cycles, containerd daemon restarts, or storage eviction. Speedwave evaluates container health on demand before establishing interactive sessions:
| Trigger condition | Automated recovery procedure |
|---|---|
| Stale mount or terminated container | Automatically regenerates the container topology and verifies socket reachability. |
| Missing MCP plugin container image | Recompiles the plugin image from local signed manifests. |
| Disk exhaustion during image builds | Automatically purges obsolete container layers and BuildKit caches, retrying compilation once. |
| Container start collides with the engine’s own restart of the same container | Waits briefly and retries once. Every container start is capped at three minutes, so a stuck start ends with an error instead of hanging. |
| Stale network rules left behind by a crashed container | Removes the stale rules and retries the start. |
| Virtual machine does not answer the image check | Shows Container engine did not answer the image check with a Retry button instead of rebuilding images that are already there. |
Recovery escalation and failure handling
Section titled “Recovery escalation and failure handling”For persistent connection issues, consult the Troubleshooting guide.
Factory reset
Section titled “Factory reset”If runtime state becomes unrecoverable, the Desktop application provides a factory reset option in Settings → Danger Zone. This terminates all active containers, removes the Lima virtual machine on macOS, unlinks CLI binaries, and deletes ~/.speedwave/ (including all local token directories and installed plugins). Speedwave restarts into the initial Setup Wizard. Treat factory reset as an action of last resort.
Critical security advisories
Section titled “Critical security advisories”Releases containing [CRITICAL] or [SECURITY] in release manifests are highlighted with high-priority visual badges in update prompts.
For details on container lifecycle orchestration, consult Container topology and Updates and recovery internals.