Updating SoAI

Update a running installation from the SoAI WebUI. With Software updates (SOFTWARE_UPDATE), open the Settings menu at the right of the header and select Updates. If the Dashboard's Quick actions section is visible, its Updates shortcut opens the same page. Application updates are separate from plugin-backend updates and, on SoAI OS, from host package updates.

Prepare and install an update

The Backup tab appears only to an Administrator with Backup administration (BACKUP_ADMIN).

  1. Select the Settings button at the right of the header, then select Settings from its menu and select Backup.
  2. Select Create backup.
  3. Keep a downloaded copy outside the host when your recovery policy requires one.

An update transaction protects the application files it changes, but it is not a substitute for a backup of data and configuration.

Install an application update

  1. On Updates, select Check for updates.
  2. In SoAI application updates, review the current version, latest version, and notes for each published release between them. If SoAI reports incomplete note history, open the official repository, select Releases, and read the missing notes before continuing.
  3. On a supported Linux, macOS (experimental), or Windows installation, select Install update and confirm the dialog.
  4. Follow preparation, download, verification, and staging progress on the Updates page. When SoAI restarts to install the update, the updating screen names the version being installed and waits for the updated application.
  5. Keep the window or page open until SoAI returns. A dialog then confirms that SoAI was updated successfully to the new version, or explains that the update did not complete and which version is still installed.

In the Windows desktop window, the window closes while the installer replaces the application. A small SoAI update window then shows that the update is installing and closes when the desktop window reopens with SoAI ready; do not turn off the computer during this step. In a browser, the page reloads automatically when SoAI is back online and loads the updated WebUI without stale cached files. Other browser tabs that stayed open during the update offer to reload once they reconnect. Every user sees the update result dialog once, the next time they open the WebUI.

The update service checks the signed release manifest, its signing key, the selected edition, and the downloaded release artifact before applying it. It stages the change in an update transaction and keeps rollback data until the updated application completes startup successfully. If the rollback data cannot be verified, the update stops before it changes the installation and the installed version stays in place. During startup, SoAI applies required database and settings migrations to the existing data directory. User accounts, conversations, settings, attachments, files, models, plugins, automations, and benchmark history remain in place. SoAI restarts the application when the update was started from a running instance.

If the updater rejects corrected homepage information in an unmodified bundled plugin with an ambiguous installed identity error, wait for the failed transaction to finish recovering. Then stop SoAI and run the current verified installer over the existing installation, using the same installation folder and data directory. Follow Update Core from a complete archive or Retry with the Windows setup program. Keep customized packages intact and resolve any separate name or author conflict before continuing.

Plugin selections and backend version limits

Application updates and installation over an existing installation keep deleted built-in plugins absent, even when their saved configuration remains. A fresh installation includes the complete bundled set. To add a deleted plugin again, use Plugins > Add plugin to upload its package or download it from a trusted URL.

Installation, application updates, and explicit dependency installation or repair reapply each installed plugin package's declared MAX_SUPPORTED_BACKEND_VERSION to its existing configuration. This also applies to third-party plugins and clones that declare the setting. SoAI preserves your selected BACKEND_VERSION, credentials, storage paths, GPU bindings, and other saved settings. Packages without the declaration and configuration files without an installed package keep their saved values.

Reapplying the limit does not install or replace a backend; backend update checks and automatic-update settings still govern installation. Later edits to the limit remain until the next application installation, update, or explicit dependency repair reapplies the package's declaration.

Windows background service and protected files

On Windows, SoAI runs in a background service that starts when a SoAI window opens. Starting SoAI no longer shows an administrator prompt for any Windows user. An installation upgraded from an earlier release changes in these ways:

  • The first start after the upgrade protects the installation folder and shows Securing SoAI files.... Every Windows user can still start SoAI, but only administrators and the service can read or change the data folder. This runs once and takes longer when the data folder holds many models or files.
  • Each Windows user signs in again once in the SoAI window. Window settings and the signed-in session are now kept for each Windows user separately.
  • Folder settings that started with ~ or used environment variables are saved as the full folders they pointed to for the user who installed the update. The HTTPS certificate SoAI created for itself moves into the installation, so browsers and paired SoAI Connect devices keep trusting the same server.
  • Folders on a network share or a mapped drive may be unreachable, because the service uses the computer account rather than a signed-in user's saved credentials. The system health check reports the affected settings as network_paths. Move those folders to a local drive, or to a share the computer account can reach.
  • Proxy and other environment variables set only for a Windows user no longer apply to SoAI. Set them for the whole computer and restart Windows.

To return to an earlier release, uninstall SoAI with its data kept, install the earlier release, and restore the backup you created before the update.

Conditions that disable automatic updates

The WebUI cannot check or install an application update when SYSTEM.RUNTIME.STAY_OFFLINE is enabled. Automatic application updates are also unavailable when SYSTEM.RUNTIME.HOST_SYSTEM_ACTIONS_DISABLED disables host actions. Core automatic installation supports Linux x64 and ARM64, macOS Intel and Apple silicon, and Windows x64. Linux and macOS use complete archives. Windows verifies and hands off the release installer, which preserves the existing data directory and replaces the launcher and application files in place.

The Updates page offers installation only when a newer release is available and the current platform has an automatic installation path. It does not provide a downgrade option; on other platforms, it can still show whether a newer release is available. To return to an older installation, restore its matching backup from before the update. An older release may be unable to open data saved by a newer one.

Edition boundaries and recovery

An application update stays within the installed edition. It cannot switch Core into the appliance edition or the reverse. In an appliance installation, the SoAI OS updates section handles host package updates separately; continue with the appliance update guide for that workflow.

Recover from an unsuccessful update

Do not begin another update while the previous transaction may still be recovering. If the WebUI does not reconnect, use the matching launcher to check status, preserve the reported error, and follow the application update recovery runbook. The updater records its progress in application_updater.log and any unexpected interpreter failure in application_updater.stderr.log, both in the configured logs directory (OBSERVABILITY.LOGGING.LOGS_PATH). Restore a verified backup only when recovery of the installation cannot retain the required data.

When an update stops while preparing its rollback data, the update result dialog explains what failed, gives a reference, and names the folder on the SoAI computer where diagnostics for that attempt were saved. Keep that folder and the reference when you ask for help.

If the WebUI update fails, correct the reported cause before retrying. Once the failed transaction has finished recovering, you can retry from Settings > Updates if SoAI is running, or update the existing installation manually. Keep a backup before either attempt, and use a newer release of the same edition for your platform.

On Windows, use the new release's verified setup executable and select the existing installation folder. Setup preserves the existing data directory. The complete ZIP is an alternative: extract it into a separate folder, stop the existing SoAI instance, and run its installer with --target pointing to the existing installation. Follow Retry with the Windows setup program or Update Core from a complete archive for the commands and checks. The archive procedure also covers Linux and macOS.

Use Reset and account recovery only when the failure is caused by a specific damaged setting or when you deliberately intend to clear managed data; an update failure does not by itself justify a factory reset.

Related documentation