# Main Entry Point for the Amnezia-Client Application: Complete Startup Analysis

> Discover the main entry point for the amnezia-client application in client/main.cpp. Understand how it initializes the Qt app, sets up SSH, and manages the GUI event loop for seamless operation.

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

---

**The main entry point for the amnezia-client application is located in [`client/main.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/main.cpp), where the `int main(int argc, char *argv[])` function orchestrates database migrations, Qt application initialization, SSH setup, and the GUI event loop.**

The amnezia-vpn/amnezia-client repository provides a cross-platform VPN client built on the Qt framework. Understanding the main entry point is essential for contributors debugging startup failures and security researchers auditing the initialization sequence. This analysis examines how [`client/main.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/main.cpp) bootstraps the application from process launch to the main event loop.

## Locating the Entry Point in client/main.cpp

The canonical entry point resides in **[`client/main.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/main.cpp)** at the repository root. This file contains the standard C++ `main()` function that serves as the first executable code when the GUI process launches. Unlike simpler Qt applications, this entry point performs critical pre-initialization tasks before constructing the QML engine or loading the interface.

The function signature follows the standard Qt application pattern:

```cpp
int main(int argc, char *argv[])

```

Inside this function, the code executes a strict sequence of initialization steps to ensure database consistency, single-instance enforcement, and proper cleanup handling.

## Step-by-Step Initialization Flow

The startup sequence in [`client/main.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/main.cpp) follows a carefully ordered pipeline to prepare the runtime environment before handing control to the Qt event loop.

### Database Migrations

First, the code runs configuration and database migrations to ensure compatibility with previous versions:

```cpp
Migrations migrationsManager;
migrationsManager.doMigrations();

```

According to the source code in [`client/core/utils/migrations.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/core/utils/migrations.cpp), this step updates schemas and migrates user settings before any GUI components attempt to read configuration data.

### Application Object and Signal Handling

Next, the code instantiates the core application wrapper and registers OS-level signal handlers:

```cpp
AmneziaApplication app(argc, argv);
OsSignalHandler::setup();

```

The **`AmneziaApplication`** class (implemented in [`client/amneziaApplication.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/amneziaApplication.cpp)) extends `QGuiApplication` and manages QML context, networking stacks, and VPN service bindings. Signal handling ensures clean shutdowns when receiving SIGINT or SIGTERM.

### SSH Library Initialization

Before spawning network threads, the application initializes the underlying SSH library:

```cpp
ssh_init();
QObject::connect(&app, &QCoreApplication::aboutToQuit,
                 [](){ ssh_finalize(); });

```

This call to **`ssh_init()`** prepares the libssh backend used for managing remote server configurations, with a lambda ensuring **`ssh_finalize()`** runs during application teardown.

### Single-Instance Protection

On non-mobile platforms, the code prevents multiple GUI instances from running simultaneously:

```cpp
if (isAnotherInstanceRunning()) {
    QTimer::singleShot(1000, &app, [&](){ app.quit(); });
    return app.exec();
}
app.startLocalServer();

```

The **`isAnotherInstanceRunning()`** check uses a local socket mechanism. If another process holds the lock, the duplicate instance triggers a 1-second timer before exiting. Otherwise, **`app.startLocalServer()`** launches the IPC server to listen for subsequent activation attempts.

### QML Registration and Font Loading

With the IPC layer active, the code registers custom QML types and loads application fonts:

```cpp
app.registerTypes();
app.loadFonts();
bool doExec = app.parseCommands();

```

The **`parseCommands()`** method processes command-line arguments and returns a boolean indicating whether the GUI should proceed to full initialization or exit immediately.

### Event Loop Execution

Finally, if execution should continue, the code initializes core services and enters the Qt event loop:

```cpp
if (doExec) {
    app.init();
    return app.exec();
}
return 0;

```

The **`app.init()`** call (defined in [`client/amneziaApplication.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/amneziaApplication.cpp)) completes the setup of VPN protocol handlers located in `client/core/protocols/`, while **`app.exec()`** blocks until the user terminates the application.

## Client vs. Service Entry Points

The repository contains two distinct entry points separated by architectural concerns:

- **[`client/main.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/main.cpp)**: Boots the graphical user interface, handles QML rendering, and manages user interactions. This is the entry point for desktop users launching the VPN client.
- **[`service/server/main.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/service/server/main.cpp)**: Implements the background service daemon that maintains VPN tunnels independently of the GUI. This runs with elevated privileges and does not initialize QML or windowing systems.

Contributors should verify they are examining the correct [`main.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/main.cpp) for their use case, as the service component uses a separate initialization path focused on protocol management rather than user interface events.

## Summary

- The **main entry point** for the amnezia-client GUI is **[`client/main.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/main.cpp)**, containing the standard `int main(int argc, char *argv[])` function.
- Startup executes a fixed sequence: **migrations** → **application creation** → **SSH init** → **single-instance check** → **IPC server** → **QML setup** → **event loop**.
- The **`AmneziaApplication`** class in [`client/amneziaApplication.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/amneziaApplication.cpp) encapsulates Qt application logic, while [`client/core/utils/migrations.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/core/utils/migrations.cpp) handles data persistence.
- The repository maintains a **separate entry point** at [`service/server/main.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/service/server/main.cpp) for the background daemon, distinct from the GUI client.

## Frequently Asked Questions

### Where is the main function defined in the amnezia-client source code?

The `main()` function is defined in [`client/main.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/main.cpp) at the repository root. This file serves as the primary entry point for the GUI application, whereas [`service/server/main.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/service/server/main.cpp) handles the background service daemon.

### What happens before the Qt event loop starts in amnezia-client?

Before `app.exec()` runs, the code performs database migrations via `migrationsManager.doMigrations()`, initializes the SSH library with `ssh_init()`, enforces single-instance constraints, starts the local IPC server, and registers QML types. These steps ensure the runtime environment is fully prepared for user interaction.

### How does amnezia-client prevent multiple instances from running?

The code checks `isAnotherInstanceRunning()` before fully initializing. If another instance holds the local socket lock, the duplicate process triggers a delayed quit via `QTimer::singleShot()` and exits. Otherwise, `app.startLocalServer()` creates the IPC endpoint for future activation signals.

### What is the difference between AmneziaApplication and a standard QGuiApplication?

**`AmneziaApplication`** (defined in [`client/amneziaApplication.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/amneziaApplication.cpp)) extends `QGuiApplication` to add VPN-specific functionality, including QML type registration, font management, command-line parsing, and initialization of protocol handlers for WireGuard, OpenVPN, and Xray. It encapsulates the complete application lifecycle beyond basic Qt windowing.