Before changing versions
Record the active config, Aion home, data directory and running build identity. Take a stopped-writer backup and retain the old binary with its configuration.
Read the target’s changelog and release availability. The public release and main both report 0.31.0, with different source commits and feature sets.
Registry release update
Install a version of Aion and hand the running server over to it.
aion update [OPTIONS]-
--version <VERSION> - Version to install. Absent, the latest STABLE version the package index publishes — the same version a plain `cargo install aion-cli` would fetch
-
--config <CONFIG> - Path to the TOML server configuration file. Used to resolve the drain patience when the running server's record carries none, to find the store the downgrade guard and the forward step read, and passed to the installed binary's `store migrate-package-rows` and to the successor as `aion server --config`
-
--patience <PATIENCE> - Seconds to wait for the running server to begin draining, and the cadence of the "still waiting" line while it finishes its stop. Absent, the running server's own recorded stop budget governs (drain window + twice the managed-worker stop grace + the fixed harness termination grace), then the stop budget its config describes.
- With no version, targets the latest stable crates.io build: currently 0.31.0 from 18 September 2026, which predates this main code. An installation can replace newer main code with that published build.
- Matching package version strings can return already current despite different source commits. The installer uses Cargo’s default features; install explicitly with --features auth to retain JWT verification.
The installation step uses Cargo’s default features. For JWT servers, install the selected package explicitly with the auth feature as shown in installation.
For a main installation, build the selected authorized checkout with its required features. Use that binary’s store migration and local restart commands during the planned handover. Read back its build commit and readiness.
For a registry update, installation happens first. A failed install leaves the running process serving.
When handing over a server, main’s updater asks it to drain and invokes the target binary’s package-row migration before starting it. Choose a target that supplies that migration command; the current public crate predates it. A completed handover reports the old and new identities. If the successor fails to boot after a successful drain, it reports that no server is serving.
Store shape and downgrade
A newer store can contain split package rows. An old binary unable to read that layout is refused before installation or signalling. Use the recorded pre-split copy when one is available, or your own backup; do not downgrade a binary over an incompatible store.
The offline migration command is idempotent. It requires the writer to be stopped and refuses rather than sharing an open store.
Split every deployed-package row still in the joined shape into a head row and an archive row.
aion store migrate-package-rows [OPTIONS]-
--data-dir <DIR> - The store's data directory. Defaults to `store.data_dir` from the configuration this machine's server would load
-
--config <FILE> - Explicit configuration file, read for the data directory and for the store's node-cache budget
- Requires a newer main build; the public 18 September 2026 crate lacks this command.
Configuration changes
Boot can insert missing required file settings while preserving the prior file beside it. Read those changes. Unknown, invalid and retired inputs still have their documented refusal or warning behavior.
Verify the successor
Read status, build identity, readiness and loaded routes. Confirm that important existing runs recovered and their workers registered.
On main, crates/aion-cli/src/update.rs:81–85 selects the registry version. crates/aion-cli/src/update.rs:329–359 performs installation. Version comparison is at crates/aion-cli/src/update.rs:273–300. Select a version or reinstall the authorized checkout; preserve the auth feature explicitly.