All docs sections
The Apps section (⌘2) has two kinds of rows. An app row sets where all of that app’s traffic goes. A service row sets where the addresses of one site or messenger go, from all apps at once.
Exceptions by address, port and protocol, such as “the browser through the proxy, but company sites direct”, are set in Rules. How routes, services and rules work together is explained in How it works.
How to add an app
- Open the Apps section.
- Click the + (Add) button in the toolbar: it shows only an icon, and the name appears as a tooltip. The Installed Apps window opens. It lists the apps from the Applications and Utilities folders, system apps, and apps from the Applications folder in your home folder.
- Find the apps you need with the search, select one or more and click Add.
Other ways to add an app:
- Drag an app from Finder or the Dock right into the list.
- The Add button’s menu (the arrow next to it):
- From Installed Apps…: the same window you get with a click;
- Choose File…: a file picker for an app or program in any folder;
- Enter Path…: type the path to a program; handy for command-line programs;
- Service and All Services…: services.
- From any section: ⇧⌘N opens the list of installed apps.
- On first launch: the Choose Apps… button on the welcome screen.
A new app gets a route through the main proxy. If there’s no proxy yet, the route is Direct. You can change the route in the route menu; see below. If the app is already in the list, Routekeeper highlights its row instead of adding a second one.
How Routekeeper recognizes an app
Routekeeper recognizes an app by its code signature: by the developer ID and the app ID. So the route stays after the app is updated or moved to another folder. Another program with the same name won’t get the route.
Routekeeper recognizes programs without a developer signature by their file path. If you move or rename such a program, you need to add it again. This often happens with command-line programs, for example from Homebrew; see below.
Details: the app key
- Apple programs and App Store apps: by the signing identifier, for example
com.apple.Safari. - Apps signed with a Developer ID: by the signing identifier together with the developer’s Team ID.
- Programs with an ad-hoc signature or no signature: by the full path to the executable file.
Under the app’s name, the row shows this identifier or path, and “without child processes” if child processes are off. If apps with the same name are in two places, the row shows the folder instead of the identifier.
An app’s route
On the right of the row is the route menu. It shows the current route, for example “Amsterdam” (the proxy’s name) or “Direct”. Click it to choose another one:
| Route | What happens |
|---|---|
| Through Proxy → proxy name | All the app’s connections go through the chosen proxy. Its UDP is blocked if the proxy’s Block UDP and QUIC toggle is on. |
| Direct | Connections go the same way they would without Routekeeper. |
| Block | The app’s connections are blocked. |
| Ask | For each new destination, Routekeeper shows a prompt; see Ask. |
For more about actions, see How it works.
Rows are grouped by route: Through Proxy, Blocked, Ask, Direct. Turned-off rows are in the Turned Off group. Above them is the Services section. If an app is sending data through the proxy right now, its row shows the speed “↕ …”.
If an app was deleted or moved, its row goes to the Not Found on Disk group: such a route sends nothing anywhere. The Remove All… button in the group’s header deletes all these rows after you confirm. An app on a disconnected disk counts as not found too; ⌘Z undoes the deletion.
At the bottom is the collapsed Allowed Automatically group, with the number of rows in it. It holds Apple programs and apps installed before Routekeeper that Ask mode allowed to go online without asking. If you choose a route for such an app, it moves to a regular group.
- The Add button, with a “+” icon. A click opens the list of installed apps; the arrow next to it opens a menu with other ways to add an app, and with services.
- Services: a route for a service’s addresses in every app. The “?” next to the heading is a reminder that a rule for a specific domain in Rules beats the service. ⓘ in a row opens the service card. The buttons below add popular services in one click.
- Apps are grouped by route: Through Proxy, Blocked, Ask, Direct. A group with no rows isn’t shown. Under the name is the app’s identifier; “without child processes” is added only when child processes are off.
- The route menu: proxies by name, then Direct, Block and Ask. A checkmark marks the current route; in the row, a proxy is shown just by its name, in blue. A service’s menu has no Ask.
- Turned Off: apps whose switch is off. Their route is gray and doesn’t apply; under the name it says where the traffic goes now.
- Not Found on Disk: apps that were deleted or moved (or are on a disconnected disk). The path is shown instead of the identifier. Remove All… deletes their routes after you confirm.
Enable, disable, delete
- The toggle on the right turns a row off without deleting it. The row moves to the Turned Off group and says how the app goes now. A turned-off row has no effect: the app follows the other rules and the mode. In Proxy Only mode, that means it goes direct.
- The context menu (right-click): Route, Enable or Disable, Include Child Processes, Show in Finder, Delete. Route, enabling and deleting also work for several selected rows at once.
- You can also delete with the Delete key. ⌘Z undoes the last change.
- Search in the toolbar looks through app names and identifiers, and for services also through domains:
githubusercontent.comfinds GitHub.
An app that isn’t in the list follows the mode. In Proxy Only mode, it goes direct.
An app row sets where all of the app’s traffic goes. Each such row is a rule, and you can also see it in the Rules section with the destination “Any address”. To send some of the app’s addresses another way, add a rule: When you need a rule.
Details: which rules are shown in Apps
This section shows permanent rules with a specific app, any address, and no port or protocol. An answer in the prompt with the Forever duration and the Anywhere destination also becomes such a row. Temporary rules with the “While the process runs” duration, rules for individual addresses and built-in rules are shown only in the Rules section; built-in ones under System.
Child processes
Many apps don’t go online by themselves but through helper programs: child processes. In browsers and in apps like Slack or VS Code, the network is handled by helper processes such as “Google Chrome Helper”. Terminal runs git, curl, npm, ssh.
The Include Child Processes setting extends the app’s route to:
- helper programs inside the app itself, from the same developer;
- programs that the app has launched, including through programs in between: Terminal → shell →
git.
The setting is on by default for every new app. For example, if Terminal has the Through Proxy route, everything you run in it goes through the proxy: git, curl, npm, brew.
To turn the setting off, uncheck Include Child Processes in the row’s context menu. Then the route applies only to the app’s main process. Do this only when you mean it: browsers and many other apps go online only through helpers, and without this setting the route may catch nothing.
A launched program’s own row wins over the row of the app that launched it. If Terminal has the Through Proxy route and curl has its own Direct row, then curl launched from Terminal goes direct. Why this is so is explained in Which rule wins.
Details: what counts as a child process
With the setting on, a process belongs to the app if at least one of these is true:
- the process is inside the app’s bundle (
…/Slack.app/…) and is signed with the same Team ID; - the process’s signing identifier starts with the app’s identifier and a dot, and the Team ID is the same:
com.google.Chrome.helperforcom.google.Chrome; - among its ancestors is the app itself or a process from the app’s bundle. Ancestors are looked up through the macOS “responsible” process, then through the parent, up to eight levels up.
If a helper of an app that goes through the proxy doesn’t meet any of these conditions and goes online directly, the Leaks section flags it as Process outside the rule.
Command-line programs
git, curl, npm, python3, ssh are separate programs, and they aren’t in the list of installed apps. There are two ways to route them.
The whole terminal
The simplest and most reliable way. Add the app you run commands from: Terminal, iTerm or a code editor with a built-in terminal. Choose a route for it. With the Include Child Processes setting on, everything you run in it follows the same route. A ready-made scenario is in the recipe Terminal, developer tools and AI apps.
A single program by path
- In the Apps section, open the Add button’s menu and choose Enter Path….
- Type the full path to the program, for example
/usr/bin/curl. You can start the path with~for your home folder. - Click Add. A row appears with the program’s name and the default route.
You can also choose the file with Choose File…. To open hidden folders like /usr/bin in the file picker, press ⇧⌘G, type the folder path and press Return.
Routekeeper recognizes Apple programs, such as /usr/bin/curl and /usr/bin/ssh, by Apple’s signature. Most others are trickier: programs from Homebrew and many others have no developer signature, and Routekeeper recognizes them by their file path.
Homebrew programs. /opt/homebrew/bin doesn’t hold the programs themselves, only links to them in a folder named after the version. Routekeeper sees a running program at its real path, so enter that path, not the path of the link. This command prints the real path (put your program in place of git):
readlink -f "$(which git)"When you update the program with brew upgrade, the path changes, and you need to add the row again. That’s why it’s easier to route the whole terminal for such programs.
Details: scripts and shared Apple programs
- Scripts in Python, Node.js and other languages go online as their interpreter:
python3,node. You need a row for the interpreter or for the terminal. - Some programs in
/usr/bin(git,python3,makeand other developer tools) are shared Apple “shims” with one and the same signature. A row for/usr/bin/gitapplies to all such programs and to whatever they launch. - The
whichcommand helps you find where a program is, for examplewhich curl.
Services
A service is a ready-made set of addresses of one well-known site or messenger: domains with all their subdomains, and sometimes subnets. A service row applies in all apps at once: in browsers, in desktop clients and in command-line programs.
For example, take the GitHub service with the Through Proxy route: any app that connects to github.com or githubusercontent.com goes through the proxy. The rest of the browser’s traffic follows the browser’s own route.
How to add a service
- Buttons for popular services in the Services section at the top of the list add a service with one click.
- The Add button’s menu → Service: all services, by group.
- All Services…: a window where you can search by name or domain:
openai.comfinds ChatGPT. Select one or more and click Add. - On first launch: the service buttons at the What to send through the proxy step of the welcome screen.
A new service gets a route through the main proxy, or Direct if there’s no proxy. A service’s route menu has the proxies, Direct and Block. Services don’t have the Ask option.
Which services there are
32 services in several groups (version 0.2.1 has 25: Slack, Zoom, GitHub, Figma and three more aren’t there). For example:
- Popular: GitHub, Slack, Zoom, Notion, Figma, JetBrains, Spotify.
- AI assistants: ChatGPT, Claude, Gemini, GitHub Copilot, Cursor.
- Russian services: Gosuslugi and government sites, Russian banks, Russian sites.
And others: the full list is in the All Services… window.
Services in the Russian services group are added with the Direct route. Banks, government services and marketplaces check where you sign in from: from an unfamiliar IP, they may ask you to confirm the sign-in or not let you in. So it’s handy to keep them direct, even if the whole browser goes through a proxy.
If the service you need isn’t there, add a rule with the site’s domains in Rules.
A service wins over an app’s route
A service row applies to any app, and for the service’s addresses it wins over the app’s own route:
- The browser goes Through Proxy, and the “Russian banks” service goes Direct. Bank sites open directly, and everything else goes through the proxy.
- The browser isn’t in the list or has the Direct route, and the GitHub service goes Through Proxy. Only GitHub goes through the proxy.
But a service can be overridden too. Your rule for a specific domain from the service’s list wins over the service. So does a rule for the same service with a specific app, port or protocol. The exact order is in Which rule wins.
A service needs a site name. Connections to a bare IP address and most UDP, including QUIC in browsers, carry no name, so they follow the app’s route. If a service goes through the proxy and the browser goes direct, some connections may go around the proxy over QUIC. The fix is the rule “browser · port 443 · UDP → Block”: how to make it. Some services also include subnets: the service recognizes such connections by IP as well.
A service’s apps are added automatically
With some services, Routekeeper also adds rows for their desktop apps and command-line programs, with the same route as the service. For example:
- Slack: the Slack app;
- Zoom: the zoom.us app;
- JetBrains: IntelliJ IDEA, PyCharm and other JetBrains IDEs;
- Claude: the Claude app and the
claudeprogram for the terminal.
Why: desktop apps sometimes connect by IP or to addresses that aren’t in the service’s list. A route for the whole app catches everything.
- Apps installed later. Routekeeper keeps track of the enabled services. When you install and launch an app of such a service, its row appears by itself.
- Your rows don’t change. If the app is already in the list with a route you chose, that route stays. A row from the Allowed Automatically group gets the service’s route.
- After that, they’re separate rows. If you change the service’s route or delete the service, the rows of its apps stay as they were. Change them separately.
In version 0.2.1, a service’s apps aren’t added automatically.
The service card
The ⓘ button in a service’s row opens its card. A double-click on the row and the More Info… item in the context menu open it too. The card has:
- at the top: the name, the number of addresses in the set, and a toggle; the group is shown only for some sets, such as AI assistants and Russian services;
- What the rule does: the Route menu, the rule in words, and caveats. For example, for messengers: “Calls use UDP and don’t work through a proxy”. Below that, These rules come first: lists your rules that take part of the service’s traffic before the service does;
- What went through the rule: apps and addresses from recent connections in Monitor that this service decided on;
- What’s included: all names and subnets in the set. In the Check an address or search the list field, type a name, for example
i.ytimg.com, and the card tells you whether it’s part of the service. The answer appears once the text contains a dot. The list below shows only entries that contain what you typed, so for a subdomain it may go empty: look at the answer line instead; - the Remove Service and Done buttons.
- The rule in words. The Route menu above it changes the service’s route. Some services have an orange caveat below it, for example messengers: “Calls use UDP and don’t work through a proxy”. GitHub has none.
- These rules come first: your rules that take some of the service’s addresses before it does. That’s a rule for a domain from the service’s list, or a rule for the same service with a specific app, port or protocol. When there are none, a note here says which rule would come first.
- Apps and addresses from recent connections in Monitor that this service decided on. Until there are any, it says “Nothing yet”.
- The address check. Type a name with a dot, for example
raw.githubusercontent.com, and the card tells you whether it’s part of the service. Below are the list entries that contain what you typed: a name “and subdomains”, “this name only”, or a subnet. While the field is empty, the whole list is shown. - Remove Service deletes the service’s row and closes the card. App rows added along with the service stay.
Service updates
Routekeeper takes the list of services, their addresses and the apps added along with them from its service catalog. The addresses come from the open v2fly/domain-list-community project, and subnets come from the lists the services publish themselves.
Every 6 hours, Routekeeper checks getroutekeeper.app for a newer catalog and installs it without an app update. This is how new services appear, addresses change and new apps of a service are added. The catalog file is signed, and the network extension checks the signature. If a check fails, for example with no network, Routekeeper tries again within the hour.
The date of the catalog and a manual check are in Settings → General → Service Catalog (Service Addresses in version 0.2.1): the Lists from and Last check lines and the Check Lists button. What Routekeeper sends over the network for this is described on the Privacy page.
Checked against the Routekeeper code (version 0.2.1 and the one after it) on October 4, 2026.