How do you use a VPN on a Mac? Install a client that matches your chip, grant the required permissions, import a subscription, and check the route used by your target app. On macOS, “Connected” is just the starting point: system proxy, tunnel mode, and app settings determine which requests actually use the route.
This guide follows the steps for first-time setup, without requiring you to understand every protocol. If something goes wrong, troubleshoot one step at a time. Changing the client, route, and DNS settings together makes it hard to identify the cause.
Before you start: Understand the client, subscription, and system connection
The client reads configuration, establishes connections, and applies routing rules. A subscription link retrieves the service's node configuration, which may include addresses, ports, credentials, and other connection parameters. Your account password is for signing in to the dashboard; it is not a subscription link and cannot be entered as a server address in any client.
The VPN settings in macOS are not a universal subscription importer. They support system connection types, but cannot read every proxy subscription. Protocols such as Shadowsocks, VMess, Trojan, VLESS, Hysteria2, and TUIC require a compatible client or core. Check the client version and the configuration format provided by the service rather than relying on “VPN” in the app's name.
VPNBoat users can sign in to the dashboard to get the client and subscription. No email address is required to create an account; just use a username and password. Before you begin, see the Guides for the current recommended setup, and avoid downloading installers from unfamiliar mirror sites in search results.
- ✅ Check your chip type and macOS version in About This Mac, then choose an installer compatible with the download page's requirements.
- ✅ Have your dashboard login details ready and store your subscription link somewhere you trust.
- ✅ Pause other clients that change network routing, and note your current proxy settings so you can restore them later.
- ❌ Don't post your full subscription link, connection QR code, or configuration file in a public forum.
Client installation: Verify the source before addressing blocks
Apple silicon and Intel Macs may require different builds. Some download pages offer a universal version, while others provide separate installers. An incompatible build may fail to launch or require compatibility translation, so choose a native build when available and check the client's supported macOS versions.
- Follow the dashboard instructions to open the client download page, then verify the developer name, supported platform, and installation instructions.
- For a disk image, open it and follow the instructions to move the app to Applications. For an installer, review each step before proceeding.
- Launch the client from Applications rather than running it long-term from Downloads or a disk image, which can cause confusion with updates and permissions.
- Once the app opens normally, import the subscription and grant the permissions needed to connect.
“Unable to verify developer” and “will damage your computer” are different warnings. The first concerns signing, notarization, or source trust checks; the second may indicate that macOS detected a risk. Verify the download source and developer guidance first. Only if you trust the source and macOS allows manual approval should you check Privacy & Security for an option to open the app.
If you see “App is damaged,” don't blindly run Terminal commands you found online. An incomplete download, an invalid signature, or modified software can cause similar warnings, so start by downloading a trusted installer again. Don't disable System Integrity Protection or turn off Gatekeeper globally just to launch the client.
System authorization: Approve only the permissions needed
Network implementations vary by client. A client using the system proxy may ask to change proxy settings; tunnel mode may ask to add a VPN configuration, enable a network extension, or install a helper tool for managing network settings. You may not see every prompt, and menu locations can vary by macOS version.
| Prompt or setting | Common purpose | What to verify first |
|---|---|---|
| Add VPN configuration | Allow the client to establish a system-managed tunnel | Confirm the app requesting access is the client you just installed and intend to use |
| Approval for a network extension or content filter | Handle traffic, routing, or filtering, depending on the client | Check that the extension developer matches the trusted download source |
| Install helper tool | Perform network configuration tasks that require elevated privileges | Confirm the prompt appears when you enable the related feature |
| Notification permission | Show connection changes, updates, and error alerts | Usually not required to establish a connection; choose based on your preference |
Don't assume every permission request is necessary for a connection. Basic network access generally doesn't require Accessibility or Full Disk Access. If a client requests either, check exactly why. On a managed Mac, configuration profiles or administrator policies may restrict extension installation; don't try to bypass those requirements.
If you denied a prompt by mistake, search System Settings for VPN, Network Extensions, or the app name, then follow the client's instructions to grant permission again. If nothing happens afterward, quit and reopen the app. Restart only when macOS or the installation instructions explicitly require it.
Import a subscription: Check the format and update status
Open the subscription or client configuration page in the dashboard, and use the import option for your client. “One-click import” usually opens the local client through an app link, and your browser may ask for confirmation. Check which app is being opened. If nothing happens, use the client's Import from URL option instead.
- Copy the full subscription link from the dashboard, without any surrounding instructions, spaces, or line breaks.
- In the client's subscription, configuration, or profile section, add the remote link and give it a recognizable local name.
- Run an update and confirm that selectable nodes or policy groups appear—not just a “Saved” message.
- Choose a route, enable the appropriate proxy or tunnel mode, and test the connection.
If import fails, first determine whether the link can't be downloaded or the configuration can't be parsed. A download failure may involve your local network, an expired subscription link, or an authentication issue. If the download succeeds but parsing fails, the subscription format, protocol support, or core version may be incompatible. Don't keep pasting incompatible configuration into different fields, and don't send the link to an unfamiliar online converter.
A route name isn't a protocol name. IEPL describes one type of transmission link, while Shadowsocks and Trojan are connection protocols at a different layer. A relayed route typically passes through an entry point before forwarding traffic; a direct route connects from your local network to the remote entry point. The experience still depends on your local network, routing, and egress environment, so don't judge speed or access by the name alone.
Choose a mode: system proxy, tunnel, or split routing
The system proxy provides an entry point for apps that follow macOS proxy settings, but it doesn't force all traffic through the client. Some command-line tools, apps with their own proxy settings, and background processes may ignore it. So if a browser can reach a site but a terminal command cannot, the node isn't necessarily at fault.
Tunnel mode usually uses a virtual network interface and route handling to cover more traffic, but it can still be affected by exclusions, route priorities, DNS settings, and the client implementation. It doesn't guarantee that every app is covered as soon as you turn it on. A corporate VPN, another tunnel tool, or network filtering software may also change routes when running at the same time.
Rule mode routes, bypasses, or blocks traffic based on domains, addresses, or other conditions. Global mode generally sends traffic already handled by the client through the selected egress route. The latter can help you quickly check whether a routing rule is the problem, but it won't automatically cover apps that don't use the system proxy.
For your first setup, keep the default rules provided by the client. Test a browser first, then the software you actually use. If only one app fails, check its own proxy settings, process rules, and DNS behavior. If a terminal needs separate settings, use the local address, port, and command examples specified by the client; don't copy someone else's port.
Bottom line: If you only need browser access, start by testing the system proxy. If more apps need to use the route, enable tunnel mode as directed by the client. What matters is whether the target app actually uses the egress route—not which mode sounds more comprehensive.
Verify the connection: egress IP, DNS, and app behavior
Record your egress details before connecting, then connect to the target route and compare results using the same browser and test method. Use a trusted IP lookup tool; you don't need to enter account details on a test page. Location databases may differ or be out of date, so treat their location labels as a reference—not a substitute for testing the app itself.
- ✅ Confirm the active configuration, policy group, and node in the client to make sure automatic selection hasn't switched to another egress route.
- ✅ Compare your public egress IP before and after connecting, and check that both IPv4 and IPv6 follow the expected route.
- ✅ Open the target app and test sign-in, page loading, and real requests—not just its home page.
- ✅ Check the DNS query path and compare the resolution behavior with the client's documentation.
- ❌ Don't treat a successful browser test as proof that command-line tools and background services are also covered.
A DNS leak occurs when DNS queries are sent outside the intended protected path. If your configuration intentionally uses a local resolver for direct-connection domains, seeing local DNS results doesn't necessarily mean something is wrong. But if those queries are meant to go through the tunnel and still leave over your local network, investigate. Browser encrypted DNS, client-side remote resolution, and system DNS may each work differently; check them against your routing rules.
To inspect local settings, run these read-only commands in Terminal. They can offer useful clues, but they won't change your configuration or prove on their own that traffic is using a proxy.
sw_vers
uname -m
scutil --proxy
scutil --dnsscutil --proxy shows system proxy settings, while scutil --dns shows system resolver configuration. Browser-based encrypted DNS may not be fully reflected in this output, and terminal requests may ignore the system proxy. Before sharing diagnostic details, check for internal domain names or network information.
Troubleshooting: Recover based on where setup failed
Connected, but websites won't load
Quit other network proxy tools first. Confirm that the client has actually enabled the system proxy or tunnel, rather than just completing a node test. Then check whether routing rules send the target domain direct and whether your local network works normally. If only one route fails, try another route for comparison; avoid changing DNS and routing rules at the same time.
Works in the browser, but not in other apps
Check whether the app follows system proxy settings, has its own proxy configured, or matches a bypass rule. If needed, switch to tunnel mode as directed by the client and test again. For managed devices or restrictions imposed by a corporate network, contact your administrator.
Disconnects after sleep or switching networks
A change in network interfaces can invalidate the connection. Wait for the local network to recover, then reconnect in the client. If the problem persists, check for a stale system proxy or duplicate VPN configuration. Before deleting a configuration, confirm which app it belongs to so you don't remove a connection required for work.
Local network access stops after quitting the client
Reopen the client and use its normal disconnect and quit options to clear the proxy. If the app is no longer available, check the proxy settings for the active network interface in System Settings and restore the settings you noted earlier. Don't clear all network configurations. Once the issue is resolved, remove any helper tools or extensions you no longer use as directed by the client.
You're set when: the client can read the subscription, system permissions match the operating mode, and the target app uses the expected egress route. Keep this working setup so you can reproduce it, then adjust routing rules one at a time. If you need help, share your OS and client versions, the exact error, and the steps you've tried—but never share subscription credentials.