Getting started with a macOS VPN: installation, system permissions and subscription setup

The first time you run a VPN client on macOS, you may need to grant system permissions, including network extension access. This guide covers installation, subscription import, connection checks, and common permission issues.

When setting up a VPN on macOS, check installation, system permissions, and subscription import separately. An app that opens may not yet have permission to create a tunnel, and a subscription that lists routes doesn't mean your chosen app is using one. First decide which apps should use the VPN, then follow the steps below.

Install a macOS VPN client

  1. Visit the client downloads page and choose a compatible app. If downloads are listed separately for Apple silicon and Intel processors, check your Mac's chip or processor under Apple menu > About This Mac, then choose the right version. Also check which macOS versions the client supports.
  2. For a disk image, open it and follow the instructions to drag the app into Applications, then launch it from there rather than running it from the disk image. For an installer package, follow the on-screen steps. Before approving any request, make sure you trust the package source.
  3. If macOS blocks the app, read the alert carefully. “Apple cannot check it for malicious software” and “the app is damaged” are different warnings. Verify the file, version, and publisher with the download source. If macOS says the file is damaged or poses a security risk, stop the installation; don't disable system security checks to get around the warning.

If you already have a client with the same name, quit the old copy completely before updating according to the release instructions. After installation, open the new version from Applications so an old Dock shortcut doesn't launch a different copy.

System permissions: when a network extension is needed

A permission prompt may appear the first time you open the app or when you first enable the tunnel. A network extension lets the client connect with macOS; adding a VPN configuration lets the client create a connection profile for the system. Some clients require only one approval, while others request both. If you use system proxy mode only, neither permission may be needed.

System proxy vs. tunnel mode
Mode What it affects How to verify
System proxy Usually affects only apps that follow the system proxy settings. Apps with their own proxy settings may not use the system proxy. Check the proxy settings for your current network service, then make a new request from the app you want to test.
Tunnel mode Routes traffic through a virtual network interface. Which traffic uses the route still depends on routing, split-tunneling rules, and the client. Check the client's connection status, then test an app or domain that should use the route and one that should connect directly.

If macOS says the extension was blocked, follow the client's instructions and search for “Network Extensions” in System Settings. You can also check “Login Items & Extensions” or “Privacy & Security.” The location varies by macOS version and extension type. If prompted to add a VPN configuration, confirm the request came from the client you just opened before allowing it. Work- or school-managed Macs may restrict these changes; contact your device administrator if a management policy blocks them.

Import a subscription and choose a route

  1. Copy the subscription URL for your client from the service dashboard. In the client, look for an option such as “Subscriptions,” “Configuration,” or “Import from URL.” Don't enter the subscription URL in the server address field for a macOS VPN configuration.
  2. After saving, run an update and check that the client lists routes. A subscription URL usually points to an updatable configuration; it isn't the connection details for a single route. If the update succeeds but no routes appear, make sure you selected the imported configuration and that the client supports its format and protocols.
  3. Choose an exit route based on what you need from the route list, then select it in the client. For the first test, keep the route and connection mode fixed. Avoid changing regions, DNS, and routing rules at the same time, or you won't know which change made a difference.

Check your exit IP, routing, and DNS

Before connecting, check your public exit IP in a browser. After connecting, make a new request to an IP-check site that should use the route, then compare the results. With split tunneling enabled, the test site may be routed directly, so an unchanged IP alone doesn't mean the connection is broken. IP geolocation databases can differ, so don't rely on the displayed city alone.

Next, test the app you actually want to use. Close any existing session, then reload the page, restart playback, or make a new connection; an existing long-lived connection may not switch routes. If your browser's exit IP changes but another app still uses its previous route, check the system proxy's coverage first. Then see whether the app has its own proxy setting, or check the client's routing logs to find which rule matched.

An exit IP check doesn't verify DNS. To route DNS queries according to your split-tunneling policy, check the client's DNS settings and whether your browser has Secure DNS enabled. A website test only shows the resolution path used for that test, not every app on your Mac. A DNS resolver in a different location from your exit IP isn't, by itself, evidence of a DNS leak.

Success criteria: New requests that should use the route reach their destination, requests meant to connect directly still work, and your network recovers after disconnecting the client. A “Connected” status in the menu bar is an indicator, not proof that everything works.

Permission issues and connection troubleshooting

  • ❌ Repeated permission prompts every time you enable the tunnel: Make sure you're launching the same client in Applications, then check for an extension or VPN configuration still awaiting approval. If this started after an update, follow the client's instructions to repair its configuration; don't remove system configurations used for other purposes.
  • ❌ Subscription update fails: First determine whether the URL can't be reached, the service returned an error, or the client couldn't parse the response. Check your network, the subscription status in the dashboard, and the import format. Keep any error code, but don't copy full request logs that contain credentials.
  • ❌ Connected, but the app you need doesn't work: Make a new request that should use the route. If your browser works but the app doesn't, check the proxy mode and split-tunneling rules first. If neither works, look in the client logs for route connection or name resolution errors.
  • ✅ Check that your network recovers after disconnecting: Turn off the tunnel or system proxy in the client, then check whether your current network service still points to the local proxy used by the closed client. Undo only settings changed for this setup, and keep your existing work network configuration. If the connection still doesn't recover, note the mode and your last step, then open a support ticket through the contact page.
Start free