Skip to main content

Upgrading

Plan an update when no mission is running. Updating or restarting the daemon can interrupt active work.

Preserve your data​

timon export --out timon-backup.tar.gz

Exports contain portable configuration and mission state, including the connections and message history of your messaging integrations, but exclude secrets. Preserve your secret material and backend authentication separately. Keep the previous application package until the new one has been checked.

Restore a backup on another machine​

timon service uninstall
timon import timon-backup.tar.gz --force
timon service install

Quit Timon from the tray or menu bar and uninstall the service first, so nothing holds the database open. Without --force, Timon refuses to import into a folder that already holds data. With --force, each part of the archive replaces what the install has: the agents of the backup become the agents of this install, and the main agent is the orchestrator you exported (the fresh _main of a new install disappears). The previous database is replaced as well. If Windows refuses to delete timon.db, Timon retries, then moves the old file aside as timon.db.replaced-<date>. If that fails too, the error gives the system codes: EBUSY means a process still holds the file (quit Timon, uninstall the service, try again); EPERM or EACCES is a permissions problem, usually a data folder copied from another Windows account — fix its owner with takeown /f %USERPROFILE%\.timon /r /d y, or import into a new folder with --to.

Projects point to folders on the machine they were created on. After the restore, timon import lists the projects whose folder does not exist on this machine. To leave every project out of the restore (the projects/ folder and the projects in the database), add --no-projects:

timon import timon-backup.tar.gz --force --no-projects

Secrets and backend sign-ins are not in the archive: reconnect your backends and re-enter your keys afterwards.

When a beta build ends​

A beta build and a beta licence both have an end date. Fourteen days before the earlier of the two, a banner tells you; it turns red for the last three days. After that date Timon shows a full-screen notice instead of the app:

  • This build has expired: install a newer build.
  • The beta has ended: your licence is over. This screen accepts a new key.

Both keep an Export my data button, so you can save your data before moving on. During the beta, Timon does not fall back to the Free plan when a licence ends.

Apply the update​

Install the new package supplied for your platform. No public release channel is assumed here.

On Linux and macOS, installing the package replaces the program, not the background service: the service runs from its own copy of the release inside your data directory, and keeps running the previous version until it is moved onto the new package. On Windows, the installer moves it.

Packaged daemons then wait for explicit approval before updating an existing database. This includes data from 0.1.0 that has no recorded version. A new installation without a database starts normally. Closing the application or restarting the service does not give approval. Until you approve, a timon command of the new package that opens your data (timon export, timon plugin…) stops with a message instead of updating them; timon update and timon doctor keep working.

With the desktop app. Quit Timon completely (from the tray or menu bar, not just its window), then open it again. It moves the service onto the new package, then asks you to approve the update.

Without the desktop app (a headless server, or a session over SSH), run these commands on the daemon host, as the OS user who runs Timon, not with sudo (set TIMON_HOME if you use a separate data directory):

timon update apply
timon update status
timon update approve <daemon-version>

timon update apply restarts the service on the installed package, checks that it answers, and ends with The service now runs Timon <version>. If the new service does not start, the previous one is restored, your data are not modified, and the details are in desktop-runtime/update-apply.log inside your data directory. When the service already runs the installed version, the command says so and changes nothing.

Then check that the daemonVersion returned by timon update status is the version of the package you installed: if it still shows the previous version, the service was not moved (timon update status and timon doctor say so and name the command to run). Approve that exact daemonVersion. Approval applies only to that version and requires no superadmin password. Timon saves a copy before migrating. If the copy fails, a destructive migration remains blocked; an additive migration can proceed with a warning. Check the returned result before continuing. Remote operators can run the same commands over SSH.

The copy is kept in backups/pre-<version>/ inside your data directory. It holds the database, the integrations database (connections and messaging history), the settings and the plugins. When only your plugins could not be copied (a partial backup), Timon tells you once: your databases and settings are saved, and restoring that copy leaves your plugins as they are. Keep your own copy of the plugins and plugins-data folders if you need them. When nothing could be copied, the desktop app tells you after each start, and Timon tries again each time it starts.

For an authorised source checkout, obtain the intended revision from your configured source, run npm ci and npm run build in orchestrator/ and app/, and restart the daemon using your OS supervisor from your own terminal. For a container-served app, rebuild that service instead of starting a second host app.

The configuration loader migrates supported older configuration versions and rejects a file newer than it understands. Do not edit the version number to bypass that check.

Verify​

timon service status
timon doctor
timon plugin list

Open the UI, inspect your projects and run a small mission. If the update does not work for you, see Going back to a previous version. If a plugin requires a newer SDK contract, update Timon or install a compatible plugin version; changing the manifest's version number does not add missing capabilities.