Skip to main content

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​

  1. A supported Sidecar starts the packaged updater; otherwise Agent requests the Backend installer command and gives it to an independent updater.
  2. 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.
  3. A local backup is created before installed files change. The updater replaces the binaries and starts the installed Agent service with its existing configuration.
  4. 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.