Setting up a network client on macOS involves more than dragging an app into Applications. The download source, processor architecture, system extensions, VPN configuration, subscription import, proxy mode, and DNS path can all affect the final result. A “Connected” status in the menu bar only confirms that the client completed a connection action; it does not prove that traffic from your browser, terminal, and other apps is using the intended route.
A reliable sequence is to confirm that the installer matches your device, understand what each permission prompt allows, import the subscription, choose the right traffic-capture mode, and then verify the exit IP, DNS, and routing results separately. When something goes wrong, trace the same chain backward instead of repeatedly reinstalling the client or switching nodes at random.
Confirm the client, architecture, and download source
macOS clients are commonly distributed as disk images, installer packages, or compressed archives. A disk image usually requires dragging the app icon into Applications; an installer package follows the system installation flow; a compressed archive must be extracted before the app is moved. Whichever format you use, obtain the file from the provider dashboard, the project’s official release page, or the client’s built-in update channel.
Mac devices may use Apple silicon or an Intel processor. If the release page provides separate builds, download the one that matches your Mac; a build labeled Universal usually includes both architectures. With an architecture mismatch, the app may fail to open or may rely on a compatibility layer. Check the chip or processor information in “About This Mac” and compare it with the label on the download page.
| What to check | Details to verify | What a mismatch looks like |
|---|---|---|
| File source | Provider dashboard, official client release page, or in-app update entry | macOS cannot verify the developer, or the app behaves differently from the official documentation |
| Processor architecture | Apple silicon, Intel, or Universal label | The app will not launch, quits unexpectedly, or asks for an additional compatibility environment |
| Installation format | The installation method for a disk image, installer package, or compressed archive | The app is still running from Downloads, making updates and permission states easy to confuse |
| System compatibility | The minimum system requirements and known limitations listed in the release notes | The network extension cannot load, or the settings path differs from the guide |
If macOS explicitly blocks an app from an unidentified source, do not disable system security controls to get around it. First verify the download URL, developer details, and release notes; if the source cannot be confirmed, download the file again from a trusted entry point. The system’s “Open” confirmation is appropriate for a first-launch prompt from a known developer, not a universal solution for every warning.
- ✅ The installer came from a verifiable official source, and its filename matches the release notes.
- ✅ The architecture label matches your Mac’s chip type, or the build is explicitly marked Universal.
- ✅ The app has been moved to Applications instead of being launched long-term from a disk image or Downloads.
- ❌ Do not disable Gatekeeper or System Integrity Protection just to skip a one-time warning.
- ❌ Do not keep multiple similar client copies from unknown sources.
Understand system extensions and network permission prompts
When a client first enables the system proxy, TUN, or VPN traffic capture, macOS may request administrator authorization or show prompts such as “Add VPN Configuration,” “Allow Network Extensions,” or filter-related notices. The wording varies by macOS version and client implementation, but the purpose is similar: to let the app establish a system-managed network path.
“Add VPN Configuration” does not mean the app can read all your private files. It allows the client to create a system-approved network configuration and send eligible traffic through the relevant network extension. Administrator authentication approves this system-level change. You can later review the status under Network, VPN, and filter-related sections in System Settings, or remove the configuration from within the client.
Some clients use the Network Extension framework to implement TUN, while others mainly modify the system proxy; some let you switch between both. If macOS says an extension was blocked, keep the client open and check Privacy & Security for pending approvals. After approving it, return to the client and enable the connection again. Restart only when the app explicitly asks you to.
System proxy vs. TUN
A system proxy writes HTTP, HTTPS, or SOCKS proxy settings to macOS. Browsers and apps that follow the system proxy hand their requests to the client, but apps with their own network stack, apps that ignore system proxy settings, or apps using special transport methods may bypass it. This mode makes fewer changes and is useful for first checking web access and basic routing.
TUN mode creates a virtual network interface. The client receives a broader range of IP traffic and then uses rules to decide whether to proxy, connect directly, or block it. It is generally better for terminal tools, development environments, and apps that do not read system proxy settings, but it is also more likely to conflict with other VPNs, filters, security software, or enterprise network extensions.
| Traffic-capture method | Primary coverage | Common limitations | Useful troubleshooting scenario |
|---|---|---|---|
| System proxy | Apps that read macOS proxy settings | Some terminal programs and standalone network stacks may not follow it | First confirm that the browser and basic rules work |
| TUN | Traffic routed through the virtual interface and handled by rules | May conflict with other network extensions or filters | The browser works but other apps do not |
| Manual proxy | A selected app with a separately configured proxy address | Configuration is scattered, so app states may differ | Isolate and test one app’s proxy support |
Import the subscription and identify protocol and route fields
After configuring permissions, copy the subscription URL from the provider dashboard and import it through the client’s “Subscription,” “Configuration,” “Remote Configuration,” or “Profiles” section. Button names vary, but the basic action is the same: save the remote URL, download the configuration, and parse the nodes. If the client supports clipboard import, make sure the clipboard contains only the complete URL, with no leading or trailing spaces, line breaks, or punctuation added by a chat app.
After a successful import, run an update once and check that nodes, policy groups, and rules appear. If you see a subscription name but no selectable routes, the download may have failed, the format may be incompatible, or the remote content may not have been parsed correctly. Check the client log for HTTP status codes, parse errors, and configuration-field warnings instead of pasting the same URL repeatedly.
- Copy the currently valid subscription URL from your account dashboard; do not open or forward it on a public page.
- Open the client’s subscription or remote-configuration section, paste the URL, and save it.
- Update the configuration manually and wait for nodes, policy groups, and routing rules to finish loading.
- Choose the policy group that matches the task, then select a specific exit route.
- Enable the system proxy or TUN, and confirm that the menu-bar status matches the network configuration in System Settings.
- After verifying the exit IP, DNS, and per-app behavior, enable automatic updates or launch at login.
Shadowsocks, VMess, Trojan, VLESS, Hysteria2, and TUIC
These names identify different proxy protocols or transport schemes, not quality tiers. Shadowsocks forwards traffic through an encrypted proxy and usually includes a server, port, encryption method, and credentials. VMess and VLESS are often handled by compatible cores and can be combined with different transport and TLS settings. Trojan commonly carries a proxy connection behind a TLS-like appearance. Hysteria2 and TUIC use QUIC-oriented transport designs, each with its own client-core and network requirements.
Do not manually rewrite ports, transport settings, security parameters, or server names in a subscription based on the protocol name alone. Whether a protocol works depends on complete field support in the client core and on a matching server configuration. Supporting a subscription format does not mean the client supports every protocol inside it. If the import produces “Unknown type” or field-parsing errors, use a client build that supports the protocol or a compatible subscription format provided by the service.
Direct, relayed, and IEPL routes
A direct route connects the client straight to the target node entry point. The path is simpler, but performance depends more on cross-network conditions between the local carrier and the entry point. A relayed route connects to an intermediate node first and then moves to the exit, allowing the provider to adjust part of the path. IEPL is a dedicated-access model for international connectivity; routing and the exit are still handled by the server side.
For macOS clients, these differences are usually encoded in the node configuration. The client connects to the specified entry point; enabling TUN does not turn an ordinary direct route into a dedicated route. Choose routes based on the labels in the subscription, the target region, and the task at hand—not on the protocol name.
Choose Global, Rule, or Direct mode
Common clients offer Global, Rule, and Direct modes. Global mode sends all traffic already captured by the client through the proxy policy and is useful for briefly ruling out rule-matching issues. Rule mode uses domains, IPs, processes, or rule sets to decide between proxying and direct access and is more common for daily use. Direct mode lets captured traffic access destinations directly and is useful for restoring local access or determining whether the proxy path causes an issue.
“Global” only describes how the client handles traffic it has already captured; it does not necessarily mean every connection on the device enters the client. If only the system proxy is enabled, apps that do not read it may still bypass the client. Conversely, after TUN captures traffic, Rule mode can still send local websites, LAN resources, or selected apps directly.
Pay attention to rule order. Specific domain rules should take effect before broad rules, while the final catch-all rule handles requests that match nothing above it. If the same domain appears in multiple rule sets, the client usually uses the first matching result in configuration order. After changing rules, reload the configuration and clear existing app connections so old connections do not continue using the previous path.
- ✅ The browser hits the expected policy group when accessing the target service, and the log shows the corresponding rule.
- ✅ Local websites and LAN resources remain direct according to the rules instead of being sent unnecessarily to a remote route.
- ✅ Terminal tools produce results consistent with, or explainably different from, the browser under the current capture mode.
- ❌ Do not interpret “Global mode” as a guarantee that every process is captured.
- ❌ Do not let multiple clients modify the system proxy or create overlapping TUN interfaces at the same time.
Verify the exit IP, DNS, and per-app behavior
Validate the connection from the network layer upward. First check whether the exit IP has changed to the selected region, then identify who resolves DNS requests, and finally test the browser, terminal, and the apps you actually plan to use. This separates an unestablished tunnel from partial app capture, an inconsistent DNS path, or restrictions imposed by the target service itself.
Check the exit IP
Use a trusted IP-check page before and after connecting to view the public exit. The result should match the selected node’s region, while accounting for browser cache, old tabs, and existing long-lived connections. Close and reopen the page, or make the request in a new private window. If the client log says the connection succeeded but the exit has not changed, first confirm that the system proxy or TUN is actually enabled, then check whether the browser uses a separate proxy or secure DNS feature.
Check for DNS leaks and the resolution path
A DNS leak generally means that application traffic goes through the proxy while domain lookups are still sent to an unexpected local resolver, separating the resolution path from the exit path. In system-proxy mode, an app may continue using system DNS. In TUN mode, the client can capture more DNS traffic, but the actual behavior still depends on configuration, rules, and the app’s own encrypted DNS settings.
Do not look only at the resolver’s name. Also confirm whether requests match the client’s DNS rules, whether results have been tampered with, and whether proxy domains resolve correctly before the tunnel is established. Browser-based secure DNS, enterprise network settings, and other network filters can all change the result. When paths conflict, first disable duplicate DNS handlers, then choose a system, remote, or rule-based resolution strategy according to the client documentation.
scutil --proxy
scutil --dns
scutil --nwi
networksetup -getwebproxy "Wi-Fi"
networksetup -getsecurewebproxy "Wi-Fi"scutil --proxy shows the current system proxy status, scutil --dns helps inspect system resolver settings, and scutil --nwi provides additional network-interface information. These commands describe the system’s current configuration only; they cannot by themselves prove that a specific app follows it, so verify with client logs and real requests as well.
Test by application
A working browser does not mean that terminal tools, development tools, and desktop apps will also work. Browsers commonly follow the system proxy but may have their own proxy extensions; command-line programs may read environment variables or connect directly; apps using QUIC, built-in DNS, or long-lived connections may behave differently. Reconnect from the target app itself and check whether the client log shows its domain, destination IP, and policy.
Common permission errors and troubleshooting order
Permission errors often come from leftover extensions, duplicate clients, or unsynchronized system state. The most effective approach is to change one variable at a time. Quit other network clients and filtering tools, confirm that the current app is in Applications, and check System Settings for old VPN configurations or network extensions. Do not keep clicking Allow while multiple clients are running; it becomes difficult to identify which app a prompt belongs to.
Authorization is requested again after approval
This often happens when the app copy has moved, an extension from an older version remains, or the client did not receive the administrator authentication needed to finish installation. Fully quit the app, delete any copy running from a disk image, and keep only the official copy in Applications. Then review VPN and filter status in System Settings, remove configurations clearly belonging to an inactive old client, and reopen the current client.
If System Settings says the extension is allowed but the client still reports that it is not loaded, disable and re-enable the relevant feature so the app can check its state again. Restart macOS only when the release notes explicitly require it. Deleting the app alone may not remove its network extension or VPN configuration; use the client’s uninstall or configuration-removal feature to clean them up.
The connection succeeds but webpages do not open
Switch to Direct mode first to confirm that the local network itself works. If Direct mode also fails, check the current Wi-Fi, enterprise network authentication, and system DNS instead of continuing to change nodes. If Direct works but the proxy does not, inspect the node handshake, subscription validity, protocol compatibility, and DNS logs. If only certain domains fail, check routing rules and resolution results rather than assuming the entire route is unavailable.
The browser works but the terminal does not
This usually means the browser reads the system proxy while the terminal program does not. Enable the client’s supported TUN mode for comparison, or configure the tool’s proxy environment according to its documentation. If the terminal works after TUN is enabled, the issue is the capture scope rather than the remote route. If it still fails, check whether the tool forces its own DNS, UDP, or network interface.
The connection is lost after sleep or wake
After waking, a Mac may switch network interfaces, obtain a new address, or restore an old connection. Disconnect and reconnect the client so routes, DNS, and the virtual interface load again. If the issue continues, check whether the client offers automatic reconnection and confirm that no other tool overwrites the system proxy after wake. If it happens frequently, save logs from before and after wake and compare interface and DNS changes.
- ✅ Quit other VPNs, proxy clients, and network filters, leaving only the current client running.
- ✅ In System Settings, confirm that the active VPN configuration and network extension match the client’s name.
- ✅ Update the subscription and inspect parse logs before deciding whether a protocol-compatible client is needed.
- ✅ Compare Direct, system proxy, and TUN modes separately to determine whether the issue is with the route or the capture scope.
- ❌ Do not reinstall the app, delete configurations, switch nodes, and change DNS all at once; doing so destroys useful troubleshooting clues.
- ❌ Do not classify handshake failures, DNS failures, and rule mismatches as simply “the client is broken.”
Final checks before regular use
Once the configuration works, decide whether to enable launch at login, automatic subscription updates, and automatic reconnection after network changes. Automation should be built on a verified configuration; otherwise the system may repeatedly load broken rules or invalid extensions at startup. Subscription updates can also change node names and policy contents, so confirm afterward that existing policy groups still point to the intended routes.
Keeping essential troubleshooting records makes future diagnosis easier. Include the client version, macOS version, capture mode, selected policy, error time, and redacted log excerpts. Remove subscription URLs, authentication fields, server credentials, and personal paths before sharing logs. When reporting an issue, state which app, which mode, and which step failed; that is more useful than simply saying “cannot connect.”
If the device is managed by a school or company, a configuration profile may restrict VPNs, proxies, or network extensions. These restrictions generally cannot be overridden with ordinary administrator approval; follow the organization’s network policy. On a personal device, periodically remove proxy settings and network extensions left by disabled clients to prevent multiple network components from competing for the same route.