Updating

Chrysalis and your apps update separately. Neither kind of update touches your data.

#Chrysalis itself

When a new version is out, admins see an Update to X button at the bottom of the launcher and in Settings > Server. Chrysalis only checks when one of those opens, never in the background.

If the button says Chrysalis cannot replace its own files, its folder is somewhere your account cannot write to (such as Program Files). Move the folder somewhere you own, like your home folder, and try again.

#If an update goes wrong

A download only replaces anything once it has proven itself:

1. It must match the size and checksum the release publishes.
2. The new version must start on your computer and report the version the release names. A build that cannot run there stops the update while the old program is untouched.
3. After the restart, the old version waits in the background until the new one has been serving for 15 seconds. If the new version stops before that, the old program and your account files are put back, the old version starts again, and Settings > Server says what happened.

The old program is kept beside the new one until the next time Chrysalis starts. If the page is still waiting after five minutes, it stops and tells you to check the window or log where Chrysalis runs.

Before an update, Settings > Server also names installed apps that say they need a different version of Chrysalis.

#Going back to an older version

Chrysalis records the data layout it last used in format.json in the data folder. A newer version may upgrade that layout; an older version then refuses to start and says which version to install, rather than reading data it does not understand and damaging it. Your data is not changed.

#Staging installs

A staging copy follows the staging pre-release instead of stable releases: whenever a newer staging build is published, it is offered. On Android the button reads Get the latest staging build. Docker users pull the :staging tag.

#If Android will not install over the old app

Android only replaces an app with one signed by the same key. Every official APK is signed with the project's release key, so updates install in place. If you once installed a build signed differently (for example one you built yourself), Android refuses with App not installed or a conflict message. Export backups of your apps, uninstall the old app, install the new one, and import the backups.

#Apps

Apps installed from the Store or from a git repository update from that repository. The launcher checks when it opens and puts an Update badge on apps with something new. Select the app to see what changed and click Update.

#Your edits are kept

You and the agent can change any app. An update is a merge, not a replacement:

• Files you did not change get the new version.
• Files only you changed keep your version.
• Files you both changed are merged line by line.

When your edits and the update change the same lines, nothing is written until you choose:

An app's data folder (your chats, characters and everything else it stores) is never replaced by an update. Before every update, your workspace is saved to its history, so any update can be walked back.

#All or nothing

• If a file cannot be written (a full disk, a file another program has open), every file the update touched goes back and nothing changes.
• One update of an app runs at a time, even with the app open on several devices.
• When an update changes an app's packages, they are installed over the ones it has. If the install fails, the app keeps its old packages and the update says so.
• Importing an app you already have from the same repository is refused. Use Update, which keeps your edits.

#Data upgrades

A new version of an app can upgrade the data an older version stored, like moving chats to a new format. If that upgrade fails, the update tells you which part failed, and it is tried again the next time the app is used, starting from the version your data still has. Your data stays as it was until the upgrade succeeds.

#What gets reviewed

For community apps, an update stops and asks before it:

• installs, changes or removes npm packages, listing each one and flagging any that come from outside the public registry;
• gives one of its plugins a permission it did not have before.

Click Allow and update to go ahead. If the repository changes between that review and your click, Chrysalis refuses and asks you to check again, so you only ever approve what you saw. Official apps skip this review.

#When an update needs a newer Chrysalis

An app can say which Chrysalis versions it needs. For apps on GitHub, the launcher shows the new version number and says so before you click Update. Either way, the update stops before changing anything and says which version it needs. Update Chrysalis first.

#Plugins you added to an app

Plugins that came with an app update with the app. A plugin you imported into an app yourself updates on its own: open the app's Plugins dialog and click Check for update next to it. You see the new version and its permissions before anything changes, and the update replaces the plugin in place. App updates never remove a plugin you imported.