# How to Test amnezia-client Locally: Complete Build and Runtime Guide > Learn to test amnezia-client locally. This guide details building the service daemon and UI client with CMake and Conan, then running them to verify IPC and VPN tunnel functionality. - Repository: [Amnezia VPN/amnezia-client](https://github.com/amnezia-vpn/amnezia-client) - Tags: how-to-guide - Published: 2026-07-29 --- **To test amnezia-client locally, you must build both the service daemon (`amnezia-service`) and the Qt UI client (`amnezia-client`) using CMake and Conan, start the service in the background, then launch the client to exercise the IPC communication layer and VPN tunnel functionality.** The **amnezia-vpn/amnezia-client** repository is a Qt-based VPN client that requires coordinated local testing between its background service and user interface. Testing the application locally involves compiling the C++ source code, initializing the Inter-Process Communication (IPC) socket layer, and validating complete user workflows from profile creation to tunnel establishment. This guide provides the exact build commands, file paths, and runtime procedures used in the project’s continuous integration pipelines. ## Understanding the Three-Tier Architecture Before testing, you must understand how the components interact. The application consists of three distinct layers that must all be running to test end-to-end functionality. ### Service Daemon (VPN Core) The **service daemon** implements the privileged VPN core that manages tunnels, routing tables, and the kill-switch. Its entry point is located at [`service/server/main.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/service/server/main.cpp), with platform-specific logic implemented in [`service/src/qtservice.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/service/src/qtservice.cpp) and Unix socket handling in [`service/src/qtunixsocket.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/service/src/qtunixsocket.cpp). This binary must run with elevated privileges to manipulate network interfaces and spawn XRay or OpenVPN processes. ### IPC Communication Layer The client and service communicate through a local IPC channel defined in [`ipc/ipc.h`](https://github.com/amnezia-vpn/amnezia-client/blob/main/ipc/ipc.h) and implemented across [`ipc/ipcserver.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/ipc/ipcserver.cpp) and [`ipc/ipcserverprocess.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/ipc/ipcserverprocess.cpp). On Unix systems, this uses [`qtunixsocket.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/qtunixsocket.cpp) for socket management, while Windows uses [`qtservice_win.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/qtservice_win.cpp) for named pipes. The service must be active first to create the socket endpoint that the client expects. ### Client UI and Core The **client application** provides the graphical interface and configuration management. Core connection logic resides in [`client/vpnConnection.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/vpnConnection.cpp) and [`client/vpnConnection.h`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/vpnConnection.h), which serialize commands and send them to the daemon via the IPC layer. The client binary (`amnezia-client`) can also operate in CLI mode for automated testing. ## Prerequisites and Build Setup The project uses **CMake** for the build system and **Conan** 1.60+ for third-party dependency management (Qt, OpenSSL, libcurl). Ensure you have these tools installed before proceeding. ```bash # Install Conan if not present pip install conan~=1.60 # Create a Conan profile matching your system conan profile new default --detect conan profile update settings.compiler.libcxx=libstdc++11 default ``` ## Building the Binaries from Source The root [`CMakeLists.txt`](https://github.com/amnezia-vpn/amnezia-client/blob/main/CMakeLists.txt) orchestrates building both the service and client targets. Run the following commands from the repository root to compile the complete stack: ```bash # Install dependencies to the build directory conan install . -if build --build=missing # Configure the CMake project cmake -S . -B build -DCMAKE_BUILD_TYPE=Release # Compile service and client binaries cmake --build build --target all ``` After compilation, the binaries reside in `build/service/amnezia-service` and `build/client/amnezia-client`. ## Local Testing Workflow Testing requires starting the service daemon before the client, then exercising the connection logic through either the GUI or command-line interface. ### Start the Service Daemon Launch the service in the background and capture its process ID for later cleanup: ```bash ./build/service/amnezia-service & SERVICE_PID=$! echo "Service PID: $SERVICE_PID" ``` The service initializes the IPC socket and waits for client connections as implemented in [`ipc/ipcserver.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/ipc/ipcserver.cpp). ### Launch the Client Application With the service running, start the Qt UI client: ```bash ./build/client/amnezia-client ``` Alternatively, run the client in CLI mode to automate testing without the graphical interface. ### Command-Line Testing Protocol Create a test profile and exercise the full connection lifecycle programmatically: ```bash # Create an OpenVPN profile configuration cat > test_profile.json <