macOS Guide
Settings, menu bar and updates (macOS)
Every menu in ProxyBridge for macOS: how routing starts and stops, the menu bar icon, Close to Menu Bar, Run at Startup, update checks and installing an update, Documentation and About.
Settings, menu bar and updates
ProxyBridge for macOS is a small app. Almost everything is in its menus and in two windows (Proxy Settings and Proxy Rules). This page lists every menu item and what it does.
The menus at a glance
| Menu | Items |
|---|---|
| ProxyBridge (app menu) | The standard macOS items, including Quit ProxyBridge (⌘Q) |
| Proxy | Proxy Settings... (⌘,), Proxy Rules... (⌘R), Enable Traffic Logging, Enable DNS |
| Profile | The profile list, New Profile..., Rename, Delete, Export, Import Profile... (see Profiles) |
| Settings | Close to Menu Bar, Run at Startup |
| Help | Documentation, Check for Updates..., About ProxyBridge |
The proxies, rules and logs have their own pages: Proxy servers, Proxy rules, Connections and logs.
Starting, pausing and quitting
There is no Start or Stop button on macOS. ProxyBridge routes traffic for as long as the app is running:
- When you open the app it installs (or reuses) the system extension, starts the tunnel, sends it your proxies and the rules of the active profile, and turns on the DNS proxy that lets it learn host names. The first time, macOS asks you to approve the extension (see Install on macOS).
- When you quit the app (⌘Q, Quit ProxyBridge, or the red close button when Close to Menu Bar is off) it clears the rules and the proxy list from the extension, and stops the tunnel. Nothing keeps being redirected after you quit.
- If the app is hidden in the menu bar, it is still running and routing.
To pause routing without quitting, switch to an empty profile (create one called Off with Profile > New Profile...), or switch rules off one by one in the rules window with their On switches. Switch back to continue.
The command line controls the same extension. The window and the command line cannot run at the same time. See Command line.
The menu bar icon
While ProxyBridge runs, a network icon sits in the menu bar. Its menu has two items:
| Item | What it does |
|---|---|
| Open ProxyBridge | Shows the main window again and brings the Dock icon back |
| Quit ProxyBridge | Quits the app (and stops routing, as described above) |
Settings menu
Both items are saved per profile: switching profiles can change them.
Close to Menu Bar
| State | What the red close button does |
|---|---|
| Off (default) | Quits ProxyBridge, and with it the routing |
| On | Hides the window and removes the Dock icon. ProxyBridge keeps running and routing in the menu bar. Open it again from the menu bar icon (Open ProxyBridge) |
Choose On when you want routing to carry on with the window out of the way. Choose Off when closing the window should mean "I am done".
Run at Startup
When on, ProxyBridge is added to System Settings > General > Login Items & Extensions > Open at Login and starts when you log in. When it was started at login, it opens hidden in the menu bar, without a window or Dock icon, and starts routing at once. Turn the setting off to remove it from the login items.
Notes:
- It uses the standard macOS login item. You can also see and remove it in System Settings.
- ProxyBridge must be installed in /Applications. A copy that runs from another folder cannot register itself, and the setting does nothing (without an error message).
- Because the setting belongs to the profile, the profile that is active when you log in decides whether the next start is hidden. See Profiles.
Enable Traffic Logging
In the Proxy menu. It switches the connection log on and off. Details in Connections and logs.
Enable DNS
In the Proxy menu. It is saved per profile and is on by default.
| State | Effect |
|---|---|
| On | ProxyBridge uses the system DNS proxy. It sees the Mac's DNS answers, learns which names belong to which addresses, and so host name rules and send hostname work |
| Off | ProxyBridge does not use the DNS proxy, and switches its own entry off in macOS (System Settings, Network). macOS then sends DNS the normal way |
macOS allows only one DNS proxy at a time. Turn Enable DNS off when another tool, such as Proxifier or a VPN client, needs that slot, or when name lookups fail while ProxyBridge runs. The change applies at once and needs no restart. Routing does not stop: rules that use IP addresses, and the BLOCK and DIRECT actions, keep working.
With Enable DNS off:
- Host names in a rule's Target hosts never match. IP addresses still match.
- Let proxy resolve DNS (send hostname) has no effect. The proxy gets the IP address.
- The Activity Logs say that the DNS proxy is off.
Because the setting belongs to the profile, switching profiles can switch the DNS proxy on or off. The command line uses the setting of the profile it runs. If you switch the entry off by hand in macOS settings while Enable DNS is on, ProxyBridge turns it on again the next time it starts. Use the menu item to keep it off.
Updates
ProxyBridge checks for a new version once each time it starts. The check asks download.interceptsuite.com for the current macOS version and compares it with the version you have. It sends nothing about you or your Mac except the usual connection details and the name ProxyBridge-UpdateChecker.
When a newer version exists, an Update Available window opens:
| Part | Meaning |
|---|---|
| Current Version, New Version | What you have and what is available |
| View Release Notes | Opens the release notes in your browser |
| Update Now | Downloads the installer and opens it |
| Later | Closes the window. You are asked again at the next start |
| Don't Ask Again | Turns off the check at start. See below |
Update Now downloads the .pkg installer to the temporary folder (with a progress bar; Cancel stops it), opens it with the macOS Installer and quits ProxyBridge so the installer can replace it. Follow the Installer as in a first installation. When the new version starts it replaces the system extension if the extension changed. macOS may ask for your approval again, and in rare cases for a restart (see Troubleshooting).
An update is offered only if the download is a .pkg file and its version is higher than yours. The check compares numbers (4.10.0 is newer than 4.9.0).
Check for Updates...
Help > Check for Updates... opens a small window that checks right away and shows Current Version and Latest Version. Download Now appears when an update is available, Check Again repeats the check, Close closes it. If the check fails (no internet, the server is not reachable) the window shows the reason in red.
Don't Ask Again
Don't Ask Again stops the automatic check at start. There is no menu item to turn it back on; the manual Check for Updates... always works. The command line has its own --update check.
Documentation and About
- Help > Documentation opens the ProxyBridge documentation in your browser.
- Help > About ProxyBridge shows the version, the author, the website and GitHub links, and the license (MIT).
What the macOS app does not have
The Windows and Linux apps have a few settings that macOS does not:
- a Pause command and a Start/Stop engine command (on macOS the app's running state is the switch),
- a language or text size setting (macOS text follows the system),
- log filters, a Live Connections table and automatic log clearing,
- a per-rule "also proxy localhost traffic" option.
Everything that exists in the app is on this page or the pages it links to.
