All docs sections
This page takes you from installation to a working check, step by step. If something stops opening after setup, the end of the page shows how to turn Routekeeper off in a second.
Macs with Apple silicon and with Intel both work.
macOS asks for an administrator password when you allow the network extension.
The address, port and, if needed, the login and password of your proxy. If you don’t have a proxy yet, see where to get one below.
Without one Routekeeper doesn’t route traffic, but you can set everything up in advance. How to get one.
Sometimes macOS asks you to restart the Mac after the extension is installed.
Installation
- Download Routekeeper. The Download button on the home page downloads the file
Routekeeper.dmgwith the latest version. All versions are on the releases page on GitHub. - Open the DMG. Double-click the downloaded file. A window opens with the Routekeeper icon and the Applications folder.
- Drag the Routekeeper icon onto the Applications folder. This puts the app in your Applications folder. Run it from there: macOS installs network extensions only for apps in Applications.
- Open Routekeeper from Applications. macOS warns that the app was downloaded from the internet and asks whether to open it. Click Open.
macOS asks this about any app that isn’t from the App Store. Routekeeper is signed with a developer certificate and checked by Apple (notarized), so you don’t need to change anything in the security settings.
Opened it straight from the DMG or from Downloads? The welcome screen shows a warning and a Move to Applications and Relaunch button. It copies Routekeeper to Applications and moves the old copy there, if there is one, to the Trash. Then Routekeeper opens again, this time from Applications. After that, you can eject the DMG.
Where to find Routekeeper
Routekeeper has no icon in the Dock. It lives in the menu bar, at the top right of the screen: look for the lantern icon.
- Click the icon to open the menu: the status, the mode, the proxy’s external address, and a way to the window.
- Right-click the icon, or click it while holding ⌥, to open the Routekeeper window right away. In the menu, Open Routekeeper (⌘O) does the same.
- A MacBook with a notch. If the menu bar has a lot of icons, the Routekeeper icon may hide behind the notch. In that case, open Routekeeper again from Applications or with Spotlight: its window opens.
The first time you open Routekeeper, its window opens by itself, with the welcome screen. Until setup is finished, you see the welcome screen instead of the usual window.
macOS also asks whether Routekeeper may show notifications. That’s up to you. In notifications, Routekeeper tells you about connections that went around the proxy and about connections that couldn’t be made through the proxy. It does this no more than once every 10 minutes for each process and kind of event.
Routekeeper 0.2.x is already on your Mac? First read how to move to the new version: you need to remove the old app with its own button, not just replace it.
Three macOS permissions
Routekeeper works through a network extension: a part that plugs into macOS and sees the outgoing connections of apps. Something like this can’t be installed silently, so macOS asks for three permissions. You give them once. The welcome screen walks you through the steps and marks each finished one with a green check mark.
| Permission | What it’s for | What you’ll see |
|---|---|---|
| 1. Network extension | Installs the part of Routekeeper that runs inside the system and decides where each connection goes. Nothing works without it. | A switch in System Settings, and the administrator password. |
| 2. Network content filtering | Lets Routekeeper see each new outgoing connection: which app is connecting and where. Based on this, Routekeeper lets the connection through, blocks it or asks you. The monitor’s data also comes from here. | The window “‘Routekeeper’ Would Like to Filter Network Content”. |
| 3. Proxy configuration | Lets Routekeeper take the connections of the apps you chose and send them through your proxy. | The window “‘Routekeeper’ Would Like to Add Proxy Configurations”. |
Routekeeper looks at which app is connecting and where. It doesn’t read the content of pages or messages, and it sends traffic only to your proxies. For details, see the privacy policy.
- A finished step: a green check mark instead of the number, and no more buttons.
- The current step: a blue number and a button. Here it’s Turn On Filter; when you click it, macOS shows a window with a question.
- The next steps are dimmed and have no buttons. They open one by one, once the previous step is done.
- Open at login is ticked in advance. Routekeeper is added to login items when you close the welcome screen. Rules work without the app open, but without it there are no notifications, firewall prompts or updates. You can change this later in Settings.
- I’ll Do It Later appears here once all three permissions are given (it has a dashed outline in this sketch). It skips the proxy and app steps.
Step 1. Network extension
- On the welcome screen, click Install. macOS may say that a system extension was blocked. A Routekeeper hint, Allow the network extension, appears on top of other windows.
- Allow the extension in System Settings. The path depends on your macOS version and is described below.
- Enter the administrator password when macOS asks for it.
- Go back to Routekeeper. After a couple of seconds, the step is marked as done by itself, and the hint says “Done, the extension is on” and closes.
macOS 15 Sequoia and later
- Click Open System Settings on the welcome screen or Open Settings in the hint.
- System Settings → General → Login Items & Extensions opens. Find Network Extensions there. If the general list of extensions opens instead, choose By Category → Network Extensions.
- Turn on the switch next to Routekeeper and confirm with your password.
- General in the System Settings sidebar.
- The Login Items & Extensions pane.
- The Network Extensions row in the Extensions group. Click ⓘ on the right to open the list of network extensions.
- The switch next to Routekeeper Extension. Turn it on, enter the administrator password and click Done.
macOS 14 Sonoma
- Open System Settings → Privacy & Security.
- Scroll down to the Security section. There you’ll see the message “System software from developer ‘Ilya Bazhenov’ was blocked from loading.”
- Click Allow next to this message and enter the administrator password. If several programs are blocked, macOS shows a button with a list instead: select Routekeeper in that list.
- Privacy & Security in the System Settings sidebar.
- The Security section. Scroll down the list to get to it.
- Allow next to the message about system software from developer “Ilya Bazhenov”. When you click it, macOS asks for the administrator password.
On macOS 14, Routekeeper’s hints describe the macOS 15 path. Sonoma has no “Login Items & Extensions” item, so the Open System Settings and Open Settings buttons take you to the wrong place. Open “Privacy & Security” yourself, as described above.
If macOS asks for a restart, the welcome screen shows “Restart your Mac to finish installing.” Restart your Mac and open Routekeeper again: the welcome screen picks up where it left off.
Closed the hint with Hide? You can bring it back from the icon’s menu: Allow Network Extension…. The Try Again button on the welcome screen sends the request to macOS again.
Step 2. Network content filtering
Click Turn On Filter. macOS shows the window “‘Routekeeper’ Would Like to Filter Network Content”. Click Allow.
Step 3. Proxy configuration
Click Turn On Proxy. macOS shows the window “‘Routekeeper’ Would Like to Add Proxy Configurations”. Click Allow.
The steps become available one by one: the filter after the extension, the proxy after the filter.
- Appears after Turn On Filter (step 2).
- Appears after Turn On Proxy (step 3).
- Click Allow in both windows. After Don’t Allow, the step stays unfinished, and you can click the button on the welcome screen again.
If you clicked “Don’t Allow”
Nothing is broken: the step simply stays unfinished.
- Filter or proxy. Click Turn On Filter or Turn On Proxy again. macOS asks again.
- Extension. If you closed System Settings without turning it on, click Open System Settings (on macOS 14, open “Privacy & Security” yourself) or Try Again.
- The prompt doesn’t appear, or the switch won’t turn on. This can happen, for example, on a work Mac managed by an organization. What to do in this case is described in Troubleshooting.
Details: what appeared in the system
- The extension is installed as a system extension. In macOS lists, it’s called Routekeeper Extension (in version 0.2.1, Routekeeper Network Extension).
- In System Settings, in the Network section, there are now two Routekeeper configurations: a content filter and a proxy. Manage them from Routekeeper, not from there.
- The filter and the proxy start with the system. After a restart, your routes work even if you don’t open the Routekeeper window.
- The status of all three parts is shown in Routekeeper’s settings, on the Extension tab, in the Status block: Network extension, Filter, Proxy.
- To list the installed system extensions, run this command in Terminal:
systemextensionsctl listYour first proxy
A proxy is a go-between server. An app connects to the proxy, and the proxy connects to the site, so the site sees the proxy’s address, not yours. Routekeeper has no servers of its own: it sends traffic to the proxy you give it.
Where to get a proxy
Rent a VPS, click Your Own Server… and enter the server’s IP and password: Routekeeper sets up an HTTPS proxy on it and adds it by itself. Step by step: Your own proxy server.
Clients such as sing-box, Xray or Clash usually open a local SOCKS5 port on the Mac, for example 127.0.0.1:1080. Add that port. Details: local client.
Your network administrator gives you the address, port, login and password. Details: work proxy.
If you were given a string like socks5://login:password@server:1080, just copy and paste it.
Routekeeper connects to three types of proxy: SOCKS5, HTTP and HTTPS. It doesn’t understand other protocols, such as Shadowsocks or VLESS, directly. For them, you need a client on the Mac with a local SOCKS5 port.
Add a proxy on the welcome screen
Once the three permissions are given, the Add a proxy server step becomes available.
- Copy the proxy string, for example
https://login:password@my.example.com:443. - Click Paste from Clipboard. The proxy form opens with the Type, Server, Port, Login and Password fields filled in.
- The DNS through proxy and Block UDP and QUIC switches are already on. Leave them on. Why they’re needed is explained in How it works.
- If you want to check the proxy before saving it, click Check. After a couple of seconds, “Working · 48 ms · IP 203.0.113.7” or an error message appears next to it.
- Click Add. Routekeeper saves the proxy and checks it right away.
Have a rented server but no proxy? Click Your Own Server…: a wizard opens that sets up a proxy on the server, see Setting it up from Routekeeper.
No string? Click Enter Manually… and fill in the fields yourself:
- Type: SOCKS5, HTTP or HTTPS.
- Server: the proxy’s address, either a domain name or an IP address. HTTPS needs a domain name: the server’s certificate is checked against it.
- Port: if you leave it empty, the usual port for the type is used: 1080 for SOCKS5, 8080 for HTTP, 443 for HTTPS.
- Login and Password: if the proxy requires them.
- Name: how the proxy is labeled in lists, for example “Amsterdam”.
If the clipboard has no proxy string, Routekeeper tells you so and shows an example. Which string formats it understands is described in Proxies.
Already past the welcome screen? Open the Proxy section and press ⌘V or click the Paste Link button below the list.
The I’ll Do It Later button at the bottom of the welcome screen skips the proxy and app steps. You can come back to them in the Proxy and Apps sections. The Open at login checkbox next to it is already ticked: clear it if you don’t want Routekeeper to open when you log in.
Your first app
The last step of the welcome screen, What to send through the proxy, offers two ways. You can combine them.
A whole app
- Click Choose Apps…. A list of installed apps opens, with a search field.
- Select one or more, for example a browser, a work messenger or Terminal, and click Add.
All traffic from these apps goes through the proxy you added. Other apps work as before, directly.
Programs that the app launches, its child processes, go through the proxy along with it. For example, if you add Terminal, the git, curl or npm you run in it go through the proxy too.
A service in every app
Below the button are services: ChatGPT, Claude, GitHub and others. A service is the set of addresses of one site or messenger. A service you select goes through the proxy in any app: in a browser, in a client app, in a command-line tool. Everything else in these apps works as before.
The All Services… button opens the full list of 32 services. If a service has its own Mac app, Routekeeper adds that app too. If you install such an app later, Routekeeper adds it while it’s running. Services from the Russian services group are added with the Direct route.
As soon as at least one app or service goes through the proxy, the welcome screen closes and the main window opens with the Overview section.
Add or change things later
Where all of an app’s traffic goes is set in the Apps section, not in the Rules section. Rules are for exceptions: a single domain, address or port.
- The Add menu has From Installed Apps…, Choose File…, Enter Path… (for command-line tools, for example
/opt/homebrew/bin/git), Service and All Services…. You can also simply drag an app into the list from Finder or the Dock. - To change a route, click it on the right side of the app’s row, for example Amsterdam. Choose another proxy, Direct, Block or Ask.
- The switch at the end of the row turns the route off without deleting it.
For details, see Apps and services.
Connections that are already open don’t move to the new route. Routekeeper decides where to send a connection at the moment it opens. If an app keeps long-lived connections, as messengers do, restart the app.
Check that it works
- The menu bar icon. Click it. If everything is fine, you’ll see “Running” under the name, with the number of apps going through the proxy. The next line shows the proxy’s external IP and its country: this is the address that sites see. If only services go through the proxy, not whole apps, it says “No apps through a proxy” there. That’s normal.
- The Check button. In the Proxy section, select a proxy and click Check. Routekeeper connects through the proxy and shows the delay and the external IP: “Working · 48 ms · IP 203.0.113.7”. If you see an error instead, such as “SOCKS5: wrong login or password” or “The proxy didn’t answer in time”, see what the error messages mean.
- Overview. This is the main screen. At the top is the overall result: “Everything works”, and which apps go through which proxy. If something is wrong, it says what, for example “Proxy ‘Amsterdam’ is unreachable” or “Some connections went around the proxy”. The Through Proxies Now block shows the apps that have traffic through a proxy right now.
- In the app itself. Open the app you sent through the proxy, for example a browser, and go to any site that shows your IP address. It should match the IP in the menu bar. The Monitor section shows that this app’s connections go through the proxy.
If an app that should go through the proxy sends something directly, Routekeeper shows it in the Leaks section and suggests how to fix it. For details, see Checking and monitoring.
How to turn it off quickly
If something stopped opening after setup, turn Routekeeper off completely. It’s safe and takes a second.
- Click the Routekeeper icon in the menu bar.
- Turn off the switch to the right of the Routekeeper name (Routekeeper On). The Routekeeper window has the same switch at the bottom of the sidebar, next to the status.
- Status. A green line means everything works. Below it: the proxy’s external IP and country (what websites see) and the total speed.
- The Routekeeper On switch. If something stops loading, turn it off: every connection goes direct.
- The mode for connections that have no rule. More in Firewall modes.
- Shown when you have two or more proxies. Clicking one moves every app to that proxy; Routekeeper asks you to confirm first.
Now all connections go direct, as they would without Routekeeper. Connections that went through a proxy are dropped, and apps reconnect right away, directly this time. Rules and the mode don’t apply, and the monitor doesn’t record connections. The lantern in the menu bar goes dark, and the Overview section shows “Routekeeper is off”.
To turn it back on, use the same switch or the Enable button in the Overview section. Your proxies, apps and rules stay where they are.
Quit Routekeeper doesn’t turn it off. This command closes only the window and the icon. The network extension keeps running and applies your rules. To make everything go direct, you need the switch.
Details: how the switch differs from other ways
| Way | What happens | How to undo it |
|---|---|---|
| The Routekeeper On switch | All connections go direct. The filter and the proxy stay registered in macOS. | The same switch. |
| Quit Routekeeper | The window and the icon close. The extension keeps working by your rules. In Ask mode there’s no one to ask, so connections without a rule are allowed. | Open Routekeeper from Applications. |
| Settings → Extension → Stop… | The filter and the proxy are turned off in macOS itself. | Reinstall in the same place. The switch won’t bring them back. |
| Settings → Extension → Delete… | The extension is removed from the system. Your rules stay on disk. | Go through the welcome screen again. |
For details, see Updates and removal.
The switch is gray and can’t be clicked? The window has lost contact with the network extension. At the top of the window you’ll see “The network extension isn’t responding” and a Reinstall Extension button. What to do is described in Troubleshooting.
Only the proxy is down? By default, the apps that go through it get a connection error instead of going direct. This is by design: traffic doesn’t go around the proxy. How to switch to another proxy for a while or let everything go direct is described in the recipe for this case.
What’s next
How Routekeeper decides where to send a connection, and what happens to DNS and UDP.
Apps and servicesRoutes, child processes, command-line tools, all 32 services.
RecipesReady-made setups for a messenger, a browser, the terminal, a local client and a work proxy.
Checking and monitoringOverview, the connection monitor and the Leaks section.
Checked against the Routekeeper code (version 0.2.1 and the one after it) on October 4, 2026.