Skip to content
AIOS

Upgrade and recovery

These instructions apply to v2.1.0. Confirm the exact tag and npm version are published before running an install. See the changelog for release status. Node 22, 24 and 26 are supported; Linux and macOS are the tested platforms. Preserve local work and inspect aios provenance --json to identify the installation actually invoked by your shell.

For a 2.0.0 → 2.1.0 upgrade, keep the existing format-2 stamp and base store; use the staged update below and review its managed-file changes. No new workspace is needed. MCP host setup is a separate optional step: run aios mcp install after upgrading, or accept the offer after a successful guided Brain connection. Package installation and aios update do not configure hosts automatically.

Stage before replacing the old package

Section titled “Stage before replacing the old package”

For every existing workspace, keep its recorded legacy installation intact until migration completes. From a clean workspace, stage the exact target in an owned prefix:

Terminal window
aios_release=2.1.0
aios_v2_stage=$(mktemp -d)
npm_config_engine_strict=true npm install --prefix "$aios_v2_stage" "@aiosbrain/aios@$aios_release"
"$aios_v2_stage/node_modules/.bin/aios" version --json
"$aios_v2_stage/node_modules/.bin/aios" update --repo "$PWD"
"$aios_v2_stage/node_modules/.bin/aios" doctor --json

Resolve conflicts and skipped dirty managed files, then repeat. Confirm stamp format 2 and a healthy base store. Review and commit .gitignore, .aios-toolkit-version, .aios/toolkit-bases and the managed-file changes together. The base store is workspace history; rollback snapshots and journals are private recovery state.

After all workspaces using the old prefix have migrated, replace the package in that same prefix. For a global install:

Terminal window
npm_config_engine_strict=true npm install --global "@aiosbrain/aios@2.1.0"
aios provenance --json
aios update
aios doctor --json

For a custom global prefix, retain its --prefix argument; for a local install, install into the original project and invoke its local .bin/aios. Do not guess a global target from a local invocation. Repeat update preserves the migrated stamp/base content; its sync timestamp may advance. The explicit aios update --self targets the invoked npm installation, while ordinary update changes workspace-managed content and never writes to an immutable registry source.

The older 0.12.0 baseline has a devtools pin that excludes Node 24/26 under engine-strict; relax that setting only for a required 0.12.0 install or rollback invocation. Keep engine-strict enabled for 2.0.0 and the candidate. If the old prefix was already overwritten, restore the exact previous package at its recorded path before staging.

Interruption and rollback

Section titled “Interruption and rollback”

Re-run the same installed version’s aios update --repo /path/to/workspace to resume. The journal records discovered, snapshotted, staged, validated and committed states; a dead owner’s lock is reclaimed. A changed target/stamp or corrupt bases is a refusal. Keep recovery evidence and restore stamp plus base store together; do not delete a journal to bypass the guard.

Terminal window
aios update --rollback --repo /path/to/workspace

The command checks the recorded installation, restores the pre-upgrade stamp/config snapshots and derives an exact reinstall command. It only runs that command after an interactive confirmation; in a noninteractive shell, execute the printed command yourself. If user configuration changed after the snapshot, rollback refuses before restoring any snapshot. Save those changes separately, reconcile them deliberately, and retry. If the installation can no longer be verified, restore the named exact prior package manually at its recorded prefix. Rollback does not discard arbitrary workspace changes.

Remove your owned staging prefix after successful migration and verification. Keep the workspace base store and recovery evidence needed by the release’s rollback policy.