Skip to content
Scryer Docs

Upgrading

Upgrade Scryer during a quiet window, when no one is actively resolving imports or editing settings.

The safest upgrade rhythm is simple: preserve the data directory, move the binary or image forward, then verify a few core screens before treating the instance as normal again.

Which Path Applies

Section titled “Which Path Applies”

Scryer classifies its own installation at startup and shows the result under Application upgrade on the System page, along with the current and available versions. The classification decides who performs the upgrade:

InstallationUpgrade path
Dockerdocker compose pull, see Docker Compose
Homebrewbrew upgrade scryer, see Homebrew
Wingetwinget upgrade, see Winget
MSI installed from the GitHub releaseIn-app upgrade
Portable binary on Linux, macOS, or WindowsIn-app upgrade, or replace the binary
Windows run as a service or from Task SchedulerReplace the binary

Package-managed installs are never upgraded from inside the app, because the package manager owns the files. The System page names the manager and shows the command to run instead.

In-App Upgrade

Section titled “In-App Upgrade”

Standalone installs upgrade from the app. That covers the portable archives on every platform and the MSI downloaded directly from GitHub.

When a newer release is published, a Scryer update available banner appears at the top of the UI with the version, a link to the release notes, and an Upgrade now button. The same button is under Application upgrade on the System page. Both need the manage system settings permission.

  1. Confirm the target version in the dialog. Scryer restarts during the upgrade, and a direct MSI install shows a Windows elevation prompt.
  2. Watch the run under Upgrade in progress. It moves through checking, downloading, verifying, staging, and applying, then restarting.
  3. Wait for the UI to come back. The run finishes as Completed with the old and new version, and the banner clears.

Behind the button, Scryer downloads the signed release manifest for the advertised tag from the GitHub release and checks its signature, then downloads the artifact for its platform and architecture and checks the size, BLAKE3 hash, and archive contents before anything is extracted. The download and extraction happen inside the data directory.

On Linux and macOS the current binary is renamed aside as a backup and the new one is moved into place. On Windows the server hands off to a small helper that waits for Scryer to exit, then either swaps the portable executables or runs the MSI through Windows Installer with a UAC prompt, and relaunches Scryer. If the tray was set to start at login, that setting is restored after the installer runs.

On the next start Scryer checks that it booted the expected version from the expected path. If it did, the backup and staging files are removed. If it did not, the run is marked failed and the backup is kept next to the binary so you can restore it by hand. An upgrade that fails before the swap leaves the current install untouched.

Only one upgrade can run at a time. When Windows Installer reports that a reboot is needed, the run stays open with Restart Windows to finish this upgrade until the machine restarts.

An install shows one of these eligibility notes when the button is unavailable:

NoteMeaning
Managed by Docker, Homebrew, or wingetUse that package manager.
Supervised externallyScryer runs in session zero or was started by Task Scheduler. Stop it and replace the binary.
Disabled by the operatorSCRYER_DISABLE_SELF_UPGRADE is set to 1 or true.
Installation directory is not writableThe account running Scryer cannot write next to the binary. Fix the permissions or upgrade manually.
Layout not supportedScryer could not resolve its own executable, or a Windows registry entry names an unknown distributor.

Docker Compose

Section titled “Docker Compose”
docker compose pull
docker compose up -d

Keep /config and media roots mounted outside the container image.

Homebrew

Section titled “Homebrew”
brew update
brew upgrade scryer
brew services restart scryer

If you need a same-version Homebrew packaging fix immediately, run:

brew update --force
brew reinstall scryer

Winget

Section titled “Winget”

Run from an elevated PowerShell or Windows Terminal, because the MSI installs per machine:

winget upgrade --id ScryerMedia.Scryer --exact

Windows Installer stops Scryer during the upgrade and a silent install does not start it again. Launch Scryer from the Start menu when the command finishes. See Winget for the full procedure.

Manual Binaries

Section titled “Manual Binaries”

Stop Scryer, replace the binary from the latest release, and start Scryer again with the same data directory. Reusing the same data directory preserves users, settings, libraries, and operational history.

Portable installs can use the in-app upgrade instead, which does the same swap for you and keeps a backup of the previous binary until the new one has started.

Upgrade Checklist

Section titled “Upgrade Checklist”
  • Keep database and config storage persistent.
  • Verify the System page after startup.
  • Open one facet overview and one Settings page to confirm the UI is healthy end to end.
  • If you run companion services, upgrade them independently according to their own release guidance.
Section titled “Related Concepts”