Docs · Getting started

How it works

Routekeeper decides what to do with each connection separately. This page covers what it’s made of, in what order it chooses an action, and what happens to DNS and UDP.

All docs sections

You don’t have to read this page to use Routekeeper: the Quick start is enough. This page helps when you want to understand why a connection went one way and not another.

What Routekeeper is made of

Routekeeper is two programs that work together.

The app

The window and the menu bar icon. This is where you add proxies and apps, write rules and watch the monitor. You can close the app: your routes keep working.

Network extension

The part of Routekeeper that plugs into macOS; macOS itself calls such modules system extensions. The extension sees each new outgoing connection, decides what to do with it, and sends traffic through the proxy. It works when the window is closed and after a restart.

The network extension keeps proxies, passwords and rules in a file that only the system can read. The window gets the settings without the passwords, and proxy checks are done by the extension itself.

Why macOS asks for three permissions

The extension has two halves inside, and macOS asks about each one separately. On top of that, there’s the permission to install the extension itself.

PermissionWhat it givesWithout it
Network extensionInstalls the extension in the system.Nothing works.
Network content filteringThe filter sees each new outgoing connection: which app is connecting and where. It lets the connection through, blocks it, or holds it while you answer a prompt. It also records connections in the monitor.No firewall, no monitor and no prompts.
Proxy configurationThe proxy part takes the connections that should go through a proxy and passes them to your proxy server.Nothing goes through the proxy.

How to give the permissions in macOS 14 and macOS 15 is described in the Quick start.

Details: the internals, for advanced users
  • The filter is an NEFilterDataProvider at the socket level: it decides what happens to a connection when the connection opens, and it doesn’t read the data being sent. The proxy part is an NETransparentProxyProvider; it takes outgoing TCP and UDP.
  • Only outgoing connections are intercepted. Routekeeper doesn’t touch incoming ones.
  • The settings are in /Library/Application Support/Routekeeper, a folder that only root can access. Versions 0.2.x kept them in /Library/Application Support/AppProxy.
  • The proxy configuration is on-demand, so after a restart or a stop, macOS starts it again by itself.
  • The decision is made once, when the connection opens. If you change a rule, connections that are already open stay where they were; new ones follow the new rule.

How Routekeeper decides what to do with a connection

For each new connection, Routekeeper knows three things: which app is connecting (by its signature), where to (the site name if it’s known, the IP address and the port), and how (TCP or UDP). Then it goes through the steps from top to bottom and stops at the first one that gives an answer.

The order in which an action is chosen for a connection If Routekeeper is off, the connection goes direct. Otherwise, Routekeeper first looks for the most specific rule for the address, port or protocol, then for the app’s route, then uses the action of the default mode. If the result is through the proxy, TCP goes through the proxy, and UDP is blocked or goes direct and is flagged. STEPS RESULT New connection app, site name or IP, port, TCP or UDP 1. Is Routekeeper on? the switch in the menu bar and in the window no Direct rules don’t apply yes 2. Is there a rule for this address? domain, IP, subnet, service, port or protocol; the most specific wins, list order doesn’t matter yes The rule’s action from Rules or a service no 3. Does the app have a route? the Apps section yes The app’s route proxy, direct, block… no 4. Default mode for connections without a rule Proxy Only → direct Silent → allow or block Ask → prompt Block All → block If the result is “Through Proxy” TCP: goes through the proxy server. Proxy down: an error, not a direct connection. UDP: blocked (“Block UDP and QUIC”) or goes direct and is flagged. DNS over UDP: goes direct and is flagged in the Leaks section.
The order in which an action is chosen. Rules and services are checked before the app’s route. The mode applies only if nothing else matched.

The steps in order

  1. Routekeeper is off: everything goes direct, as if Routekeeper weren’t there. The Routekeeper On switch is in the icon’s menu and at the bottom of the window’s sidebar.
  2. A rule for the address. This includes the rules from the Rules section (domain, IP address, subnet, port, protocol) and the services from the Apps section. If several match, the most specific one wins: an exact address beats *.domain, a domain beats a subnet, and for the same address, a rule with a port beats a rule without one. The order of lines in the list doesn’t matter. Worked examples are on the Rules page.
  3. The app’s route: what’s chosen for the app in the Apps section. It applies to all of the app’s traffic that more specific rules didn’t take. If Include Child Processes is on, the route also applies to the app’s child processes, the programs the app launches. If such a program has a route of its own, its own route wins. A route through a proxy leaves addresses on a local network (your home network, a corporate VPN, Tailscale) direct: a remote proxy can’t reach them. This is the Settings → Network → Local networks go direct setting.
  4. The default mode: what to do with a connection that has neither a rule nor a route. In Proxy Only mode (the one set right after installation), such a connection goes direct. The other modes are described in Firewall modes.

Example

A browser is added to Apps with a route through the “Amsterdam” proxy. The Rules section has the rule “any app · *.corp.example → Direct” for the company portal. Terminal isn’t added anywhere, and the mode is Proxy Only.

ConnectionWhat appliedResult
Browser → portal.corp.exampleStep 2: the rule for *.corp.example is more specific than the browser’s routeDirect
Browser → example.orgStep 3: the browser’s routeThrough “Amsterdam”
Terminal → example.orgStep 4: no rule and no route, Proxy Only modeDirect
Terminal → portal.corp.exampleStep 2: the rule for any appDirect
Details: the exact order, for advanced users
  • Before rules. If Routekeeper is off, the connection goes direct and isn’t recorded in the monitor. Connections to the proxy server itself (its address and port from the Proxy list) always go direct; otherwise the proxy couldn’t be reached.
  • Built-in rules with the source Default: 127.0.0.0/8 and ::1 → Direct, Routekeeper itself → Direct (these are its proxy checks). They take part in the choice on equal terms with yours.
  • Comparing rules. Of the enabled rules that match the app, address, port and protocol, one is chosen. They are compared in this order: how specific the address is (an exact name or IP, then *.domain, where longer is more specific, then a subnet, where a longer prefix is more specific, then “any address”); an address typed in by hand beats a service at the same specificity; a rule with a port wins; a rule with a protocol wins; the exact app beats its child processes, and they beat “any app”; on a full tie, Block wins, then Through Proxy, then Direct, then Ask.
  • An app’s route is also a rule: the app and “any address”, with no port or protocol. So it loses to any rule with an address, port or protocol, and wins over the rule “any app · any address”.
  • Local networks. If the winner is a Through Proxy rule with any address, and the address is on one of this Mac’s networks (a connected network or a VPN tunnel), the connection goes direct. Rules with an address, subnet or service aren’t affected, and neither are DNS queries. The exact conditions are in Which rule wins.
  • Without a site name, domain rules don’t match: a connection to a bare IP matches only rules with IPs and subnets. Some services include subnets, and these match by IP too. More in Limitations.
  • Without a rule, if Settings → Network → Leave localhost alone is on (it is by default), connections to the Mac itself go direct. Then the mode applies. In Ask mode, before a prompt is shown, automatic allows still apply to Apple software and to programs installed before Routekeeper.
  • Time-limited rules from a prompt (“While the process runs”) disappear when the process exits.

What happens after a “Through Proxy” decision

The TCP connection goes to the proxy server. If the proxy is down, the connection fails with an error and doesn’t go direct. This way, Routekeeper doesn’t reveal your address when the proxy is down: this is called fail-closed. If you’d rather have apps keep working somehow, turn on Settings → Network → If the proxy is down, go direct (off by default).

Details: if the connection to the proxy stalls

To carry a connection, Routekeeper first opens a tunnel to the proxy: it connects to the server, sets up encryption for an HTTPS proxy, and asks the proxy to connect to the site. If the tunnel isn’t ready after 1.5 seconds, Routekeeper opens a second attempt alongside the first, and a third after 4 seconds. The first one that succeeds wins, and the others are closed. The overall limit is 15 seconds; after that, the connection fails with “The proxy didn’t answer in time”.

This happens on some hosting networks: one connection to the server stalls while new ones get through. Without extra attempts, the app would wait 15 seconds and get an error. If the proxy refuses outright, for example a wrong password or a refused connection, the error comes at once, with no retries. Nothing reaches the site until a tunnel is ready, so the extra attempts only touch the proxy. Proxy latency in the monitor includes the whole wait.

UDP is different: it never goes through the proxy. What happens to it is described below, in the sections on DNS and on UDP.

Four actions

A rule, an app’s route and a service each have one of four actions.

ActionWhat happens to the connectionNotes
Through ProxyIt goes through the chosen proxy server. The site sees the proxy’s IP, not yours.In lists, it’s shown by the proxy’s name, for example Amsterdam. Only TCP goes through the proxy.
DirectIt goes through your usual connection, as it would without Routekeeper.All the apps you haven’t added go this way by default.
BlockThe connection is cut right away. The app sees a network error.At equal specificity, a blocking rule beats the others.
AskThe connection waits until you answer in the prompt: Block, Through Proxy or Allow.With no answer, the connection is allowed after 60 seconds (you can change both values in Settings → Firewall). If the Routekeeper app isn’t running, there’s no one to ask, so the connection is allowed and an allow rule marked For Review is created for that app. Services don’t have this action.

Your answer in the prompt is saved as a rule: forever, or while the program is running. The Once option doesn’t save a rule. For details, see Firewall modes.

DNS: how apps find a site’s address

Sites on the internet are found by numeric addresses, called IP addresses. People and programs find names, like example.com, easier to use. DNS is a lookup service that turns a name into an address. Usually your internet provider or your router answers these lookups, so it sees which names your Mac asks about.

What “DNS through proxy” does

Each proxy has a DNS through proxy switch, and it’s on by default. When an app connects to a site by name, Routekeeper passes the name itself to the proxy, not the address. The proxy server looks up the address and connects to it. The site opens the same way as if you opened it from the server.

There’s usually no reason to turn this switch off. Without it, the proxy gets the IP address that your Mac looked up.

What still goes around the proxy

Turn on “DNS over HTTPS” in your browser. Chrome, Edge, Firefox and Brave have this setting. With it, the browser looks up addresses inside an ordinary HTTPS connection (DoH), and if the whole browser goes through the proxy, these lookups go through the proxy too. Don’t block port 53 for the browser: without DoH, it will stop opening sites.

Details: what counts as DNS and where you see it
  • Routekeeper treats a connection to port 53 or 853 as a DNS lookup. If such a connection goes over UDP from an app that should go through the proxy, it goes direct whatever the Block UDP and QUIC setting, and it’s flagged as “DNS around the proxy”. This is the least serious kind of flag.
  • You can block it only with an explicit rule: the Block DNS button in the Leaks section creates the rule “app · port 53 → Block”. Browsers don’t get this button: they need DoH.
  • The service names ipv4only.arpa and _dns.resolver.arpa aren’t flagged: every system asks for them in the same way, and they say nothing about you.
  • Flags depend on where the connection itself was supposed to go by the rules. A process slipping past its rule is flagged only for apps whose whole route goes through a proxy. DNS and UDP are flagged when that connection should have gone through the proxy by the rules. So a browser that sends only certain services or domains through the proxy is barely checked: its DNS queries go to a DNS server’s address, not to those domains. More in what Routekeeper detects.
  • With the switch on, a SOCKS5 proxy gets the host name in the connect request, and HTTP and HTTPS proxies get the name in the CONNECT request. With the switch off, they get the IP address.
  • Ask mode has a separate setting, Allow DNS queries (UDP 53): it lets DNS lookups from apps without a rule through without a prompt. It’s off by default.

UDP and QUIC

Data travels over the network in two main ways. TCP is like a conversation with confirmations: the two sides agree on a connection and check that everything arrived. Sites, email and most apps run on it. UDP is like sending postcards with no confirmation: it’s faster, but there are no guarantees. Calls, real-time video, games, DNS and QUIC, a newer way to load sites that browsers use, all go over UDP.

In Routekeeper, SOCKS5, HTTP and HTTPS proxies carry only TCP. This means that UDP from an app sent through the proxy can’t go through the proxy. What happens to it is decided by the Block UDP and QUIC switch in the proxy’s settings.

SwitchWhat happens to UDPWhat you’ll notice
On (default)UDP is blocked.Browsers switch to regular HTTPS over TCP by themselves and work through the proxy. Calls and voice chats may not work; see Limitations.
OffUDP goes direct, around the proxy.Each such connection is flagged in the Leaks section as “UDP around the proxy”.

The exception is DNS over UDP. Whatever the switch position, it goes direct and is only flagged, as described above.

Why a service rule may not catch QUIC

Domain and service rules recognize a site by its name. A UDP connection, including QUIC, usually has no site name, only an IP address. Such a connection doesn’t match a domain rule and follows the app’s route.

Example: the browser goes direct, and the GitHub service from the Services list goes through the proxy. Connections over QUIC will go direct: to Routekeeper, it’s just the browser’s UDP connection to port 443. The rule “browser · port 443 · UDP → Block” helps. QUIC stops working, the browser switches to TCP, where the site name is known, and the service rule applies. A ready-made setup is in the recipe on one service in the browser.

Details: how Routekeeper handles UDP
  • The filter sees outgoing TCP and UDP, and the proxy part takes both. If Through Proxy is chosen for a UDP connection, DNS (ports 53 and 853) goes direct and is flagged. Everything else is closed if Block UDP and QUIC is on, or goes direct and is flagged as “UDP around the proxy” if it’s off.
  • The switch is set for each proxy separately and applies to the apps that go through that proxy.
  • The Block UDP button in the Leaks section turns this switch on for the proxy that the app goes through. If the app has no route through a proxy, the button creates the rule “app · UDP → Block”.
  • Rules with the Block and Direct actions apply to UDP the same way as to TCP.

Checked against the Routekeeper code (version 0.2.1 and the one after it) on October 4, 2026.