mack-a/v2ray-agent: an eight-protocol install script for Xray-core and sing-box

What v2ray-agent actually installs on a VPS

The repository describes itself as an eight-in-one script for Xray, Tuic, hysteria2 and sing-box. In practice it is a provisioning layer: you run it on a fresh server, it installs a proxy core, writes configuration, obtains a TLS certificate and prints connection details. The protocols listed in the README are VLESS, VMess, Trojan, Hysteria2, Tuic and NaiveProxy, with Xray-core and sing-box as the two selectable cores.

The audience is narrow and specific. You need root on a Linux VPS, a domain name you control, and enough patience to point that domain at the server before the script runs. It is not a consumer VPN client and it does not provide servers. Everything it does assumes you already have the machine. That constraint is what makes the rest of the design coherent: because it owns the server, it can install Nginx, request certificates and rewrite configuration files whenever you pick a new menu entry.

How the menu, the cores and the certificates fit together

The install path downloads install.sh, marks it executable and runs it as root. From that point the script is interactive. The README says it offers a menu to manage users, ports and configuration, which implies the script keeps state on disk and re-reads it each time you invoke the menu rather than regenerating everything from scratch.

TLS is handled automatically according to the README: the script applies for and renews SSL certificates. That is the part that most hand-built setups get wrong, and it is also the part that couples the script to a working DNS record and to port 80 or 443 being reachable during issuance. The README does not describe the certificate authority used, the renewal mechanism, or what happens if issuance fails midway.

Beyond the proxy core, the README lists several auxiliary features: subscription link generation, split-routing management for WireGuard, IPv6, Socks5, DNS, VMess over WebSocket and SNI reverse proxy, a domain blacklist, and BT download blocking. These are configuration generators layered on the same core. The topics list on the repository includes cloudflare, grpc-cloudflare, httpupgrade, reality, reality-grpc, trojan-grpc, tuic-v5, vless and xtls-rprx-vision, which suggests the menu exposes transport and security variants rather than a single fixed profile. The repository layout supports that reading: install.sh sits at the top level, with shell/ holding additional scripts and documents/ holding documentation.

Installing v2ray-agent and opening the menu again

The README gives a single command for the script version. It downloads install.sh into /root, sets the mode to 700 and executes it. You should expect an interactive menu after this, not a silent install.

wget -P /root -N --no-check-certificate "https://raw.githubusercontent.com/mack-a/v2ray-agent/master/install.sh" && chmod 700 /root/install.sh && /root/install.sh

After installation, the README states that running vasma reopens the management menu. That is the command you use for later changes such as adding a user or changing a port.

vasma

There is a second, Docker-based path documented in the README. It fetches a different script, shell/docker_reality.sh, and its menu command is vasmad rather than vasma. The README links to a separate usage page for the Docker Reality variant, so treat the two paths as distinct products with different documentation.

wget -P /root -N --no-check-certificate "https://raw.githubusercontent.com/mack-a/v2ray-agent/master/shell/docker_reality.sh" && chmod 700 /root/docker_reality.sh && /root/docker_reality.sh

vasmad

The README does not document a non-interactive install, a configuration file you can pre-seed, or a way to uninstall. If you need reproducible provisioning, that gap matters more than any feature listed above.

Where the one-click model breaks down

The most obvious limitation is that the script is the source of truth. Configuration lives wherever the script decides to put it, and the README does not describe the file layout, the service unit names, or how to roll back a change the menu made. If you edit the generated configuration by hand, the next menu action may overwrite it.

Automatic TLS is a convenience with a failure mode. Certificate issuance depends on DNS resolving to the server and on the validation path being reachable. The README does not document what the script does when issuance fails, whether it retries, or whether it leaves the core running without a certificate.

There is also a scope mismatch. The README mentions media unblocking, IP verification workarounds and BT blocking, which are policy features rather than transport features. If your goal is a single, minimal, auditable proxy endpoint, you are installing a menu system and a set of routing rules to get it. A reader who wants to understand every line of their configuration will find the Shell-plus-menu approach harder to reason about than a hand-written config, even though it is faster to stand up.

The AGPL-3.0 licence is the other boundary. If you modify the script and expose it to users over a network, the licence's network clause is relevant to how you distribute those changes. That is a real consideration for anyone planning to run this as part of a paid or public service, and it is not something the README discusses.

How it differs from ProxySU and 233boy's script

The related searches around this project include ProxySU and 233boy v2ray, which are the two comparisons people actually make. ProxySU is a graphical installer: you point and click through a Windows application and it provisions a remote server over SSH. v2ray-agent runs on the server itself and is driven from a terminal menu.

That difference determines who each tool suits. ProxySU keeps the operator on their own machine and treats the server as a target; v2ray-agent keeps the operator on the server and treats the local machine as irrelevant. If your only access to the VPS is a web console or a phone SSH client, the server-side menu is the one that works.

233boy's script is the closer comparison because it is also a server-side Shell installer. The distinguishing claim here is core breadth: the README states support for both Xray-core and sing-box, and lists Hysteria2, Tuic and NaiveProxy alongside the older VLESS, VMess and Trojan options. A script that installs one core with one protocol family is a smaller surface to maintain. Whether that breadth is worth the extra moving parts depends on whether you actually need more than one protocol, which many single-server setups do not.

Maintenance, updates and what the licence asks of you

The repository is not archived, and the last push was on 2026-09-15. The recent release list shows v3.5.25 on 2026-09-15, v3.5.24 on 2026-09-09 and v3.5.23 on 2026-09-03. That cadence, roughly weekly, means the install command always pulls the current master version of install.sh, so two servers installed a week apart may not be running identical code. The README does not document a version pinning option or a changelog inside the repository itself; release notes live on the release page.

Upgrade cost is mostly the cost of re-running the menu and confirming your configuration survived. Because the script manages certificates and core configuration together, an upgrade is not just a binary swap. The README does not describe an upgrade procedure or a backup step, so anyone running this in production should treat the generated configuration as something to copy off the server before touching the menu.

The project is licensed AGPL-3.0. For a private server that you alone use, the practical effect is limited. For anyone who modifies the script and offers it to others over a network, the licence's copyleft and network provisions are worth reading in the LICENSE file at the repository root. That is a description of the licence, not legal advice.

Editorial conclusion

Adopt v2ray-agent if you already rent a VPS and want VLESS, Trojan, Hysteria2 or Tuic running with automatic certificate renewal and a menu for user and port changes. Do not adopt it if you need a client-side application, a hosted service, or a configuration you can audit line by line without reading Shell. Before installing, verify that your server has a domain pointed at it and that the AGPL-3.0 obligations are acceptable for how you intend to redistribute anything you build on top.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. mack-a/v2ray-agent on GitHub
3. Project website
4. README
5. Releases