{"id":15107205,"url":"https://github.com/tzmax/v2rayxs","last_synced_at":"2025-05-14T20:02:15.469Z","repository":{"id":42110585,"uuid":"466259529","full_name":"tzmax/V2RayXS","owner":"tzmax","description":"GUI for xray-core on macOS","archived":false,"fork":false,"pushed_at":"2025-02-18T12:19:46.000Z","size":32581,"stargazers_count":1085,"open_issues_count":35,"forks_count":90,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-06T17:01:42.782Z","etag":null,"topics":["macos","objective-c","proxy","shadowsocks","v2ray","v2rayx","v2rayxs","vpn","xray","xray-core"],"latest_commit_sha":null,"homepage":"https://github.com/Cenmrev/V2RayX","language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tzmax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-04T20:19:55.000Z","updated_at":"2025-04-06T11:02:05.000Z","dependencies_parsed_at":"2023-11-23T17:28:19.014Z","dependency_job_id":"a75052d1-66d5-4145-b7c7-09396c1f212f","html_url":"https://github.com/tzmax/V2RayXS","commit_stats":null,"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tzmax%2FV2RayXS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tzmax%2FV2RayXS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tzmax%2FV2RayXS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tzmax%2FV2RayXS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tzmax","download_url":"https://codeload.github.com/tzmax/V2RayXS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248766683,"owners_count":21158302,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["macos","objective-c","proxy","shadowsocks","v2ray","v2rayx","v2rayxs","vpn","xray","xray-core"],"created_at":"2024-09-25T21:21:03.644Z","updated_at":"2025-04-13T19:19:30.398Z","avatar_url":"https://github.com/tzmax.png","language":"Objective-C","readme":"# V2RayXS: A simple GUI for Xray on macOS\n\n[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/tzmax/V2RayXS)](https://github.com/tzmax/V2RayXS/releases)\n![GitHub release (latest by date)](https://img.shields.io/github/downloads/tzmax/V2RayXS/latest/total)\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/tzmax/V2RayXS/build-actions.yml)](https://github.com/tzmax/V2RayXS/actions/workflows/build-actions.yml)\n\n**Attention**: If you want to use v2ray-core version please install the original project. \u003chttps://github.com/Cenmrev/V2RayX\u003e\n\n\u003e This repo is based on the [Cenmrev/V2RayX](https://github.com/Cenmrev/V2RayX) project for maintenance and update, uses the [Xray-core](https://github.com/XTLS/Xray-core) implementation to support the VLESS and XTLS protocol, and the copyright of the application belongs to the original author [@Contents](https://github.com/Cenmrev). Pay tribute to [@Contents](https://github.com/Cenmrev), Thanks to the [@XTLS](https://github.com/XTLS) community and all contributors\n\n## What is XTLS? Xray?\n\n**READ THIS**: [XTLS? Xray? V2Ray?](https://xtls.github.io).\n\n**YOU SHOULD READ XTLS'S OFFICIAL INSTRUCTION BEFORE USING V2RAYXS!**\n\n## What is Tun Mode? (Experimental)\n\n**Warn**: You must read this part of the document before using tun mode.\n\nFirst of all, please note that this function is an experimental function and is still under development and design. Due to the particularity of the tun mode, I hope you can use it after fully understanding it.\n\nThis mode adopts the tun2socks method to forward all traffic, realizes the creation of a utun virtual network card device, and transmits the traffic of the tun device to your server through the socks5 proxy, and then the application sets up the routing table, and sets the default gateway to this tun device (please Note that this step may cause the default gateway routing settings of your device to be damaged. Although I have done a backup and repair process in the application, I cannot guarantee that it will be effective on all devices, please use it with caution!)\n\nFinally, if you are interested in this technology, you can also try to contact me or submit a PR to help me improve this function. If you can recommend this software to friends or post a blog and be able to link this project in other post replies, I will Very happy 😋, thank you for your attention and contribution (Welcome to contribute documents in other languages)\n\n1. Please understand what transparent proxy is (recommended reference this page [What is a transparent proxy?](https://xtls.github.io/Xray-docs-next/document/level-2/transparent_proxy/transparent_proxy.html)), if PAC mode and global mode can meet your needs, please try to use it.\n\n2. You have a certain understanding of the computer network and can solve the network problem of your device independently.\n\n### Have you encountered a problem?\n\nQ: After using tun mode, the device is disconnected from the network? \n\nA: It may be that the route of the default gateway is broken. You can check your routing table by executing the `netstat -r` command through the device terminal. Normally, there will be a `default` route, as follows\n\n```\ntzmaxdeMacBookPro: tzmax$ netstat -r\nRouting tables\n\nInternet:\nDestination        Gateway            Flags           Netif Expire\ndefault            192.168.1.1        UGScg             en0       \n127                localhost          UCS               lo0       \nlocalhost          localhost          UH                lo0    \n………\n```\n\nQ: How to fix you gateway? (if you can't access the Internet after turning off tun mode after using tun mode, you can try to fix it like this. If it still doesn't work, you can try to restart your device)\n\nA: If you know your default gateway, after turning off tun mode, you can set the default gateway through the `/sbin/route add -net` command\n\nfor example: `sudo /sbin/route add -net default 192.168.1.1`\n\nQ: Which tun device does the V2RayXS create?\n\nA: The name of the tun device on macos will be determined by the system, but the tun device created by V2RayXS will be bound to the `10.0.0.0` network segment by default, which can be used as a reference to find\n\nfor more questions, you can also check issues first, and submit issues if you do not find a solution.\n\n## Download V2RayXS\n\nDownload from [Releases](https://github.com/tzmax/V2RayXS/releases).\n\n## How to build\n\nV2RayXS.app is built by running one of the following commands in your terminal. You can install this via the command-line with curl.\n\n`sh -c \"$(curl -fsSL https://raw.githubusercontent.com/tzmax/V2RayXS/master/compilefromsource.sh)\"`\n\nor step by step:\n\n`git clone --recursive https://github.com/tzmax/V2RayXS.git`\n\nopen V2RayXS.xcodeproj and use Xcode to build V2RayXS.\n\n## How does V2RayXS work\n\nV2RayXS provides a GUI to generate the config file for V2Ray. It includes Xray's binary executable in the app bundle. V2RayXS starts and stops V2Ray with `launchd` of macOS.\n\nV2RayXS also allows users to change system proxy settings and switch proxy servers on the macOS menu bar.\n\nAs default, V2RayXS will open a socks5 proxy at port `1081` as the main inbound, as well as a http proxy at port `8001` as an inboundDetour.\n\nV2RayXS provide three modes:\n\n-   Global Mode: V2RayXS asks macOS to route all internet traffic to xray core if the network traffic obeys operating system's network rules.\n-   PAC Mode: macOS will determine the routing based on a pac file and some traffic may be routed to xray core.\n-   Manual Mode: V2RayXS will not modify any macOS network settings, but only start or stop xray core.\n-   Tun Mode (**Experimental**): V2RayXS will create a virtual network card, and then try to set the default gateway to take over and proxy the full traffic of the device.\n\n\nOptions in menu list `Routing Rule` determine how xray core deals with incoming traffic. Core routing rules apply to all three modes above.\n\n### auto-run on login\n\nOpen macOS System Preferences -\u003e Users \u0026 Group -\u003e Login Items, add V2RayXS.app to\nthe list.\n\n### manually update xray-core\n\nreplace `V2RayXS.app/Contents/Resources/v2ray` with the newest xray\nversion from [xray-core\nrepo](https://github.com/XTLS/Xray-core/releases). However, compatibility is not guaranteed.\n\n\u003e If you want to use v2ray-core version please install the original project. \u003chttps://github.com/Cenmrev/V2RayX\u003e\n\n### Uninstall\n\nV2RayXS will create the following files and folders:\n\n-   `/Library/Application Support/V2RayXS`\n-   `~/Library/Application Support/V2RayXS`\n-   `~/Library/Preferences/cenmrev.V2RayXS.plist`\n\nSo, to totally uninstall V2RayXS, just delete V2RayXS.app and the files above. :)\n\n## Other protocols supported\n\nThanks to the excellent implementation of [Xray core](https://github.com/XTLS/Xray-core), the client supports multiple protocols such as Shadowsocks, Socks, Trojan, Wireguard as outbounds protocols.\n\nFirst of all, I would like to explain here why the current GUI configuration only supports `VMess` and `VLESS` configuration for the time being, because the workload of adapting all outbounds is not small, and each protocol is constantly updated. Due to the current layout of hard-coding implementation, the GUI configuration page requires the cost of updating and maintaining the software for each protocol update is very high (if anyone is willing to adapt, I am willing to review it). The benefits of this is not as good as having a setting function that can directly configure the json configuration of outbounds, so I think that's what [@Cenmrev](https://github.com/Cenmrev) thought when he designed the `Advanced / Outbounds` function.\n\nBecause more people have asked before issues [#18](https://github.com/tzmax/V2RayXS/issues/18) [#34](https://github.com/tzmax/V2RayXS/issues/34) [#52](https://github.com/tzmax/V2RayXS/issues/52) (including recent friends also asking how to use `Trojan` with V2RayXS?), so I took time to write this explanation.\n\nNext, I will try to introduce how to import `Trojan` outbounds in V2RayXS and make them work (I will use the oral method. If anyone is willing to write a GUI screenshot operation blog or related documents, I would be happy to merge or link here).\n\n1. You need to know what the **subscription address is**, what the **URL sharing link** is, and what the **JSON configuration** file is. If it is a subscription address or URL sharing link, you need to convert it to a **JSON configuration** file first (if you don't know how to convert, please use the client of other platforms to import and then select the specified node before exporting the JSON configuration file).\n\n2. After obtaining the complete JSON configuration file, the general configuration file content is as follows (the following configuration example comes from [Xray-examples/Trojan-TCP-XTLS](https://github.com/XTLS/Xray-examples/blob/main/Trojan-TCP-XTLS/config_client.json), and the content of the configuration files of different protocols may vary greatly)\n\n```json\n{\n    \"log\": {\n        \"loglevel\": \"debug\"\n    },\n    \"inbounds\": [\n        {\n            \"port\": 1080,\n            \"listen\": \"127.0.0.1\",\n            \"protocol\": \"socks\",\n            \"settings\": {\n                \"udp\": true\n            }\n        },\n        {\n            \"port\": 1081,\n            \"protocol\": \"http\",\n            \"sniffing\": {\n              \"enabled\": true,\n              \"destOverride\": [\"http\", \"tls\"]\n            },\n            \"settings\": {\n              \"auth\": \"noauth\"\n            }\n        }\n    ],\n    \"outbounds\": [\n        {\n            \"protocol\": \"trojan\",\n            \"settings\": {\n                \"servers\": [\n                    {\n                        \"address\": \"example.com\",  // your domain name or server IP\n                        \"flow\": \"xtls-rprx-direct\",  // Linux or android can be changed to \"xtls-rprx-splice\"\n                        \"port\": 443,\n                        \"password\": \"your_password\"  // your password\n                    }\n                ]\n            },\n            \"streamSettings\": {\n                \"network\": \"tcp\",\n                \"security\": \"xtls\",\n                \"xtlsSettings\": {\n                    \"serverName\": \"example.com\"  // your domain name\n                }\n            }\n        }\n    ]\n}\n```\n\n3. Take out the `outbounds` part of the field. If there are more than one, please choose the most suitable one (I will delete the comment information in the example, because this is an irregular JSON format), and finally get the following JSON configuration information.\n\n```json\n{\n    \"protocol\": \"trojan\",\n    \"settings\": {\n        \"servers\": [\n            {\n                \"address\": \"example.com\",\n                \"flow\": \"xtls-rprx-direct\",\n                \"port\": 443,\n                \"password\": \"your_password\"\n            }\n        ]\n    },\n    \"streamSettings\": {\n        \"network\": \"tcp\",\n        \"security\": \"xtls\",\n        \"xtlsSettings\": {\n            \"serverName\": \"example.com\"\n        }\n    }\n}\n```\n\n4. Add the `tag` field to the configuration data. **TAG** is used to identify the server configuration, which can help you find it in the server list.\n\n```json\n{\n    \"tag\" : \"⭐️ MyTrojanNode\",\n    \"protocol\": \"trojan\",\n    \"settings\": {\n        \"servers\": [\n            {\n                \"address\": \"example.com\",\n                \"flow\": \"xtls-rprx-direct\",\n                \"port\": 443,\n                \"password\": \"your_password\"\n            }\n        ]\n    },\n    \"streamSettings\": {\n        \"network\": \"tcp\",\n        \"security\": \"xtls\",\n        \"xtlsSettings\": {\n            \"serverName\": \"example.com\"\n        }\n    }\n}\n```\n\n5. Open `Configure` -\u003e `Advanced` -\u003e `Outbounds`, click Add to replace the input box with the **JSON configuration data** above, then click `Finish` to complete the addition, and click 'OK` on the configuration page to save the data.\n\n6. Open the V2RayXS menu bar and select `Server`. Now you should be able to see the `⭐️ MyTrojanNode` server. Select it and use it to take you where you want to go.\n\nOf course, you can also use it to control your `VMess` and `VLESS` configuration in more detail (**note: the configuration here will not appear in the Config configuration panel, but will only appear in the Server list**). For more protocol configurations, please refer to the following link.\n\n- [Shadowsocks](https://xtls.github.io/en/config/outbounds/shadowsocks.html) \n- [Socks](https://xtls.github.io/en/config/outbounds/socks.html)\n- [Trojan](https://xtls.github.io/en/config/outbounds/trojan.html)\n- [VLESS](https://xtls.github.io/en/config/outbounds/vless.html)\n- [VMess](https://xtls.github.io/en/config/outbounds/vmess.html)\n- [Wireguard](https://xtls.github.io/en/config/outbounds/wireguard.html)\n- And others that are supported by `Xray core`\n\n## Acknowledge\n\nThis repo is based on the [Cenmrev/V2RayX](https://github.com/Cenmrev/V2RayX) project for maintenance and update.\n\nV2RayXS uses [GCDWebServer](https://github.com/swisspol/GCDWebServer) to provide a local pac server. V2RayXS also uses many ideas and codes from [ShadowsocksX](https://github.com/shadowsocks/shadowsocks-iOS/tree/master), especially, the codes of [v2rays_sysconfig](https://github.com/tzmax/V2RayXS/blob/master/v2rayx_sysconf/main.m) are simply copied from [shadowsocks_sysconf](https://github.com/shadowsocks/shadowsocks-iOS/blob/master/shadowsocks_sysconf/main.m) with some modifications.\n\n## Donation\n\nIf Project V2Ray or V2RayX (V2RayXS) helped you, you can also help us by donation **in your will**. \n\nTo donate to Project V2Ray, you may refer to [this page](https://www.v2ray.com/chapter_00/02_donate.html).\n\nTo donate to Project Xray, you may refer to [this page](https://xtls.github.io/#%E5%B8%AE%E5%8A%A9-xray-%E5%8F%98%E5%BE%97%E6%9B%B4%E5%BC%BA).\n\n## Disclaimer\n\nV2rayXS will not be updated frequently. Users can replace V2RayXS.app/Contents/Resources/xray with the newest Xray-core downloaded from \u003chttps://github.com/XTLS/Xray-core/releases\u003e.\n\nThe developer currently does not have enough time to add more features to V2RayXS. However, welcome to the contribution at any time, and the fork and your own version.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftzmax%2Fv2rayxs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftzmax%2Fv2rayxs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftzmax%2Fv2rayxs/lists"}