Updates¶

The launcher updates itself. Every release carries a signed record of its size and hash; Xol checks that signature against keys built into the app, refuses replays and downgrades, and verifies the download before anything is opened.

Updates need a valid access key. Without one, Settings ▸ Service ▸ Launcher updates reads "Updates need an access key."

This page is about the launcher. The Xol client mod ships inside the launcher, so a launcher update is also how a new client version reaches you; your instances move to the new client jar the next time you press Play. Game files are never "updated"; a profile pins exact versions.

How an update happens¶

1. Check. When the launcher starts, and when you press Check now, it asks the Xol service whether a newer release exists for your operating system and CPU architecture. The request carries your access key, the launcher version, the operating system and the architecture.
2. Evaluate. The offer contains a release record signed with Ed25519. Xol evaluates the record before it downloads anything; see What is verified.
3. Download in the background. With Update automatically on, the download starts by itself. The banner shows progress and a Cancel button. The file is written under a temporary name.
4. Verify. The download is aborted if it grows past the signed size. Its SHA-256 is compared with the signed record before the file is given its real name. A mismatch is deleted.
5. Stage (macOS only). The verified disk image is mounted read-only, Xol.app is copied next to the running app, and the copy is checked. See macOS.
6. Install. When you close Xol, or when you press Restart and update. Never while Minecraft is running.

Your instances, worlds and settings are not touched by an update.

The update banner¶

The version numbers and sizes above are examples. A banner can be dismissed for the session unless the update is mandatory.

The setting¶

Settings ▸ Service ▸ Launcher updates ▸ Update automatically, on by default. "New versions download in the background and install when you close Xol. Switch this off and Xol asks first." With it off, nothing is downloaded until you press Download update, and nothing is installed until you press the install button.

The same panel shows the running version and the result of the last check, for example "Xol is up to date." The possible results are listed under Check results.

Never while Minecraft runs¶

An update is not installed while a game is being prepared or is running. Pressing the button then gives "Close Minecraft before installing the update." Closing Xol while the game is still open does not install the update either; it installs the next time you close Xol with no game running.

What is verified¶

Only the signed fields mandatory and minLauncherVersion can block Play. The same flags in the unsigned part of an offer are ignored for that purpose.

macOS¶

1. The verified disk image is mounted read-only, without opening a Finder window.
2. Xol.app is copied out of it with ditto to a hidden folder next to the running app. ditto keeps the ad-hoc signature that every Apple Silicon program needs.
3. The copy is checked: its bundle identifier must be Xol's, its version must be the version the signed record promised, and codesign --verify --deep --strict must pass. If any check fails the copy is deleted and the update fails with the reason.
4. The disk image is unmounted. Everything slow has now happened in the background.
5. Install is two renames on the same volume: the running app is moved aside to a hidden name, and the staged copy takes its place. If the second rename fails, the first is undone and the old app is put back.
6. Xol starts again. The previous app is removed at the next start, once the new one has shown that it runs.

Why macOS asks only once¶

Gatekeeper assesses only files that carry the quarantine mark, and that mark is added by the program that downloaded the file: a browser, Mail or AirDrop. Your first copy of Xol comes from a browser, so macOS asks once (Install on macOS). An update is downloaded by Xol itself, so it carries no quarantine mark, its bytes match a hash inside a signed release record, and the app is copied out of that verified image. The replacement never enters Gatekeeper's queue. Nothing is bypassed; there is simply no new browser download to assess.

When Xol is signed with an Apple Developer ID and notarized, the first prompt goes away too. There is no date for that; see the roadmap.

When Xol cannot replace itself¶

Some copies of Xol cannot swap themselves. Xol then says why, and for that update falls back to opening the verified disk image so you can drag the new app into place. The button reads Open the installer.

After the fallback: "The disk image is open in Finder. Quit Xol, drag the new Xol to Applications (replace the old one), then start it again."

What has been proven on macOS¶

An automated macOS 14 build machine runs the whole staging and swap sequence for both architectures: a quarantined image, a staged copy with no quarantine mark, the swap, the signature check, a start of the new app, and the clean-up. Not yet observed: the full loop from a running, installed copy on a tester's Mac. That needs 0.2.2 installed and a later release published.

Windows¶

The update is the normal installer, run silently with the arguments that keep the installation folder and, after Restart and update, start Xol again. The banner reads "Updating. Xol closes and starts again in a moment." When the update installs because you closed Xol, it reads "Updating in the background." and Xol does not reopen.

An automated Windows Server 2022 machine runs a silent update over an existing install and checks that Xol starts again. It has not been observed on a tester's PC yet.

Rollback installers kept on disk¶

Verified installers are kept in the updates folder inside the data folder. After each verified download the folder is pruned to the last two installers. The older one is your manual way back: if a new version misbehaves, quit Xol and run the previous installer (Windows) or open the previous disk image and drag the app into place (macOS).

Xol itself will not install an older version unless the release record authorises it. If a release has to be pulled back, a signed rollback record can name the version it replaces; the banner then reads "Xol 0.2.2 (a rollback: ) is available".

Before it hands a stored installer over, Xol re-hashes it. If it changed: "The downloaded installer changed on disk after it was verified, so it was deleted. Download the update again."

Mandatory updates¶

A release can be marked mandatory, or can declare a minimum launcher version, inside its signed record. Only then does Xol block Play. The button reads Update required, the line above it "Update Xol to keep playing", and the reason is one of:

• "Xol 0.2.3 is a required update. Install it to keep playing."
• "Xol 0.2.0 is no longer supported; version 0.2.2 or newer is required. Install the update to keep playing."

The banner of a mandatory update cannot be dismissed. A flag that is not covered by the signature cannot block anything, so a compromised server cannot lock you out.

Check results¶

Settings ▸ Service ▸ Launcher updates shows the result of the last check.

A refused or failed check never blocks Play, and never discards an installer that is already verified and waiting.

Failure messages¶

Every failure ends with "Xol keeps running."

With diagnostics on, a failed update is reported automatically: launcher version, system type and the reason, with no game log. The banner then adds "A report was sent (diagnostics are on)." With diagnostics off, nothing is sent. See Privacy and data.

Linux¶

There is no Linux build, so there is nothing to update. A copy of the launcher running on Linux, which today means a developer build, says under Launcher updates: "Installers are published for Windows and macOS only; this build does not update itself." An AppImage build and its update path are planned; see the roadmap.