LeanVPN

A tiny, menu-bar-only Proton VPN client for macOS that does one thing: put you on the fastest server that isn't overloaded, and move you to another one when it fills up or stops answering.

Unofficial. LeanVPN is an independent project. It is not made, endorsed or supported by Proton AG. "Proton" and "Proton VPN" are trademarks of Proton AG. You need your own Proton account. Use it at your own risk (see Disclaimer).

Status: alpha. It works daily on the author's Mac, but it has been tested on exactly one machine. See Status and testing before relying on it.

Website: https://zephyrsai.github.io/LeanVPN/

Why

The official app is a 233 MB, full-featured client. My real problem was simpler: servers got congested and the connection kept dropping, so I was constantly switching servers by hand. LeanVPN picks a good server by itself, keeps checking it, and switches before you notice. It has no window, no settings, no country list. Just a shield in the menu bar.

Footprint

Measured on an M-series MacBook Pro, macOS 26 (memory = Activity Monitor's "Memory" column):

	LeanVPN	Proton VPN 6.5.1
On disk	6.1 MB (app 124 KB + helper 6 MB)	233 MB
Menu-bar app memory	11–15 MB	168 MB
Background helper	Only while connected; exits 30 s after you disconnect	Always running
Idle CPU	~0% (one cheap counter check every 10 s)	Noticeable over a day
Picking a server	~0.3 s (all candidates probed in parallel)	n/a

Requirements

• An Apple silicon Mac running macOS 13 Ventura or later
• A Proton account. Free works (free servers only); paid plans can use every non-Secure-Core server.
• Apple's Command Line Tools: xcode-select --install
• Go: brew install go

No Xcode, no Apple developer account, no App Store.

Install

git clone https://github.com/ZephyrSai/LeanVPN.git
cd LeanVPN
make install

make install builds everything (about a minute the first time), then asks for your admin password once. That's needed to install the background helper that creates the VPN interface. The installer:

• copies LeanVPN.app to /Applications and starts it (it also starts at login);
• installs the helper to /Library/PrivilegedHelperTools/com.leanvpn.helper and registers it with launchd (/Library/LaunchDaemons/com.leanvpn.helper.plist). launchd only starts it when the app asks, and it quits again when the VPN is off.

Quit the official Proton VPN app first. Two VPNs at once fight over routes and DNS.

Sign in (one time)

LeanVPN never sees your password. It uses Proton's "enter a code on the web" sign-in, the same flow the Proton VPN Apple TV app uses.

1. Click the shield in the menu bar, then Sign In…
2. Your browser opens account.protonvpn.com/appletv and the 8-character code is already on your clipboard. Sign in to Proton there if asked, paste the code and approve.
3. That's it. LeanVPN connects on its own a few seconds later.

If that page doesn't load (some networks block protonvpn.com), open the same address on your phone over mobile data and type the code shown in the LeanVPN menu. The code is valid for about 10 minutes.

Using it

Icon	Meaning
Shield with a check	Connected. Hover for server, city, load and latency.
Half-filled shield	Connecting or switching servers
Shield with !	Waiting for network, or the last attempt failed (it retries by itself)
Plain shield	Disconnected
Shield with a slash	Signed out

The menu only ever shows what makes sense right now: Connect, Disconnect, Switch Server (jump to the next-best server), Retry Now, Sign Out, and Quit (which also turns the VPN off).

If you were connected when you shut down, LeanVPN reconnects after a restart.

How it picks a server

1. Shortlist. Out of Proton's server list (filtered to your plan, skipping Secure Core, Tor, restricted servers and servers in maintenance): the 10 best by Proton's own score (distance + load from where you are), plus the 6 least-loaded of the 60 nearest.
2. Measure. Real latency to every candidate at once: a TCP connect to each server, sent over your normal connection, never the tunnel. About 0.3 s in total.
3. Score. Lowest latency_ms + 300 × (load/100)² wins. Load hardly matters when it's low, but it dominates as a server nears saturation. A 40 ms server at 90% load loses to a 90 ms server at 30% load.
4. Verify. A WireGuard handshake isn't proof a server works (overloaded servers often complete one), so LeanVPN also needs an answer from Proton's in-tunnel DNS resolver before it calls itself connected. If there's no answer, it tries the next server, up to 4, rotating through Proton's alternative WireGuard ports in case your network blocks the default one.

How it stays connected

Every 10 seconds the helper reads two counters from WireGuard. That costs almost nothing.

• Stalled (sending but receiving nothing for 20 s), or no handshake for 200 s: it asks the in-tunnel resolver. No answer twice means it switches to the next-best server, and avoids the dead one for 30 minutes.
• Every 15 minutes: it refreshes server loads. If yours is 85% full or more and one at least 20 points lighter exists, it moves. A server entering maintenance is left immediately.
• Network changes (Wi-Fi ↔ Ethernet, sleep/wake, DHCP renewals): it re-pins the server route, rebinds the socket and re-applies DNS.
• Certificates and sign-in tokens are renewed automatically. If Proton's API can't be reached, a still-valid certificate and the cached server list are enough to connect.
• If switching fails, the tunnel is taken down rather than left routing your traffic nowhere, and LeanVPN keeps retrying (immediately when your network comes back).
• If the helper ever crashes, launchd restarts it; it restores your DNS and reconnects.

This is the beginning of the README. Read the rest at the original. Read the full README ↗