Safely Upgrade a Self-Hosted EmperorClaw Instance

Before upgrading

Read the release notes and check for new environment variables, Compose profiles, migrations, or storage actions. Schedule a quiet period for meaningful releases so agents are not claiming or writing work during the transition.

Export a PostgreSQL backup.
Snapshot or copy the artifact storage volume.
Save the current .env and Compose configuration securely.
Record the currently deployed image tag.
Confirm that the backups can be read.

Use the update script

Installations made with the one-line installer include an update script. Run it from the install folder (~/emperorclaw by default). It pulls the new prebuilt image and recreates the services.

bash scripts/update.sh --docker

# Windows PowerShell
.\scripts\update.ps1 -Docker

To do it by hand, pull the image and recreate the services. No Git checkout or local build is involved:

docker compose pull
docker compose up -d

Source installs (a Git checkout built with Node.js) use ./scripts/update.sh without --docker.

Database migrations

The application runs registered migrations during startup. EmperorClaw release migrations are designed to be additive: they add tables, columns, or indexes without dropping existing business data. Do not replace this process with drizzle-kit push in production.

Watch startup logs until migrations complete. If a migration fails, stop and investigate before repeatedly restarting every service.

Verification checklist

Confirm every container is healthy and stable.
Open the dashboard and check the displayed version.
Open an existing customer, project, task, and Company Brain note.
Download an existing artifact and verify its contents.
Send a test message to an agent and confirm its reply stays in the correct thread.
Check integrations and the update banner.

Rollback

If the new application cannot operate safely, stop it, restore the matching database and storage backups, restore the previous Compose configuration, and start the previous tag. Rolling back only the image while retaining migrated state is not a complete recovery plan.

Every release is published as its own image tag. Pin the previous one in docker-compose.yml (the app service uses :latest by default), then pull and recreate:

# docker-compose.yml, service "app":
#   image: ghcr.io/emperorclaw/emperorclaw:v0.8.103
docker compose pull app
docker compose up -d app

Switch the line back to :latest when you are ready to upgrade again.

Special note for version 0.8.0

Version 0.8.0 adds the storage mirror schema and real filesystem folder layout. After the normal migration, preview storage reconciliation and then apply it before enabling Google Drive:

docker compose exec app npm run storage:reconcile
docker compose exec app npm run storage:reconcile -- --apply

The command is idempotent and preserves existing artifact IDs. Google Drive remains optional; installations that do not enable its Compose profile continue using the normal storage path.