Gnosis VPN Client

Gnosis VPN is a VPN solution build on top the HOPR mixnet. This repo contains the system service and a control application. It is part of a larger project consisting of:

• Gnosis VPN App handling user interface
• Gnosis VPN Server handling VPN server side

Reporting Issues

We use Gnosis VPN repository as the central hub for all user feedback.

How to report an issue

1. Visit Gnosis VPN Discussions board.
2. Search existing Discussions and Issues to see if your topic is already covered.
3. If not, start a new Discussion in the Issues & Bug Reports category.
4. Provide as much detail as possible using the provided template.

The team will review all discussions and promote confirmed bugs or planned features to actionable issues. This repository is reserved for tracking actionable work on this component.

General concept

The client offers three binaries, gnosis_vpn-root, gnosis_vpn-worker and gnosis_vpn-ctl. The client system service (gnosis_vpn-root) runs with root privileges and takes care of routing setup. It spawn the worker process (gnosis_vpn-worker) which is responsible for the application logic. The control application (gnosis_vpn-ctl) is used to manage the client and its connections.

Development setup

1. Create an extra user on your system (e.g. gnosisvpn) with normal privileges. This user will be used to run the worker process.

2. Only for: Ubuntu 26.04 LTS (TODO: remove once userspace wireguard is merged)

sudo tee /etc/apparmor.d/local/wg-quick >/dev/null <<'EOF'
# Local build: allow wg-quick to read the dev user's managed config.
/home/<VPN_USER>/wg0_gnosisvpn.conf r, # VPN_USER: e.g. gnosisvpn, gnosisvpnrotsee, gnosisvpnjura
EOF

sudo apparmor_parser -r /etc/apparmor.d/wg-quick`

3. Build binaries via: cargo build or nix build .#gnosis_vpn-dev.

4. Copy worker binary into user's home directory and make it owned by the user:

> sudo cp target/debug/gnosis_vpn-worker /home/gnosisvpn/
# or from nix build:
# sudo cp result/bin/gnosis_vpn-worker /home/gnosisvpn/
> sudo chown gnosisvpn:gnosisvpn /home/gnosisvpn/gnosis_vpn-worker

5. Run the root binary with sudo and provide the path to the worker binary:

> sudo RUST_LOG="debug" GNOSISVPN_HOME=/home/gnosisvpn ./target/debug/gnosis_vpn-root -c <config.toml> \
    --hopr-blokli-url <hopr blokli url> --worker-binary /home/gnosisvpn/gnosis_vpn-worker
# or from nix build:
> sudo RUST_LOG="debug" GNOSISVPN_HOME=/home/gnosisvpn ./result/bin/gnosis_vpn-root -c <config.toml> \
    --hopr-blokli-url <hopr blokli url> --worker-binary /home/gnosisvpn/gnosis_vpn-worker

Worker user configuration

There are three environment variables that control the worker process setup:

• GNOSISVPN_HOME: The home directory for the service. This is where state and caching data will be stored. Defaults to /var/lib/gnosisvpn on Linux and /Libary/Application Support/gnosisvpn on macOS.

• GNOSISVPN_WORKER_USER: The user with limited privileges that will run the worker process. This user needs to have read and execute permissions for the worker binary and write permissions for the GNOSISVPN_HOME directory. Defaults to gnosisvpn.

• GNOSISVPN_WORKER_BINARY: The path to the worker binary. The worker process will be spawned with this binary.

Testing

Unit tests

cargo test

Installation

Use the latest installer.

Verify integrity before installing - see SECURITY.md.

Idle shutdown

When --client-autostart <duration> (or GNOSISVPN_CLIENT_AUTOSTART) is set, the service starts the worker automatically on launch and shuts it down after the worker has been idle for the given duration.

The idle countdown behaves as follows:

• Idle: countdown runs; worker shuts down when it reaches zero.
• Connected: countdown is suspended for the lifetime of the VPN tunnel.
• Disconnected: countdown resumes from the full duration.
• Any other command to the worker (e.g. status) resets the countdown.

Example — shut down the worker after 10 minutes of idle time:

gnosis_vpn-root --client-autostart 10m ...

General usage

Check available params and env vars via:

gnosis_vpn-root --help gnosis_vpn-ctl --help

Dependency Updates

Renovate runs on Renovate's schedule:earlyMondays preset with a 14-day minimum release age, so most PRs appear early Monday morning and only for packages that have been released for at least two weeks.

Updates are grouped by ecosystem:

Group	What it covers	Notes
nix flake updates	flake.lock inputs (nixpkgs, crane, rust-overlay, …)	digest/pinDigest updates; pinDigests disabled for the nix manager since nix pins via flake.lock
github-actions	.github/workflows action refs	digest-pinned
(individual PRs)	Cargo crates	one PR per crate

prCreation: immediate is intentional — CI only triggers on pull request events, so waiting for branch checks would deadlock.

Deployment

Show potential deployment targets:

nix flake show

Build for a target, e.g. x86_64-linux or aarch64-linux:

# For x86_64 (AMD64)
nix build -L .#binary-gnosis_vpn-x86_64-linux

# For ARM64
nix build -L .#binary-gnosis_vpn-aarch64-linux

The resulting binaries are in result/bin/:

$ ls -l result*/bin/
result/bin/:
total 4752
-r-xr-xr-x 1 root root  4863367 Jan  1  1970 gnosis_vpn-root
-r-xr-xr-x 1 root root 14863367 Jan  1  1970 gnosis_vpn-worker
-r-xr-xr-x 1 root root  1740058 Jan  1  1970 gnosis_vpn-ctl