Guide

From download to connected in a couple of minutes, and what to do when something doesn't work.

Install

Windows

1. Download NullVPN-windows-x64-setup.exe from the download page.
2. Run it. If SmartScreen says "Windows protected your PC", click More info → Run anyway. The installer isn't code-signed yet; nothing is wrong with it.
3. Allow administrator access when the installer asks.
4. System Proxy mode works straight away. For TUN mode, start NullVPN as administrator (right-click it → Run as administrator): it creates a virtual network adapter, and Windows only allows that with administrator rights. The app tells you if it needs this.

Android

1. Download the APK. Almost every phone from the last several years needs arm64-v8a; use armeabi-v7a only on old 32-bit phones and x86_64 only for emulators.
2. Open the file. If Android asks, allow your browser or file manager to install unknown apps.
3. If Google Play Protect warns that it hasn't scanned the app, tap Scan, or More info → Install.
4. The first time you connect, Android asks to allow a VPN connection. Tap OK.

Linux

For x86_64 distributions with glibc 2.34 or newer: Debian 12, Ubuntu 22.04, Linux Mint 21, Fedora 35, RHEL 9 and everything since.

Debian, Ubuntu, Mint:

sudo apt install ./NullVPN-linux-amd64.deb

Fedora, RHEL, openSUSE:

sudo dnf install ./NullVPN-linux-x86_64.rpm

Both add two menu entries: NullVPN for System Proxy mode, and NullVPN (TUN), which starts it with the permission TUN mode needs.

AppImage (any distribution with FUSE, nothing installed):

chmod +x NullVPN-linux-x86_64.AppImage
./NullVPN-linux-x86_64.AppImage

Manual (.tar.gz):

tar xzf NullVPN-linux-x64.tar.gz
cd NullVPN-*-x64
./nullvpn               # run it from here
sudo ./install.sh       # or install it, with menu entries and `nullvpn` on PATH

System Proxy mode needs no privileges and drives GNOME's proxy setting (GNOME, Cinnamon, Budgie, Unity). On KDE, Xfce or a bare window manager, point apps at 127.0.0.1:10809 yourself, or use TUN mode. To start TUN mode from a terminal:

pkexec env DISPLAY=$DISPLAY XAUTHORITY=$XAUTHORITY /opt/nullvpn/nullvpn

Running elevated still uses your servers and settings, not root's.

macOS

One app for Apple silicon and Intel Macs, macOS 12 or newer.

1. Download NullVPN-macos-universal.dmg, open it, and drag NullVPN into Applications.
2. The app isn't signed by Apple yet, so run this once in Terminal before opening it:

   xattr -dr com.apple.quarantine /Applications/NullVPN.app

3. System Proxy mode works straight away. TUN mode asks for your administrator password the first time, to install a small helper; after that, connecting asks for nothing.

To remove the TUN helper later:

sudo /Library/PrivilegedHelperTools/com.nullvpn.helper uninstall

iPhone and iPad

iOS 15 or newer. The .ipa is unsigned, so you sign it yourself.

1. Download NullVPN-ios-unsigned.ipa.
2. Sign and install it with ESign, Sideloadly or Xcode, using a certificate whose provisioning profile includes the Network Extension capability (packet tunnel). Without it the app installs but can't connect.
3. The first time you connect, iOS asks to add a VPN configuration. Tap Allow.

Psiphon and Tor bridges aren't available on iOS: both are separate programs, and iOS doesn't let an app run them.

Your first connection

NullVPN is a client: it connects to servers you add. If you have none, use Aether, the free tunnel built in.

1. Open Servers.
2. Add your servers: paste a subscription link, scan a QR code, or import from the clipboard (a vless://, vmess://, trojan:// or ss:// link, or a list of them).
3. Tap Ping all and pick the fastest to test every server and select the best one.
4. Go back to Home and tap the big button. The screen shows your new country and IP, the session time, and live speeds.

Subscriptions update in one tap from the Subscriptions tab in Servers. Servers you add one by one live under Local.

Aether: the free tunnel

Aether connects through Cloudflare WARP. No server, account or subscription needed.

1. In Servers, choose Add Aether.
2. Leave the defaults and save. The first time, it registers a device with Cloudflare; that takes a few seconds and happens once.
3. Select it and connect. Finding a working Cloudflare address can take up to a minute on a restricted network.

Options worth knowing

• Protocol: how it reaches Cloudflare. MASQUE (QUIC) is the fastest; MASQUE (TCP) works where UDP is throttled and is the one to try when nothing else connects; WireGuard is classic WARP. The two-hop options (WARP-in-WARP, MASQUE-in-MASQUE) give you an exit address from a different range.
• Scan: how hard it searches for a reachable Cloudflare address, from Turbo (fast) to Ironclad (most thorough).
• Tor: WARP, then Tor hides your traffic from Cloudflare too. Tor can use obfs4 bridges, built in or your own. Tor needs a carrier that stays up, so use MASQUE under it.
• Exit location: by default you come out at Cloudflare. Choose a country, or Fastest anywhere, to leave through a public relay there instead.

Tunnel modes

On desktop, choose in Settings → Connection → Tunnel mode.

On Android and iPhone, the VPN always carries the whole phone (on Android, or just the apps you pick; see Phone extras).

TUN options

These appear under Tunnel mode when TUN is selected. They apply on the next connect.

• TUN engine: Zeptun (the default) is lighter and faster. Xray is the core's own packet engine; switch to it if anything misbehaves.
• MTU: 1500 suits most networks. If pages start loading and then stall, lower it, e.g. to 1400.
• IPv6: sends IPv6 traffic through the tunnel too.
• Strict route: blocks traffic the tunnel can't carry instead of letting it go around it, so sites never see your real IP. Keep it on.

Rules and DNS

The Rules tab decides what goes through the proxy, what goes direct and what is blocked. Keeping local sites direct makes them faster and avoids breaking services that don't expect a foreign IP.

Settings → DNS Settings picks how names are resolved: DoH, DoT, DoQ or plain resolvers, with FakeDNS.

Settings → Rules → Geo files chooses where the routing databases (geoip.dat and geosite.dat) come from: Chocolate4U, Loyalsoldier, runetfreedom, v2fly or your own addresses. Update them by hand or on a schedule. Every download is checked against its publisher's checksum and against the categories your rules use, and a file that fails never replaces the one that works.

Updates

When a new version is out, NullVPN shows an update capsule with the version and the download size. It asks before doing anything, downloads with a progress bar, and checks the file against the release's SHA256SUMS.txt before installing it.

• Windows: NullVPN closes and the normal installer opens.
• Android: it picks the APK for your phone's architecture and opens Android's installer. The first time, allow NullVPN to install apps.
• Linux: it updates the package you installed: AppImage, .deb, .rpm or the tarball.
• macOS: it replaces the app and clears its quarantine flag, so no Terminal command is needed.
• iPhone: it opens the release page, since a new .ipa has to be signed again.

Updating keeps your servers, subscriptions and settings.

Phone extras

• Per-app proxy: choose which apps go through the VPN, or which ones skip it, in the Rules tab.
• Quick Settings tile: pull down the notification panel, tap Edit, and drag NullVPN into your toggles. It connects even with the app closed.
• iPhone Control Center (iOS 18 and later): open Control Center, tap +, then Add a Control, and choose NullVPN. It also works on the Lock Screen and the Action button, and connects with the server you last used. Connect once from the app first.

Subscriptions that limit devices

Some providers refuse to list servers unless the app sends a device ID. This is off by default. If you need it, turn on Settings → Subscriptions → Send device ID to subscriptions, then update the subscription.

Troubleshooting

FAQ