# V2RayXS: a macOS menu bar app that owns the xray config and the launchd lifecycle > V2RayXS is an Objective-C front end for xray-core on macOS that generates the configuration, starts and stops the core under launchd, and switches servers from the menu bar. Its tun mode is the interesting part and the part the author warns about at length. **tzmax/V2RayXS** — GUI for xray-core on macOS - Repository: https://github.com/tzmax/V2RayXS - Website: https://github.com/Cenmrev/V2RayX - Stars: 1,252 · Forks: 102 - Language: Objective-C - License: GPL-3.0 - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/tzmax-v2rayxs ## It generates the config, owns the process, and stays out of the way V2RayXS is a GUI for xray-core on macOS, and the README describes exactly what it takes over. It provides a GUI to generate the configuration file for the core, it includes xray's binary executable inside the app bundle, and it starts and stops that core with `launchd`, the macOS service manager. It also lets users change the system proxy settings and switch proxy servers from the macOS menu bar. The split is what makes it usable. The heavy lifting, the protocol handling, is the xray binary, and the app is a configuration editor and a process supervisor around it. There is no second implementation of anything, which means the app inherits xray's behaviour and its limits exactly. By default the app opens a socks5 proxy at port `1081` as the main inbound, and an http proxy at port `8001` as an inboundDetour. Those two defaults are worth knowing because everything else in the app, including the PAC file it can serve, refers to them. The project is GPL-3.0 licensed, and the repository is explicit about its provenance. It is based on the Cenmrev/V2RayX project, taken over for maintenance and updates, it uses the Xray-core implementation to support the VLESS and XTLS protocols, and the copyright of the application belongs to the original author. The README also states that anyone who wants v2ray-core should install the original project instead. The last push was on 2026-10-07, and the releases v1.6.4, v1.6.3 and v1.6.2 came out on 2026-10-07, 2026-06-02 and 2026-03-26. ## Three steady modes and one experimental one The menu offers three settled modes and a fourth that is labelled differently. Global Mode asks macOS to route all internet traffic to xray core, if the traffic obeys the operating system's network rules. PAC Mode lets macOS decide the routing from a pac file, so some traffic goes through the core and the rest does not. Manual Mode changes no macOS network settings at all: the app only starts and stops the core, and the proxy is used by whatever points at it. Tun Mode is the one marked experimental. It creates a virtual network card and tries to set the default gateway to take over and proxy the full traffic of the device. Options in the menu list under `Routing Rule` determine how the core deals with incoming traffic, and the README says core routing rules apply to all the modes above, so the routing configuration is shared rather than per mode. The practical difference between Manual Mode and the others is worth being explicit about. Manual Mode leaves the system network configuration untouched, which is what you want on a machine where you do not want a proxy to become the default path for every application, and it is the safest of the four. The other three all involve macOS routing state, which is where things can go wrong. For auto-run on login, the README's instruction is to open macOS System Preferences, then Users and Groups, then Login Items, and add V2RayXS.app to the list. That is a manual step, and it is the kind of detail that is often automated in other applications and left to the user here. ## Tun mode rewrites your default gateway, and the author says so twice The tun mode section is the longest in the README, and it is a warning as much as a description. The mechanism is tun2socks. The app creates a utun virtual network card device, transmits the traffic of the tun device to the server through the socks5 proxy, and then the application sets up the routing table and sets the default gateway to this tun device. The author's own caveat is that this step may damage the default gateway routing settings of the device. There is a backup and repair process in the application, but the README says it cannot be guaranteed to be effective on all devices, and asks you to use it with caution. The function is described as experimental and still under development and design, and the README asks you to read that part of the document before using it. It also asks you to understand what a transparent proxy is before you start, and to try PAC mode and global mode first if they meet your needs. It then lists two prerequisites: an understanding of transparent proxying, and enough networking knowledge to solve your own network problems. The troubleshooting section answers the question that follows from the warning. If the device is disconnected from the network after using tun mode, the likely cause is a broken default gateway route, and you can check the routing table with the `netstat -r` command, where a normal table shows a `default` route: ```shell $ netstat -r Routing tables Internet: Destination Gateway Flags Netif Expire default 192.168.1.1 UGScg en0 ``` The recovery is to set the default gateway yourself after turning tun mode off: ```shell sudo /sbin/route add -net default 192.168.1.1 ``` The last piece of orientation is how to recognise the device if you need to. The tun device name is chosen by the system, but the one V2RayXS creates is bound to the `10.0.0.0` network segment by default, which is the reference to look for. ## The PAC file is a template, and the app fills in the ports The PAC mode has a small feature that solves a real annoyance. V2RayXS serves a pac file from `http://127.0.0.1:8070/proxy.pac` and supports placeholder replacement when it does. There are two placeholders. `${V2RAYXS_SOCKS}` is replaced with the current local SOCKS proxy port, and `${V2RAYXS_HTTP}` with the current local HTTP proxy port. The example given is a proxy declaration like this: ```javascript var V2Ray = "SOCKS5 127.0.0.1:${V2RAYXS_SOCKS}; SOCKS 127.0.0.1:${V2RAYXS_SOCKS}; DIRECT;"; ``` The design detail is that the PAC file stored on disk stays a template. The substitution happens only when the PAC content is served by the built-in HTTP server, so changing the local ports does not require editing the PAC file by hand. That matters when the app is on a non-default port, which is exactly when a hand written PAC file breaks silently: the browser follows a rule pointing at a port nothing is listening on, and the failure looks like a network problem rather than a configuration problem. The built-in server on port 8070 is therefore part of the design, not a debug convenience, and it is another reason the tun mode is not the only thing that can leave the app listening on a local port. ## Building from source and swapping the core binary by hand The README gives two ways to build the app, and one of them is a single command. The one-liner installs the command line tool with curl: ```shell sh -c "$(curl -fsSL https://raw.githubusercontent.com/tzmax/V2RayXS/master/compilefromsource.sh)" ``` The step by step route is a recursive clone, because the project has submodules, and then building the Xcode project: ```shell git clone --recursive https://github.com/tzmax/V2RayXS.git ``` You then open V2RayXS.xcodeproj and build V2RayXS with Xcode. The repository layout explains the pieces. There is a `V2RayXS.xcodeproj/` directory for the Xcode project, a `V2RayX/` directory that holds the application sources, `Librarys/` for the bundled libraries, a `GCDWebServer` directory for the built-in HTTP server that serves the PAC file, a `v2rayx_sysconf/` directory for the system configuration handling, a `jsonplist/` directory for property list handling, and the scripts `build.sh`, `compilefromsource.sh`, `prepare_zip.sh` and `update_pac.sh`. The manual core update is a documented but blunt operation. The README says to replace `V2RayXS.app/Contents/Resources/v2ray` with the newest xray version from the xray-core releases, and immediately adds that compatibility is not guaranteed. That is the honest form of the instruction: you can do it, it is how you get a newer core than the bundled one, and nobody is promising the app will still drive it correctly. ## Where V2RayXS is the wrong tool The first wrong case is anything that is not macOS. This is an Objective-C application built as an Xcode project for one platform, with a menu bar integration and launchd lifecycle. There is no Linux or Windows build described, and no route to one without porting it. The second is a v2ray-core user. The README says so directly and twice, including in the attention block at the top: install the original project. V2RayXS is built on the Xray-core implementation, and the protocols and configuration surface of v2ray-core are not the same. The third is a machine where you cannot recover the network yourself. The tun mode can leave the device without a working default gateway, and the recovery is a `sudo /sbin/route add` command from a terminal. On a locked-down or remote machine without physical access, that failure mode is not a warning to read but an outage. The fourth is a setup that needs a verifiable core version. The bundled xray binary can be replaced manually, but the README says compatibility is not guaranteed, and there is no version check or integrity step described for that swap. For a configuration that matters, running a known core version with a known configuration is safer than a manual file replacement. The fifth is a requirement for the newest protocol work. The application is a front end, so protocol features added upstream appear only when the maintainer updates the bundled binary. The project itself says to read the XTLS official instructions before using V2RayXS, which is a pointer to the core documentation for exactly this reason. ## Conclusion Adopt V2RayXS if you run xray-core on macOS and want a menu bar app that generates the configuration, manages the core process and switches servers without editing JSON by hand. Do not adopt it if you need v2ray-core, since the README points those users to the original project, or if you need tun mode to be dependable, because the author calls it experimental and warns that it rewrites the default gateway. Before you enable tun mode, note that recovery means running `netstat -r` and `sudo /sbin/route add -net default ` from a terminal, and check that the built-in xray binary still matches the configuration the app generates. ## FAQ ### What does V2RayXS do on macOS? It provides a GUI to generate the configuration file for the core, includes xray's binary executable in the app bundle, starts and stops the core with launchd, and lets you change system proxy settings and switch servers from the menu bar. ### What are the proxy modes in V2RayXS? Global Mode routes all internet traffic to the core, PAC Mode lets macOS decide routing from a pac file, Manual Mode changes no macOS network settings and only starts or stops the core, and Tun Mode creates a virtual network card and tries to set the default gateway to proxy all traffic, which is marked experimental. ### How do I recover the network after using tun mode? The README says the default gateway route is probably broken, and to check it with `netstat -r` from the device terminal. To fix it, set the default gateway with `sudo /sbin/route add -net default 192.168.1.1` after turning tun mode off, using your own gateway address. ### Can I update the xray-core binary that V2RayXS ships with? The README says to replace `V2RayXS.app/Contents/Resources/v2ray` with the newest xray version from the xray-core releases, and warns that compatibility is not guaranteed. ## Sources - [License: GPL-3.0](https://github.com/tzmax/V2RayXS/blob/master/LICENSE) - [Project website](https://github.com/Cenmrev/V2RayX) - [README](https://github.com/tzmax/V2RayXS/blob/master/README.md) - [Releases](https://github.com/tzmax/V2RayXS/releases) - [tzmax/V2RayXS on GitHub](https://github.com/tzmax/V2RayXS) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tzmax-v2rayxs