All docs sections
Here is the short version, with details on each item below.
| Limitation | In short |
|---|---|
| UDP, calls and games | Only TCP goes through the proxy. UDP from an app on the proxy is blocked or goes direct. |
| Domain rules | They work only when the app gives the site’s name. Connections to a bare IP follow the app’s route. |
| Browser profiles | All profiles of one browser follow the same route. |
| Extension restart | For a couple of seconds, new connections may go direct. |
| Other VPNs and extensions | Routekeeper doesn’t know about them and doesn’t check for conflicts. |
| Work HTTP proxy | Only Basic authentication: no NTLM, Kerberos or PAC. |
| Proxy types | Only SOCKS5, HTTP and HTTPS. Other protocols work through a local client. |
UDP: calls, voice and games
What you’ll notice.
- In an app that goes through the proxy, audio and video calls don’t connect or keep dropping, and voice channels don’t work.
- Online games through the proxy don’t connect or have long delays.
- A browser on the proxy opens sites as usual, but without QUIC (HTTP/3). You usually won’t notice this.
Why. The proxies Routekeeper works with (SOCKS5, HTTP and HTTPS) carry only TCP. UDP from an app whose route goes through a proxy never gets into the proxy:
- by default, it’s blocked: the proxy’s Block UDP and QUIC switch is on;
- if you turn the switch off, UDP goes direct, and the monitor flags it as UDP around the proxy.
Calls and games usually need UDP. Browsers see that QUIC is closed and switch to TCP by themselves. The service card (ⓘ in the Apps section) warns about this, for example: “Calls use UDP and don’t work through a proxy”.
What you can do.
- Keep apps for calls and games on the Direct route.
- If an app needs the proxy but you also want its calls, turn off Block UDP and QUIC for its proxy. Messages and files will go through the proxy, and calls will go direct, with your usual address. The monitor will flag them as UDP around the proxy. The switch belongs to the proxy, so it affects all the apps that go through it. For details, see DNS through proxy and UDP blocking.
- If calls must go through the server too, you need a tool that carries UDP, such as a VPN. Routekeeper doesn’t do this.
Details: UDP and DNS for an app on the proxy
- Routekeeper doesn’t use UDP relaying through SOCKS5 (UDP ASSOCIATE).
- DNS queries over UDP (ports 53 and 853) from an app on the proxy aren’t blocked. They go direct and are flagged as DNS around the proxy. You can block them with a rule. How this works is explained in DNS: how apps find a site’s address.
- For TCP connections through the proxy, the proxy itself finds the site’s address by its name if DNS through proxy is on (it’s on by default).
- With Settings → Network → Look up site addresses through the proxy, UDP DNS queries to port 53 of an app on the proxy go through the proxy, except local names. For details, see Site addresses through the proxy.
Domain rules need a site name
What you’ll notice. A rule like *.example.com → Through Proxy, or a service rule, doesn’t catch all the traffic. Some connections follow the app’s route, for example going direct. In the monitor, such connections have a bare IP in the Host column, and the Decision field shows the app’s route, not your rule.
Why. Domain and service rules compare the site name that the app gives when it connects. Connections to a bare IP have no name, and neither do most UDP and QUIC connections. Some apps look up addresses themselves and connect only by IP. Without a name, the rule doesn’t apply, and the connection follows the app’s route. The exception is services whose lists include subnets: they also match by IP.
What you can do.
- If the whole app should go through the proxy, set its route in the Apps section instead of using domain rules.
- If you know the addresses, add a rule by IP or subnet (CIDR). How to write one is explained in Rule fields.
- For a browser and a service, block UDP to port 443 for the browser. Then the browser switches to TCP, where the site name is available. For step-by-step instructions, see the recipe One service in the browser through a proxy.
For more, see Rules by site name.
Two profiles of one browser
What you’ll notice. You want the “Work” profile to go through one proxy and “Personal” through another. Both go the same way.
Why. Routekeeper recognizes apps by their code signature and processes. All profiles of one browser are one app with the same processes, and a profile isn’t visible at the network level.
What you can do.
- Use different browsers, for example Chrome for work and Firefox for personal use. Each one can have its own route.
- Within one browser, split the traffic by site with domain rules or services. For details, see Services.
Details: beta versions of browsers
Chrome Beta, Dev and Canary are separate apps with their own signatures, and you can give each its own route. But if Include Child Processes is on for Chrome, Chrome’s route covers them too: their signing IDs start with Chrome’s signing ID, and the developer is the same. To make a beta version go its own way, add it to Apps with its own route. A rule for the exact app takes priority over a rule for child processes. Beta versions of Edge work the same way.
Pause when the extension restarts
What you’ll notice. After the extension updates (starting with version 0.5.0, it updates by itself right after the app does), after you click Reinstall, or if macOS restarted the extension, connections through the proxy break off, and apps connect again. For a couple of seconds, new connections may go direct, around the proxy. They don’t appear in the monitor.
Why. Routekeeper makes its decisions inside the network extension. While the extension restarts, nobody checks connections, and macOS lets them through as usual. When you update the extension from the banner, Routekeeper warns about this in the confirmation dialog.
What you can do.
- Update Routekeeper while apps that must go only through the proxy are closed: starting with version 0.5.0, the extension updates together with the app. In version 0.4.1 and earlier, the extension updates only from the banner: Update…, then Update Now or Later. How to update Routekeeper is described on the Updates and removal page.
- After an update or reinstall, restart such apps: quit them and open them again. Connections that are already open don’t change their route. A connection that opened directly during the pause stays direct until it closes.
- Check in the monitor that the app’s new connections go through the proxy.
Details: when connections don’t go direct
If Routekeeper’s filter is already working, but the part that sends traffic through the proxy isn’t yet (for example, right after the Mac starts up), connections meant for the proxy are blocked instead of going direct. The app gets an error and tries again. This behavior is called fail-closed.
The Routekeeper On switch and Stop… let everything go direct on purpose. How the ways to turn Routekeeper off differ is described on the Updates and removal page.
Other VPNs and network extensions
Routekeeper doesn’t check whether the Mac has other VPNs, proxy clients or firewalls, and doesn’t warn you about them. What happens alongside them follows from how Routekeeper works:
- Routekeeper hands connections that don’t go through the proxy (the Direct route, or no rule) back to macOS untouched. From there, they go wherever the system sends them, through another VPN if one is on.
- Routekeeper’s own connection to the proxy server also goes wherever the system sends it. If a VPN for all traffic is on, the connection to the proxy goes inside it, and the proxy server sees the VPN’s address, not yours.
- Direct in the monitor means “not through a Routekeeper proxy”. If the system then sends such a connection into a VPN, Routekeeper doesn’t know about it.
What you’ll notice when there’s a conflict. An app doesn’t go where the monitor says. Sites see an unexpected IP. Apps on the proxy lose the network when another VPN connects or disconnects. The proxy check fails.
Why. Several programs that intercept connections can work at the same time: a proxy client in TUN or “system proxy” mode, another firewall, another app router. Routekeeper doesn’t control the order in which they see a connection.
What you can do.
- Keep just one “router”. If you use sing-box, Xray or Clash, turn off TUN mode and the system proxy in the client, and add its local SOCKS5 port to Routekeeper. For details, see the recipe On top of sing-box, Xray or Clash.
- If you have another firewall, allow the Routekeeper network extension (Routekeeper Extension) to connect to the proxy server in it. Otherwise, apps on the proxy will be left without a network.
- To find out whether another VPN gets in the way, turn it off for a while and check the IP in the menu bar and the monitor. See Checking and monitoring.
Work HTTP proxy: Basic only
What you’ll notice. Check shows HTTP: the proxy requires authentication (407), even though the login and password are correct. Or a browser works through the work proxy (it was set up automatically), but Routekeeper doesn’t. Or connections to ports other than 443 get an error like “The HTTP proxy answered 403 …”.
Why.
- Routekeeper sends the login and password for HTTP and HTTPS proxies only with the Basic method. It doesn’t support NTLM, Kerberos (Negotiate) or automatic configuration files (PAC).
- Routekeeper opens every connection with the CONNECT command, even plain HTTP to port 80. Some work proxies allow CONNECT only to port 443.
What you can do.
- Ask your administrators whether there is a way in with Basic authentication, or a SOCKS5 address.
- Run a go-between program on the Mac that supports NTLM or Kerberos (for example, Px or Cntlm). Add it to Routekeeper as an HTTP proxy with the address 127.0.0.1 and its port.
- For details, see the recipe A work proxy for internal addresses and the Work proxy section about the fields.
Details: SOCKS5 authentication
SOCKS5 works without a password or with a login and password (the username/password method). The login is 1 to 255 bytes, and the password is up to 255 bytes. Other SOCKS5 authentication methods aren’t supported: the check will show SOCKS5: the proxy accepted no authentication method.
Only SOCKS5, HTTP and HTTPS
What you’ll notice. You can’t add a link to a VLESS, Shadowsocks, WireGuard or similar server to Routekeeper.
Why. Routekeeper talks to proxies only over SOCKS5, HTTP CONNECT and HTTPS (CONNECT inside TLS). Chains of several proxies aren’t supported either.
What you can do. Run a client for that protocol on the Mac (sing-box, Xray, Clash and others) with a local SOCKS5 port, and add it to Routekeeper. For details, see the recipe On top of sing-box, Xray or Clash. If you don’t have a server of your own, you can set one up with the Your own proxy server guide.
Other things worth knowing
- Outgoing connections only. Routekeeper decides where the connections opened by programs on the Mac go. It doesn’t filter incoming connections, for example to a server running on this Mac.
- Open connections don’t move. A new route or rule applies to new connections. Restart messengers and other programs with long-lived connections, or wait until they reconnect.
- The Mac’s processor doesn’t matter. You need macOS 14 or later. The app is universal: it runs on both Intel and Apple Silicon. The server requirements are separate: the script from the Your own proxy server guide installs only on an x86_64 (amd64) server.
Checked against the Routekeeper code (version 0.2.1 and the one after it) on October 4, 2026.