Install Launcher

The launcher is distributed as a portable archive without an installer wizard. Actual setup occurs on first execution: it initializes .venv, downloads Python, and clones the core repository.

Download Channels

Channel	URL
GitHub Releases	github.com/wess09/AzurPilotLauncher/releases/latest
Official Portal	azurpilot.com/download.html
CNB Mirror	Regional mirror for mainland China

Download the archive matching your operating system and architecture:

Filename Suffix	Target Platform
windows-x64	Standard 64-bit Windows
windows-arm64	Windows on ARM
macos	Apple Silicon / Intel macOS
linux-x64 / linux-arm64	Linux per CPU architecture
-cn	Uses mainland China mirrors

International vs. CN Mirror Editions

Both editions share identical launcher binaries. The distinction lies in deployment configuration: -cn routes repository downloads via git://git.pull/AzurPilot and connects to regional PyPI mirrors.

Destination Directory

Extract into a permanent, writable directory with a simple path:

• ✅ D:\AzurPilot\
• ✅ ~/Applications/AzurPilot/
• ❌ C:\Program Files\ (requires elevated write privileges for regular updates)
• ❌ Paths containing spaces or non-ASCII characters
• ❌ Cloud sync directories (OneDrive / iCloud lock active .venv files)

Never Run from Temporary Folders

The launcher stores repositories, .venv, settings, and logs within its root directory. Temporary directories risk automatic purge by OS cleanup utilities.

Windows

01

Extract archive

Extract using 7-Zip or Windows Explorer. Do not run the executable from inside the compressed zip view.

01

Grant Administrator privileges

The alas-launcher.exe manifest declares requireAdministrator to handle ADB drivers and system networking. Confirm the UAC prompt.

01

Handle SmartScreen warnings

Unsigned binaries may trigger Windows SmartScreen. Click "More info" followed by "Run anyway".

01

Verify WebView2

Windows 11 includes WebView2 by default. On Windows 10, install the WebView2 Runtime if prompted.

macOS

# Extract and move to Applications
xattr -dr com.apple.quarantine /Applications/AzurPilot.app
open /Applications/AzurPilot.app

The application lacks Apple developer code signing. Double-clicking directly causes Gatekeeper blocks. Strip quarantine flags with xattr before opening.

Avoid Repeated System Dialog Retries

Certain macOS versions cache rejection states. Removing the quarantine attribute via terminal is the cleanest fix.

Linux

tar -xf azurpilot-launcher-linux-x64.tar.xz
cd AzurPilot
chmod +x alas-launcher
./alas-launcher

System dependencies:

Dependency	Purpose
libwebkit2gtk-4.1	WebView rendering
Recent glibc	CI builds against Ubuntu 22.04
libgtk-3	Window management

Debian / Ubuntu installation:

sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0

If your distribution lacks modern WebKitGTK packages, you can run the core program directly via terminal: uv run python gui.py (requires system Python 3.14 and uv).

First-Run Verification

Initial startup executes a complete environment bootstrap. Verify successful completion against this checklist:

Checkpoint	Expected Behavior
Splash Screen	Displays progress through .venv creation, Python download, Git clone, and dependency sync
Application Window	Renders WebUI directly without login prompts
Listening Port	Defaults to 22267
Directory State	Creates .venv/, config/, frontend/, and log/

Command Line Flags

Flag	Purpose
`--lang <zh-CN	zh-TW
--skip-update	Skips Git repository updates (useful offline or during debugging)
--preview-crash	Renders crash diagnostics UI
--start-minimized	Launches directly to system tray (used for OS startup)

Uninstallation

Delete the installation directory. The launcher writes no registry entries (except optional autostart) and leaves no system library artifacts.

Backup config/ before deletion to prevent permanent loss of instance settings, statistics, and vault keys:

Preserve: config/, AzurPilot_Data_Backup/
Safe to delete: .venv/, frontend/, log/, cache/

Common Installation Issues

Symptom	Cause	Solution
Double-click produces no window	UAC denied or antivirus blockage	Check security logs; grant admin privileges
Prompt reports missing WebView2	Runtime not installed	Install Edge WebView2 Runtime
macOS alerts "App is damaged"	Quarantine attribute present	Run xattr -dr com.apple.quarantine
Linux reports missing libwebkit2gtk	Missing 4.1 package	Install libwebkit2gtk-4.1-0
Path contains whitespace	Toolchain path parsing error	Move installation to path without spaces
Continuous launcher restart loop	Initialization crashed	Review Initialization Failures