Update & recovery reference

The app and Øphio on the computer have no built-in updater. Neither downloads or installs updates of itself; Øphio can keep the agents it runs up to date (below). Update a store-installed Android app through its store. For a sideloaded app or Øphio on the computer, obtain the new package from the same trusted source as the installed version. Settings → Versions shows the app version, installer when Android reports a recognized store, the version of Øphio on the computer and the negotiated protocol.

A connection requires a protocol version supported by both installations. An incompatible connection leaves remote actions unavailable; phone drafts, Inbox items and downloaded files remain local. Update the side named by the connection error. Older versions on the computer may not report their supported versions; in that case compare the two packages from their original source before updating.

Before updating Øphio on the computer, finish or stop active work and confirm it has stopped. Close Øphio. Keep a backup of its data directory and configuration using the same access protections as the originals. Install the new package and start it. Confirm the paired identity and access grants before running work.

Øphio on the computer stores its journal, projection records and command outcomes in SQLite. Before each schema migration it creates a backup beside the database: <database-stem>.before-v<destination-schema>-<id>.sqlite. For example, migrating companion.sqlite to schema 1 creates companion.before-v1-<id>.sqlite. The backup includes committed WAL pages. A successful transaction changes the schema; a failed transaction does not leave a partially applied migration. Added optional record fields can load with their specified defaults without a schema migration.

Stored commands from older releases remain readable even when a newer app must send additional safety information. For example, old permission-change history may lack the editor’s expected grants; a new request without that baseline is refused with an instruction to update the app. Pending commands recovered after a restart require review and are never automatically sent again.

If an individual stored command cannot be decoded, Øphio keeps its original bytes, permanently reserves its command ID, and records an unknown outcome requiring reconciliation. The service log includes the command ID and a decode diagnosis without the stored values. Managers can see the unknown outcome in the journal; retries of that ID are refused. Review the actual effect before issuing a new command. A malformed ID stays reserved locally but cannot be represented as a journal command ID.

Startup still refuses unreadable authority/projection documents or database failures: skipping permission, task, or approval state could allow unsafe work, and a failed recovery transaction cannot durably record an unknown outcome. Journal decoding also remains strict; skipping journal entries could conceal effects. Startup diagnostics are written to the service log as well as printed by ophio run. Release compatibility fixtures and their refresh procedure are in crates/store/tests/compatibility.rs.

To roll back:

Stop Øphio and confirm it is no longer running. Preserve the current database, its -wal and -shm files, configuration and the migration backups in a separate protected directory.
Reinstall the previous Øphio package from the same trusted source.
Restore the backup made before the first migration that the previous version cannot read, using the database’s original filename. Move the newer database and its WAL/SHM files aside together; do not leave a newer WAL next to the restored database. Keep the backups until recovery is verified.
Start the previous version and check its identity, grants and records. An older version refuses a newer schema instead of attempting a downgrade. If it still refuses, use a compatible backup or reinstall the newer version.

Restoring a database loses records on the computer written after that backup. It does not undo project files, terminal commands, agent work, transfers already written to disk, or changes to outside applications. It does not roll back the Android app, phone drafts, downloads or native agent accounts. Pairing and revocation records also return to their backup state: review device/channel access before reconnecting. Never assume a restored record proves an external action was undone.

Keeping Claude Code and Codex up to date

Øphio can keep its own copies of Claude Code and Codex at their makers’ newest releases, so new models show up without anyone updating the computer. It is off until you turn it on: ophio setup asks once in its Agents step and recommends it, and Settings › Agents and accounts › Keep Claude Code and Codex up to date in the app turns it on or off. Changing it from the app needs the Manage access permission.

While it is on, Øphio checks when it starts and every six hours. For each agent installed on the computer it downloads the newest release’s program for this computer’s system from the npm registry, where Anthropic and OpenAI publish them; checks it against the checksum the registry publishes; and starts it once with --version. Only a copy that passes all three is used, from the next task on. Each check starts the copy in use the same way; one that no longer starts is set aside, so tasks use the computer’s program until a new copy replaces it. Tasks already running keep the version they started with, which stays until the following update. The settings card shows each copy’s version, when it was last checked, and why a check or download didn’t finish.

Tasks and terminals Øphio starts then use its copies. The Claude Code and Codex installed on the computer stay as they are, with the same sign-in, settings and history; Øphio’s copy of Claude Code starts with its own updater off so it never installs over the computer’s. The copies live in agents/ in Øphio’s data directory and take up to about 1.5 GB. Turning the setting off sends the next tasks back to the computer’s programs and removes the copies; the one tasks were last using stays for those still running until the next check or restart.

Upgrading from the earlier companion program

Before the product was named Øphio, the program on the computer was called companion. Upgrading keeps the computer’s settings, identity, paired devices and history:

On Linux, run the new archive’s install.sh, then ophio service install. packaging/linux/INSTALL.md lists the steps.
On Windows, stop the earlier companion.exe before running any ophio.exe command: close its window, or end it in Task Manager. Øphio’s commands cannot reach the earlier program while it runs, and its folders cannot move until it stops. Then run .\ophio.exe service install from the new directory; it starts Øphio, replaces the logon registration the earlier program made and leaves any other alone.
When Øphio starts, it renames the earlier folders to its own: ~/.config/companion and ~/.local/share/companion on Linux, %APPDATA%\companion and %LOCALAPPDATA%\companion on Windows. A folder that already exists under the new name is never merged into or replaced.
If the earlier program is still running, or a folder cannot be renamed, for example because the new name is on another filesystem, Øphio says what happened and keeps using the old folder. Stop the earlier program or fix the cause, then start Øphio again.
The Øphio app for Android has a new app ID, so it installs beside the earlier app instead of replacing it. Pair it with ophio pair as a new device, then remove the earlier app and end its access with ophio devices revoke.

To go back to the earlier program, stop Øphio and rename its folders back to the earlier names before starting the earlier program.