Android Update, Backup & Maintenance

The Android host maintains three independent update channels:

The Three Update Channels

Channel	Updated Content	Trigger	Data Retention
App (APK)	Kotlin host, native bridge, UI	In-app check / APK overwrite	Yes
Runtime (Full)	Ubuntu rootfs, Python, dependencies, OCR	Manual toggle in Settings	Yes (preserves config / logs)
Script Hot-Update	Upstream AzurPilot source + frontend dist	Automatic (idle) / manual	Yes

App Updates

• Lightweight thin APKs target specific ABIs without bundled rootfs payloads, keeping downloads minimal.
• Downloaded packages are verified against SHA-256 hashes before passing to the system package installer.
• Signing certificates must match: Debug and Release builds cannot overwrite each other; doing so causes INSTALL_FAILED_UPDATE_INCOMPATIBLE requiring full uninstallation.
• Downgrading version codes requires adb install -r -d.

Runtime Full Updates

Evaluation relies on BUILD_MANIFEST.rootfs_version:

<upstream-commit-first-12>-<build-input-hash-first-10>

• Matching input hash with different commit → Sets commitOnly; handled via script hot-update.
• Differing input hash → Requires full rootfs redeployment (Python, system libraries, overlays, or dependencies changed).

Full updates preserve config/ (SQLite and instance configurations), password.txt, and log/.

Script Hot-Updates

Hot-updates swap source scripts and pre-built frontend assets without altering the underlying Python binary:

1. Evaluates target commit on upstream tracking branch.
2. Shallow-clones the commit into /opt/azurpilot-update/source (prioritizing CNB mirrors with GitHub fallback).
3. Compares uv.lock: If lockfiles differ, sets requiresRuntimeUpdate=true and aborts hot-update in favor of full deployment.
4. Executes npm ci and npm run build in a temporary directory (600s timeout).
5. Writes a transaction record and halts running instances.
6. Backs up previous dist → Swaps source code → Installs new dist → Atomically updates manifest → Restores instances.
7. Reverts to prior source, dist, and manifest on any failure.

Hot-Updates Do Not Install Python Dependencies

Dependency installations are intentionally blocked during hot-updates to prevent unverified libraries from entering production. Any change to uv.lock requires a full Runtime update.

Automatic hot-updates run only when instances are idle. Hot-updates and full deployments share a unified pipeline lock.

Selecting the Right Update Channel

Scenario	Recommended Channel
Routine upstream automation script updates (no dependency changes)	Script Hot-Update
Upstream modifies uv.lock or Python dependencies	Full Runtime Update
UI enhancements or native bridge bugfixes	App APK Update
Device migration or clean reinstallation	Full APK + Restore config backup
Crashes following a hot-update	Inspect transaction log; rollback or run full update

Backup Checklist

Content	Path	Importance
Instance Configurations	Runtime config/*.json	Critical
Server Configuration	config/deploy.yaml	Contains credentials
Analytics Database	config/azurpilot.db	Historical records
Diagnostic Logs	log/ and proot/session.log	7-day rotation
Remote Pairing Tokens	config/remote-access.json	Preserves fixed tunnel endpoints

Export options:

1. Settings → Logs → Export (generates a zip archive).
2. Command line: adb pull /sdcard/Android/data/com.azurpilot.ghio/files/.

Uninstallation Deletes All Data

Uninstalling the app wipes the Linux Runtime, instance settings, and logs without keeping cloud copies. Export settings before removing the app.

Troubleshooting Common Failures

Runtime Fails to Start

Symptom	Verification Check
Status NotInstalled	Tap "Download Runtime" on Home screen
Status LowDisk	Ensure device has ≥ 2 GB free internal storage
Status NotBundled	Verify architecture matches release packages
Status Failed	Expand error reason; switch download mirrors and retry
WebUI loading exceeds 90s	First-time bytecode compilation is running; wait for completion

Immediate App Crashes

• Architecture mismatch (e.g. attempting to run an x86 APK on an ARM processor).
• External storage inaccessible on startup.
• Incompatible signature during update installation.

Permissions Revoked in Background

Device OEM battery managers may revoke granted permissions:

• Overlay permission revoked → Floating panel disappears.
• Battery optimization reset → Process terminated when display sleeps.
• USB debugging authorization cleared → Privileged service dies; re-pair required.

Solution: Re-grant permissions and ensure the app is added to OEM Autostart whitelists.

Task Interruption Causes

Diagnostic Clue	Root Cause
Logs abruptly cut off with no stack trace	Process killed by OS low-memory killer (LMK)
EmulatorNotRunningError	Virtual display or privileged bridge crashed
Repeated consecutive ScriptError entries	Upstream automation bug; check for updates
Crash following hot-update	Inspect config/android-update-transaction.json to verify rollback
Frontend compilation timeout	Device performance or storage constraints during on-device build

Diagnostic Commands

# Stream app logs
adb logcat -v time --pid=$(adb shell pidof com.azurpilot.ghio)

# Inspect Runtime session logs
adb shell tail -n 200 /sdcard/Android/data/com.azurpilot.ghio/files/log/proot/session.log

# Forward WebUI port to PC browser
adb forward tcp:25548 tcp:25548

Windows users can utilize tools/watch-android-logs.ps1 to track com.azurpilot.ghio logs automatically.