# Where to Find the Amnezia VPN Client Backend Code: Complete Developer Guide

> Locate the Amnezia VPN client backend code in the amnezia-vpn/amnezia-client repository's service/ directory. Access system service wrapper and VPN engine controller code easily.

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

---

**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/main/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/main/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/main/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/main/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/`](https://github.com/amnezia-vpn/amnezia-client/tree/dev/service/server)** directory contains the actual VPN implementation. **[[`main.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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:

| Component | Purpose | Source Location |
|-----------|---------|-----------------|
| **Build Configuration** | CMake definitions for the `amnezia-service` binary | **[[`service/CMakeLists.txt`](https://github.com/amnezia-vpn/amnezia-client/blob/main/service/CMakeLists.txt)](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/CMakeLists.txt)** |
| **Service Wrapper** | Cross-platform system service abstraction | **[[`service/src/qtservice.h`](https://github.com/amnezia-vpn/amnezia-client/blob/main/service/src/qtservice.h)](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/src/qtservice.h)** |
| **IPC Server** | Communication channel between UI and service | **[[`ipc/ipcserver.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/ipc/ipcserver.cpp)](https://github.com/amnezia-vpn/amnezia-client/blob/dev/ipc/ipcserver.cpp)** |
| **Entry Point** | Service initialization and component wiring | **[[`service/server/main.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/service/server/main.cpp)](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/server/main.cpp)** |
| **Routing Abstraction** | Platform-agnostic interface for network routes | **[[`service/server/router.h`](https://github.com/amnezia-vpn/amnezia-client/blob/main/service/server/router.h)](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/server/router.h)** |
| **Windows Routing** | Route addition/removal on Windows | **[[`service/server/router_win.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/service/server/router_win.cpp)](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/server/router_win.cpp)** |
| **macOS/Linux Routing** | Unix-based routing implementations | **[[`service/server/router_mac.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/service/server/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/main/router_linux.cpp)](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/server/router_linux.cpp)** |
| **Xray Integration** | Controls the Xray proxy core | **[[`service/server/xray.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/service/server/xray.cpp)](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/server/xray.cpp)** |
| **Xray Definitions** | Protocol constants and structures | **[[`service/server/xray_defs.h`](https://github.com/amnezia-vpn/amnezia-client/blob/main/service/server/xray_defs.h)](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/server/xray_defs.h)** |
| **TAP Controller** | Windows TAP adapter management for OpenVPN | **[[`service/server/tapcontroller_win.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/service/server/tapcontroller_win.cpp)](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/server/tapcontroller_win.cpp)** |
| **Kill Switch** | Firewall rules to block traffic when VPN disconnects | **[[`service/server/killswitch.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/service/server/killswitch.cpp)](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/server/killswitch.cpp)** |
| **Service Launcher** | UI-side code that starts the backend process | **[[`client/vpnConnection.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/vpnConnection.cpp)](https://github.com/amnezia-vpn/amnezia-client/blob/dev/client/vpnConnection.cpp)** |

## 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/main/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/main/client/vpnConnection.cpp)](https://github.com/amnezia-vpn/amnezia-client/blob/dev/client/vpnConnection.cpp)**, the GUI initiates the backend binary:

```cpp
// 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/main/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:

```cpp
// 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/main/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:

```cpp
// 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/main/service/CMakeLists.txt)](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/CMakeLists.txt)**:

```cmake

# 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 the `amnezia-vpn/amnezia-client` repository.
- **Service Wrapper:** Cross-platform system service logic resides in **`service/src/`** (notably [`qtservice.h`](https://github.com/amnezia-vpn/amnezia-client/blob/main/qtservice.h) and platform implementations).
- **Core Logic:** VPN engine control, routing, and protocol implementations are in **`service/server/`** (entry point at [`main.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/main.cpp)).
- **Key Components:** Xray integration ([`xray.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/xray.cpp)), TAP device management ([`tapcontroller_win.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/tapcontroller_win.cpp)), kill-switch ([`killswitch.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/killswitch.cpp)), and routing abstractions ([`router.h`](https://github.com/amnezia-vpn/amnezia-client/blob/main/router.h) and platform-specific implementations).
- **Client Integration:** The UI launches the backend via [[`client/vpnConnection.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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/main/service/CMakeLists.txt)](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/CMakeLists.txt) produces the `amnezia-service` executable.

## 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/main/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/main/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/main/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/main/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/main/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/main/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/main/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/main/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/main/service/server/killswitch.cpp)](https://github.com/amnezia-vpn/amnezia-client/blob/dev/service/server/killswitch.cpp)**.