Major updates

A major version (1.x to 2.0) is the only one allowed to remove what an earlier version deprecated (see Versions and support). Its release notes list every removal and what to do about it. Read them first: the steps below are the same for every major version, the release notes say what is particular to this one.

Minor and patch versions need none of this: back up, update the town hall, then the agents.

Before

1. Update to the last minor version of your major version, and let it run a day. Of the previous major version, a new major version promises to accept the agents of that last minor version only. Each deprecation was announced by then, in the release notes, before it becomes a removal.

2. Read the release notes of the major version. For each removal they list (a key of the town plan, a route of the API, an event, an option of the command line), change your side now: most changes can be made while the old version still runs, since it accepted the new way for a whole minor version.

3. Back up the town hall, and keep the instance secret apart:

   npx @myrtillehq/cli backup --town-hall https://town.example.com --out myrtille-before-2.0.db

   The backup holds the accounts, the audit log, the state of the town plan and the encrypted credentials. The instance secret that reads them is not in it: MYRTILLE_SECRET, the file myrtille.secret of the volume, or SERVICE_HEX_64_MYRTILLE in Coolify.

4. Keep a copy of myrtille.yaml if the town plan is not in a git repository already.

Update, in this order

1. The town hall. With Coolify, redeploy the service (Install with Coolify); with Docker Compose, pull and start it again (Install with Docker Compose). Both follow the latest image: to choose when a major version arrives, give the image a version tag (ghcr.io/myrtillehq/engine:1.4.2; with Docker Compose through MYRTILLE_IMAGE, with Coolify in the image of the service) and change it here. The town hall migrates its database when it starts. If the town plan uses something the new version removed, the mail says the town plan is invalid: fix the plan, it is read again as soon as the file changes.
2. The Docker agents, on each server: redeploy their service so that it pulls ghcr.io/myrtillehq/agent of the new version.
3. The workstations. On each one: npm install -g @myrtillehq/cli, then start myrtille agent again, and run myrtille init --hooks once to refresh the hooks of Claude Code.

Until a workstation or a server is updated, its agent of the last minor version of the previous major version keeps working with the new town hall. An agent older than that is not supported: it may be refused when it connects, and its citizens then turn grey with the time they were last seen.

Check

• npx @myrtillehq/cli doctor --town-hall https://town.example.com checks the town hall, its couriers and their webhooks.
• The town shows every citizen in a known state, or grey with a time: grey means the town has no news, never that it guessed.
• The mail has no item that says the town plan was refused.

Go back

A town hall never opens a database that a newer version migrated. To go back to the previous major version:

1. Stop the service.
2. Restore the backup made before the update, with the image of the previous version (Install with Docker Compose and Install with Coolify show the restore command). The restore keeps the database it replaces beside it, and never deletes it.
3. Start the previous version again, and put the agents back to it too.

What happened in the town between the update and the restore (mail, audit entries, decisions) is in the database the restore set aside, not in the restored one.