self-update

how it works

The self-update is handled by the service command handler in owlette_service.py:

1. Receives an update_owlette command from Firestore.
2. Requires installer_url and checksum_sha256; reads target_version when provided and otherwise tries to infer vX.Y.Z from the installer URL.
3. Rejects the command if another update marker is less than 10 minutes old.
4. Checks for at least 500 MB of free disk space.
5. Downloads the installer to %ProgramData%\owlette\tmp\owlette-Update.exe with retry/backoff.
6. Verifies the file looks like a Windows executable and matches the supplied SHA-256 checksum.
7. Writes %ProgramData%\owlette\logs\update_in_progress.json so the next service start can report the update result.
8. Creates and runs an OwletteUpdate_* scheduled task as SYSTEM with highest privileges. The task launches the installer with /VERYSILENT /NORESTART /SUPPRESSMSGBOXES /ALLUSERS /LOG="<path>".
9. Creates an OwletteRecovery_* scheduled task that waits about five minutes, checks whether OwletteService is running, and starts it if needed.
10. On the next service start, checks the update marker, compares agent/VERSION with the target version, reports success or failure to Firestore, and removes stale update/recovery tasks.

The service does not stop itself and run the installer inline. Task Scheduler owns the installer process so it can continue after the service stops.

triggering an update

from the dashboard

1. Open the deploy page in the dashboard.
2. Click update owlette in the page header. The button is only shown while at least one machine on the current site is behind the latest installer.
3. Select the machines to update. Only outdated machines are listed, and an offline machine cannot be selected — the agent has to be online to receive the command.
4. Confirm the update.

The dashboard uses the current latest installer metadata automatically and sends an update_owlette command with the installer URL, expected SHA-256 checksum, and target version.

on the machine itself

The installer runs with /VERYSILENT, so nothing appears on screen. Setup closes the owlette desktop app before it copies files, so the window and the tray icon both disappear for the length of the update — that is expected, not a crash. The installer does not bring them back: the service relaunches the desktop app in tray mode as soon as it starts again.

what gets preserved

The installer upgrades in place and avoids deleting the ProgramData configuration, token, log, cache, and temp directories. It does not perform a separate config backup/restore step.

update command payload

{
  "type": "update_owlette",
  "installer_url": "https://firebasestorage.googleapis.com/.../Owlette-Installer-v2.1.8.exe",
  "target_version": "2.1.8",
  "checksum_sha256": "2f4c2f0e6d8f0c2f2a4f6f7a8b9c0d1e2f3a4b5c6d7e8f90123456789abcdef0",
  "deployment_id": "deploy_abc123"
}

Required fields:

version verification

After the update completes:

1. The service starts and reads the installed version from agent/VERSION.
2. The startup check reads %ProgramData%\owlette\logs\update_in_progress.json.
3. The agent compares the installed version with target_version.
4. The command is marked completed or failed in Firestore.
5. The next heartbeat reports agent_version.

troubleshooting updates

update stuck

If the machine goes offline and does not come back:

1. Check the machine physically if remote access is unavailable.
2. Open the desktop app from the start menu (Owlette). The service is what relaunches it, so it will not be in the tray while the service is down. Opening the app attempts to start the service on its own, and its status footer keeps a start service button — either may raise a single UAC prompt.
3. Read the logs. The app menu (☰) → logs opens %ProgramData%\owlette\logs, and the start menu's View Logs shortcut opens the same folder without the app:
   • service.log — the agent's own account of the update.
   • installer_update.log — what the installer did.
   • update_in_progress.json — old version, target version, command ID, and deployment ID. The service deletes this file on its next start, so finding it still present means the service has not come back.
4. Check for leftover OwletteUpdate_* or OwletteRecovery_* scheduled tasks. OwletteRecovery_* should already have tried to start the service about five minutes after the update began.
5. Start the service manually with net start OwletteService from an elevated prompt if the desktop app is unavailable.

version did not change

If the agent reports the same version after update:

1. Review %ProgramData%\owlette\logs\installer_update.log for installer failures.
2. Confirm the installer URL was reachable from the target machine.
3. Confirm the checksum_sha256 value matches the exact installer binary.
4. Confirm target_version matches the version embedded in the installer.

rollback

To roll back to a previous version, trigger another update_owlette command that points to the older installer and includes that installer's SHA-256 checksum.