Update, Backup & Migration

The three components run on independent versioning tracks. Understanding their separation clarifies what actually changes when applying updates.

Component Update Matrix

Component	Update Method	What Updates	Required Restart
Core Program	WebUI Update tab (updater.*)	git pull source + dependency sync	Stop and restart instance workers
Desktop Launcher	Launcher self-updater (mTLS + mirrors)	Launcher binary itself	Restart launcher
Android Host App	System package installer overwrite	Kotlin / C++ host binaries	Restart app
Android Runtime	Host in-app Runtime updater	rootfs image (contains core source and frontend dist)	Restart Runtime
Android Core Scripts	Hot update channel	Upstream source + local frontend build	Restart Runtime

Backup Configurations Before Updating

Updates can introduce configuration schema migrations. Copying the entire config/ directory before updating provides a safe rollback path.

Core Program

The WebUI "Update" page displays upstream commits, local HEAD, and commit diffs:

1. Check updates (updater.status / updater.commits).
2. Fetch changes (updater.fetch).
3. Apply updates (updater.apply): stops all active workers, checks out new code, syncs dependencies, and restarts instances.

You can cancel downloads via updater.cancel. For Docker deployments, execute git pull and uv sync --frozen on the host before restarting the container.

Handling Post-Update Configuration Incompatibilities

Configuration templates are generated by module/config/config_updater.py, and legacy settings migrate on load. If fields are missing:

1. Diff config/<instance>.json against config/template.json.
2. Never manually edit args.json, menu.json, or config_generated.py—they are generated artifacts.
3. If migration fails, restore your backup and isolate the failing task group.

Desktop Launcher

On startup, the launcher updates the core repository (git pull with up to 20 retries) and runs uv sync --frozen. The launcher binary itself updates via a dedicated channel:

• Default manifest: https://launcher-api.azurpilot.com/updata/stable.json.
• Override via LAUNCHER_UPDATE_URL for private testing or mirrors.
• Binaries are verified over mTLS with fallback mirror redundancy.

Pass --skip-update to bypass repository git pulls when working offline or debugging startup crashes.

Android Host

Android features three independent update avenues; see Update, Backup & Maintenance:

• Host code changes → Install lightweight update APK over existing installation; Runtime and configurations remain intact.
• Runtime changes (dependencies, Python version, frontend toolchains) → Update rootfs image; stop services, replace image, retain /config.
• Upstream script changes → Hot update: diffs uv.lock; if dependencies match, pulls source and builds frontend locally; automatically rolls back upon failure.

Backup

Automated Backups

The core program enables automated daily backups by default (Alas.Backup.Enable, 7-day retention). Backups are written to the project root:

AzurPilot_Data_Backup/
└── 2026-10-20/
    ├── azurpilot.db
    ├── ap.json
    ├── ap-2.json
    └── backup_info.json

Backups include the global SQLite database and all instance configurations. The database is exported via the SQLite online backup API, flushing uncommitted WAL records.

Setting	Default	Description
Alas.Backup.Enable	Enabled	Executes on the first scheduling loop of each day
Alas.Backup.KeepDays	7	Directories older than this count are pruned

Manual Backup Checklist

Path	Contents	Mandatory
config/*.json	Instance configurations (task states and timestamps)	Yes
config/deploy.yaml	Server port, bind address, credentials, language	Recommended
config/remote-access.json	Device identity and paired client tokens	If retaining remote pairing
azurpilot.db (data dir)	Analytics, drops, resource historical records	If retaining statistics
log/	Execution logs and error dumps	For troubleshooting
AzurPilot_Data_Backup/	Automated backup archives	Optional

Keep Credentials Out of Source Control

Files like config/remote-access.json, config/deploy.yaml, and password.txt contain secret credentials. Never commit them to public Git repositories.

Migrating to Another Machine

01

Stop scheduler workers on the source machine

Terminate all running instances to avoid concurrent configuration writes during file copying.

01

Copy config directory

Copy config/ including deploy.yaml. Directory paths can differ on the target machine; configurations contain relative paths only.

01

Install AzurPilot on the target machine

Install the launcher or clone source, starting once to initialize .venv and dependencies before stopping it.

01

Paste configuration and launch

Overwrite config/ in the target project root and start the WebUI. Confirm all instances and task states are intact.

01

Reconfigure device-specific parameters

Update emulator serials, ADB paths, and screenshot backends for the new host. Because the account vault encrypts secrets with hardware-bound keys, credentials must be re-entered.

Rollback Procedures

• Core Program: Run git log to locate a stable commit, git checkout <sha>, and uv sync --frozen. Avoid git reset --hard to prevent losing uncommitted local tweaks.
• Configuration: Copy files from AzurPilot_Data_Backup/<date>/ back into config/.
• Android Runtime: The host retains the previous rootfs directory; hot updates roll back automatically upon build failure.
• Desktop Launcher: Download the previous release archive and replace the executable; .venv and config/ are untouched.