# VPN Bypass

![VPN Bypass](<https://geiserx.github.io/VPN-Bypass/images/banner.svg>)

[![Downloads](<https://img.shields.io/github/downloads/GeiserX/VPN-Bypass/total?style=flat-square&amp;logo=apple&amp;logoColor=white>)](<https://github.com/GeiserX/VPN-Bypass/releases>) [![GitHub Stars](<https://img.shields.io/github/stars/GeiserX/VPN-Bypass?style=flat-square&amp;logo=github>)](<https://github.com/GeiserX/VPN-Bypass/stargazers>) [![Release](<https://img.shields.io/github/v/release/GeiserX/VPN-Bypass?style=flat-square>)](<https://github.com/GeiserX/VPN-Bypass/releases>) [![License: GPL-3.0](<https://img.shields.io/github/license/GeiserX/VPN-Bypass?style=flat-square>)](<https://github.com/GeiserX/VPN-Bypass/blob/main/LICENSE>)

---

**VPN Bypass** is a macOS menu bar app that decides which traffic goes through your VPN. In Bypass mode the services and domains you pick go straight to the internet and everything else stays on the VPN. VPN Only mode is the reverse, and Custom mode gives each rule its own exit. Install it with [Homebrew](<https://geiserx.github.io/VPN-Bypass/getting-started/index.md>), then pick a mode in [Routing modes](<https://geiserx.github.io/VPN-Bypass/routing/index.md>).

Corporate VPN clients send everything through the tunnel, so streaming stalls, AirPlay and Chromecast break, and personal traffic crosses the company network. Most clients lock their own split tunnelling, and a route added by hand is gone at the next reconnect or when a CDN moves. VPN Bypass adds the routes for you and puts them back every time the VPN or the network changes.

- **[Install](<https://geiserx.github.io/VPN-Bypass/getting-started/index.md>)**

  ---

  Three Homebrew lines, or the DMG from Releases. Needs macOS 13 or later.
- **[First run](<https://geiserx.github.io/VPN-Bypass/getting-started/#first-run>)**

  ---

  Approve one admin prompt, connect your VPN, turn on a service, and see what "working" looks like.
- **[Everyday use](<https://geiserx.github.io/VPN-Bypass/usage/index.md>)**

  ---

  The dropdown, the Settings pages, the `vpnb` command line and the [MCP server](<https://geiserx.github.io/VPN-Bypass/mcp-server/index.md>) for AI agents.
- **[Routing modes](<https://geiserx.github.io/VPN-Bypass/routing/index.md>)**

  ---

  Bypass, VPN Only and Custom: routes, rules and the first-match order.

## The menu bar app

Everything lives in the dropdown: the VPN it found, a status chip that says whether routes are enforced, the mode, a field to add a domain, and what is routed, one row per service or domain you added. Settings opens from the gear at its foot. See [Usage](<https://geiserx.github.io/VPN-Bypass/usage/index.md>).

![The dropdown in Bypass mode: WireGuard connected, the status chip reads On, and four services and two domains skip the VPN, each with how many addresses it routes](<https://geiserx.github.io/VPN-Bypass/images/screenshots/menu-bar.png>)

Bypass mode

![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>)

First run

![The dropdown in VPN Only mode: the mode track on VPN Only, the status chip reads On, two domains go through the VPN, and everything else goes direct](<https://geiserx.github.io/VPN-Bypass/images/screenshots/vpn-only.png>)

VPN Only mode

## Settings

Status comes first and says whether it is working right now: the helper, the VPN and gateway, the routes, DNS, the tunnels and recent warnings. Every page is in the sidebar in every mode. Bypass and VPN Only use Domains and Services, Custom mode uses Rules and Routes, and a page of another mode opens read-only. General holds launch at login, `/etc/hosts` and notifications; Logs and About are for debugging. See [Settings](<https://geiserx.github.io/VPN-Bypass/usage/#settings>).

![The Services page: Your services lists Telegram, WhatsApp, YouTube and Spotify, each with what it holds, the addresses it routes and its switch, and Browse catalogue… under the list](<https://geiserx.github.io/VPN-Bypass/images/screenshots/services.png>)

![The Rules page in Custom mode: a domain sent to a SOCKS5 proxy, a service sent direct, a subnet sent to the VPN, and Everything else as the last row](<https://geiserx.github.io/VPN-Bypass/images/screenshots/rules.png>)

Rules, first match wins

![The Routes page in Custom mode: Direct and the detected VPN under Always there, and a SOCKS5 proxy route with its local address and upstream on one line](<https://geiserx.github.io/VPN-Bypass/images/screenshots/routes.png>)

Routes: where traffic can exit

## What it changes on your Mac

- Host routes in the system routing table, one per resolved address of each domain or service pack you turned on. In Bypass mode they point at your local gateway, in VPN Only mode at the VPN interface, in Custom mode at whatever the matching rule says. The app removes its routes when you quit, when you choose Remove All Routes…, and when the VPN goes away.
- Entries in `/etc/hosts`, only if you turn on Pin listed names in /etc/hosts in Settings \> General.
- One small root helper, installed once with your admin password as a launchd daemon. It is the only part that runs as root, it does nothing but add and remove routes and hosts entries, and it accepts requests from this app alone (pinned to the app's code hash). There is no Network Extension and no kernel extension, so nothing to approve in System Settings beyond the Login Items entry on macOS 13 and later.
- A config file and a log under `~/Library/Application Support/VPNBypass/`, plus a socket there that only your account can open, which is what `vpnb` and the [MCP server](<https://geiserx.github.io/VPN-Bypass/mcp-server/index.md>) talk to.

## How it runs

```
flowchart LR
    U[You] --> M[Menu bar app]
    C[vpnb CLI] -->|user-only socket| M
    A[MCP server] -->|user-only socket| M
    N[VPN connects, disconnects,<br/>network changes] --> M
    M -->|resolves| D[Domains and service packs]
    M -->|XPC| H[Root helper]
    H --> R[Routing table]
    H -.->|optional| E["/etc/hosts"]
```

- The app watches the network interfaces and running processes. A tunnel counts as a VPN when it is up and has an IPv4 address in a VPN range; Tailscale counts only when it is an exit node. See [Supported VPN types](<https://geiserx.github.io/VPN-Bypass/how-it-works/#supported-vpn-types>).
- When the VPN connects, disconnects, or the network changes, the routes are rebuilt. Domains are re-resolved on a schedule, so a route follows a CDN when its addresses rotate.
- With several tunnels up, Bypass and VPN Only act on one and leave the others alone; in Custom mode a VPN route can name a specific tunnel. See [Other VPNs and proxies](<https://geiserx.github.io/VPN-Bypass/coexistence/index.md>).
- Route verification checks which way up to 10 routed single addresses leave and whether they answer on port 443, with a control address that must leave the other way, and says how many of the routes it checked. `vpnb why <host>` answers the same for any site, with the entry or rule that routes it.
- A proxy route is a listener on `127.0.0.1` that forwards to the proxy you gave it; a Tailscale peer route sends traffic out through a device already in your tailnet. The app runs no VPN of its own.

## What it does not do

- It does not route per application. Rules are about where traffic goes, never about which process sent it; that would need a Network Extension, which the app deliberately does not use.
- It never touches Tailscale's own range, loopback, or kernel-reserved addresses, whatever a rule asks for, and it never picks Tailscale as the VPN to act on. See [Addresses that are never touched](<https://geiserx.github.io/VPN-Bypass/coexistence/#addresses-that-are-never-touched>).
- It does not change what your VPN client does with DNS. The `/etc/hosts` option works around a client that forces DNS through the tunnel; it does not switch that off.

## Privacy

- The app talks to no server of its own: no telemetry, no update check, no account. The only network activity it starts is resolving the domains you list, forwarding traffic to a proxy you configured, and, when you check routes, opening a connection to port 443 of up to 10 routed destinations and of the site you ask `vpnb why` about, plus one connection attempt to a documentation address (`192.0.2.1`, `198.51.100.1` or `203.0.113.1`) that serves as the check's control and is closed before it completes.
- Config, logs and proxy credentials stay in your account's Application Support folder. The Logs tab shows local events only.
- Proxy credentials live in the config file, readable by your account alone, and the local listener asks for them, so another account on the same Mac cannot spend them. `vpnb` reads passwords from standard input, never from the command line.

## Getting help

- If something does not work, read [Troubleshooting](<https://geiserx.github.io/VPN-Bypass/troubleshooting/index.md>) first, then open a [bug report](<https://github.com/GeiserX/VPN-Bypass/issues/new?template=bug_report.yml>) with the details it asks for.
- For a question, use the [question template](<https://github.com/GeiserX/VPN-Bypass/issues/new?template=question.yml>).
- To report a security problem, follow the [security policy](<https://github.com/GeiserX/VPN-Bypass/blob/main/SECURITY.md>) and do not open a public issue.
- What changed between versions is on the [Releases](<https://github.com/GeiserX/VPN-Bypass/releases>) page. Planned work is in the [roadmap](<https://github.com/GeiserX/VPN-Bypass/blob/main/ROADMAP.md>).
- To build it or send a fix, read [Development](<https://geiserx.github.io/VPN-Bypass/development/index.md>).

## License

VPN Bypass is released under the [GPL-3.0-or-later](<https://github.com/GeiserX/VPN-Bypass/blob/main/LICENSE>) license.
