macOS from Scratch: Client Installation and Subscription Import Complete Guide

This complete macOS client installation and subscription import guide is for anyone setting up international routes on a Mac for the first time. The core process is straightforward: get the client from a trusted source, approve the required system permissions, import the subscription, choose a route, and confirm that traffic is actually passing through the client. The parts most likely to cause trouble are not clicking Connect, but installing the wrong build, missing a network permission, running similar tools at the same time, or assuming that a successful subscription import means the connection is already active.

Interface labels vary between macOS clients, but the underlying steps are largely the same. Some clients work through system proxy settings, while others use macOS Network Extension to create a virtual network interface; some offer both modes. Once you understand the difference, permission prompts, split-tunneling rules, DNS handling, and troubleshooting become much easier to follow.

Pre-installation checks: version, source, and network environment

First confirm which chip architecture your Mac uses. Newer devices generally use Apple silicon, while older models may use Intel chips. If the download page offers separate installers, choose the build that matches your Mac; if it provides a universal build, use that instead. A mismatched architecture can prevent the app from opening or trigger a request for additional compatibility components.

You can check the architecture from the Apple menu in the top-left corner of the screen. Open “About This Mac” and read the Chip or Processor field. Do not rely on the device’s appearance, and do not download installers from unknown reposting sites. If a client with the same name was previously installed, decide whether its old configuration should be kept before choosing an upgrade or a clean reinstall.

• ✅ Download the installer from the user panel or the client’s official release page.
• ✅ Confirm that the installer matches your Mac’s chip architecture.
• ✅ Pause other tools that modify system proxy or network filtering rules.
• ✅ Record the original settings for company networks, campus networks, or custom DNS.
• ❌ Do not paste a subscription URL into a search box or a public chat.
• ❌ Do not enable the same system proxy in multiple clients at once.

A subscription link is essentially an access credential. It may return node names, server addresses, ports, protocol parameters, and update information. Once you have the link, import it directly into the client. Do not share it publicly or inspect it through an online parsing site. When moving to another device, copy it again from the user panel instead of repeatedly searching through browser history.

Download the client and launch it for the first time

After downloading the installer, you will commonly receive a disk image or an installation package. A disk image usually asks you to drag the app icon into the Applications folder; an installer uses a system wizard to place the required files. Once installation is complete, launch the client from Applications rather than running it indefinitely from Downloads or a mounted disk image.

1. Sign in to the user panel, open the client download area, and choose the macOS version.
2. When the download finishes, open the installer, move the app to Applications, or complete deployment through the installation wizard.
3. Launch the client from Applications. If macOS says the app is from an identified developer, verify the app name and download source before continuing.
4. When the client asks to add a VPN configuration, network extension, or proxy permission, review the developer and app name shown by macOS before approving it.
5. After launch, avoid switching repeatedly between modes. Keep the defaults while completing the first subscription import.

macOS may show a security prompt on first launch. If the system blocks the app, verify the installer’s source first, then open the Privacy & Security area in System Settings to review the blocked app. Continue only when the app name, developer information, and download source all match. Do not disable the entire system security mechanism to work around authorization for one app.

Menu bar icon and main window

Many macOS networking clients provide both a main window and a menu bar icon. Closing the main window may only hide the interface and does not necessarily quit the app; while the menu bar icon remains active, the system proxy or network extension may continue running. To stop it completely, use Quit from the menu, or disconnect first and then quit the client.

After the first launch, check for options such as “Launch at login,” “Launch silently,” or “Connect automatically.” It is best to turn automatic connection off initially, run a manual test, and decide whether to enable it later. That way, unsuitable split-tunneling or DNS settings will not immediately reproduce the problem the next time you sign in.

Importing a subscription: links, updates, and node lists

Once the client opens successfully, import the subscription. Common entry points include “Subscriptions,” “Configurations,” “Config Files,” and “Remote Config.” Typical methods are importing from the clipboard, entering the link manually, or scanning a QR code. On a Mac, copying the full subscription link and pasting it into the client is usually the safest option and makes it easier to spot accidental spaces.

1. Copy the complete subscription link from the user panel; do not manually cut out part of it.
2. Open the client’s subscription manager and choose to add a remote subscription or import one from the clipboard.
3. Give the subscription a clear local name. The name is only used to distinguish it inside the client and does not change the server configuration.
4. Save it, run an update, and wait for the client to parse the configuration and generate the node list.
5. Choose a route for the target region, return to the main screen, and enable the connection or system proxy.

“Import successful” and “Connected” are two different states. A successful import only means the client has read the configuration; seeing nodes in the list does not mean system traffic is being forwarded. For the connection to take effect, you must select a node and enable the relevant proxy mode or network extension. If the client shows only the subscription name with no nodes, run an update first, then check that the link is complete and the subscription is still accessible.

A subscription update can overwrite node parameters delivered remotely. If the client allows editing an individual remote node, avoid placing important changes directly in a subscription-generated configuration because the next update may restore the original values. For custom split tunneling, prefer the client’s separate rules area, a local override file, or a dedicated configuration layer.

System permissions: VPN configurations, network extensions, and proxies

The permissions requested by a macOS client depend on its operating mode. System proxy mode typically changes the HTTP, HTTPS, or SOCKS proxy settings for the current network service. It works for browsers and apps that follow the system proxy, but some command-line tools, games, or apps with their own networking stack may bypass it.

Modes that use Network Extension or a virtual network interface take control of a broader range of traffic at the system network layer. macOS may show prompts to add a VPN configuration or enable network filtering, and require system authentication. After approval, the configuration should appear in the Network or VPN area of System Settings. The exact location varies by client, but it should be identifiable by an entry matching the app name.

System extension issues commonly appear as a client stuck waiting for authorization, a connection button that immediately switches back, or an extension shown as blocked in System Settings. Return to Privacy & Security, review any pending approval items, and restart the client. If permission was previously denied, repeatedly clicking Connect usually will not bring back the full prompt; handle it directly in System Settings instead.

Why the system proxy did not return to normal after disconnecting

If the client exits unexpectedly, the device sleeps, or the process is force-quit, the system proxy may remain enabled after the local proxy port has stopped listening. The result can look like the browser has suddenly lost network access. Reopen the original client, disconnect normally, and then quit the app; this usually restores the settings. If it does not, inspect the proxy entries for the current network service in System Settings.

During troubleshooting, you can also read network status from Terminal. The commands below only read configuration and do not change the system:

scutil --proxy
scutil --dns
route -n get default
networksetup -listallnetworkservices

scutil --proxy shows whether the system proxy is still enabled; scutil --dns shows the current DNS resolvers and scopes; default route information helps identify the main traffic exit; and the network service list confirms the names of the Wi-Fi, Ethernet, or other interfaces currently in use.

Connection verification: exit location, DNS, and split-tunneling results

A changed connection button color only proves that the client has entered an active state; it does not by itself prove that all traffic is being forwarded as expected. Verification should cover the exit location, target website access, DNS resolution, and split-tunneling results. Before testing, disable independent proxy extensions in the browser so its own settings do not interfere with system-level checks.

1. Before connecting, note the region of your current network exit without publicly saving the full address.
2. Choose the target route in the client, enable the connection, and wait for its status to stabilize.
3. Reopen the browser page and confirm whether the exit region changed with the selected route.
4. Visit different services that require direct access or routed access and check whether the split-tunneling results match expectations.
5. Review the DNS test results and confirm that resolution requests were not sent to an unexpected resolver through the wrong network exit.
6. Test again after switching routes to rule out misleading results caused by browser cache or reuse of an old connection.

A DNS leak usually means that traffic is already using a proxy or virtual interface, but domain lookups are still handled by an unexpected resolver on the local network. It does not always cause a complete outage; more often, results are unstable, a target service identifies the wrong region, or different apps behave inconsistently. If the client offers options such as “Remote DNS,” “Proxy DNS,” or “DNS Hijacking,” start with the value recommended by the service and avoid stacking multiple custom DNS solutions.

Split-tunneling rules determine which domains, addresses, or apps use the proxy and which connect directly. Rule mode suits everyday use and reduces unnecessary cross-border traffic; global mode is useful for short troubleshooting sessions because it temporarily removes rule omissions from the equation. If global mode works but rule mode does not, the issue is usually rule matching or DNS routing rather than the installation itself.

Understanding protocol and client differences

A subscription may include protocols such as Shadowsocks, VMess, Trojan, VLESS, Hysteria2, or TUIC. Most users do not need to enter protocol parameters manually; the subscription supplies the server address, port, authentication, and transport settings to the client. However, the client must genuinely support the protocols included in the subscription. Otherwise, nodes may fail to import or may appear in the list without connecting.

IEPL dedicated lines, relay routes, and direct connections describe how a route is organized, not the proxy protocol. IEPL is commonly used to carry user traffic onto a controlled international link; a relay route first reaches an entry server and then forwards traffic to the exit; a direct route connects the user’s network straight to an overseas server. The protocol defines how data is encapsulated and authenticated, while the route defines the path it takes. They should not be confused.

When choosing a route, first check whether your current network can reach the entry point reliably, then consider the region where the target service is located. Direct does not always mean faster, and relay does not always mean slower; actual performance depends on local carrier routing, congestion, UDP availability, and the exit location. Do not judge a node by its name alone—consider connection stability and the target service’s access results.

Common troubleshooting: narrow the scope step by step

When first-time setup fails, the most effective approach is to troubleshoot by layer: confirm that the app runs, then confirm that the subscription updates, next confirm that a node can connect, and only then address DNS and split tunneling. Skipping the basic states and immediately changing complex rules often makes the issue harder to reproduce.

Subscription update fails

First check that the copied link is complete and that no spaces were added at either end. Confirm that the current network can reach the subscription URL and that the system clock is accurate. If the client provides update logs, look for parsing errors, certificate errors, or connection timeouts. Do not repeatedly add the same subscription after an update fails, or duplicate configurations will accumulate.

Connection drops immediately after clicking Connect

First check whether macOS has approved the VPN configuration or network extension, then confirm that the client supports the node’s protocol. Next, test another route from the same subscription for comparison. If every route drops immediately, permissions, the client core, or local network restrictions are more likely; if only a few routes fail, keep the working ones instead of reinstalling the entire client.

No internet access at all after connecting

Disconnect first and confirm that direct access has returned. If access is still unavailable, check for a leftover system proxy. Once direct access works again, reconnect with the default rules; if it still fails, switch connection modes and inspect the DNS settings. If a company or campus network requires web authentication, complete that authentication while the client is disconnected, then enable the route.

Browser works, but other apps do not

This usually means the browser follows the system proxy while the target app does not. Check whether the client offers a virtual network interface mode or per-app routing. Command-line tools may also read their own proxy environment variables, so behavior in a Terminal session may differ from that of graphical apps.

Connection fails after waking from sleep

After switching Wi-Fi, waking from sleep, or changing network interfaces, an old connection may have expired while the client status has not refreshed. Disconnect manually and reconnect. If this happens often, turn off automatic connection for comparison and check whether the client offers a reconnect-after-network-change setting.

• ✅ App will not launch: check the architecture, source, and system security prompts.
• ✅ Subscription will not update: check the link, current network, and system time.
• ✅ Node will not connect: check permissions, protocol support, and local network restrictions.
• ✅ No network after connecting: check for a leftover proxy, DNS, and connection mode.
• ✅ Some apps are unaffected: check system proxy coverage and split-tunneling rules.
• ✅ Connection fails after waking: disconnect and reconnect, then watch for network interface changes.

Routine maintenance and safe shutdown

Once setup is complete, routine maintenance mainly means updating the subscription and client, checking for unavailable routes, and confirming that the system proxy returns to normal. Before updating the client, record the current subscription name, connection mode, and custom rules if needed, but never include the subscription link in a public screenshot. After an upgrade, recheck the network extension status and split-tunneling results on the first launch.

When you are finished, disconnect in the client first, then quit normally from the menu bar. Closing only the main window may leave the app running in the background. Before switching to a company network, campus network, or a network that requires web authentication, disconnect first to reduce proxy leftovers that could interfere with the login page.

If you plan to uninstall the client, first remove or disable the VPN configuration, network filters, and startup items it created, then remove the app. After uninstalling, check that the system proxy has returned to its original state. Deleting only the icon from Applications may not remove the associated network configuration.

After completing these steps, first-time macOS setup follows a clear loop: the installation source is verified, system permissions are approved, the subscription updates, routes connect, the exit and DNS are verified, and network settings recover after disconnecting. If an issue appears later, check in this order: installation, subscription, connection, DNS, then split tunneling.