How to Test amnezia-client Locally: Complete Build and Runtime Guide

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, with platform-specific logic implemented in service/src/qtservice.cpp and Unix socket handling in 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 and implemented across ipc/ipcserver.cpp and ipc/ipcserverprocess.cpp. On Unix systems, this uses qtunixsocket.cpp for socket management, while Windows uses 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 and 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.

# 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 orchestrates building both the service and client targets. Run the following commands from the repository root to compile the complete stack:

# 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:

./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.

Launch the Client Application

With the service running, start the Qt UI client:

./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:

# Create an OpenVPN profile configuration

cat > test_profile.json <<EOF
{
  "type": "openvpn",
  "server": "us.example.com",
  "username": "user",
  "password": "pass"
}
EOF

# Import the profile

./build/client/amnezia-client --import test_profile.json

# Start the VPN tunnel

./build/client/amnezia-client --connect test_profile

# Verify traffic routes through VPN

curl https://ifconfig.me

# Disconnect and cleanup

./build/client/amnezia-client --disconnect test_profile
kill $SERVICE_PID

This sequence tests profile parsing, IPC command serialization in client/vpnConnection.cpp, tunnel creation in the service, and the kill-switch behavior.

CI Reference and Automation

The definitive build and test procedures are maintained in .github/workflows/deploy.yml. These workflows demonstrate cross-platform builds for Linux, macOS, and Windows, including dependency caching and packaging steps. Reference this file to replicate the exact compiler flags and environment variables used in production releases.

Summary

• Build Requirements: amnezia-client requires Conan (~1.60) and CMake to resolve Qt and OpenSSL dependencies specified in the root CMakeLists.txt.
• Service First: Always start amnezia-service before the client; the IPC layer in ipc/ipc.h and ipc/ipcserver.cpp depends on the daemon creating the socket endpoint.
• CLI Validation: Use --import, --connect, and --disconnect flags to script regression tests without GUI overhead.
• Source Locations: Key files include service/server/main.cpp (daemon entry), client/vpnConnection.cpp (client logic), and .github/workflows/deploy.yml (CI automation).

Frequently Asked Questions

What dependencies are required to build amnezia-client locally?

You need Conan 1.60 or later, CMake 3.16+, and a C++17-compatible compiler. The conan install command resolves Qt, OpenSSL, and libcurl automatically. Platform-specific service logic in service/src/qtservice.cpp may require additional system libraries like libsystemd on Linux.

Why does the client fail to connect if started before the service?

The client communicates via the IPC protocol defined in ipc/ipc.h, which expects a Unix socket (Linux/macOS) or named pipe (Windows) created by the service at startup. If amnezia-service is not running, the connection logic in client/vpnConnection.cpp cannot establish the transport channel, resulting in immediate failure.

How can I debug the service daemon during local testing?

Run the service binary in the foreground without backgrounding it (./build/service/amnezia-service) and attach a debugger such as GDB or LLDB. The service outputs diagnostic logs to stdout, allowing you to trace routing table modifications and VPN interface creation handled in service/src/qtservice.cpp.

Can I run integration tests without installing the Qt GUI dependencies?

Yes. While the GUI requires Qt, you can test the core client-service communication by building only the service and using the client’s CLI mode. The .github/workflows/deploy.yml demonstrates headless build configurations that validate the IPC layer and tunnel management without launching the graphical interface.

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