Understand the client, subscription, and system permissions first
Setting up a macOS VPN involves more than dragging an app into the Applications folder. A complete setup includes installing the client, granting network permissions, importing a subscription, choosing a node, selecting a proxy mode, and verifying the connection. If any step is incomplete, the client may show “connected” while websites still use the local network, or a node list may appear while connections fail.
The client reads configuration and creates the tunnel; the subscription link supplies nodes, protocols, and server parameters; macOS network extension permissions allow the client to handle traffic covered by the rules. They work together but are not the same thing. Removing the client usually does not clear leftover configuration, and reimporting a subscription cannot replace system authorization.
| Configuration item | Primary role | Common issue | What to check |
|---|---|---|---|
| Client app | Parse configuration, create the tunnel, and apply split-tunneling rules | Will not start; no menu bar status | Verify the download source and app permissions |
| Network extension | Process connections within the system network stack | Repeated authorization prompts; disconnects immediately | Check permission status in System Settings |
| Subscription link | Sync nodes and protocol parameters | Empty list; update fails | Check the link and network reachability |
| Proxy mode | Determine which traffic uses the route | Some apps work while others connect directly | Check rules, the system proxy, or tunnel mode |
| DNS settings | Translate domain names into destination addresses | Pages fail to open; unexpected resolution results | Check whether DNS is handled through the tunnel |
Download and install a macOS-compatible client
Get the macOS client from the download link in the service dashboard. Do not install an app based only on a protocol name: supporting one protocol does not mean the app supports every field in your subscription. Clients can differ in their compatibility with routing rules, DNS, transport parameters, and update formats, so use the client explicitly recommended by the service whenever possible.
Open the installer once the download is complete. If the app comes as a disk image, drag it into Applications; if it uses an installer, follow the on-screen steps. macOS may verify the app's source on first launch. Continue only after confirming that the file came from the expected download page. Do not disable system-wide security protections to bypass a prompt for one app.
Some clients run mainly from the menu bar and do not open a traditional main window. Check the status bar at the top of the screen instead of repeatedly clicking the app icon. If the menu bar is crowded, another item may be hiding the icon; quit unnecessary menu bar apps and check again.
- ✅ The download came from the service dashboard or the project's official release page.
- ✅ The app is in Applications rather than running from the Downloads folder or a disk image.
- ✅ After the first launch, a main window or menu bar status control is visible.
- ✅ The publisher shown during installation matches the expected app.
- ❌ Do not disable system-wide security protection to handle a routine authorization prompt.
Intel and Apple silicon Mac models may use different builds, or both may be covered by one universal build. Follow the labels on the download page instead of guessing from the filename. If the app quits immediately after launch, first confirm that the build matches your Mac, then check whether macOS blocked its network extension rather than repeatedly reinstalling the same file.
Handle network extension and VPN configuration permissions
When the client connects for the first time, macOS usually asks to add a VPN configuration or enable a network extension. This system prompt allows the app to create a network interface and process traffic according to its configuration. Confirm that the app name is correct, approve the request, and complete authorization using the authentication method requested by your Mac.
Clients do not all request permission at the same point. Some ask on first launch, some only after you click Connect, and others request additional access when tunnel mode is enabled. Not seeing a prompt immediately after opening the client does not mean installation failed. Import the subscription, try connecting, and then watch for system prompts.
If permission was previously denied, clicking Connect repeatedly may no longer bring up a prompt. Open System Settings and review the sections related to Privacy & Security, VPN, or network extensions to confirm that the client is allowed. The exact group names vary by macOS version, so follow the app name and network configuration shown in Settings.
A request to add a VPN configuration does not mean that every client uses a traditional VPN protocol. Protocols such as Shadowsocks, VMess, Trojan, VLESS, Hysteria2, and TUIC can be parsed by the client, which then uses the network extension supplied by the system to send traffic through a proxy or tunnel. The protocol governs communication between the client and server; system permissions let the app access the network traffic it needs to handle. These two layers should not be confused.
Import the subscription and check the node list
Sign in to the service dashboard and copy the subscription link for the macOS client. Return to the client and look for “Import subscription,” “Add from URL,” or a similar option. Paste the complete link and confirm. Some clients call a subscription a configuration group, remote configuration, or profile; the wording differs, but the function is the same: fetch nodes and rules from a remote source.
After the import succeeds, do not connect immediately. Open the node list and confirm that the region names, protocol types, and configuration group are present. If the list is empty, update the subscription manually. If the update still fails, check for spaces, line breaks, or punctuation introduced during copying. Browser address bars may truncate what they display, so use the copy button provided by the dashboard instead of selecting only the visible text.
A subscription may include Shadowsocks, VMess, Trojan, VLESS, Hysteria2, or TUIC nodes. The client can load them only when it supports the corresponding protocol and parameters. If some nodes are ignored, marked unavailable, or missing fields after import, switch to the client recommended by the service instead of editing the server address, transport method, or TLS parameters yourself.
- Open the client download or subscription section in the service dashboard.
- Choose the subscription format that matches your macOS client.
- Copy the complete subscription link and do not share it publicly.
- Create a remote subscription or configuration group in the client.
- Run an update and wait for the node list to finish parsing.
- Choose a node in the target region, then open the connection settings.
Choose system proxy, tunnel, and split-tunneling modes
Common client modes include system proxy and tunnel mode. A system proxy mainly affects apps that follow macOS proxy settings; some programs create their own connections and may continue connecting directly. Tunnel mode uses a network extension to handle a broader range of traffic, usually providing more complete coverage but relying more heavily on system authorization and correct routing.
Split-tunneling rules determine which domains, addresses, or apps use international routes and which connect directly. Rule mode suits everyday use and avoids unnecessary detours. Global mode is useful for troubleshooting because it sends more traffic through the current node; direct mode does not use the proxy route. You can switch modes briefly for comparison, but restore the setting that matches your actual use once the issue is understood.
IEPL dedicated lines, relay routes, and direct routes describe how the connection path is organized, not the proxy mode inside the client. A direct route reaches the remote entry point from the local network, with a simpler path but greater sensitivity to local carrier and cross-border routing changes. A relay route connects to an intermediate entry point before reaching the remote node. An IEPL dedicated line typically carries part of the cross-border transmission over a private link. The client still connects according to the subscription parameters; switching to “Global” cannot turn an ordinary direct node into a dedicated line.
| Mode | Traffic coverage | Best for | What to troubleshoot |
|---|---|---|---|
| Rule-based split tunneling | Matches domains, addresses, or rules | Everyday browsing across multiple apps | Whether the target domain matches the correct rule |
| Global proxy | Send as much traffic as possible through the current node | Determining whether split-tunneling rules cause the issue | Whether local services are being routed unnecessarily |
| System proxy | Apps that follow system proxy settings | Browsers and standard desktop apps | Whether the app bypasses the system proxy |
| Tunnel mode | Connections handled by the network extension | When more app traffic needs coverage | System authorization, routing, and DNS |
| Direct connection | Does not enter the proxy route | Local resources or temporarily pausing the service | Whether a direct connection was mistaken for an active VPN connection |
If a browser can reach the target website but a terminal, game platform, or standalone updater cannot connect, first check whether those apps bypass the system proxy. If switching to tunnel mode fixes the issue, the problem is probably the traffic coverage. If tunnel mode still has no effect, continue checking the node connection, routing rules, firewall, and DNS.
Verify the exit location, DNS, and actual connection status
A client showing “Connected” only means that its local process believes the tunnel is established; it does not by itself prove that the target app's traffic uses the selected route. During verification, check the exit location, DNS resolution, and behavior across different apps. Close old browser pages, open a new window, and visit a trusted IP-check page to confirm that the exit location matches the selected node.
Next, check DNS. A DNS leak usually means that traffic passes through the proxy or tunnel while domain lookups are still handled by a resolver on the local network, creating a mismatch between the destination and the resolution path. If the client offers remote DNS, encrypted DNS, or a “DNS through proxy” option, enable it according to the recommended configuration. Do not stack multiple apps that try to control DNS at the same time, as this can cause resolution loops, timeouts, or inconsistent results.
Test a browser and an app that does not rely on browser proxy settings separately. If their exit locations differ, the proxy coverage or split-tunneling rules still need adjustment. After testing, let the Mac sleep and wake it to see whether the client reconnects automatically. Recheck the exit location after switching between Wi-Fi, Ethernet, a hotspot, or another network, because an underlying interface change can invalidate the old tunnel.
- ✅ The client shows a connected status without continuous reconnect attempts.
- ✅ A newly opened lookup page shows the exit location associated with the target node.
- ✅ The DNS resolution path matches the current proxy policy.
- ✅ The browser and desktop apps that need the route behave consistently.
- ✅ Check the connection again after sleep, wake, or a network change.
- ❌ Do not treat a selected node name as proof of the exit location.
Troubleshoot permission prompts, import failures, and disconnects
The client repeatedly asks to add a VPN configuration
First check whether the stable, beta, or older version of the client is installed at the same time. Quit all similar apps, review existing VPN configurations and network extensions in System Settings, and keep only the one you actually use. After cleaning up, reopen the client and approve the matching request. If the app asks for permission on every launch, also confirm that it is not running from a disk image or temporary folder.
The subscription link copies successfully, but the client cannot update
Confirm that the import screen accepts remote subscriptions rather than only single-node share links. Subscription URLs and single-node URIs have different structures and purposes, so using the wrong entry point may produce an invalid-format error. Make sure the link was not rewritten by a chat app and does not include a full stop or other text from the surrounding message. If an old subscription still shows nodes but cannot update, delete the configuration group and copy it again from the dashboard.
Connected, but only the browser works
This commonly occurs in system proxy mode. The browser follows the system proxy while other apps connect directly. Check whether the client supports tunnel mode and confirm that its network extension is authorized. If rule mode is required, verify that the domains and addresses used by the target app are not classified as direct. Do not add only one webpage domain; desktop apps may also rely on API domains, content delivery domains, or separate connections.
The old exit location remains after switching nodes
Disconnect manually first, then select the new node and reconnect. Close app windows that may retain the old connection, and reopen the target app if necessary. Browser connection reuse, DNS caching, and a tunnel that the client did not rebuild can all make short-term checks point to the old route. If the client offers a “Clear system proxy on disconnect” option, confirm that it works correctly.
The connection will not recover after the Mac wakes from sleep
The underlying network interface may have changed after wake, while the client still holds the old session. Disconnect and reconnect first; if this happens often, check the client's automatic reconnect setting. UDP-based connections such as Hysteria2 and TUIC also need to rebuild their path after a network change. VMess, Trojan, VLESS, and Shadowsocks can likewise reconnect when the original session becomes invalid; the protocol name alone cannot prevent this.
Local websites or LAN resources fail after connecting
Check whether Global mode was enabled accidentally or whether the tunnel configuration is sending local subnets to the remote route. Switch back to rule mode and test again. If the client offers “Bypass LAN” or an equivalent option, enable it after confirming that it fits your needs. Corporate networks, development environments, and local devices may have their own DNS and routing requirements, so avoid letting two network policies override each other.
Routine maintenance and update practices
Once setup is complete, ongoing maintenance mainly involves updating the client, refreshing the subscription, and reviewing permissions. Client updates may change protocol support, network extension behavior, or DNS handling; subscription updates may change node parameters and configuration groups. Note the working configuration before updating, then recheck the node list and exit location afterward instead of assuming the old state was fully preserved.
Treat the subscription link like a credential. Do not store it in public notes, shared terminal history, or screenshots. If you suspect that the link has been exposed, replace it in the service dashboard rather than merely deleting it from the client. Removing local configuration clears the record on that device but does not automatically invalidate copies already made elsewhere.
When multiple proxies, filters, corporate network components, or security tools run together, define which layer each tool controls. Several tools changing the system proxy, routing, or DNS at once can make the connection order unpredictable. For troubleshooting, temporarily quit nonessential network tools, confirm that the single client works, and restore the others one at a time.
- ✅ Recheck the network extension status after updating the client.
- ✅ Refresh the subscription regularly and confirm that nodes parse correctly.
- ✅ Recheck the exit location and DNS after changing networks.
- ✅ Let only necessary network tools control the proxy, routing, or resolution.
- ❌ Do not store or share the subscription link like an ordinary public URL.
After completing these steps, configuring a VPN on macOS is no longer just a matter of clicking Connect. The client, system permissions, subscription, protocol, split tunneling, and DNS each have a defined role. When something goes wrong, locating the problem by layer is more effective than repeatedly deleting the app or switching nodes blindly, and it makes it easier to preserve settings that have already been verified.