Installation
Verify Environment & Compatibility before installing. The four installation paths below are ordered by recommendation; desktop users should use the launcher.
Desktop Launcher (Recommended)
Download
Download the archive matching your operating system and CPU architecture from the Official Download Page or GitHub Releases. Mainland China users should select the -cn mirror edition.
Extract and Launch
The launcher initializes .venv, clones the core repository, and saves configurations inside its directory. Do not place it in temporary folders, read-only locations, or sync drives with poor multibyte character handling.
- Windows: Double-click
alas-launcher.exe. Administrator privileges are requested (for ADB installation and system directory writes) via UAC. - macOS: Open
AzurPilot.app. Unsigned binaries may trigger Gatekeeper blocks; see instructions below. - Linux: Run
chmod +x alas-launcher && ./alas-launcher.
The splash screen displays: Create .venv → Download Python 3.14.6 → Update repository → uv sync --frozen. Initial setup requires internet access and takes several minutes depending on network bandwidth.
The window opens authenticated directly into the AzurPilot WebUI. The launcher binds to port 22267 by default (the core program standalone default port is 25548).
macOS Gatekeeper Warnings
The binary lacks Apple developer signatures. If macOS reports that the developer cannot be verified, run:
xattr -dr com.apple.quarantine /Applications/AzurPilot.appThen reopen the app. Avoid repeatedly clicking "Open Anyway" inside System Settings.
Missing Windows WebView2
Tauri relies on WebView2. Windows 11 includes it out of the box; on Windows 10, install the Microsoft Edge WebView2 Runtime if prompted.
Android Host
Review Android Installation & Architecture for full details. Brief workflow:
- Verify your device runs Android 9.0+ on ARM64 or x86_64.
- Download the Full APK (bundles Runtime) or Thin APK (downloads ~1 GB Runtime on first boot) matching your architecture.
- Install and launch; wait 1–3 minutes for the rootfs to unpack.
- Activate ADB via built-in wireless pairing or Root.
- Open the in-app console to configure instances.
Docker
Best suited for NAS appliances, home servers, and headless machines. The container runs the WebUI and scheduler while the emulator runs on the host:
git clone https://github.com/wess09/AzurPilot.git
cd AzurPilot
docker compose up -d --builddocker-compose.yml specifies network_mode: host, running .venv/bin/python gui.py inside the container. For mainland China networks, switch the Dockerfile to deploy/docker/Dockerfile.cn and configure UV_INDEX_URL.
Long Initial Build Times
The multi-stage build downloads Node 24 for frontend assets and Python 3.14 for runtime dependencies. First-time --build takes time; subsequent rebuilds reuse cache layers.
Source Installation
Recommended for developers, debugging, and custom enhancements.
Prerequisites
- Python 3.14 (refer to
pyproject.tomlfor precise bounds) - uv
- Node.js (for frontend builds;
gui.pyautomatically builds assets whenfrontend/distis missing)
Execution Steps
git clone https://github.com/wess09/AzurPilot.git
cd AzurPilot
uv sync --frozen --no-dev
uv run python gui.pyAccess http://127.0.0.1:25548 in your browser. The server listens on 0.0.0.0 by default; host and port settings are loaded from WebuiHost and WebuiPort in config/deploy.yaml.
Common CLI flags:
uv run python gui.py --port 25548 --host 127.0.0.1 --key "your-password"| Flag | Description |
|---|---|
--host | Overrides WebuiHost |
-p, --port | Overrides WebuiPort |
-k, --key | Sets dashboard password |
--ssl-key / --ssl-cert | Enables HTTPS |
--run <instance> | Starts specified instance worker immediately on launch |
Verification
# Import smoke test: validates module resolution without connecting devices
uv run python -m dev_tools.import_smoke_test
# Python unit test suite
uv run python -m unittest discover -s testsIf the WebUI loads, task lists render, and logs contain no tracebacks, the backend is sound. Device configuration is the next step.