Skip to main content

​
Overview

The Mullvad VPN repository contains all source code for desktop and mobile versions of the app, including the system daemon, graphical and command-line interfaces, and platform-specific implementations.

​
Top-Level Structure

​
Application Components

  • mullvad-daemon/ - Main Rust crate building the daemon binary
  • mullvad-cli/ - Terminal-based CLI frontend for controlling the daemon
  • desktop/ - Electron + React GUI application
  • android/ - Android app with dedicated frontend
  • ios/ - Standalone iOS implementation

​
Build and Distribution

  • build.sh - Main build script that performs sanity checks and builds installers
  • build-windows-modules.sh - Compiles C++ libraries required on Windows
  • dist-assets/ - Icons, binaries, and files for creating distributables
    • binaries/ - Git submodule with third-party binaries (Wintun, etc.)
    • linux/ - Scripts and configuration for deb/rpm packages
    • pkg-scripts/ - Scripts for macOS pkg installer
    • windows/ - NSIS installer configuration and assets

​
Submodules

  • dist-assets/binaries/ - Git submodule containing third-party binaries and build scripts
  • wireguard-go-rs/libwg/wireguard-go - WireGuard Go implementation (required for Android, Windows, Linux, macOS)
All merge commits in the binaries submodule must be signed. See wireguard-go-rs README for details.

​
Cargo Workspace

The repository uses a Cargo workspace structure defined in the root Cargo.toml.

​
Workspace Members

The workspace includes 47 crates organized into two main categories:

​
Mullvad-Specific Crates

Crates prefixed with mullvad- contain Mullvad-specific functionality:
  • mullvad-daemon - Main daemon binary
  • mullvad-cli - CLI application
  • mullvad-api - API client for Mullvad services
  • mullvad-management-interface - gRPC management interface
  • mullvad-relay-selector - VPN relay selection logic
  • mullvad-types - Shared type definitions
  • mullvad-paths - Platform-specific path handling
  • mullvad-logging - Logging configuration
  • mullvad-fs - File system utilities
  • mullvad-problem-report - Problem report generation
  • mullvad-version - Version information
  • mullvad-encrypted-dns-proxy - DNS proxy functionality
  • mullvad-masque-proxy - MASQUE protocol proxy
  • mullvad-exclude - Process exclusion utilities
  • mullvad-leak-checker - VPN leak detection

​
Platform-Specific Mullvad Crates

  • mullvad-jni - Android JNI bindings
  • mullvad-ios - iOS-specific code
  • mullvad-nsis - Windows NSIS installer
  • mullvad-setup - Installation and setup
  • mullvad-update - Auto-update functionality

​
Talpid Crates

Crates prefixed with talpid- provide generic VPN client functionality independent of Mullvad specifics:
  • talpid-core - Main VPN client implementation (Mullvad-agnostic)
  • talpid-tunnel - Tunnel management
  • talpid-wireguard - WireGuard integration
  • talpid-routing - Routing table management
  • talpid-dns - DNS configuration
  • talpid-net - Network utilities
  • talpid-future - Async utilities
  • talpid-time - Time-related utilities
  • talpid-tunnel-config-client - Tunnel configuration

​
Platform-Specific Talpid Crates

  • talpid-platform-metadata - Platform detection
  • talpid-dbus - D-Bus integration (Linux)
  • talpid-macos - macOS-specific functionality
  • talpid-windows - Windows-specific functionality

​
Other Crates

  • wireguard-go-rs - Rust bindings for wireguard-go
  • tunnel-obfuscation - Traffic obfuscation
  • windows-installer - Windows installer tools
  • installer-downloader - Installer download utilities
  • android/translations-converter - Translation file converter
  • desktop/packages/nseventforwarder - macOS event forwarding
  • desktop/packages/windows-utils - Windows utility functions

​
Default Members

Running cargo build in the root directory only builds:
  • mullvad-cli
  • mullvad-daemon
  • mullvad-problem-report
  • mullvad-version
To build all crates, use cargo build --workspace.

​
Workspace Configuration

  • Edition: Rust 2024
  • Minimum Rust version: 1.91.0
  • License: GPL-3.0-or-later
  • Resolver: Version 2

​
Design Philosophy: Mullvad vs Talpid

​
Talpid: Generic VPN Client

Talpid crates implement a generic, privacy-focused VPN client with no knowledge of:
  • Mullvad API endpoints
  • Mullvad account management
  • Mullvad relay lists
  • Mullvad-specific business logic
Talpid provides:
  • Secure tunnel establishment
  • Firewall management
  • DNS leak protection
  • Kill switch functionality
  • Split tunneling
  • Generic VPN client operations

​
Mullvad: Service Integration

Mullvad crates build on Talpid to create the Mullvad-specific VPN client:
  • API communication with Mullvad servers
  • Account authentication and validation
  • Relay server selection
  • Mullvad-specific features (multihop, DAITA, etc.)
  • App settings and preferences
This separation ensures the core VPN functionality remains reusable and independently testable.

​
Desktop Application Structure

​
Electron App (desktop/packages/mullvad-vpn/)

desktop/packages/mullvad-vpn/
├── assets/              # Graphics and stylesheets
├── src/
│   ├── main/
│   │   └── index.ts     # Main process entry point
│   └── renderer/
│       ├── app.tsx      # Renderer process entry
│       ├── routes.tsx   # Route configuration
│       └── transitions.ts # View transition rules
├── tasks/               # Gulp build tasks
│   └── distribution.js  # electron-builder config
└── test/                # Electron GUI tests

​
Additional Desktop Packages

  • desktop/packages/nseventforwarder - macOS event forwarding (native)
  • desktop/packages/windows-utils - Windows utility functions (native)

​
File Paths

​
Settings Directory

Can be overridden with MULLVAD_SETTINGS_DIR
PlatformPath
Linux/etc/mullvad-vpn/
macOS/etc/mullvad-vpn/
Windows%LOCALAPPDATA%\Mullvad VPN\
AndroidgetFilesDir()

​
Log Directory

Can be overridden with MULLVAD_LOG_DIR
PlatformPath
Linux/var/log/mullvad-vpn/ + systemd
macOS/var/log/mullvad-vpn/
WindowsC:\ProgramData\Mullvad VPN\
AndroidgetFilesDir()

​
Cache Directory

Can be overridden with MULLVAD_CACHE_DIR
PlatformPath
Linux/var/cache/mullvad-vpn/
macOS/Library/Caches/mullvad-vpn/
WindowsC:\ProgramData\Mullvad VPN\cache
AndroidgetCacheDir()

​
RPC Address File

Can be overridden with MULLVAD_RPC_SOCKET_PATH
PlatformPath
Linux/var/run/mullvad-vpn
macOS/var/run/mullvad-vpn
Windows//./pipe/Mullvad VPN
AndroidgetNoBackupFilesDir()

​
Desktop GUI Settings

PlatformPath
Linux$XDG_CONFIG_HOME/Mullvad VPN/gui_settings.json
macOS~/Library/Application Support/Mullvad VPN/gui_settings.json
Windows%LOCALAPPDATA%\Mullvad VPN\gui_settings.json

​
Submodules

​
Required Submodules

Basic submodules (first level only): 
git submodule update --init
WireGuard Go submodule (required for most platforms): 
git submodule update --init wireguard-go-rs/libwg/wireguard-go
Android Rust plugin: 
git submodule update --init android/rust-android-gradle-plugin
iOS WireGuard: 
git submodule update --init --recursive ios/wireguard-apple

​
Avoiding Recursive Clone

Some submodules have their own large submodules not needed for building. Clone the repository normally, then get only one level of submodules: 
git clone https://github.com/mullvad/mullvadvpn-app.git
cd mullvadvpn-app
git submodule update --init  # Not --init --recursive

​
Vocabulary

  • App - The entire product (everything in the repository)
  • Daemon - The mullvad-daemon Rust program (headless, management interface)
  • Frontend - Any program connecting to the daemon:
    • GUI - Electron + React graphical interface
    • CLI - mullvad terminal-based interface

Build docs developers (and LLMs) love

Get started for freeTalk to us