The functionality of v2rayA depends on the V2Ray core, so the kernel needs to be installed.

v2rayA and v2ray/xray do not yet support Packet Filter firewall on macOS/FreeBSD, so transparent proxy cannot be enabled. For security, this wiki will run v2rayA with non-root privileges.

It is recommended to install v2ray core by using Homebrew, so v2rayA will automatically use the existing v2ray core on your computer. Without installing the core from brew, you will need to manually specify the path of v2ray core.

Install with Homebrew

Please make sure Homebrew is installed and well working.


Add v2rayA Tap:

brew tap v2raya/v2raya

Install v2rayA:

brew install v2raya/v2raya/v2raya

Start up

After the installation is complete, you can run v2raya --lite command in the terminal, or you can start the service:

brew services start v2raya

Manual installation

Create directory

These directories may already exist, please check before creating them.

Binary directory:

sudo mkdir /usr/local/bin/

Data files directory:

sudo mkdir -p /usr/local/share/v2ray/

Service file directory:

mkdir ~/Library/LaunchAgents/

Download v2rayA

Download the binaries for macOS from GitHub Releases or GitHub Action, then rename to v2raya and save it to /usr/local/bin/ .

For example:


sudo curl -L -o /usr/local/bin/v2raya


sudo curl -L -o /usr/local/bin/v2raya

Download V2Ray Core / Xray Core

Install V2Ray:
Install Xray:

After decompressing the compressed package, move the files in it to the corresponding directory:

sudo mv v2ray /usr/local/bin/
sudo mv v2ctl /usr/local/bin/
sudo mv *dat /usr/local/share/v2ray/

Permission settings

Give v2rayA and v2ray executable permissions:

sudo chmod 755 /usr/local/bin/v2raya
sudo chmod 755 /usr/local/bin/v2ray
sudo chmod 755 /usr/local/bin/v2ctl

If you encounter the security restrictions of macOS, then you need to run the following command:

sudo xattr -d -r  /usr/local/bin/*

Create service files

Create a new service file and save it to ~/Library/LaunchAgents/

For example:

nano ~/Library/LaunchAgents/org.v2raya.v2raya.plist


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">

Start up

launchctl load ~/Library/LaunchAgents/org.v2raya.v2raya.plist

If you want to close the v2rayA service, replace the above command from load to unload . The logs can be viewed through the web pages.

Edit this page on GitHub

Last update on: Oct 05, 2022 08:03 +0800

Contributors: xkicdt mt-gitlocalize I404I