Mac VPN Setup: Complete Guide for macOS Beginners

The short version: on macOS the order is approve first, import second, verify last. Doing it out of order won't throw an error right away, but it will send you looking in the wrong place when something breaks — you'll blame the server when the real problem is that the system extension never loaded. The sections below follow that order.

Before You Begin: Confirm Your macOS Version and Admin Rights

Since macOS 10.15 Catalina, third-party network clients have gradually migrated from kernel extensions to the System Extension framework, and the approval entry point is managed centrally by the OS. Starting with macOS 13, System Preferences was renamed System Settings — earlier versions still use the old name, so menu labels differ — but the logic is the same: the extension has to be allowed to load before the client can take over network traffic.

On the account side, installing the client, approving the system extension, and writing VPN configuration all require administrator rights. If this Mac is shared with family and you normally sign in as a standard user, make sure you know the admin username and password beforehand — otherwise you'll be stuck staring at the approval prompt with nothing to type.

Think about where the client comes from, too. The App Store version is limited by sandboxing and review rules, so it can only use the network APIs the system provides and its feature set is more restrained; the version downloaded directly from the official site can install a system extension and supports TUN mode for handling all traffic. Don't install clients from both sources at once — they'll fight over the same VPN configuration, and the symptom is a client that installs fine but never connects.

• ✅ Your system is running macOS 10.15 or later, and you know which menu path applies to your version.
• ✅ You're signed in as an administrator, or you know the admin password.
• ✅ You have a working subscription link on hand, usually one that starts with https.
• ❌ Don't install clients from two sources at the same time, and don't install a new one before the old client has been fully removed.

Install the Client: Get Past the System Extension Step

After you drag the installer into your Applications folder, the first launch may be blocked by Gatekeeper. Go to System Settings → Privacy & Security and click Open Anyway next to the notice — there's no need to disable the system's security features.

Now the most important part of this guide: the order of approvals. Follow the five steps below and you'll skip the classic detour of "it won't connect, so the server must be broken."

1. Launch the client. The first time it tries to connect, macOS shows a system dialog asking to add a VPN configuration — enter your login password or confirm with Touch ID. This prompt comes from the OS, not the client, and it's there to confirm that you're authorizing this app to handle network traffic.
2. If the client uses a system extension (basically any client that supports TUN mode), installation or first launch will show a notice that system software from the developer was blocked. Open System Settings → Privacy & Security, find that notice at the bottom of the page, click Allow, and enter your password again.
3. macOS 15 and later moved this notice into the Privacy & Security → System Extensions area. The path changed, but the button is still called Allow.
4. Once approval is done, the system will ask you to restart the client, and some versions ask for a full Mac restart. Follow the prompt — don't skip it. If the extension isn't loaded, every setting after this point is spinning in place.
5. Go back to the client and check its status. When the extension has loaded properly, the connect button is available and the status bar reads Connected; when it hasn't, the button is greyed out or clicking it does nothing at all.

Import Your Subscription: Link, QR Code, or Manual Entry

The subscription link is the only credential between the client and the routes — it contains the node list, protocol parameters, and the update address. There are three ways to import it, ordered by convenience:

• Paste the link: in the client, click Add Subscription or Import from Clipboard, paste the whole https link, name it whatever you like, and confirm — the client will pull the node list automatically.
• Scan a QR code: subscription pages usually show a QR code alongside the link. On a Mac you can use the client's built-in scanner, or scan it with your phone and send the link over to the Mac.
• Enter it manually: type in the server address, port, protocol type, and password or UUID one field at a time. Use this only when you don't have a subscription link — manual entry easily misses protocol parameters, which leaves you connected but unable to open any web page.

Once the import succeeds, a subscription group appears in the client's sidebar; expand it to see individual node names and regions. If the group is empty or you get an update failed message, first check whether the link was cut off by a line break — copying a link out of a chat window often adds a trailing space or drops a few characters.

On the protocol side, mainstream clients support Shadowsocks, VMess, Trojan, VLESS, Hysteria2, and TUIC. Hysteria2 and TUIC are built on QUIC and perform better on lossy routes, but they require a recent client version; if your client is older, these two protocols may not show up at all. That doesn't mean the link is broken — just update the client.

Connect and Verify: Three Checks That Prove the Tunnel Is Working

Clicking connect and seeing the status change to Connected doesn't mean your traffic is actually going through the route. On macOS you should verify at least three things: whether the exit IP changed, whether DNS resolution is being handled, and whether IPv6 is leaking.

1. Check the exit IP: open any page that displays your IP in a browser and compare the result before and after connecting. If the IP hasn't changed, your traffic isn't going through the proxy — usually because a routing rule sends that site direct, or because the client is in rule mode and no rule matched.
2. Check DNS: run scutil --dns in Terminal and look at the resolvers currently in use. When traffic goes through the proxy, the resolvers usually point to a local loopback address or an address on the provider side; if you still see your ISP's DNS, resolution isn't being handled and there's a leak risk.
3. Check IPv6: visit any IPv6 test page. If your IPv6 address is still exposed and doesn't match the proxy exit, the client is only handling IPv4 traffic — turn on Block IPv6 in the settings, or pick a route that supports dual stack.

# Show the current DNS resolvers
scutil --dns | grep nameserver

# Show the default route and network interfaces
netstat -rn | head -n 10

# Show the current exit IP (requires a network connection)
curl -s https://api.ipify.org

Once all three checks pass, you're ready for everyday use. Two minutes here saves you a lot of confusing "sometimes it works, sometimes it doesn't" later on.

Routing Rules and Route Types: Choose by Use Case, Not by Name

Routing rules decide which traffic goes through the proxy and which goes direct. There are three common modes: global mode sends everything through the route; rule mode follows a built-in rule set, sending local sites direct and overseas sites through the proxy; direct mode uses no proxy at all. Beginners should start with rule mode, and if a site that should go through the proxy goes direct instead, add a rule for that domain specifically.

As for route types, IEPL dedicated lines are end-to-end private channels that don't transit the public internet, with stable latency and low packet loss — good for video meetings and real-time collaboration; relay routes connect to a regional entry point first and then hand off to an overseas exit, which costs less, and their peak-hour performance depends on the entry point's bandwidth; direct routes connect straight to overseas servers, are the simplest to configure, and suit use cases where latency isn't critical. None of the three is universally better — pick based on what you're actually doing.

Common Permission Errors and How to Fix Them

These are the errors you'll run into most often on macOS, and you can fix almost all of them yourself.

"System software was blocked from loading"

Go to System Settings → Privacy & Security, find the blocked entry at the bottom, click Allow, and enter your password. If the button is greyed out, unlock the padlock in the lower-left corner first. On macOS 15 and later this entry may appear under the System Extensions subsection — different path, same steps.

The prompt keeps coming back after you've approved it

This is usually leftover files from an older client version. Drag the client to the Trash, then check whether a folder with the same name still exists under Library → Application Support, clear it out, and reinstall. When clients from two sources are both present, the system will keep asking about the same configuration.

It connects, but web pages won't open

Check in order: first whether DNS is being handled, then whether a routing rule sends that domain direct, and finally whether the client has local network direct enabled while the target happens to sit in that subnet. All three produce the same symptom but need completely different fixes.

Subscription update fails

First confirm your connection itself is working — subscription URLs are usually hosted overseas, so an update that doesn't go through the proxy may simply time out. Some clients offer a use proxy for updates toggle; turn it on. The link may also have expired, in which case just get a new one.

Ongoing Maintenance: Updates, Backups, and Multiple Devices

After every major macOS upgrade, the system extension approval status may be reset — the symptom is a client that opens but won't connect. After upgrading the OS, open the client and check its status first, and re-approve if needed.

Keep your subscription link inside the client rather than screenshotting it into a group chat. If you suspect the link has leaked, generate a new one — the old link stops working immediately. For multiple devices, the same subscription can be imported separately on a Mac, phone, and tablet, with no limit on the number of devices.

On privacy, this service's policy is no logs — no browsing content and no access history. That's a policy statement, not an absolute guarantee, and you're still responsible for keeping your account and links safe.