Routekeeper
Quick start
- Install Routekeeper and complete the macOS onboarding: allow the system extension, network filter and proxy configuration.
- Add a proxy in Proxies. For a personal server, HTTPS on port 443 or a local SOCKS5 port from sing-box, Xray or Clash are the most common choices.
- Enable DNS through proxy when the proxy supports it, so names are resolved away from your ISP.
- Enable UDP and QUIC blocking for browsers and messengers when you need a no-leak setup.
- Create a rule: app → proxy, direct or block. Routekeeper recognizes apps by signature and follows helper processes.
- Check Monitor and Leaks: they show what went through the proxy, what went direct and what looks suspicious.
Common recipes
Add ChatGPT, Claude, Codex, Cursor, VS Code, Terminal or iTerm. A terminal rule covers child processes such as curl, git, npm, pip and brew.
Route the app or browser through a proxy. For a browser, narrow the rule to service domains, such as YouTube, while banks and local sites stay direct.
Let another client handle VLESS, Shadowsocks or another protocol, while Routekeeper decides which apps use its local SOCKS5 port, for example 127.0.0.1:1080.
Create a rule for work domains, subnets or ports: *.corp.example through the office proxy, everything else direct.
Run Tor locally and add SOCKS5 127.0.0.1:9050. Enable DNS through proxy so names resolve inside Tor.
Route an app through a proxy and do not allow direct fallback. If the proxy is down, connections do not leave directly.
Your proxy
Routekeeper supports SOCKS5, HTTP CONNECT and HTTPS proxies. For the public internet, an HTTPS proxy on your own VPS is usually the practical option: from the outside it looks like a normal TLS site on port 443.
One simple server setup is Caddy with forwardproxy@naive. In Routekeeper, add it as type “HTTPS”: domain, port 443, username and password.
Scripts/deploy-proxy-server.sh -H root@<IP> -d <domain> -i ~/.ssh/<key>If HTTPS proxying is unstable on your network, use sing-box or Xray on the server and a local SOCKS5 client on the Mac. In Routekeeper you only change the proxy; app rules stay as they are.
Leak checks
The useful check is not one external website, but comparing three places: Routekeeper Monitor, the Leaks tab and the proxy server’s active connections.
- Open the app that has a proxy rule.
- In Routekeeper Monitor, make sure connections are marked with the expected proxy, not “direct”.
- Open Leaks: direct DNS, rule bypasses and UDP are shown separately.
- On your server, check active proxy connections and make sure they come from your Mac.
Apple push notifications may go through the system apsd process rather than through the app’s rule. That is normal: it is not the app’s own traffic.
Limits
| Scenario | Status | Why |
|---|---|---|
| Regular app TCP traffic | Works well | Routekeeper intercepts outgoing TCP connections and applies rules. |
| DNS through proxy | Works when the hostname is known | If the app provides a hostname, the proxy resolves it. |
| QUIC, UDP, calls and voice | Limited | Current proxy routes carry TCP. Block UDP when a no-leak setup matters. |
| Games | Usually not a fit | Many games use UDP and custom network protocols. |
| Two browser profiles on different proxies | Not supported | Rules are attached to the app and process signature, not to an in-app profile. |
Troubleshooting
- Proxy check fails: verify domain, port, username, password and certificate. For HTTPS, use a domain, not an IP address.
- The app goes direct: make sure the rule targets the right app and helper processes are included.
- The browser bypasses the proxy: enable UDP and QUIC blocking, then restart the tab or browser.
- Monitor is empty: make sure the system extension and network filter are allowed in macOS Settings.
- You need to attach diagnostics: collect the archive in Routekeeper Settings, inspect it and only then attach it to a public issue.
Bug reports and feature requests belong in GitHub Issues. If your report contains private addresses or logs, remove the extra details first.