The proton-vpn-core-api acts as a facade to the other Proton VPN components, exposing a uniform API to the available Proton VPN services.

Even though our CI pipelines always test and build releases using Linux distribution packages, you can use pip to set up your development environment.

If you didn't do it yet, to be able to pip install Proton VPN components you'll need to set up our internal Python package registry. You can do so running the command below, after replacing {GITLAB_TOKEN} with your personal access token with the scope set to api.

pip config set global.index-url https://__token__:{GITLAB_TOKEN}@gitlab.protontech.ch/api/v4/groups/777/-/packages/pypi/simple

In the index URL above, 777 is the id of the current root GitLab group, the one containing the repositories of all our Proton VPN components.

This component depends on the PyGObject python package.

To be able to pip install PyGObject, please check the required distribution packages in the official documentation.

sudo apt install pkg-config libdbus-1-dev libglib2.0-dev

You can create the virtual environment and install the rest of dependencies as follows:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

The Rust code has a path dependency on the protun submodule, so make sure it is checked out first. A clone without --recurse-submodules leaves it empty, and cargo then fails to read its manifest before compiling anything:

git submodule update --init --recursive

Building the kill switch also needs the nftables development headers, which provide the pkg-config files the nftnl-sys and mnl-sys build scripts look for:

sudo apt install libnftnl-dev libmnl-dev        # Debian/Ubuntu
sudo dnf install libnftnl-devel libmnl-devel    # Fedora

Build the Rust binary:

cargo build --features "python,core,local_agent,protun,kill_switch"

Create a symlink to the rust binary:

ln -sf ../../target/debug/libproton_vpn_platform.so proton/vpn/platform.abi3.so

Then install the package in editable mode:

pip install -e .

After each cargo build the symlink automatically points to the updated .so — no reinstall or re-copy needed.

Build a release .so and package it as a wheel in target/:

cargo build --release --target x86_64-unknown-linux-gnu \
    --features "python,core,local_agent,protun,kill_switch"
./ci-libraries-rust/scripts/build-wheel

You can run the python tests with:

pytest

proton-vpn-platform is the Rust backend for ProtonVPN's Linux client. It implements a NetworkManager VPN plugin for WireGuard-based connections (protun), a local agent communication layer, and server scoring — exposing functionality to higher-level ProtonVPN tooling via both native Rust and Python (PyO3) interfaces.

cargo build --features 'core,python'

cargo test --features 'core'

python is left out on purpose: pyo3's extension-module leaves the CPython symbols for the interpreter to resolve, so a standalone test binary fails to link against it.

An nftables kill switch, applied by a D-Bus service and driven from Python. See docs/kill_switch.md for building, installing and calling it.

cargo build --features 'local_agent'

cargo test --features 'local_agent'

cargo build --bin nm-protun-service --lib --features 'protun, python'

cargo test --features 'protun, python'

Register the plugin with NetworkManager:

sudo bash -c 'cat resources/nm-protun.name | envsubst > /usr/lib/NetworkManager/VPN/nm-protun.name'

Grant the plugin rights to the D-Bus namespace:

sudo cp resources/nm-protun-service.conf /usr/share/dbus-1/system.d/

Use the cli nm command to generate and apply the nmcli command from a WireGuard config file:

cargo run --bin nm-protun-service --features protun -- cli nm --read-config /path/to/wireguard.conf | bash
nmcli connection up proton0

Use this command to see stdout/stderr of the plugin.

sudo journalctl -u NetworkManager.service -f -o cat

Use the cli protun command to send commands to a running protun service. For example, to start and stop a packet capture:

cargo run --bin nm-protun-service --features protun -- cli protun pcap-start --file-path /tmp/capture.pcap
cargo run --bin nm-protun-service --features protun -- cli protun pcap-stop