# How to Set Up a Development Environment for amnezia-client

> Set up your amnezia-client development environment easily. Install Qt, CMake, and Conan, then compile the desktop client and VPN service. Start contributing today.

- Repository: [Amnezia VPN/amnezia-client](https://github.com/amnezia-vpn/amnezia-client)
- Tags: how-to-guide
- Published: 2026-07-29

---

**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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/.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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/conanfile.py) at the repository root. Resolve these dependencies before compiling:

```bash
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:

```bash
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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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:

```bash
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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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:

```bash

# 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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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`:

```bash
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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/conanfile.py).

### Can I build amnezia-client without Conan?

While technically possible, building without Conan is not recommended. The [`conanfile.py`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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.