Update Watcher

Update the self-hosted server first. Watcher clients installed with the public installer then follow the server version automatically or when you run watcher update.

Update the server

1. Back up the database and deployment configuration.

2. Verify and unpack the new self-host bundle beside the current bundle. Read the new WATCHER_IMAGE_TAG from the bundle's .env.example. If you use an internal registry, import the new tag for xylon-api, bootstrap, and analyzer before continuing.

3. From the current deployment directory, run:

   cp <new-bundle>/docker-compose.yml docker-compose.yml
   sed -i 's/^WATCHER_IMAGE_TAG=.*/WATCHER_IMAGE_TAG=<new-tag>/' .env
   docker compose pull
   docker compose up -d

4. Confirm the update:

   docker compose ps -a
   docker compose logs watcher-bootstrap
   curl -fsS "http://localhost:$(docker compose port analyzer 80 | sed 's/.*://')/api/v1/health"

The bootstrap container should exit successfully after applying database migrations. Refresh any release-owned files you use from support-bundle.sh, scripts/, auth-proxy/, prompts/, and modules/. Preserve your .env, server-config.yaml, Compose overrides, certificates, and proxy configuration.

If you use the bundled Terraform module, update it separately and review terraform plan. Read Replace the instance before applying a plan that replaces the host.

To roll back, stop the stack, restore the previous docker-compose.yml and WATCHER_IMAGE_TAG, and run docker compose pull. Then follow the restore procedure with the pre-update database backup. This starts the previous server release against the restored database.

Update Watcher clients

A client installed with the public installer and running through its login service checks every two to two-and-a-half hours. It reads the configured server's version and installs that client release, including moving back to an older release after a server rollback. Sign-in and local settings are kept.

To update immediately on one machine, run:

watcher update
watcher --version

Clients running only in the foreground do not check automatically. Run watcher update for those clients.

Clients installed from an internal mirror do not update themselves. Publish the approved client release to the mirror and redeploy it through your fleet tooling. An MDM installation that uses the public installer can rely on the built-in update check while the MDM continues to repair the installation.

See Client deployment for installation paths and MDM rollout for managed fleets.