How to Set Up a Development Environment for amnezia-client

Install Qt 5.15 or later, CMake 3.20+, and Conan 1.59+, then configure the build with cmake .. -G Ninja and compile the desktop client and VPN service using ninja.

The amnezia-vpn/amnezia-client repository is a cross-platform VPN client built with C++ and Qt. The project uses CMake as its build system and Conan to manage third-party libraries including OpenVPN, WireGuard, and Xray. Setting up the development environment involves installing specific toolchains, resolving dependencies via the conanfile.py recipe, and building both the Qt GUI and the background service daemon.

Prerequisites

Before cloning the repository, ensure your system meets the following minimum requirements:

• Git 2.30 or later for version control
• CMake 3.20 or later for build configuration
• Conan 1.59 or later (install via pip install conan) for C++ dependency management
• Qt 5.15 or later (Qt 6 is also supported) including Qt Quick and QML modules
• Ninja build system for faster compilation (optional but recommended)
• Python 3.8 or later (required for Conan)

On Debian-based Linux distributions, install the toolchains using:

sudo apt update
sudo apt install git cmake ninja-build qtbase5-dev qtdeclarative5-dev libssl-dev python3-pip
pip3 install conan

On macOS with Homebrew:

brew install git cmake ninja qt@5 python
pip3 install conan

On Windows, install the Qt Online Installer, Visual Studio Build Tools with C++ CMake support, and Python from python.org, then run pip install conan.

Clone the Repository

Clone the active development branch and navigate to the project root:

git clone https://github.com/amnezia-vpn/amnezia-client.git
cd amnezia-client
git checkout dev

The dev branch contains the latest build configurations and unstable features used by contributors. Alternatively, the repository includes a .gitpod.yml that defines a ready-made cloud environment with all dependencies pre-installed.

Install Conan Dependencies

The project defines its third-party requirements—such as OpenSSL, OpenVPN, and WireGuard libraries—in conanfile.py at the repository root. Resolve these dependencies before compiling:

conan profile new default --detect
conan profile update settings.compiler.libcxx=libstdc++11 default
conan install . --output-folder=build --build=missing

The --build=missing flag is critical. It instructs Conan to compile dependencies from source when pre-built binaries are unavailable for your specific platform, architecture, or compiler version.

Configure the Build with CMake

Create a dedicated build directory and generate the build system using Ninja:

mkdir -p build && cd build
cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Release

You can append these optional flags to the cmake command:

• -DCMAKE_BUILD_TYPE=Debug to generate debug symbols
• -DENABLE_QT6=ON to force Qt 6 instead of Qt 5
• -DENABLE_CODE_SIGNING=OFF to disable macOS/Windows code signing for local development
• -DCMAKE_PREFIX_PATH=/path/to/qt if CMake cannot locate your Qt installation automatically

The top-level CMakeLists.txt orchestrates the build of three main components: the desktop GUI in client/, the background service in service/, and shared utilities in common/.

Build the Client and Service

Compile both executables with a single command:

ninja

This generates two primary binaries:

• client/amnezia-client — The Qt Quick-based desktop GUI application
• service/amneziavpn-service — The background VPN daemon

According to the source code in service/server/main.cpp, the service binary handles IPC and tunnel management, while the connection logic used by the GUI resides in client/vpnConnection.cpp.

Run the Application

You must start the background service before launching the client, as the GUI communicates with the daemon via local sockets to control VPN tunnels:

# Terminal 1: Start the service (requires elevated privileges)

sudo ./service/amneziavpn-service

# Terminal 2: Launch the client

./client/amnezia-client

On macOS, the service requires root privileges to create network interfaces; use sudo or configure a launch daemon. On Windows, run the executables from the build directory or the Visual Studio solution.

Development Workflow Tips

Hot-reload QML: The interface uses Qt Quick defined in QML files under client/ui/. Edit these files and restart only the client binary to see UI changes instantly without recompiling the C++ backend.

Logging: The shared logging facility implemented in common/logger/logger.cpp outputs to stdout and rotating log files. Monitor these logs in the service terminal to debug VPN connection handshakes and protocol errors.

Code formatting: The repository includes a .clang-format configuration matching the project's style. Run clang-format -i $(git ls-files *.cpp *.h *.hpp) before committing to ensure consistency with the existing codebase.

Packaging: To create distributable installers for testing, use CPack with the configurations provided in cmake/CPack.cmake and cmake/util/codesign.cmake:

cpack -G DEB  # For Linux .deb packages

cpack -G WIX  # For Windows MSI installers

cpack -G DragNDrop  # For macOS .dmg files

Troubleshooting Common Issues

Qt modules not found: If CMake reports missing Qt components, ensure qtbase5-dev and qtdeclarative5-dev are installed on Linux, or set -DCMAKE_PREFIX_PATH to your Qt installation directory on macOS and Windows.

Conan missing binary errors: When Conan reports that pre-built packages are unavailable for your compiler, re-run conan install . --build=missing to force local compilation of the dependencies defined in conanfile.py.

Service permission denied: The daemon requires administrator rights to modify routing tables and create VPN tunnels. On Linux, run the service with sudo; on macOS, adjust the launch daemon configuration; on Windows, run as Administrator.

OpenSSL headers missing: Install libssl-dev (Linux) or brew install openssl (macOS), then pass the location to CMake using -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl.

Summary

Setting up the amnezia-client development environment requires:

• Installing Qt 5.15+, CMake 3.20+, Conan 1.59+, and Ninja
• Cloning the dev branch from the amnezia-vpn/amnezia-client repository
• Running conan install . --build=missing to resolve dependencies like OpenVPN and WireGuard libraries
• Configuring the build with cmake .. -G Ninja in a dedicated build/ directory
• Compiling with ninja to produce the GUI client and background service binaries
• Executing amneziavpn-service with elevated privileges before launching amnezia-client to enable VPN functionality

Frequently Asked Questions

What is the minimum Qt version required to build amnezia-client?

The project requires Qt 5.15 as a minimum, though Qt 6 is also supported. The QML-based interface in client/ui/ relies on Qt Quick modules available in these versions. Configure the specific version using the -DENABLE_QT6 CMake flag in the build configuration step.

Why does the build fail with "missing binary" in Conan?

This occurs when Conan lacks pre-built packages for your specific operating system, architecture, or compiler version. Resolve this by appending --build=missing to the conan install command, which instructs Conan to compile the dependencies from source using the recipes defined in conanfile.py.

Can I build amnezia-client without Conan?

While technically possible, building without Conan is not recommended. The conanfile.py manages complex dependencies including specific versions of OpenSSL, OpenVPN, and WireGuard libraries. Manual installation would require individually sourcing, compiling, and linking these libraries, and the CMakeLists.txt expects to locate them via Conan-generated paths.

How do I debug the VPN service during development?

Run the service binary ./service/amneziavpn-service in a separate terminal with elevated privileges. The service outputs detailed logs using the logger implementation in common/logger/logger.cpp. Attach a debugger like gdb or Visual Studio to the running process, or run the client and service in separate debuggers to trace the IPC communication between the GUI and daemon.

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