Docs · Setup

Rules: exceptions by address

A rule decides where connections to certain addresses, ports or protocols go. The route of a whole app is set in Apps; rules are for exceptions and for addresses shared by all apps.

All docs sections

A rule answers the question “which app, where to, on which port and over which protocol, and what to do with it”. The Rules section (⌘3) shows all rules, including the rows from Apps.

When you need a rule

Most of the time, you don’t need to write rules:

Rules are for exceptions and fine-tuning:

How to create a rule:

A new rule starts as “Any App · any address → main proxy”. If you save it without changing anything, all apps that don’t have their own row will go through the proxy. Fill in Destination or choose an app. If there’s no proxy yet, a new rule’s action is Direct.

Rule fields

A double-click on a rule, or New Rule, opens a window with these fields:

FieldWhat it sets
AppAny App or a specific one. The Change button offers Any App, Choose… (a file picker) or one of the apps that are already in your rules.
Include Child ProcessesAppears when a specific app is chosen. What it does is explained in Child processes.
DestinationWhere the connection goes; see the table below. The Service menu next to it fills in a service.
PortA single number from 1 to 65535: the server’s port. Empty means any port. For example, 443 is HTTPS and QUIC, 80 is HTTP, 22 is SSH, 53 is DNS.
ProtocolTCP and UDP (any), TCP or UDP. Almost all connections are TCP; UDP is used by QUIC, calls and DNS.
ActionA proxy from the Through Proxy section, Direct, Block or Ask. For more, see How it works.
NoteAny text for yourself. It’s shown under the destination, and search looks through it.

Buttons: Save, Cancel and, for an existing rule, Delete. The window has no duration setting: a rule made in it stays in effect until you turn it off or delete it.

  1. The “?” next to the title opens a short reminder of which rule wins. The details are in Which rule wins.
  2. Any App or a specific one, picked from the Change menu. For a specific app, Include Child Processes appears below.
  3. Where the connection goes: a name (files.example.com), a wildcard (*.corp.example: the domain itself and all its subdomains), an IP, a subnet or @service. An empty field means any address and shows the hint “Any address · *.example.com · 10.0.0.0/8 · @youtube”. The Service menu fills in a service. How to write an address is in the table below.
  4. Port is a single number; empty means any port. Protocol is a menu: TCP and UDP, TCP or UDP.
  5. What to do with the connection: a proxy, Direct, Block or Ask.
A sketch of the new rule window: Chrome goes through the proxy, and the company’s sites go direct. The data is made up.

How to write an address

What to enterWhat it matchesExample
EmptyAny address. * and any mean the same.—
A nameOnly this name, without subdomains.files.example.com matches neither example.com nor a.files.example.com
*.nameThe name itself and all its subdomains (a wildcard).*.example.com matches example.com, www.example.com, a.b.example.com
An IP addressOnly this address, IPv4 or IPv6.203.0.113.10, 2001:db8::1
A subnetAll addresses in the subnet.10.0.0.0/8, 192.168.1.0/24, fd00::/8
@serviceAll addresses of the service.@github, @chatgpt, @ru-banks
Details: service codes for @

The Service menu fills in the code for you. If you’d rather type it:

  • github, slack, zoom, notion, figma, jetbrains, spotify;
  • chatgpt, claude, gemini, copilot, cursor, perplexity, grok;
  • ru-gov, ru-banks, ru-sites.

For the other codes, it’s easier to pick the service from the Service menu than to type it. Version 0.2.1 doesn’t have slack, zoom, github, figma and three more services.

The Through Proxy action for UDP: UDP can’t go through a proxy, so what happens to it is decided by the proxy’s Block UDP and QUIC toggle.

Which rule wins

What decides is precision, not the order in the list. For each connection, Routekeeper takes all enabled rules that match it and picks the most precise one. Rules are compared step by step until a difference is found:

  1. A more precise destination. An exact name or IP address wins over a *. wildcard, a wildcard wins over a subnet, and a subnet wins over any address. Of two wildcards, the longer one wins (*.cdn.example.com wins over *.example.com); of two subnets, the smaller one does (/24 wins over /8).
  2. An address typed in by hand wins over a service if both are equally precise.
  3. A rule with a port wins over a rule without a port.
  4. A rule with a protocol wins over a rule without a protocol.
  5. A specific app wins over its child processes, and they win over “Any App”.
  6. Action: Block wins over Through Proxy, which wins over Direct, which wins over Ask.

If no rule matches, the mode decides. In Proxy Only mode, the connection goes direct.

Address first, then app. That’s why the rule “Any App · *.corp.example → Direct” for company sites wins over the route “Browser → Through Proxy”, even though the browser is named specifically. For the same reason, a service wins over an app’s route.

Worked examples

1. Browser through the proxy, company sites direct

ConnectionResultWhy
Browser → news.example.orgThrough “Amsterdam”Only the browser’s route matches.
Browser → wiki.corp.exampleDirectBoth match. A wildcard is more precise than any address, and the destination is compared before the app.

2. Two wildcards

ConnectionResultWhy
img.cdn.example.comDirectBoth match; the longer wildcard is more precise.
www.example.comThrough “Amsterdam”The second wildcard doesn’t match here.

3. A service and your own domain

ConnectionResultWhy
app.slack.comThrough “Office”The service matched on slack.com, which is just as precise as *.slack.com. With equal precision, an address typed in by hand wins over a service.
slack-edge.comThrough “Amsterdam”This name is only in the service.

4. Port, app and child processes

ConnectionResultWhy
ssh from Terminal → a server, port 22DirectBoth rules have any address as the destination. The rule with a port wins, and the port is compared before the app.
curl from Terminal → any siteDirectThe row for curl itself wins over the row for Terminal, which launched it.
git from Terminal → github.com, port 443Through “Amsterdam”Only Terminal’s row matches: git is its child process.
Details: the exact algorithm
  1. If Routekeeper is turned off with the Routekeeper On switch, everything goes direct.
  2. A connection to the address and port of any proxy in the list goes direct, and rules aren’t checked.
  3. The candidates are enabled, unexpired rules whose app, destination and, if set, port and protocol match. The app matches exactly, as a child process (if the rule has the setting on) or as “Any App”.
  4. Each candidate gets a weight: six numbers that are compared in order:
    • destination: an exact name or IP address is 4000; a *.name wildcard is 3000 plus the length of the wildcard in characters; a subnet is 2000 plus the prefix length; any address is 0. A service gets the weight of the entry that matched: a “this name only” name from its list counts as an exact name, a “with subdomains” name as a *.name wildcard, and a subnet as a subnet;
    • address typed in by hand: 1, service: 0;
    • port set: 1, not set: 0;
    • protocol set: 1, not set: 0;
    • app: exact 3, child process 2, any 1;
    • action: Block 3, Through Proxy 2, Direct 1, Ask 0.
  5. The higher weight wins. If everything is equal, the rule that appeared earlier in the list of rules wins. Sorting the table doesn’t affect this.
  6. If the winner is a Through Proxy rule with any address (an app’s route, including one a child process inherits) and Settings → Network → Local networks go direct is on (it is by default), Routekeeper checks the address. If it’s on one of this Mac’s local networks, the connection goes direct instead of to the proxy. An address counts as local when it’s private (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10, which includes Tailscale addresses, fc00::/7) and the Mac’s routing table sends it either to a connected network without a router or into a VPN tunnel (the utun, ipsec, ppp, tun and tap interfaces). The addresses 169.254.0.0/16 and fe80::/10 are always local. DNS queries (ports 53 and 853) are never let through this way. Rules with an address, subnet or service and rules with another action aren’t affected.
  7. If there are no candidates: a connection to this same Mac (127.0.0.0/8, ::1, localhost) goes direct if the Leave localhost alone setting is on; everything else is decided by the mode.

What follows from this:

  • A rule with a port but any address loses to a rule with an address but no port: address precision is compared first.
  • If a service’s list has an exact name, the service wins over your *. wildcard for that name: a wildcard loses to an exact name, no matter who typed it. To override the service, type the exact name.
  • A wildcard always wins over a subnet. *.corp.example beats 10.0.0.0/8 for a name in that domain, even if its address is in the subnet.
  • The rule “Any App · any address” applies before the mode: the mode decides only when no rule matches.
  • An app’s route through a proxy doesn’t send your home network, a corporate VPN or Tailscale to the proxy: a remote proxy can’t reach them. To send such an address through a proxy anyway, for example an office one, create a rule with that address or subnet and the Through Proxy action, as in the recipe A work proxy for internal addresses.
  • A private address that leaves through the ordinary router doesn’t count as local. Some DNS servers answer a name query with a private address. Such a connection goes to the proxy, and the proxy finds the site’s real address itself.
  • If a company’s internal servers sit on public addresses, Routekeeper doesn’t recognize them as a local network. For them, create a rule with the company’s subnet → Direct.
  • Local addresses go direct over UDP too: Block UDP and QUIC doesn’t block them, and the Leaks section doesn’t mark them. In Monitor, their Decision field says “local network, past the proxy of the rule for …”.

Rules by site name

Rules with a name (example.com, *.example.com) and services compare the server name. Routekeeper knows the name when the app asked macOS to connect by name. Browsers and most apps do this.

There’s no name when:

Then name rules and services don’t match the connection. It follows rules with an IP address or subnet and the app’s route. The exception is services that include subnets: their connections are recognized by IP too. For more, see Limitations.

Example: part of a site in the browser goes around the proxy

The browser goes Direct or isn’t in the list, and the GitHub service goes Through Proxy. Pages open through the proxy: regular HTTPS goes over TCP and carries the name. But the browser often sends some requests over QUIC, which is UDP to port 443, usually without a name. Such a connection follows the browser’s route, that is, it goes direct.

The fix is to block QUIC for the browser:

  1. In the Rules section, press ⌘N.
  2. App: Change → choose the browser.
  3. Leave Destination empty. Port: 443. Protocol: UDP. Action: Block.
  4. Click Save.

The browser switches to regular HTTPS over TCP. Such a connection carries the name and follows the service’s rule, through the proxy. Sites keep working. A detailed recipe: One service in the browser through a proxy.

If the browser itself goes Through Proxy, you don’t need this rule: its UDP is already blocked by the proxy’s Block UDP and QUIC toggle.

Monitor shows connections without a name only with their IP address; see Monitor.

The list of rules

The control in the toolbar chooses which rules you see:

Below the window title is how many rules of each kind there are, for example “Mine: 9 · system: 372”. If a search finds nothing among your rules but finds something among the system ones, a Search All button appears.

Columns

Clicking a column header sorts the list. Search in the toolbar looks through the app, the address and the note.

Sources

SourceWhere the rule comes from
ManualYou created it yourself: in the rule window, in Apps, by adding a service, or from Monitor.
From PromptYour answer in the prompt with the “While the process runs” or Forever duration. An answer with the Once duration doesn’t create a rule. See Ask.
AppleAsk mode allowed an Apple program by itself.
Installed BeforeAsk mode allowed an app installed before Routekeeper by itself.
For ReviewRoutekeeper let the connection through without asking and left a rule for you to review. This happens in Ask mode when there was no one to answer (the Routekeeper app wasn’t running), and in Silent mode with the Create rules “for review” setting.
DefaultBuilt-in rules; see below.

The Apple, Installed Before and Default rules are system rules: they show under System and All. The rest show under Mine. To go through the For Review rules, click the Source column header to bring them together, open a rule with a double-click, choose an action and click Save. Or select several rules and set the action from the context menu. After that, the source becomes Manual.

Working with the list

Built-in rules

Three rules with the Default source are there from the first launch. They are system rules, so Mine doesn’t show them:

Don’t delete or turn off the built-in rules. Without the first two, an app routed through a proxy would also send its connections to this same Mac to the proxy: the app’s route wins over the Leave localhost alone setting, which applies only when no rule matches.

Two more exceptions work outside the list: connections to the address and port of the proxies themselves always go direct, and the proxy check is run by the network extension, so rules don’t apply to it.

Import and export

Export

  1. In the Rules section, click Import and Export in the toolbar and choose Export…. From any section: File → Export Rules….
  2. Choose where to save the file. By default, it’s called Routekeeper-rules.json.

The file contains all rules, including the built-in ones, and all proxies: server addresses, ports and logins. Proxy passwords aren’t saved in the file. Settings (the mode, the Settings tabs) aren’t saved either. Keep the file private: it has the addresses and logins of your proxies.

Import

  1. Import and Export → Import…, or File → Import Rules…. Choose the file.
  2. Routekeeper asks: Replace all rules and proxies? It also shows how many rules and proxies you have now and how many are in the file.
  3. Click Replace.
  4. Open the Proxy section, enter the passwords for proxies that have a login, and click Check.

Import replaces; it doesn’t add. All current rules and proxies are deleted, and the rules and proxies from the file take their place. This can’t be undone, and ⌘Z won’t help. Before you import, export your current rules so you keep a copy.

Moving to another Mac: export the rules, copy the file over, import it on the other Mac and enter the proxy passwords. Apps with a developer signature are recognized there too. Programs without a signature are recognized by their file path, so if they’re in a different place on the other Mac, add them again; see Command-line programs.

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