Where to Find the Amnezia VPN Client Backend Code: Complete Developer Guide
The Amnezia VPN client backend code resides entirely within the service/ directory of the amnezia-vpn/amnezia-client repository, specifically under service/src/ for the system service wrapper and service/server/ for the VPN engine controller.
The Amnezia VPN client follows a split architecture where the graphical frontend communicates with a privileged backend service that manages actual VPN tunnels. This backend implements the core VPN logic, routing rules, and protocol engines like Xray and OpenVPN. All source files for this subsystem are located in the dev branch under the service/ path, compiled into the amnezia-service binary.
Anatomy of the Backend: The service/ Directory
The service/ folder contains everything required to build the background service that runs with elevated privileges. It separates cross-platform service management from platform-specific VPN implementations.
System Service Layer (service/src/)
This layer handles installation and lifecycle management of the background service across Windows, macOS, and Linux. The [service/src/qtservice.h](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/src/qtservice.h) and [qtservice.cpp](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/src/qtservice.cpp) files provide the QtService class abstraction, while platform helpers like [qtservice_win.cpp](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/src/qtservice_win.cpp) and [qtservice_unix.cpp](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/src/qtservice_unix.cpp) handle OS-specific service registration.
VPN Engine Controller (service/server/)
The service/server/ directory contains the actual VPN implementation. [main.cpp](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/server/main.cpp) initializes the IPC server and routing components, while specialized modules manage individual VPN protocols and network interfaces.
Key Backend Components and File Locations
The following table maps functional areas to their specific source files in the dev branch:
How the Backend Starts: Code Examples
The UI launches the backend service as a separate process, then communicates via the IPC layer defined in [ipc/ipcserver.cpp](https://github.com/amnezia-vpn/amnezia-client/blob/dev/ipc/ipcserver.cpp).
Launching the Service from the Client
In [client/vpnConnection.cpp](https://github.com/amnezia-vpn/amnezia-client/blob/dev/client/vpnConnection.cpp), the GUI initiates the backend binary:
// client/vpnConnection.cpp – starts the privileged service process
void VpnConnection::startService()
{
// Construct path to the service binary adjacent to the client executable
QString servicePath = QStringLiteral("%1/amnezia-service")
.arg(QCoreApplication::applicationDirPath());
QProcess *serviceProcess = new QProcess(this);
serviceProcess->start(servicePath);
serviceProcess->waitForStarted();
}
Service Entry Point and Initialization
The [service/server/main.cpp](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/server/main.cpp) file creates the local IPC server and initializes routing components:
// service/server/main.cpp – backend service entry point
#include "localserver.h"
#include "router.h"
#include "xray.h"
int main(int argc, char *argv[])
{
QCoreApplication app(argc, argv);
LocalServer server; // IPC endpoint for UI commands
Router router; // Platform-specific routing manager
Xray xrayEngine; // Xray protocol handler
// Initialize components and start event loop
return app.exec();
}
Implementing Split-Tunnel Routes
Platform-specific routing logic resides in files like [service/server/router_win.cpp](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/server/router_win.cpp). The Windows implementation executes system route commands:
// service/server/router_win.cpp – adds a route for split-tunneling
bool RouterWin::addRoute(const QString &cidr, const QString &gateway)
{
QString cmd = QStringLiteral("route add %1 mask %2 %3")
.arg(cidr)
.arg(maskFromCidr(cidr))
.arg(gateway);
int exitCode = QProcess::execute(cmd);
return exitCode == 0;
}
Build Configuration
The backend compiles into an executable named amnezia-service defined in [service/CMakeLists.txt](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/CMakeLists.txt):
# service/CMakeLists.txt – defines the service binary target
add_subdirectory(src)
install(TARGETS amnezia-service
RUNTIME DESTINATION bin)
After building the project, the binary appears at build/.../bin/amnezia-service (location varies by platform) and is launched automatically by the client when establishing a VPN connection.
Summary
- Primary Location: All backend code lives in the
service/directory of theamnezia-vpn/amnezia-clientrepository. - Service Wrapper: Cross-platform system service logic resides in
service/src/(notablyqtservice.hand platform implementations). - Core Logic: VPN engine control, routing, and protocol implementations are in
service/server/(entry point atmain.cpp). - Key Components: Xray integration (
xray.cpp), TAP device management (tapcontroller_win.cpp), kill-switch (killswitch.cpp), and routing abstractions (router.hand platform-specific implementations). - Client Integration: The UI launches the backend via [
client/vpnConnection.cpp](https://github.com/amnezia-vpn/amnezia-client/blob/dev/client/vpnConnection.cpp) and communicates through the IPC layer. - Build System: CMake configuration in [
service/CMakeLists.txt](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/CMakeLists.txt) produces theamnezia-serviceexecutable.
Frequently Asked Questions
Where is the main entry point for the Amnezia VPN backend service?
The entry point is located at [service/server/main.cpp](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/server/main.cpp). This file initializes the Qt application, creates the LocalServer instance for IPC communication, instantiates the Router for network management, and starts the VPN engine controllers before entering the event loop.
How does the Amnezia client UI communicate with the backend service?
The UI spawns the amnezia-service binary as a separate process using QProcess (implemented in [client/vpnConnection.cpp](https://github.com/amnezia-vpn/amnezia-client/blob/dev/client/vpnConnection.cpp)), then exchanges commands via a local socket IPC mechanism implemented in [ipc/ipcserver.cpp](https://github.com/amnezia-vpn/amnezia-client/blob/dev/ipc/ipcserver.cpp). This architecture keeps the privileged VPN code isolated from the user interface.
Which files handle the Xray protocol implementation?
The Xray VPN protocol is wrapped in [service/server/xray.cpp](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/server/xray.cpp) with corresponding definitions in [service/server/xray_defs.h](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/server/xray_defs.h). These files handle generating Xray configurations and managing the Xray core process lifecycle.
Where is the split-tunneling and kill-switch logic implemented?
Split-tunneling routes are managed by the Router class with platform-specific implementations in [service/server/router_win.cpp](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/server/router_win.cpp), [router_mac.cpp](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/server/router_mac.cpp), and [router_linux.cpp](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/server/router_linux.cpp). The kill-switch firewall rules reside in [service/server/killswitch.cpp](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/server/killswitch.cpp).
Have a question about this repo?
These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:
curl -s "https://instagit.com/install.md" 
Maintain an open-source project? Get it listed too →