Docs · In practice

Recipes: ready-made setups

Seven common tasks, step by step. Each recipe says who it’s for, what to click, how to check the result and where you might trip up.

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.

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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

Pitfalls

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

  1. 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.
  2. 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.
  3. 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”.
    Click Save.
  4. 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

Pitfalls

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.

  1. Chrome. Open chrome://settings/security in the address bar. Turn on “Use secure DNS” and choose a specific provider from the list, for example Cloudflare or Google.
  2. Edge. Open edge://settings and search for “DNS”. Turn on “Use secure DNS” and choose a provider from the list.
  3. Firefox. Open about:preferences#privacy, scroll to the “DNS over HTTPS” section and choose “Max Protection” with any provider.
  4. Brave. Open brave://settings/security. Turn on “Use secure DNS” and choose a provider from the list.
  5. 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

Pitfalls

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

  1. Open Apps → Add → From Installed Apps…. Select Terminal and, if you use it, iTerm. Click Add.
  2. 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.
  3. Add your code editor the same way (VS Code, Cursor, JetBrains IDEs). Its extensions and built-in terminal are the editor’s child processes.
  4. Add AI apps for Mac, for example ChatGPT or Claude, the same way as in step 1.
  5. New commands go through the proxy right away. Connections that are already open, such as an ssh session, 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/ip

In 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

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

  1. In the client’s settings, find the local SOCKS5 inbound (sometimes it’s called mixed): the address 127.0.0.1 and a port, for example 1080 or 7890.
  2. 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.
  3. In Routekeeper, open Proxy and add a proxy. The easiest way is to copy a line like socks5://127.0.0.1:7890 and 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 is 127.0.0.1, Port is the client’s port. Leave the DNS through proxy and Block UDP and QUIC switches on. Click Add.
  4. 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.
  5. In Apps, send the apps you need to this proxy, as in the messenger recipe.
  6. 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

Pitfalls

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

  1. 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 example 3128. Login and Password: if the proxy requires them. Click Add.
  2. 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.
  3. Create a second rule the same way, but in Destination enter the subnet 10.0.0.0/8.
  4. 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

Pitfalls

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

Move one proxy’s routes

  1. 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.
  2. Routekeeper shows exactly what will move and from where. Click Move.
  3. 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:

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

How to check

Pitfalls

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.