How to Build Amnezia-Client from Source: Complete CMake & Qt6 Guide

To build amnezia-client from source, clone the repository with submodules, install dependencies via Conan, and execute the platform-specific build script in deploy/ that configures CMake with Qt 6.10+ to compile both the GUI client and background service.

Amnezia-Client is the open-source VPN client from the amnezia-vpn/amnezia-client repository, written in C++17 and built on Qt 6. The codebase separates the user interface from the tunneling logic, using CMake as the meta-build system and Conan for third-party dependency management. This guide provides the exact commands and configuration details needed to compile the project for Linux, Windows, macOS, and Android.

Prerequisites

Before compiling, verify your system meets the following requirements.

• CMake ≥ 3.25 – Required to process the top-level configuration.
• C++17 Compiler – gcc/clang on Linux, Xcode on macOS, or Visual Studio 2022 on Windows.
• Qt 6.10+ – Must include Qt Core, Qt 5 Compatibility, and Qt Remote Objects modules.
• Conan – Package manager to fetch OpenSSL, libssh, wintun, and other libraries.
• Git – With submodule support for fetching nested dependencies.

Optional Tools

• Qt Installer Framework – Required only if generating installers (.dmg, .exe).
• WIX Toolset – Needed for Windows MSI packaging.
• Android SDK & NDK – Mandatory only when targeting Android.

Ensure all tools are available in your system PATH or export environment variables such as QT_INSTALL_DIR and ANDROID_HOME so the build scripts can locate them.

Repository Structure

The project is organized into two distinct components that compile together:

• client/ – Contains the Qt/QML GUI application and platform-specific networking utilities (e.g., macosUtil.mm, qtunixsocket.cpp).
• service/ – Houses the background daemon that manages VPN tunnels (OpenVPN, WireGuard, Xray-core) via cross-platform service wrappers (qtservice.cpp, qtservice_unix.cpp, qtservice_win.cpp).

As defined in the root CMakeLists.txt at line 72, the service subdirectory is excluded from mobile builds:

if(NOT IOS AND NOT ANDROID AND NOT MACOS_NE)
    add_subdirectory(service)
endif()

Step-by-Step Build Instructions

1. Clone Repository and Initialize Submodules

The project vendors several external libraries via submodules.

git clone https://github.com/amnezia-vpn/amnezia-client.git
cd amnezia-client/dev
git submodule update --init --recursive

2. Install Conan Dependencies

Run Conan once to download and build missing libraries into the build/ directory.

conan install . --output-folder=build --build=missing

This populates OpenSSL, libssh, and wintun headers and binaries required by the VPN service layer.

3. Execute the Build Script

The deploy/ directory contains wrappers that detect Qt installations and invoke CMake with the correct toolchain.

Linux and macOS

# Compile client and service binaries only

./deploy/build.sh

# Compile and generate distribution installers

./deploy/build.sh --installer all

The script automatically searches standard Qt paths (~/Qt, /opt/Qt) or respects the QT_INSTALL_DIR environment variable (see logic around lines 65–82 of deploy/build.sh).

Windows

Open a x64 Native Tools Command Prompt for Visual Studio 2022, then run:

# Basic build

deploy\build.bat

# Build with Qt Installer Framework installer

deploy\build.bat --installer ifw

# Build with both IFW and WIX (MSI) outputs

deploy\build.bat --installer ifw --installer wix

4. Cross-Compile for Android (Optional)

From a Linux or macOS host, target Android by specifying the android target and desired ABIs:

./deploy/build.sh -t android --installer all --abi all

The script resolves the Android toolchain file, sets ANDROID_HOME, and configures CMake to cross-compile the Qt application (see the Android block in deploy/build.sh, lines 122–154).

5. Locate Build Artifacts

All output resides in deploy/build/:

• Desktop platforms: AmneziaVPN (or AmneziaVPN.exe) and the amnezia-service binary.
• Installers: CPack artifacts (.deb, .dmg, .exe, .msi) appear when --installer flags are used.

CMake Configuration Details

Understanding the build system helps troubleshoot linking errors or customize compilation.

Root Configuration

The top-level CMakeLists.txt (lines 33–45) sets the C++ standard, extracts version numbers, and defines MZ_PLATFORM_NAME based on CMAKE_SYSTEM_NAME. It also forces Qt build tools to run during cross-compilation:

set(QT_BUILD_TOOLS_WHEN_CROSS_COMPILING ON)  # Line 47

Conan Integration

Line 11 of CMakeLists.txt includes conan_provider.cmake, which automatically invokes conan install before configuring the project. This ensures that find_package(OpenSSL) and similar calls resolve to Conan-managed libraries rather than system versions.

Qt Kit Selection

The build scripts populate CMAKE_PREFIX_PATH with the detected Qt installation. For Android builds, they additionally pass -DCMAKE_TOOLCHAIN_FILE pointing to the Android NDK's CMake toolchain, enabling proper compilation of Qt's networking components for ARM architectures.

Summary

• Amnezia-Client splits into a client/ GUI and a service/ daemon, both built via CMake.
• Conan handles third-party dependencies; run conan install . --output-folder=build --build=missing before compiling.
• Helper scripts in deploy/build.sh (Unix) and deploy/build.bat (Windows) automate Qt detection and CPack packaging.
• Android cross-compilation is supported from Linux/macOS hosts using the -t android flag.
• Binaries output to deploy/build/, with installers generated when --installer options are specified.

Frequently Asked Questions

What is the difference between the client and service components?

The client component provides the graphical interface and user interaction logic, while the service component runs as a background daemon with elevated privileges to manage VPN tunnels. The service is omitted when building for iOS or Android, where tunneling is handled by platform-specific VPN extensions rather than a standalone daemon.

Can I build amnezia-client without Conan?

Technically possible but discouraged. The official build system relies on the conan_provider.cmake module (referenced at line 11 of CMakeLists.txt) to locate OpenSSL, libssh, and platform-specific libraries like wintun. Manual builds would require installing these dependencies system-wide and modifying CMAKE_PREFIX_PATH manually, which is not tested by the upstream maintainers.

How do I build for Android from Linux or macOS?

Use the cross-compilation mode in the build script: ./deploy/build.sh -t android --installer all --abi all. Ensure ANDROID_HOME is exported and contains the Android SDK and NDK. The script automatically configures the toolchain file and builds APKs for multiple architectures.

Where are the compiled binaries located after building?

Final executables are placed in deploy/build/. On desktop platforms, you will find the main AmneziaVPN executable alongside the amnezia-service binary. If you passed --installer flags to the build script, distribution packages (.deb, .dmg, .exe, or .msi) are generated in the same directory via CPack.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}