Update to a later engine

Move this instance to a later engine release. The swap runs on the host beside your compose file, and moves the pin the engine service runs on.

Before you start

• Install Revetly from the handout and start the stack
• You have shell access on the host Docker runs on.

Configuration page

Command line

1. In a terminal at the project root, read the image this instance pins:

   revetly doctor
   

   [PASS] engine         running the image docker-compose.yml pins …
   

   Revetly answers this line only from inside the engine service, so run it there as Run a revetly command says.

2. Ask what is published, and install nothing. If that release reads only from a revision later than your data holds, --check stops and Troubleshooting says what installs it.

   ./revetly-update --check
   

   You should see Run ./revetly-update to install it. (as the update script shows it)

3. Install it. Leave watch alone — the swap recreates the engine container, the loop stops with it, and where [watch] enabled = true the engine starts the loop again by itself once the container is back, a key an instance that relied on interval alone needs from 0.6.0 on.

   ./revetly-update
   

   You should see Reconnect your editor's MCP client (/mcp in Claude Code) to reach the new engine. (as the update script shows it)

4. Read which engine answers now:

   revetly --version
   

   Revetly <VERSION> (commit <COMMIT>)
   

5. Price the revision this release is owed. Revetly refuses every read and write against a corpus below the revision it reads from, and context_health and revetly doctor name the step — an update from 0.6.0 or 0.7.0 owes none, and one from 0.5.0 owes two, to revision 7 and revision 8, neither calling a provider.

   revetly migrate
   

   <COUNT> step(s) from revision <REVISION> to <ENGINE>:
     -> <REVISION>: <WHAT_THE_STEP_DOES>
   No artifact has to be read again. This migration calls no provider and costs nothing.
   

6. Apply it. If a pass is running, Revetly waits up to 900 s for it to land, and past that stops with REFUSED — the pass is still running after 900s and changes nothing — run this step again once that pass has landed.

   revetly migrate --apply
   

   Corpus is revision <ENGINE>. `revetly doctor` confirms it.
   

7. Read that your data is now what this engine reads:

   revetly migrate
   

   Already at revision <REVISION>. Nothing to migrate, nothing changed.
   

8. Start the loop again only where you started it by hand, as Run watch unattended describes:

   docker compose exec -d revetly revetly watch
   

   Leave the compose prefix on this one — -d is a compose flag, and the loop belongs inside the engine service.

Troubleshooting

• The container is still the image it was before. It was left up from the earlier image. Restart the service so it runs the pin.
• The release cannot read the corpus as it stands. --check stops with <VERSION> reads corpus revision <READS_FROM> and up; your data is revision <REVISION>. It needs a migration before that release can read it, and ./revetly-update --migrate-ok is what installs it. That install ends on YOUR DATA STILL HAS TO BE MIGRATED., because the migration runs after the swap, in the engine that reads the new revision — steps 5 to 7 above.

Next steps

• Run watch unattended
• Move an instance