For macOS users installing v2rayN for the first time or troubleshooting launch blocks and proxy issues after an update. Check the app’s source and CPU architecture first, then allow the individual app if macOS offers that option. Once it opens, test the system proxy, local network access, and TUN separately rather than treating them as one permission issue.
Identify Gatekeeper warnings and app architecture
Code signing verifies the signing identity and confirms that signed code has not changed. Notarization is Apple’s automated security review for submitted software. Gatekeeper evaluates downloaded apps according to macOS security policies. If you see “Apple cannot verify the developer” or “Apple cannot check it for malicious software,” the alert alone does not prove the app is safe or unsafe, and not every launch failure is caused by missing notarization.
- Architecture: Open the Apple menu → About This Mac. If it shows Apple silicon, choose ARM64; if it shows an Intel processor, choose x64. An architecture mismatch is separate from signature verification. Changing security settings cannot make an incompatible build run natively.
- Source: Check the download source, release version, and file name. Don’t open files from unfamiliar mirrors, chat attachments, or repackaged downloads just because their names and icons look familiar.
- Warning type: If macOS explicitly reports malware or says the app is damaged, do not open it. Verify the source and download a fresh copy. On a managed Mac, ask your administrator about your organization’s app policies.
Allow an individual app in Privacy & Security
These steps apply to macOS versions with System Settings. Proceed only if you trust the source and macOS offers an exception for this app. You don’t need to disable Gatekeeper or change system-wide security policies.
Move the app to Applications
For a disk image, open it and drag v2rayN to Applications as instructed. For an archive, extract it first, then move the app inside. Launch it from Applications in Finder to avoid opening an outdated copy in Downloads.
Trigger the launch check
Double-click the newly installed v2rayN. If a verification alert appears, close it and note the app name. If there’s no alert and the main window opens, skip the rest of this section.
Find the security alert
Open the Apple menu → System Settings → Privacy & Security, then scroll down to Security. Check that v2rayN is listed among recently blocked apps, then click Open Anyway. This option is usually available for about an hour after you try to launch the app.
Confirm that you want to open it
Follow the system dialog to authenticate and confirm. This exception applies only to the selected app; it does not grant network permissions. If the alert returns after an update or replacement, verify the new app’s source and version first.
Test the system proxy and TUN separately
Opening the main window confirms only that the app launched. It doesn’t confirm that the core is listening or that browser traffic is being proxied. For your first test, enable only one connection method. If both are enabled, restored browser access won’t tell you which setting worked.
How to check each connection method
System proxy: test with a browser first
- Turn off TUN and select a node. In v2rayN, open System Proxy and choose Automatically Configure System Proxy. If macOS asks you to authenticate for this change, make sure the request matches the action you just took, then follow the prompt.
- Go to System Settings → Network → your current service (such as Wi-Fi) → Details → Proxies and check which options are enabled. Confirm that the address and port match v2rayN’s local listener. If you switch to Ethernet, check the active service again.
TUN: test the virtual network interface next
- Clear the system proxy first, then enable TUN mode in v2rayN. Follow the actual prompts for administrator authentication, adding a VPN configuration, or allowing a network extension. These are separate permissions, and not every implementation uses a network extension.
- On macOS 15, if you’re specifically told that a network extension is disabled, go to System Settings → General → Login Items & Extensions → Network Extensions, open its details, and enable the relevant item. If macOS instead asks to add a VPN configuration, verify the name in the confirmation dialog, then check its status under System Settings → VPN.
A matching port on the proxy page and in the client confirms only that both settings point to the same local endpoint. Check the core logs and make a real request to verify the node connection.
Changing the system proxy doesn’t always trigger an authorization prompt, and there’s no persistent permission switch that applies to every macOS version. If the proxy page doesn’t change, make sure v2rayN isn’t set to “Do not change system proxy,” then check its logs for permission errors. If other software or a managed policy controls the proxy, record the current settings before making changes.
Local network access depends on what you’re connecting to
In macOS 15, the Local Network permission controls whether an app can access devices on your LAN. A browser connecting to the local loopback address 127.0.0.1 is a different connection from v2rayN or its core connecting to another LAN host. If you’re using a public node and pointing your browser to a loopback port, don’t enable Local Network access just because a webpage won’t load.
Public node with a loopback listener
RecommendedKeep the proxy listener on your Mac. Test the connection with a browser that honors the system proxy. If you entered the example port 10808 but the logs show a different listening port, update the client or proxy settings.
Best for: first-time setup and proxying apps on this Mac
Connecting to a LAN node
If the node is actually on the same LAN—for example, at 192.168.1.20—go to System Settings → Privacy & Security → Local Network and check the switch for the relevant app. If it isn’t listed, try connecting to the device and see whether macOS prompts for access. Use the requester shown by macOS to identify the app; don’t allow unknown entries in bulk.
Best for: a node or target service hosted on your LAN
What to check if you still can’t connect
- Check the local listener. In Terminal, run
lsof -nP -iTCP:10808 -sTCP:LISTEN, replacing the port with the one currently configured in the client. If there’s a result, verify the process name. If there isn’t, check the v2rayN logs to see whether the core started or failed to bind the port. A listening port doesn’t prove the remote handshake succeeded. - Check the node handshake. Select a node, send a request, and check the core logs from that time. For a connection timeout, verify the node address and port. For a handshake error, check the transport and security settings required by the server. Don’t rely on the node name to infer its configuration, and don’t disable certificate verification to hide an error.
- Check the app and routing. If the browser works but one app doesn’t, check whether that app uses the system proxy. If only TUN mode fails, turn off other VPNs and check for routing or DNS conflicts. If only a LAN service fails, review the routing rules, Local Network permission, and whether the target device is online.
- Restore your network settings. When troubleshooting is complete, turn off TUN first, then clear the system proxy in v2rayN. Recheck the Proxies page for your current network service. If your device uses a work or manual proxy, restore the settings you recorded instead of disabling everything.