# Getting started

## Homebrew (Recommended)

```
# Add the tap (first time only)
brew tap geiserx/vpn-bypass

# Trust the tap (first time only, required on Homebrew 6+)
brew trust --cask geiserx/vpn-bypass/vpn-bypass

# Install VPN Bypass
brew install --cask vpn-bypass
```

The tap is the canonical install path: it tracks the latest release and updates with `brew upgrade`. After an upgrade the running app notices the new copy within 30 seconds and restarts into it. On Homebrew 6+, trust the tap first (as shown above) or the install will be blocked.

Do not install the raw `Casks/vpn-bypass.rb` from this repository; it is a frozen snapshot and installs an old build.

## Manual Download

Download the latest `.dmg` from [Releases](<https://github.com/GeiserX/VPN-Bypass/releases>), open it, and drag **VPN Bypass** to your Applications folder.

## Build from Source

```
# Clone the repository
git clone https://github.com/GeiserX/VPN-Bypass.git
cd VPN-Bypass

# Build and run
make run
```

The privileged helper only accepts an app signed with the project's Developer ID, so a build from source can't use it as is. To run your own build, put your team ID in `HelperConstants.teamIdentifier` and in the two code requirements in `Info.plist` and `Helper/Info.plist`, then sign with your certificate. `make release` signs, notarizes and builds the DMG; it needs `SIGN_IDENTITY` and notary credentials, listed at the top of [`scripts/sign-and-notarize.sh`](<https://github.com/GeiserX/VPN-Bypass/blob/main/scripts/sign-and-notarize.sh>).

## Xcode

Open `Package.swift` in Xcode and run the project.

## First run

1. Open VPN Bypass from Applications. It lives in the menu bar; there is no Dock icon.
2. macOS asks for an administrator password once. That installs the root helper that edits the routing table. On macOS 13 and later it may also ask you to allow VPN Bypass under System Settings \> General \> Login Items; the app says so in its dropdown when that is the case.
3. Connect your VPN. The dropdown reads VPN Connected and names the client it found.

A fresh install routes nothing. The status chip in the dropdown reads Off, in grey, and the dropdown asks "What should skip the VPN?" with six common services, each with a switch, a row for all the services, and a field to add a site.

![The dropdown right after install: WireGuard connected, the status chip reads Off, and the question What should skip the VPN? over six services with switches and a field to add a site](<https://geiserx.github.io/VPN-Bypass/images/screenshots/first-run.png>)

Switch on a service there, or type a site into the field and press Return. "All 75 services…" opens Settings on the Services page with the service catalogue open. When the Mac's region (System Settings \> General \> Language &amp; Region) is a country the catalogue has services for, a row above it, such as "Services for Spain…", opens the catalogue on that country's government sites and banks. The region is read as it is; nothing is asked. If you want the opposite, only a few sites on the VPN, click "Use VPN Only instead…". It worked when:

- the status chip reads On;
- the menu bar mark shows its arrow head (it is two plain lines and a bar while nothing is routed);
- the question gives way to the normal dropdown, and the service or domain appears under Skipping the VPN with how many addresses it routes.

If the status chip reads Not routing and the dropdown says the helper is not running, Settings \> Status shows its state, with an Install, Update or Retry button; the dropdown's Fix… button opens it. If macOS says the app is damaged, see [Troubleshooting](<https://geiserx.github.io/VPN-Bypass/troubleshooting/#app-wont-open-damaged-error-macos-gatekeeper>).

## Uninstall

1. If you turned on per-app routing, turn it off first in Settings \> General (or `vpnb engine.off`), and enter your administrator password when macOS asks: that removes its extension. Quit only once Settings \> General says the extension is removed or will be removed at the next restart (`vpnb engine.status` shows `removal: removed` or `needsRestart`); quitting before that can leave it installed. Homebrew cannot remove it once the app is gone; see [Remove the per-app routing extension](<https://geiserx.github.io/VPN-Bypass/troubleshooting/#remove-the-per-app-routing-extension>).
2. Quit VPN Bypass from its menu. Quitting removes its routes and its `/etc/hosts` entries.
3. `brew uninstall --cask vpn-bypass` (add `--zap` to delete your settings too), or move the app from Applications to the Bin.
4. Remove the privileged helper. Stopping it removes its wildcard resolver files from `/etc/resolver`:

```
sudo launchctl bootout system/com.geiserx.vpnbypass.helper
sudo rm -f /Library/PrivilegedHelperTools/com.geiserx.vpnbypass.helper /Library/LaunchDaemons/com.geiserx.vpnbypass.helper.plist
```

## Requirements

- macOS 13.0 (Ventura) or later
- Admin privileges (for route management and hosts file)

## Permissions

The app requires: - **Network access**: To detect VPN connections and resolve domains - **Admin privileges**: To add routes and modify `/etc/hosts` (prompted when needed) - **Notifications**: Optional, for VPN status alerts (prompted on first launch)
