This macOS client installation and subscription import guide starts with pre-download checks, then covers app installation, system permissions, subscription updates, node selection, split-tunnel verification, and troubleshooting. First-time setup problems usually come from an incompatible app build, an unapproved network extension, an inactive configuration, or browser-specific DNS and proxy settings—not the route itself.
A network client on Mac is not simply a matter of “open and go.” To handle connections that require a proxy, it may create a system proxy, virtual network interface, or network extension. macOS treats these as sensitive network configuration changes, so confirmation prompts during the first launch are normal. Check the app source and request details, then grant explicit permission instead of repeatedly dismissing prompts and re-importing the subscription.
Checks before client installation
First confirm your Mac’s processor architecture and current macOS version, then check the installer offered on the client’s release page. Apple silicon and Intel Macs use different architectures; some projects provide separate builds, while others offer a universal installer. Choosing the wrong build can cause the app not to open, quit immediately, or require a compatibility layer.
Get the installer from the client project’s official release channel, the download area in the service dashboard, or the system app store. After downloading, verify that the file name, app name, and publisher match the documentation. If macOS warns that the app was downloaded from the internet, continue only after confirming the source. If it reports a damaged file, unverifiable developer, or invalid signature, download it again and check the official guidance—do not routinely disable system protection.
- ✅ Confirm that the processor architecture matches the installer.
- ✅ Get the client from an official release channel or service dashboard.
- ✅ Quit other proxy clients before installation to prevent conflicting system proxy settings.
- ✅ Keep the subscription link as original text; do not transfer it via screenshots or manual transcription.
- ❌ Do not add configuration profiles from unknown sources to System Settings.
- ❌ Do not permanently disable macOS security checks because of a single launch failure.
A common installation method is to open the disk image, drag the app into the “Applications” folder, and launch it from there. Running it long-term from the Downloads folder or disk image can cause problems with automatic updates, helper component paths, or permission records. If the client comes as an archive, extract it fully before moving the app to “Applications.”
System permissions and network extensions
When the client first enables a system proxy, enhanced mode, or virtual network interface, macOS may ask to add a VPN configuration, network extension, or helper component. Clients use different connection methods, so the names shown in the interface may vary. A system proxy usually affects apps that follow system proxy settings; a virtual network interface can handle more types of traffic but requires a higher level of system authorization.
When granting permission, read the app name shown in the system dialog and confirm that it matches the client you just installed. Then complete the confirmation using the current Mac account’s system authentication. If you dismissed the prompt, open the Privacy & Security, Network, or VPN section of System Settings and look for pending approvals. After approval, return to the client and enable the relevant mode again; in some cases, quit and relaunch the client.
| What you see | Possible cause | What to try |
|---|---|---|
| System proxy is enabled, but some apps still connect directly | The app does not follow the system proxy or uses its own networking stack | Check whether the client supports a virtual network interface and review the traffic rules |
| Enhanced mode turns off immediately after being enabled | The network extension was not approved, or the helper component was not fully installed | Check System Settings for pending approvals, then restart the client |
| The menu bar shows connected, but webpages will not open | The node is unreachable, DNS resolution failed, or the rules conflict | Switch nodes, restore the default rules, and test domain names and network addresses separately |
| Network problems remain after quitting the client | A system proxy remains active, or another network tool is still handling connections | Turn off the system proxy, quit similar tools, and reconnect to the local network |
If System Settings contains VPN configurations or network extensions left by an old client, do not delete everything without confirming its purpose. Quit the old client first, verify that the configuration is no longer needed, and remove items one at a time. On managed devices, network extensions may be controlled by organizational policies, and a personal account may not have approval privileges.
Importing a subscription and updating the configuration
A client launching normally does not mean it has a usable configuration. Sign in to the service dashboard and find the subscription entry for a universal client or your current platform. Use the page’s copy button to avoid truncating characters at the end of the link. A subscription link can grant access to configuration data, so never publish it, share it in screenshots, or paste it into an untrusted online conversion tool.
Depending on the client, the entry may be called “Subscription,” “Configuration,” “Remote Configuration,” or “Profile.” Choose import from the clipboard or URL, paste the complete link, save it, and run an update. A successful update usually shows a node list, policy groups, or a configuration name. If the list remains empty, check the update error first rather than creating multiple subscriptions with the same name; duplicates make later switching and troubleshooting harder.
- Open the service dashboard and copy the subscription link for your current client.
- Open the client’s subscription or configuration manager and choose to add one by URL.
- Give the configuration a recognizable name, paste the link, and save it.
- Run a manual update and confirm that nodes or policy groups appear.
- Choose a target node, then enable the system proxy or virtual network interface.
- Test webpages, DNS, and app connections to confirm that the rules work as expected.
A subscription may include protocols such as Shadowsocks, VMess, Trojan, VLESS, Hysteria2, or TUIC. The protocol name describes how the client connects to a node; it does not indicate route quality. The client must support the protocols and parameters actually used by the subscription. An older version may recognize node names but fail to parse newer fields. If you see “Unknown protocol,” “Invalid configuration,” or an imported node that cannot be selected, update the client first and then check whether the subscription format is compatible.
Importing a subscription is not the same as importing a single node. A single-node link contains one connection configuration and usually must be retrieved again after service-side changes; a subscription link can be updated by the client to keep node changes in sync. For everyday use, keep one clearly named primary subscription and enable sensible automatic updates when supported. If an update fails, the old configuration may still appear in the list, so seeing nodes does not prove that the subscription updated successfully.
Check the path after importing
Configuration name → Update result → Node list → Policy selection → Traffic mode → Access verification
Change one thing at a time when troubleshooting
Restore the default rules first
Then switch nodes
Next check DNS
Finally check the app’s own proxyHow to choose nodes, routes, and traffic modes
Node names usually indicate a country or region, city, route type, and purpose. First-time users do not need to start with complex policy combinations. Choose a node in a suitable location that the client can connect to, then verify it with the default rules. This is easier to troubleshoot than changing the protocol, DNS, rule set, and interface parameters at the same time.
A direct route connects the device straight to the target node, keeping the path simple, but cross-border links can be affected by changes in local carrier routing. A relay route reaches a relay entry point first and then continues across the border, with the focus on improving entry quality and route organization. IEPL dedicated lines are generally used for cross-border transfers where stability matters, and their route structure differs from ordinary public-internet connections. A route name only describes the provider’s classification; choose based on your network, target app, and actual connection performance.
A system proxy works well for browsers and desktop apps that follow system settings, is simple to configure, and can be disabled easily. A virtual network interface, often called enhanced mode or TUN mode, covers more apps and non-traditional proxy traffic but is more likely to conflict with firewalls, other VPNs, virtual machines, and enterprise management tools. After installation, start with a system proxy to verify the subscription and node, then decide whether to enable a virtual network interface based on your app requirements.
Global mode sends most traffic that can be handled through the current proxy policy, making it useful for briefly checking whether a target connection is being missed by the rules. Rule mode decides between direct and proxied access based on domains, network addresses, or app rules, so it is better for daily use. Global mode does not mean every piece of data must follow the same path; local-network access, system services, and client exclusions may still follow their own rules.
DNS, traffic rules, and connection checks
After the connection button shows an enabled state, verify the exit path, DNS resolution, and traffic rules separately. Open a network-check page first to see whether the current exit matches the selected node, then visit sites that require proxy access and sites that should connect directly. If a network address works but its domain does not, the issue is more likely DNS. If the browser works but a desktop app fails, check whether that app bypasses the system proxy.
A DNS leak occurs when domain queries do not follow the resolution path configured by the client and continue to a resolver provided by the local network. It may not stop webpages from loading, but it can make traffic-rule decisions inaccurate and cause the query path to differ from the exit path. If the client offers DNS takeover, encrypted DNS, or remote resolution, start with the project’s recommended defaults. Do not configure multiple conflicting resolution methods in the browser, system, and client at the same time.
Some browsers have their own Secure DNS setting, which may bypass the client’s system resolution configuration. During troubleshooting, temporarily restore the browser default, confirm that the client’s DNS path works, and then decide whether to use the browser’s own resolver. If a company, campus, or hotel network requires portal authentication, complete local network sign-in before enabling the client.
- ✅ The node shows connected without constant reconnects.
- ✅ The network-check result matches the selected exit region.
- ✅ Domains that require proxy access resolve and open normally.
- ✅ Local sites and LAN resources follow the traffic rules.
- ✅ The system network returns to normal after the client is closed.
- ❌ Do not judge every app’s status from a single webpage result.
The most effective way to verify traffic rules is to observe one target at a time. Start with the default rules and confirm that the basic connection works; then inspect the client’s connection log to see whether the target domain matched a proxy, direct, or reject rule. An app using a fixed network address, QUIC, or its own proxy may behave differently from the browser. Adjust the rules around the app’s actual connection method instead of permanently switching all traffic to global mode.
Common permission errors and the recovery order
“Unable to add configuration” usually means that system authorization is incomplete, an old configuration conflicts, or the current account lacks sufficient privileges. Quit other similar clients first, then check existing VPN configurations and network extensions in System Settings. Remove an old configuration only after confirming it is no longer in use, and restart the current client to trigger authorization. Repeatedly clicking Connect without handling pending approvals in System Settings usually changes nothing.
“Helper component installation failed” can occur when the app is not in “Applications,” its path has changed, signature verification fails, or an old component is still running. Quit the client, move the app to the correct folder, reinstall it from an official source, and launch it again. If the client provides a built-in helper removal tool, use it instead of manually deleting system files whose purpose is uncertain.
“Subscription update failed” may indicate an unreachable network, an expired link, an incompatible format, or an incorrect system clock. Copy the link again from the service dashboard, review the client’s error message, and confirm that your Mac uses normal date and time synchronization. Do not paste the subscription link into a regular search box, since it may contain access credentials. If the dashboard offers a subscription reset option, use it only after confirming that the old link should be invalidated.
Handle “connected but no internet” in a fixed order: disable the virtual network interface and fall back to the system proxy, restore the default traffic rules, switch to another available node, and then check DNS. If access still fails after quitting the client, check for a leftover system proxy and reconnect to the current Wi-Fi or wired network. Reinstall only after these basic checks have been ruled out.
The troubleshooting principle is to preserve a reproducible path: record whether the error occurred during installation, authorization, updating, connection, or resolution, and change one variable at a time. Replacing the client, node, mode, DNS, and rules all at once may make the problem disappear temporarily, but it will not reveal the real cause.
When a complete reinstall is necessary
Before a complete reinstall, export rules you wrote yourself and record the current subscription name and essential settings, but never put a credential-bearing subscription link in public notes. Then disable the system proxy and virtual network interface in the client, use the project’s removal option to uninstall helper components, and quit the app. After deleting the app, restart the Mac to reduce the chance that old processes or network extensions remain in use.
After reinstalling, do not immediately restore every custom setting. Import the primary subscription first, use the default rules and system proxy for basic verification, then restore DNS, rules, and enhanced mode one at a time. This helps determine whether the problem comes from the installation environment or an old configuration. If the default setup connects normally and the problem returns after one setting is restored, that setting is the next thing to investigate.
Everyday use and configuration maintenance
After the first installation, keep the configuration simple and easy to restore. Give the primary subscription a clear name and manage custom rules separately from rules delivered by the service. Before updating the client, read the release notes, especially changes to protocol support, network extensions, and configuration formats. If the node list changes after a subscription update, use the update result as the source of truth rather than relying indefinitely on a local copy removed from the subscription.
Before and after leaving an untrusted public network, check the status of the system proxy and virtual network interface. After waking from sleep or switching networks, a long-lived connection may retain an old network state; if it stalls, disconnect and reconnect before clearing the configuration. When switching from Wi-Fi to Ethernet or a hotspot, the client must rebuild the path, so a brief reconnect is normal.
Finally, protect the subscription link like account credentials. This service can be activated with a username and password without an email address, but those credentials should still be unique and stored securely. Client logs can help identify the connection stage, yet may contain node addresses, domains, or configuration fragments; review and remove unrelated sensitive information before sending logs to support.