All docs sections
The recipes assume that Routekeeper is already installed, the macOS permissions are given and at least one proxy is added. If not, start with the Quick start.
The whole app, and how to make sure it really goes through the proxy.
One service in the browserThe service through a proxy, other sites direct.
DNS over HTTPS in the browserSo that the browser doesn’t look up site addresses around the proxy.
Terminal and AI appsgit, npm, pip, brew, curl and Mac apps.
On top of sing-box, Xray or ClashRoutekeeper sends apps to the client’s local port.
A work proxyOnly for your company’s internal addresses.
The proxy stopped answeringWhat happens and how to move the routes.
Proxy Only mode suits all the recipes: only your rules apply, and everything else goes direct. You choose the mode in the panel at the bottom of the window’s sidebar or in the menu of the menu bar icon. The stricter modes are described in Firewall modes.
A whole messenger through a proxy
Who it’s for: you want a messenger on your Mac (for example, a work Slack) to go online only through your proxy, while other programs work as usual.
Here it’s better to send the whole app through the proxy, not separate sites. Messengers often connect to their servers by IP address, without a site name. A domain rule won’t recognize such a connection, but an app’s route applies to all of its connections.
Steps
- Open the Routekeeper window (menu bar icon → Open Routekeeper) and go to Proxy. Make sure the proxy has a green dot. If the dot is gray or red, select the proxy and click Check. Next to the button, you’ll see “Working”, the response time and the external IP, or an error message.
- Go to Apps, click Add → From Installed Apps…, select the messenger and click Add. You can also simply drag the app from Finder into the list.
- Look at the messenger’s row. Its route is on the right, for example Amsterdam, the proxy’s name. A new app gets the main proxy right away: the one that most rules go through. If there are no proxies yet, the route is Direct. To choose another proxy, click the route and pick one in the menu.
- Right-click the row and check that Include Child Processes is selected. It is by default. Then the messenger’s helper processes follow the route too, and they usually carry almost all of its traffic.
- Quit the messenger completely (⌘Q) and open it again. Connections that are already open don’t move to the new route, and messengers keep a connection open for hours.
How to check
- On the Overview screen, the Through Proxies Now block shows the messenger and the proxy it goes through.
- In Monitor, type the messenger’s name in the search field. In the Route column, its connections should show the proxy’s name, not Direct. If you select a row, the Decision field at the bottom shows which rule applied.
- The Leaks section should stay empty for the messenger. What shows up there and what doesn’t is described in What Routekeeper notices and what it doesn’t.
Pitfalls
- Calls. Voice and video usually go over UDP, but a proxy carries only TCP. By default, Routekeeper blocks UDP for apps on a proxy, so calls through the proxy most likely won’t work. For details, see Limitations.
- If the proxy goes down, the messenger won’t switch to a direct connection. It will show “Connecting…”. This is by design. What to do in this case is described in the recipe The proxy stopped answering.
- Push notifications are delivered by macOS directly, through its own system process
apsd. This isn’t the messenger’s traffic, and Routekeeper doesn’t count it as a connection around the proxy. - Another build of the same messenger (a beta, a copy from another store) is a different app for Routekeeper if it has a different signature. Add it separately.
Details: a service instead of an app
If the messenger is in the Services list, you can add the service too: Apps → Add → Service. A service rule sends this service’s addresses through the proxy in any app, including the web version in a browser. Starting with version 0.3.0, Routekeeper also adds the service’s Mac app along with the service, if the app is installed now or gets installed later. In 0.2.1, you need to add the app yourself, as in the steps above.
A service rule recognizes connections by site name, and for some services also by subnet. A route for the whole app is more reliable: it doesn’t depend on whether Routekeeper knows the name. For more about services, see Services.
One service in the browser through a proxy
Who it’s for: you want only one service to go through the proxy, for example GitHub from the Services list. Your bank, the work portal and other sites in the same browser should open directly.
Steps
- Open Apps and click Add → Service → GitHub. If the service you need isn’t in the short menu, choose All Services…, select it and click Add. The service appears in the Services group with a route through the main proxy.
- Don’t add the browser itself to the list of apps. If it’s already there with a route through a proxy, the whole browser already goes through the proxy, and you don’t need this recipe.
- Go to Rules and click New Rule (⌘N). Fill in the window like this:
- App: click Change → Choose… and select the browser. Leave Include Child Processes on.
- Destination: leave it empty. This means any address.
- Port:
443. - Protocol: UDP.
- Action: Block.
- Note: for example, “Browser QUIC”.
- Quit the browser completely and open it again, so that old connections don’t stay on the previous route.
Why the UDP rule
Browsers often open sites over QUIC, a protocol on top of UDP. A service rule recognizes a connection by site name, but Routekeeper doesn’t always see that name in QUIC connections. Without the name, the service rule doesn’t apply, and the connection follows the browser’s route, that is, goes direct.
The rule “browser · 443 · UDP → Block” closes QUIC for the browser. The browser then switches by itself to ordinary HTTPS over TCP, where the site name is known, and the service rule applies. Other sites won’t notice a difference: they also open over TCP.
How to check
- Open github.com. In Monitor, type
githubin the search field: these connections should show the proxy’s name in the Route column. - The browser’s UDP connections to port 443 are marked Blocked in the monitor. That’s expected.
- Open the service card: in Apps, right-click the GitHub row → More Info…. It shows what the rule matched, and in the Check an address or search the list field you can check any site name.
Pitfalls
- A service includes only the addresses on its list. For example, project sites on their own domains and external CI aren’t on the GitHub list, so they follow the browser’s route. Check the address you need in the service card.
- Connections around the proxy aren’t tracked for such a browser. Routekeeper checks this only for apps that go through the proxy as a whole. For details, see What Routekeeper notices and what it doesn’t.
- The rule applies to one app. If you use the service in two browsers, create a UDP rule for each. You can’t send two profiles of one browser different ways: see Limitations.
- Don’t turn off Block UDP and QUIC for the proxy. With this switch on, UDP connections that still fall under the service rule are blocked instead of going direct.
Details: why the right rule wins
Routekeeper picks one rule, the most specific one. The order in the list doesn’t matter. The address is compared first. The service rule matches by site name, so for connections to GitHub it wins over the browser’s route, whose address is “any”. The UDP rule’s address is also “any”, but it has a port and a protocol, so for UDP connections to port 443 it wins over the browser’s route.
If a UDP connection still arrives with a site name from the list, the service rule applies, and its route goes through the proxy. But UDP isn’t carried through a proxy, so the Block UDP and QUIC switch blocks it. The full order is described in Which rule wins, and site names in Rules by site name.
DNS over HTTPS in the browser
Who it’s for: the whole browser goes through the proxy, but DNS around the proxy entries from the browser appear in the Leaks section, or Overview says “DNS queries go direct” (in version 0.2.1, “Leaks detected”).
To open a site, the browser first looks up its address on a DNS server. Some browsers do this themselves, with an ordinary query to port 53 on your internet provider’s DNS server, and such a query goes around the proxy. The main traffic still goes through the proxy, but the DNS provider sees your IP and the names of sites.
The fix is to turn on DNS over HTTPS (DoH) in the browser. Then the browser looks up addresses over an encrypted HTTPS connection, and that connection goes through the proxy with the rest of the browser’s traffic.
Steps
The names of the settings depend on the browser’s version and language. If you can’t find the setting, type DNS in the search field of the browser’s settings.
- Chrome. Open
chrome://settings/securityin the address bar. Turn on “Use secure DNS” and choose a specific provider from the list, for example Cloudflare or Google. - Edge. Open
edge://settingsand search for “DNS”. Turn on “Use secure DNS” and choose a provider from the list. - Firefox. Open
about:preferences#privacy, scroll to the “DNS over HTTPS” section and choose “Max Protection” with any provider. - Brave. Open
brave://settings/security. Turn on “Use secure DNS” and choose a provider from the list. - Restart the browser.
Don’t block port 53 for the browser. For browsers, Routekeeper deliberately doesn’t show the Block DNS button. Without DoH, a browser with port 53 closed stops opening sites. Even with DoH, a browser sometimes needs ordinary DNS, for example to look up the address of the DNS service itself.
How to check
- New DNS around the proxy entries from the browser stop appearing in the Leaks section. Old entries stay in the list. That’s normal.
- The Overview headline no longer reports direct DNS queries because of the browser.
Pitfalls
- Choose a specific provider. In Chrome, Edge and Brave, the “current service provider” option encrypts queries only if your network’s DNS server supports it. Otherwise, queries go the old way, to port 53.
- “Increased Protection” in Firefox falls back to ordinary DNS when DoH fails, and the entries around the proxy appear again. “Max Protection” doesn’t do that: if DoH fails, Firefox shows an error.
- A browser managed by an organization may not let you change this setting.
- You need this recipe only if the whole browser goes through the proxy. If only a service goes through the proxy, as in the recipe above, the rest of the browser goes direct, and direct DNS is expected.
Details: which DNS queries Routekeeper sees
A browser’s secure DNS is an HTTPS connection to port 443. Routekeeper sends it along the browser’s route, that is, through the proxy. An ordinary query to UDP port 53 from an app on a proxy isn’t blocked: Routekeeper lets it go direct and flags it as DNS around the proxy. This is the lowest severity. The service queries ipv4only.arpa and _dns.resolver.arpa are the same for everyone and aren’t flagged.
Safari and most programs look up addresses through a macOS system service. The system itself makes these queries, and Routekeeper doesn’t tie them to an app. When an app passes a site name and the proxy has DNS through proxy on, the proxy server looks up the address. For details, see DNS: how apps find a site’s address.
Terminal, developer tools and AI apps
Who it’s for: you need git, npm, pip, brew, curl and AI apps for Mac to go online through your proxy. For example, when a work repository or API accepts connections only from your server’s address. Other programs keep working as usual.
Steps
- Open Apps → Add → From Installed Apps…. Select Terminal and, if you use it, iTerm. Click Add.
- Check that Include Child Processes is selected for the terminal (right-click the row; it’s on by default). Then everything you run in this terminal follows its route:
git,npm,pip,brew,curl,ssh. These are its child processes. - Add your code editor the same way (VS Code, Cursor, JetBrains IDEs). Its extensions and built-in terminal are the editor’s child processes.
- Add AI apps for Mac, for example ChatGPT or Claude, the same way as in step 1.
- New commands go through the proxy right away. Connections that are already open, such as an
sshsession, stay on the previous route until they reconnect.
How to check
Run this command in the terminal. It should print the proxy’s external IP, the same one that the menu of the menu bar icon shows.
curl https://ipinfo.io/ipIn Monitor, type curl in the search field. The Route column shows the proxy’s name, and the Decision field of the selected row shows the terminal’s rule.
Pitfalls
- Programs not started from the terminal don’t follow its route: background services (
brew services), scheduled tasks, programs that another app launches. Add such a program by its path: Add → Enter Path…, for example/opt/homebrew/bin/node. For details, see Command-line programs. - Docker Desktop. The traffic of all containers and image downloads comes from one Docker Desktop process. Add Docker Desktop as an app: one rule covers all containers. You can’t single out one container with its own rule.
- The
HTTP_PROXY,HTTPS_PROXYandALL_PROXYvariables aren’t needed for Routekeeper. If they’re set, programs go to the proxy they name on their own, and the traffic goes through two proxies in a row. Remove them from~/.zshrcif you set them before. gitandsshon port 22. Some proxies, more often work ones, allow only ports 80 and 443. Then either switch the repository to anhttps://address, or create the rule “Terminal · port 22 → Direct”: a rule with a port wins over the terminal’s route.- Voice modes and calls in AI apps usually go over UDP and don’t work through a proxy. Text mode works.
Details: services for AI tools
The Services list has ChatGPT, Claude, Gemini, GitHub Copilot, Cursor, Perplexity and Grok, as well as GitHub and JetBrains. A service sends its addresses through the proxy in any app: in a browser, in an editor and in command-line programs, even if they aren’t started from the terminal.
Starting with version 0.3.0, Routekeeper also adds a service’s apps along with the service: for example, ChatGPT, Claude, Cursor, JetBrains IDEs, and for Claude also the claude command-line program. An app installed later is added by itself. In 0.2.1, you need to add the apps separately.
A child process is matched to Terminal by its chain of parents. curl started from Terminal falls under Terminal’s rule, even though curl itself is signed by Apple. For details, see Child processes.
On top of sing-box, Xray or Clash
Who it’s for: you already have a client such as sing-box, Xray or Clash. It connects to a server over a protocol that Routekeeper doesn’t speak itself (for example, VLESS or Shadowsocks). The client opens a local SOCKS5 port on the Mac, and Routekeeper decides which apps to send to it.
App → Routekeeper → 127.0.0.1:port → client → your server → internet
Steps
- In the client’s settings, find the local SOCKS5 inbound (sometimes it’s called mixed): the address
127.0.0.1and a port, for example1080or7890. - In the client, turn off System Proxy and TUN mode (also called Enhanced Mode). Only one program should manage the routes. Otherwise, Routekeeper’s rules won’t apply.
- In Routekeeper, open Proxy and add a proxy. The easiest way is to copy a line like
socks5://127.0.0.1:7890and click Paste Link under the list of proxies: the fields fill in by themselves. Or click Add Proxy and fill them in yourself: Type is SOCKS5, Server is127.0.0.1, Port is the client’s port. Leave the DNS through proxy and Block UDP and QUIC switches on. Click Add. - Routekeeper checks the new proxy right away. The external IP appears next to the Check button: the address of the server the client is connected to.
- In Apps, send the apps you need to this proxy, as in the messenger recipe.
- If you work in Ask or Block All mode, allow the client itself to go online: add it to Apps with the Direct route. In Proxy Only mode, you don’t need this step.
How to check
- Check on the proxy shows your server’s address, not your home address.
- In Monitor, the connections of the apps you chose go through this proxy, and the client’s own connections go Direct.
Pitfalls
- The client must be running. If it’s closed, the check shows “Couldn’t connect to the proxy”, and the apps on this proxy are left without a network: they won’t go direct. Set the client to open at login.
- Don’t send the client itself through the proxy. That makes a loop: the client tries to connect to its server through itself.
- If the client runs as a system service (for example, started with
brew services), add its program by path in Ask and Block All modes: Add → Enter Path…. - TUN mode, if it’s on in the client, takes all of the Mac’s traffic, including what Routekeeper lets go direct. It’s one more network extension next to Routekeeper: see Other VPNs and network extensions.
- UDP doesn’t go through such a proxy: Routekeeper passes only TCP to SOCKS5 and blocks UDP from apps on a proxy. Calls through the client won’t work this way.
Details: why turn off the client’s system proxy
The system proxy is a macOS setting that browsers and many programs read themselves. With it, a browser sends everything to the client without Routekeeper. Routekeeper sees only a connection to 127.0.0.1, and it doesn’t touch connections to the same Mac (Settings → Network → Leave localhost alone). In the end, the client decides, and Routekeeper’s rules don’t apply to such a browser.
Connections from any app to the address and port of a proxy added to Routekeeper always go direct, in any mode. So you don’t need to allow the client’s local port separately. For details, see Local client: sing-box, Xray, Clash.
A work proxy for internal addresses
Who it’s for: your company gives you an HTTP proxy that opens internal sites, for example *.corp.example, and the 10.0.0.0/8 network. Everything else should go as usual: direct or through your personal proxy.
Steps
- Open Proxy → Add Proxy. Fill in the fields. Name: “Office”. Type: HTTP (or HTTPS, if your company’s instructions say so). Server: for example
proxy.corp.example. Port: for example3128. Login and Password: if the proxy requires them. Click Add. - Go to Rules → New Rule. Leave App set to Any App. In Destination, enter
*.corp.example. In Action, choose “Office” in the Through Proxy group. In Note, enter “Work sites”. Click Save. - Create a second rule the same way, but in Destination enter the subnet
10.0.0.0/8. - In Apps, don’t send anything to “Office”: these two rules are enough.
The wildcard *.corp.example covers corp.example itself and all its subdomains (more about wildcards). The entry 10.0.0.0/8 is the range of addresses from 10.0.0.0 to 10.255.255.255 (a subnet). Other ways to write an address are in Rule fields.
How to check
- Open an internal site. In Monitor, its connections show “Office” in the Route column and your rule in the Decision field.
- An ordinary outside site in the same browser follows the browser’s route: Direct or through your personal proxy.
Pitfalls
- Login and password only. Routekeeper can sign in to an HTTP proxy with a login and password (Basic). Signing in with a Windows account (NTLM, Kerberos) and PAC auto-configuration files aren’t supported. If your company uses a PAC file, open its address in a browser and find a line like
PROXY host:port: that’s the server and port you need. - Check may show an error even though everything works. The check goes through the proxy to the outside service ipinfo.io. If the work proxy doesn’t let you out to the internet, the check fails, but internal sites still open. Rely on the monitor.
- Be careful when you move all apps to another proxy. The Move all apps to item in the sidebar panel and the Proxy for all apps list in the menu bar move all rules that use a proxy, including the “Office” rules. To move only your personal proxy’s routes, use the menu of its row on the Overview screen → Move Routes To.
- UDP to the internal network doesn’t go through the proxy: the proxy carries only TCP.
- An app’s route to “Office” leaves the local network alone. If you send a whole app to “Office”, addresses on the networks the Mac is already on and the subnets of a corporate VPN still go direct: that’s what Settings → Network → Local networks go direct does. To send them through “Office”, you need a rule with the subnet, as in step 3.
Details: why these rules win over the browser’s route
Even if the whole browser goes through your personal proxy, connections to *.corp.example go through “Office”. Routekeeper picks the most specific rule. A name wildcard is more specific than a subnet, and a subnet is more specific than “any address”. An app’s route has exactly that: “any” address. The order of rules in the list doesn’t matter. For details, see Which rule wins.
A name rule applies when the app passed a site name. A subnet rule checks the IP address and always works, including for connections by name if the name points into that subnet. Connections to the address and port of “Office” itself always go direct, so there’s no loop. For more about a work proxy, see Work proxy.
The proxy stopped answering
Who it’s for: the proxy server went down, can’t be reached from your network or changed its password, and you need your apps to work again.
What happens
- Apps that go through this proxy are left without a network. Their connections don’t go direct: this way, Routekeeper doesn’t reveal your real address. This is the default behavior (more about it).
- Apps with the Direct route and apps that go through other proxies work as before.
- The Overview headline says “Proxy ‘…’ is unreachable”, or “Partly working” if other routes are fine. The menu bar icon and the status line in its menu also show that the proxy is unreachable.
- In Monitor, connections show Error, and the details give the reason, for example “The proxy didn’t answer in time”. What the messages mean is described in App messages.
- If notifications are allowed, you get the notification “…: proxy failed”, no more than once every 10 minutes for each app.
- While the main proxy is unreachable, Routekeeper checks it again once a minute, and also a few seconds after the network changes. When the server comes back, everything starts working by itself.
Move one proxy’s routes
- Open Overview. In the Routes block, the unreachable proxy has a Move to “…” button with the name of another proxy. Click it. You can also choose the other proxy yourself: the row’s menu (the button with an ellipsis) → Move Routes To.
- Routekeeper shows exactly what will move and from where. Click Move.
- If you moved the routes to the wrong proxy, you can click Undo under the proxy in the sidebar panel within 10 seconds. You can also undo with ⌘Z while the window is open.
Move all apps at once
When you have two or more proxies, you can move all routes in one action:
- in the window: the panel at the bottom of the sidebar → the proxy row → Move all apps to → the proxy you need;
- in the menu bar: the icon → Proxy for all apps → the proxy you need.
Routekeeper asks you to confirm and shows what will move. Keep in mind that this moves all rules with any proxy, including the ones you sent through another proxy on purpose, for example a work one.
If there’s no other proxy
- You can switch the apps you need to Direct in Apps for a while.
- Or turn on Settings → Network → If the proxy is down, go direct. Then, while the proxy is unreachable, connections go direct, around the proxy, and Routekeeper doesn’t warn you about it separately. Turn the switch off when the server works again.
How to check
- In Overview, click Check All: the working proxy has a green dot and a response time.
- In Monitor, the app’s new connections show the new proxy’s name.
Pitfalls
- Open connections don’t move. They stay on the old proxy until the app reconnects. It’s easier to restart a messenger.
- Moving back moves everything. If you later move the new proxy’s routes back, all of its routes move, including the ones that were on it from the start. To get back to how it was, move the apps you need back yourself in Apps.
- “Slow” isn’t “unreachable”. If the response time is 1500 ms or more, it says “slow” next to it, and the dot is orange. A distant server that works fine shows 500–800 ms. That’s normal.
- To find out why the server doesn’t answer, look up the error text in App messages. If it’s your own server, see server troubleshooting.
Details: how Routekeeper picks the proxy for the button on Overview
The Move to “…” button offers the first proxy that passed its last check. If there’s none, it offers simply the first other proxy in the list. Moving one proxy’s routes affects only the enabled rules that go through it. Moving all apps affects all enabled rules with any proxy except the chosen one. A rule that you changed while the confirmation was open isn’t moved. For more about several proxies, see Switching to another proxy.
Checked against the Routekeeper code (version 0.2.1 and the one after it) on October 4, 2026.