v2rayN for macOS: Installation, Unverified Developer Warning & Network Permissions

At a glance

For anyone installing v2rayN on a Mac for the first time or troubleshooting startup and network issues after replacing the app. Choose the right build for your chip, then address any Gatekeeper block. Once the app opens, check that the core is listening, then verify the system proxy and TUN permissions separately. A system proxy is not a virtual network interface, and a network extension prompt won’t appear with every installation. Troubleshoot the affected layer instead of granting every permission at once.

1. Choose the right build and install it in Applications

Open Apple menu → About This Mac. If it shows an Apple chip, choose the Apple Silicon build; if it shows an Intel processor, choose the Intel build. An incompatible build may fail to launch, prompt you to install an additional compatibility environment, or open while its bundled core fails to run. Don’t assume every startup issue is caused by developer verification.

Check your chip

Open Apple menu → About This Mac and note your chip type. Choose the matching build in the macOS section of the client download page.
Extract the download

For an archive, extract it and locate the app. For a disk image, open it and copy the app inside. Don’t drag the archive itself, and don’t run the app long-term from a temporary preview folder.
Move it to Applications

In Finder, choose Go → Applications, then drag v2rayN into the folder. When upgrading, quit the old process before replacing the app, and keep a backup of your existing configuration.
Open it for the first time

Launch the app from Applications. If macOS blocks it, read the full warning, then follow the next section to allow it under Privacy & Security. Don’t keep extracting extra copies and trying them one by one.
Check that the core is running

Once the main window opens, import your configuration, select a node, and check the logs. A working interface doesn’t mean the proxy core has started. First check for a port conflict or configuration parsing error.

This guide uses v2rayN.app as the app name. Actual filenames, menu labels, and feature locations can vary by client build; make sure any app path in a command matches the name shown in Finder. The system paths refer to the System Settings interface used in macOS 13 and later. This does not indicate the client’s minimum system requirement.

2. “Unable to verify developer”: Allow the app through Gatekeeper

“Unable to verify developer” and “Apple cannot check it for malicious software” are security warnings shown before an app runs. They’re unrelated to subscription URLs or VMess and VLESS settings. Before allowing the app, confirm that the download is from the expected source and that you’re opening the copy in Applications.

Try opening the app once. Note the warning, then close it.
Go to Apple menu → System Settings → Privacy & Security, then scroll down to the Security section.
If you see a block notice for the app, verify its name and click Open Anyway. This button is usually available only for a limited time after the most recent block.
Authenticate with your password or Touch ID if prompted. If macOS asks again, verify the app and choose Open.

On some macOS versions, you can Control-click the app in Finder and choose Open. Newer versions may still require confirmation under Privacy & Security. If your Mac is managed by an organization, its policies may prevent you from clicking Open Anyway. Contact your administrator rather than changing system policies.

To review the app’s quarantine status, you can run this read-only command in Terminal (Applications → Utilities → Terminal). The com.apple.quarantine attribute indicates that the file has a download quarantine flag; it doesn’t by itself prove the file is safe or harmful. The result is not a complete audit of the program’s behavior.

xattr -l "/Applications/v2rayN.app"
spctl --assess --type execute --verbose "/Applications/v2rayN.app"

3. System proxy or TUN: choose how to route traffic

Once v2rayN opens, start with the system proxy for basic testing. It points the active network service’s proxy settings to a local listening port, for apps that respect the system proxy. It won’t automatically route traffic from every process or handle all UDP traffic. TUN uses a virtual network interface and routing, with different permissions and failure points.

System proxy

Recommended

Start with this mode when installing for the first time. After importing a node, choose System Proxy → Set system proxy in v2rayN, then check the proxy address in macOS. Menu locations vary by build, so use the options shown in your client.

Best for: browsing, initial connection checks, and troubleshooting one layer at a time.

TUN mode

Use this when traffic needs to be routed at the network layer. Support depends on the macOS client build, the core in use, and any required components. It may need elevated privileges, an auxiliary component, or approval for a network extension. The presence of a TUN toggle alone doesn’t tell you how it’s implemented.

Best for: apps that ignore system proxy settings, when your build explicitly supports TUN.

Start with TUN off and use only one routing method at a time. After the system proxy works, test TUN if needed. Enabling both adds complexity when troubleshooting routes, DNS, and loopback traffic, and makes it harder to tell which path a connection is taking.

4. Match local listeners to macOS proxy settings

This guide uses 10808 as an example proxy inbound port and 10809 as an alternate. These aren’t asserted as the default ports for every version. In v2rayN, open Settings → Parameter Settings and check the local listener options. Use the saved configuration and current startup logs as the source of truth. If you change a port, update the system proxy to match.

10808

Example proxy inbound port

10809

Alternate example for a port conflict

127.0.0.1

Local IPv4 loopback address

Go to System Settings → Network → your active Wi-Fi or Ethernet service → Details → Proxies. HTTP, HTTPS, and SOCKS are separate options; check which protocol the core’s inbound accepts before entering values. Point both HTTP and SOCKS traffic to the same port only if the inbound explicitly supports both.

Example: HTTP system proxy

Server: 127.0.0.1
Port: 10808
Network options: Web Proxy (HTTP), Secure Web Proxy (HTTPS)
Inbound requirement: Local inbound that supports HTTP

Secure Web Proxy uses a proxy connection for HTTPS requests; it doesn’t mean the local proxy itself must use TLS.

Example: SOCKS app proxy

Server: 127.0.0.1
Port: 10808
Protocol: SOCKS5
Inbound requirement: Local inbound that supports SOCKS

Use this only if the inbound supports SOCKS. Check app-level manual proxy settings separately from the system proxy.

Use these read-only Terminal checks to inspect the listener and current system proxy. If the first command returns nothing, check whether the core is running or using a different port. A listener only confirms that a process has bound the port; it doesn’t prove the remote node works. The proxy address shown by the second command should match the client’s local inbound.

lsof -nP -iTCP:10808 -sTCP:LISTEN
scutil --proxy

5. Network permissions: approve only what you need

System proxy, network extensions, local network access, and the inbound firewall are separate layers. Enabling the system proxy doesn’t necessarily trigger a network extension approval. A local network prompt also doesn’t mean a proxy to a public server needs LAN access. Approve only permissions required for your current setup, and check which app or component is requesting them.

Scenario	Where to check	What to do
System proxy settings aren’t applied	System Settings → Network → active network service → Details → Proxies	Check the server and port first, then look for a write error in the client logs or a management policy that blocks changes.
TUN asks to install an auxiliary component	The client prompt and its corresponding system authentication dialog	Verify the component’s source before approving it. An auxiliary process and a network extension are different implementations.
macOS says a system extension was blocked	Follow the prompt to Privacy & Security. On newer systems, look under General → Login Items & Extensions → Network Extensions.	Only act if the relevant extension is actually installed. Enable it as prompted by macOS and restart the app if needed.
Local network access is restricted	On systems that support this setting, go to Privacy & Security → Local Network	This setting is for accessing devices on the same network. A failed approval doesn’t by itself indicate a problem with a remote node.
Other devices can’t connect to this Mac	Network → Firewall → Options; also check the listening address	Using a loopback address on this Mac is different from sharing access over the LAN. You don’t need to turn off the firewall for a local proxy.

If macOS doesn’t show a network extension approval and the client logs indicate a different TUN implementation, don’t keep reinstalling to look for a toggle that isn’t there. Check the logs to find the failure stage: interface creation, permission request, route setup, or DNS. If the system proxy works, keep using it while troubleshooting TUN separately.

6. Permissions and stale proxy settings after an upgrade

Replacing the app can change its executable, signature status, or auxiliary components, prompting macOS to ask for permissions again. But a lost permission isn’t the only reason your connection may fail after an upgrade. An old process holding a port, a new core that can’t read the configuration, a change in network service, or system proxy settings left behind after quitting can all look similar.

Before replacing the app: Back up your configuration, clear the system proxy and turn off TUN in the client, then quit the app. If needed, use Activity Monitor to confirm the old process has exited.
After replacing the app: Launch only the new copy from Applications. If macOS shows a developer verification warning again, follow the steps above. Don’t run an older copy from your Downloads folder at the same time.
Check permissions: Review the relevant extension or auxiliary component only if macOS explicitly asks you to approve it again. Disabling and re-enabling every permission isn’t a standard upgrade step.
Check the port: Find the listening address in the logs and compare it with the output of scutil --proxy. If the ports don’t match, reapply the system proxy in the client.
Restore a direct connection: If the app can’t run, open Proxies for your active network service, turn off the options you enabled for the local proxy, and apply the changes. Ask your administrator before changing managed proxy settings.

7. Common installation and Gatekeeper questions

Why can’t I find Open Anyway?

Try launching the intended copy from Applications again, then go straight to the Security section under Privacy & Security. Make sure the warning isn’t about an incompatible architecture or a damaged file. On a managed Mac, your organization may block users from allowing apps; ask your administrator to check the policy.

The app opens, but my browser still can’t connect. What should I check?

Turn off TUN first, then use lsof to check whether the actual port is listening. Next, check HTTP and Secure Web Proxy for the active network service. Once the listener is active and the addresses match, check node authentication, the server address, routing rules, and DNS. An open app window doesn’t mean the core is working.

Will TUN ask for my password every time?

Whether macOS asks you to authenticate again depends on how your build starts its privileged component; it doesn’t necessarily mean the installation failed. Check which action triggered the authentication dialog. If approval keeps failing, look for permission or interface errors in the logs and temporarily switch to the system proxy. Don’t run the entire client as an administrator just to avoid authentication prompts.

My network stops working after I quit v2rayN. How do I fix it?

Go to System Settings → Network → your active network service → Details → Proxies and check whether a proxy still points to a 127.0.0.1 port that’s no longer listening. Turn off the local proxy options you enabled and apply the changes. Once the connection is back, relaunch the client and set up the proxy again.