First Launch & Android Runtime
Initial execution on Android proceeds in two phases: deploying the Linux Runtime to private storage, followed by launching the core AzurPilot engine within that Runtime.
Provisioning State Machine
| State | Meaning | Action Required |
|---|---|---|
Checking | Validating existing installation | Automatic transition |
NotInstalled | Not deployed yet | Tap "Download Runtime" on Home screen |
NotBundled | Thin APK used; release lacks matching ABI | Switch to Full APK |
LowDisk | Less than 2 GB free storage | Free up disk space |
Downloading | Transferring payload (compressed bytes) | Wait for download |
Extracting | Unpacking payload | Wait for completion |
Ready | Provisioning complete | Ready to start |
Failed | Provisioning failure | Check reason and retry |
Provisioning requires manual initiation: even with the Full APK, you must tap "Download Runtime" to start extraction, preventing silent disk exhaustion.
Provisioning Phases
- If an interrupted deployment exists (
rootfs.previous), it is restored. - Compares
.provisionedmarkers,BUILD_MANIFEST, and device ABI. - Unpacks into
rootfs.tmp, performing an atomic directory rename torootfsupon completion to avoid partial corruption. - Preserves
config/(SQLite and instances),password.txt, andlog/. - Writes the new version marker and marks state
Ready.
Downloads utilize 4 parallel connections when payloads exceed 8 MiB with HTTP Range support, falling back to a single stream upon network failure. Payloads are verified against SHA-256 hashes.
Why First WebUI Boot Takes Time
Pre-compiled __pycache__ files are stripped from distribution images. On first launch, Python must compile all bytecode on-device, often requiring over 90 seconds. The log reports:
AzurPilot WebUI not ready within 90000msThis is an expected warning, not an error. The server becomes ready shortly afterward; subsequent boots load at standard speed.
Do Not Force-Kill the App During First Boot
Force-killing leaves stale locks and orphaned sessions. Allow initialization to finish, or tap "Stop Runtime" inside the app for graceful termination.
Essential App Permissions
| Permission | Purpose | Impact if Denied |
|---|---|---|
| Notifications | Foreground service, pairing codes, task alerts | Cannot view pairing codes in notifications |
| Battery Optimization Exemption | Background execution survival | Process terminated when screen turns off |
| Display Over Other Apps | Global floating controller | Cannot display overlay panel |
| Install Unknown Apps | In-app APK updates | Must download and install updates manually |
| All Files Access (Optional) | Export logs to public folders | Logs export to private storage only |
Device OEM settings may include additional toggles for "Autostart", "Background Popups", and battery savers.
Privilege Activation
Local execution requires privileged shell access to create virtual displays, capture screens, and inject touch inputs:
| Method | Target Android Version | Configuration Path |
|---|---|---|
| Built-in ADB (Recommended) | Android 11+ | Settings → Operation & Security → Built-in Shizuku |
| Root | Rooted devices | Same screen; select Root |
| External Shizuku / Sui | Existing Shizuku installation | Same screen; select External Service |
Review Privilege Activation for comprehensive setup steps.
Starting Runtime
- Verify Runtime status displays
Readyon Home. - Tap "Start".
- Wait for the status indicator to transition to running.
- Open "Console" to access the embedded WebUI.
The embedded WebUI matches the desktop version, listening on 127.0.0.1:25548 inside the Runtime. The host's AzurPilotGateway serves as the exclusive subscriber to /api/v1/ws.
Creating Your First Instance
Console → Installed Configurations → New. Name it ap or choose a custom identifier.
Select the package name corresponding to your game client.
The Android host strictly requires the azurpilot_android screenshot and control backend. Standard ADB backends cannot access the virtual display.
Enable "Research" or "Harvest" and set the next execution time to current.
Monitor the Automation view for live screen streaming and verify task start/finish messages in logs.
Verification Checklist
| Check | Passing Standard |
|---|---|
| Runtime Status | Continuously running without restarts |
| Video Stream | Automation view renders the live game screen |
| Console | Instance list and task settings load successfully |
| Task Execution | Logs output task lifecycle; game state updates |
| Backgrounding | Switching apps for 5 minutes does not interrupt tasks |