---
title: Update, Backup & Migration
description: Update channels for core, launcher, and Android host; config backup locations, restore flows, and machine migration.
updated: 2026-10-20
---

# Update, Backup & Migration

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

## <DocIcon name="refresh" /> 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 |

::: warning Backup Configurations Before Updating
Updates can introduce configuration schema migrations. Copying the entire `config/` directory before updating provides a safe rollback path.
:::

## <DocIcon name="zap" /> Core Program

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

1. <DocIcon name="search" /> Check updates (`updater.status` / `updater.commits`).
2. <DocIcon name="download" /> Fetch changes (`updater.fetch`).
3. <DocIcon name="zap" /> 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. <DocIcon name="search" /> Diff `config/<instance>.json` against `config/template.json`.
2. <DocIcon name="ban" /> Never manually edit `args.json`, `menu.json`, or `config_generated.py`—they are generated artifacts.
3. <DocIcon name="refresh" /> If migration fails, restore your backup and isolate the failing task group.

## <DocIcon name="rocket" /> 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:

- <DocIcon name="cloud" /> Default manifest: `https://launcher-api.azurpilot.com/updata/stable.json`.
- <DocIcon name="file-pen" /> Override via `LAUNCHER_UPDATE_URL` for private testing or mirrors.
- <DocIcon name="lock" /> Binaries are verified over mTLS with fallback mirror redundancy.

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

## <DocIcon name="smartphone" /> Android Host

Android features three independent update avenues; see [Update, Backup & Maintenance](/en/android/user/maintenance):

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

## <DocIcon name="drive" /> 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:

```text
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 |

::: danger 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.
:::

## <DocIcon name="laptop" /> Migrating to Another Machine

<Steps>
<Step title="Stop scheduler workers on the source machine">

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

</Step>
<Step title="Copy config directory">

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

</Step>
<Step title="Install AzurPilot on the target machine">

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

</Step>
<Step title="Paste configuration and launch">

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

</Step>
<Step title="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.

</Step>
</Steps>

## <DocIcon name="refresh" /> Rollback Procedures

- <DocIcon name="refresh" /> **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.
- <DocIcon name="drive" /> **Configuration**: Copy files from `AzurPilot_Data_Backup/<date>/` back into `config/`.
- <DocIcon name="smartphone" /> **Android Runtime**: The host retains the previous rootfs directory; hot updates roll back automatically upon build failure.
- <DocIcon name="medal" /> **Desktop Launcher**: Download the previous release archive and replace the executable; `.venv` and `config/` are untouched.