macOS from Scratch: Install the Client, Grant System Permissions, and Import a Subscription

Before installation: client, architecture, and subscription details

First sign in to the service dashboard, download the macOS client from the download area, and copy your subscription link from the subscription section. The installer and subscription link serve different purposes: the installer provides the connection capability, while the subscription link provides routes, protocols, and the update source. Installing the client without importing a subscription usually leaves no routes available to connect to.

Check the processor architecture

A Mac may use Apple silicon or an Intel processor. If the download page offers separate installers, choose the version that matches your Mac; if it offers a universal installer, you can use that instead. A mismatched architecture commonly causes the app not to open, to quit immediately after launch, or to request an additional compatibility environment.

You can check the chip or processor information on the Mac’s About This Mac page. No system parameters need to be changed; just match the installer type to the device. If the client offers both a graphical interface and a command-line version, beginners should start with the graphical version because it makes the subscription update time, current route, and proxy mode easier to monitor.

Identify the protocols supported by the client

Routes in a subscription may use Shadowsocks, VMess, Trojan, VLESS, Hysteria2, or TUIC. The client must support the relevant protocol to parse the configuration and establish a connection. If the route list is empty after import, the subscription may not be invalid: the client could be outdated, or it may not recognize a protocol field used by the subscription.

• ✅ The installer came from the service dashboard or the client’s official release channel.
• ✅ The Mac’s processor architecture matches the installer.
• ✅ The complete subscription link was copied and stored privately.
• ✅ The system date, time, and time zone are set to update automatically.
• ❌ Do not download repackaged installers from unverified reposting pages.

Install the client and grant system permissions

Open the downloaded installer and follow the prompts to move the app to the Applications folder, then launch it from there. Running it long-term from a disk image or the Downloads folder can interfere with automatic updates, helper processes, or saved permissions. On first launch, macOS checks the developer signature and may ask to add a VPN configuration or network extension.

Why network extension permission is required

System proxy mode mainly changes macOS proxy settings so apps that follow the system proxy can pass traffic to the local client. Tunnel mode uses Apple’s network extension interface to handle a broader range of connections. In either case, the client should not bypass system security controls to obtain permission; the correct approach is to respond to the authorization prompt shown by macOS.

When macOS asks whether to allow a VPN configuration, network extension, or network content filter, first verify the app name shown in the prompt, then follow the system instructions. Some actions require the password for the current Mac user account or local authentication. This is the normal macOS process for authorizing system setting changes, not the subscription service collecting credentials.

1. Move the client to the Applications folder and launch it.
2. Read the system prompt and confirm that the requesting app name is correct.
3. Allow the VPN configuration to be added or enable the network extension.
4. Return to the client and confirm that the status bar no longer says permission has not been granted.
5. Do not enable global mode yet; complete the subscription import and basic checks first.

What to do when the permission prompt does not appear

Quit the client, then reopen it from the Applications folder. Next, open the Privacy & Security section in System Settings and check the bottom of the page for a blocked system software or extension notice. You can also check the network settings to see whether the corresponding VPN configuration has already been created. A client that has already been authorized will not show the prompt every time, so no prompt does not necessarily mean that permission is missing.

If the system says an extension was blocked, allow only the item whose developer name matches the current client. Restart the client or Mac as instructed. If the client was moved, renamed, or installed over an existing copy, fully quit the old process first, then reinstall it without changing the app name so the authorization record does not point to an old path.

Import the subscription link and load routes

Open the client’s Subscription, Configuration, or Remote Configuration page, then choose Import from Clipboard or Add Subscription Link. You may enter any name that makes the service easy to identify; paste the complete link copied from the dashboard into the address field. After importing, run an update so the client can retrieve the current routes and groups from the server.

A subscription link is not a single route address. It usually returns a set of encoded or structured configurations containing route names, server addresses, ports, protocol parameters, and group information. The client turns these into selectable routes only after parsing them. When routes change, use Update Subscription to sync them instead of editing each one manually.

Import succeeds but no routes appear

Start by checking the error type reported by the client. For a failed network request, check whether the current network can reach the subscription address. For a parsing failure, update the client. For an authentication or invalid-link error, return to the user dashboard and copy the subscription again. Do not include explanatory text, quotation marks, line breaks, or trailing spaces when copying, and do not mistake a webpage address for a subscription address.

Some clients can import a single Shadowsocks, VMess, Trojan, or VLESS share link directly, but that is different from importing a subscription. A single import provides only the current configuration and will not sync automatically when the service updates its routes. For long-term use, keep the subscription entry and let subscription updates maintain the route list.

Choose a protocol and route type

The protocol determines how the client and server package and transmit data, while the route type describes the network path used by the traffic. A direct route connects to the remote route from the current network; its path is simple, but quality depends more heavily on the local carrier and international gateway. A relay route connects to an entry point first, then uses the relay network to reach the exit, which often makes cross-network routing easier to control. IEPL is designed around a relatively dedicated cross-border transport path and is not the same as a direct connection over the public internet.

Hysteria2 and TUIC use QUIC-based transport approaches and may recover from packet loss differently from traditional TCP solutions. Trojan, VLESS, VMess, and Shadowsocks also depend on the client implementation, server configuration, and actual network conditions. Do not judge speed from the protocol name alone; compare connection setup, page response times, and long-connection stability on the same network and at similar times.

Choose a proxy mode and verify the connection

After importing the subscription, choose a route and enable rule mode or system proxy mode. Rule mode uses domains, address ranges, and app requests to decide whether traffic goes through the proxy or directly, making it suitable for everyday use. Global mode sends more traffic through the remote route and can help with short-term diagnosis, but it may also reroute local websites, LAN devices, or software updates. Direct mode generally means the client remains running while requests bypass the remote route.

System proxy mode versus tunnel mode

System proxy mode relies on apps following macOS proxy settings. Browsers and most conventional network applications usually work with it, but apps with their own network stack may ignore it. Tunnel mode handles connections at the system network layer, covers more traffic, and is better suited to UDP or full-device traffic, but it requires a higher-level network extension permission.

During the first verification, do not run two different clients at the same time, and do not stack browser extensions, other proxy tools, and a system tunnel. Multiple local proxies changing system settings can cause port conflicts, proxy loops, or proxy settings that remain after the client is closed.

• ✅ The client shows a connected status and the current route name is clear.
• ✅ Regular webpages and the target international websites open normally.
• ✅ After disconnecting, the system network returns to its previous state.
• ✅ In rule mode, local services and LAN resources remain accessible.
• ❌ Do not run multiple clients that take control of the system proxy at the same time.
• ❌ Do not submit the complete subscription address to public testing pages.

Check whether DNS and routing match

DNS translates domain names into network addresses. If domains are resolved by the local network while subsequent connections are sent through a remote route, the resolved location may not match the exit location, and a DNS leak may occur. When troubleshooting, check whether the client’s DNS mode, routing rules, and the resolver currently used by the system are consistent.

After enabling tunnel mode, you can use a trusted DNS testing page to see whether lookup requests still point to an unexpected local network. Interpret the result together with the client configuration: a local resolver does not necessarily indicate a failed connection, because rule mode may intentionally use local DNS for direct domains. The issue to fix is a domain that should use a remote route but continues to resolve through the wrong path.

If webpages open but one app cannot connect, first determine whether that app ignores the system proxy. You can temporarily switch to tunnel mode to test its coverage, or inspect the client rules to see whether the app’s domain or address was incorrectly classified as direct. Do not attribute every problem to route speed; an incorrect routing match is often more likely.

A practical troubleshooting order

Start troubleshooting with the least disruptive actions. Refresh the subscription and switch routes first, then check the mode and permissions, and reinstall only as a last resort. Deleting the client immediately may also remove logs, subscriptions, and state useful for locating the problem, making it harder to identify which layer failed.

The extension is blocked or the Connect button does nothing

Open Privacy & Security in System Settings and check for any item awaiting approval; then check whether the VPN configuration is enabled in Network settings. If the configuration exists but the client still reports that it is unauthorized, quit and restart the client. If it remains unresponsive, remove the corresponding old network configuration and let the client request it again, handling only items that match this client.

Subscription update failed

Confirm that the basic network works, then copy the subscription address again. If the service dashboard opens in a browser but the client cannot update, check the system time, client version, and whether another proxy tool is intercepting requests. If the subscription address has been exposed or reset, generate a new entry in the dashboard and delete the old configuration from every client.

Webpages will not open after connecting

Try updating the subscription, switching routes, using rule mode, and checking DNS settings in that order. If only the browser is affected, disable its separate proxy extension and try again. If every app is affected, focus on tunnel permission, leftover system proxy settings, and whether the current network restricts the selected transport method. When switching protocols for diagnosis, choose a configuration already included in the subscription rather than guessing server parameters.

The internet still does not work after closing the client

This is usually caused by the system proxy not being restored. Reopen the client, disconnect or disable the system proxy first, and then quit normally. If the client can no longer launch, open macOS network settings and check whether proxy options remain enabled for the current network service. Clear the leftover settings and reconnect to the network; there is no need to modify the router or delete other network services.

1. Confirm that the local network can access ordinary websites.
2. Update the subscription and note the specific error message.
3. Switch to another route in the same group.
4. Check for conflicts between rule mode, system proxy mode, and tunnel mode.
5. Check the network extension, VPN configuration, and DNS settings.
6. Quit other proxy tools and test again.
7. Keep the error information before deciding whether to reinstall the client.

Routine updates and configuration maintenance

Once the client runs normally, routine maintenance mainly means updating the subscription, updating the client, and checking the rules. Subscription updates sync routes; client updates add support for new protocol fields and system interfaces. Neither replaces the other. If connection behavior changes after a macOS update, first confirm that the client supports the current system, then check the network extension again.

Do not create duplicate subscriptions repeatedly. Importing the same entry multiple times can produce duplicate route names and make it difficult to tell which configuration is actually in use. Keep one valid subscription, give it a clear name, and maintain it through the client’s built-in update function.

When moving to a new Mac, obtain the client and subscription again from the user dashboard instead of copying the entire app folder. Network extension authorization is tied to the local system, and moving old files cannot replace authorization on the new device. After migration, delete the subscription configuration from the old device to reduce the chance that the link remains stored on a device no longer in use.

Remember the complete chain: the client runs the connection, system permissions allow it to handle network traffic, the subscription delivers routes, the protocol carries the data, routing rules determine the path, and DNS resolves domain names. A failure at any layer may look like a connection failure, but checking each layer narrows the problem quickly.