Upgrade
Upgrade replaces the currently running agent with a newer version released. It is the standard path for rolling out bug fixes, security patches, or new features while preserving the device identity and configuration.
When it happens
- CLI (terminal):
nimbus system upgrade - UI: Click the upgrade action from the robot overview page or fleet console when a new version is available.
How it works
- A supported Sidecar starts the packaged updater; otherwise Agent requests the Backend installer command and gives it to an independent updater.
- The updater downloads and validates the package before stopping a service-managed Agent. A manually launched Agent exits once the external updater owns the handoff.
- A local backup is created before installed files change. The updater replaces the binaries and starts the installed Agent service with its existing configuration.
- Local service and version checks establish the installation result. Cloud reconnection and robot configuration startup can finish afterward.
Follow progress or request cancellation
nimbus system upgrade-status --watch
nimbus system stop-upgrade
Status shows package-download percentage, bytes and speed when known, followed by extraction, installation and verification stages. The watcher follows the same operation through temporary restarts. Ctrl+C stops watching and leaves the upgrade running.
Supported Agent-owned and Sidecar-owned installers accept cancellation during package download or extraction. The installer confirms cancellation at its safe checkpoint before service changes or installed-file replacement; a queued request is not yet a cancelled upgrade. Requests after that boundary are refused. Older installers or an unverified owner cannot accept cancellation. For a manual handoff, confirmed cancellation restores and verifies the unchanged installed service.
Local recovery remains available through Sidecar while Agent restarts. For Agent-owned upgrades
without a reachable Agent or Sidecar, run sudo nimbus system upgrade-status --watch to read the
independent supervisor's private status. See System Manager
for operation selection and command details.
Why the backup matters
- Each upgrade uses the backup as a safety net for restoring the previous installed build.
- Automatic backups are stored locally so they survive even if the upgrade tarball is removed or the device loses internet access mid-upgrade.
- Learn how the snapshots are stored, listed, and deleted on the Backup page.
- When you need to roll back after an upgrade failure, follow the steps on Restore (Rollback).
Notes
- Backup is always created before upgrade.
- Backup name is auto-generated (e.g.,
backup20260113125514). - Sidecar-owned upgrades use the packaged installer; Agent-owned upgrades retain the Backend-supplied command. Both run independently of the Agent process.
- An Agent-only upgrade keeps an unchanged, healthy Sidecar running, preserving its terminal sessions. Updating Sidecar itself requires a restart.