# v2rayA: a browser-controlled Xray core with transparent proxy

> v2rayA is a Go web client that drives its own Xray-based core and can route a whole machine through it via tun, tproxy or redirect. It suits Linux boxes and routers, and it is a poor fit if you want a desktop tray app or a single portable binary.

**v2rayA/v2rayA** — A web client for its own Xray-based core with global transparent proxy on Linux, Windows and macOS.

- Repository: https://github.com/v2rayA/v2rayA
- Stars: 15,645 · Forks: 1,612
- Language: Go
- License: AGPL-3.0
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/v2raya-v2raya

## What v2rayA actually is, and who it is for

v2rayA is not a proxy protocol implementation. It is a web client that manages a separate binary called v2raya_core, which the README describes as Xray-based. The Go service holds the configuration, decides which node to use, and exposes a browser interface; the core does the tunnelling. That split explains most of the project's constraints, including the requirement that the two binaries be the same version.

The intended user is someone with a machine that stays on: a Linux server, a router, a NAS. The README says v2rayA runs as a service and is used from a browser, on the machine itself or on a router or NAS. On such a box, a browser UI is more convenient than a config file, because subscriptions, node groups and routing rules change often.

It imports subscriptions and share links for VMess, VLESS, Shadowsocks, Trojan, Hysteria2, TUIC, Juicity, AnyTLS, WireGuard, SOCKS5 and HTTP(S). ShadowsocksR is explicitly not supported, which matters if your existing subscription list still contains SSR nodes. Nodes can be grouped, and the group either picks the member with the lowest measured latency or a pinned one. Traffic splitting is written in RoutingA, the project's own rule language, rather than in the JSON config of the core.

The audience is therefore narrow and technical: people who are comfortable enabling a systemd unit or an OpenRC init script, and who accept that the interesting features need root.

## How the service, the core and the routing rules fit together

The data flow has three layers. Subscriptions and share links enter through the web UI. v2rayA turns them into a node list, groups them, and measures latency to choose a member. It then writes the core's configuration and starts or reloads v2raya_core, which listens on the configured inbounds. Finally, traffic reaches those inbounds either because an application was pointed at them explicitly or because the operating system was told to redirect it.

That last step is what the README calls transparent proxy, and it is platform-specific. On Linux it needs root plus iptables or nftables for the redirect and tproxy modes, and /dev/net/tun together with the ip command from iproute2 for tun mode. On Windows, tun requires administrator and Windows 10 build 14393 or later; started without elevation the service runs in lite mode and can still set the current user's system proxy. On macOS, tun needs root, and a service started as an ordinary user runs in lite mode with the system proxy instead.

So there are two distinct operating modes, and the difference is not cosmetic. Lite mode changes one user's proxy settings and leaves everything else alone. Transparent proxy intercepts traffic at the network layer, which is why it needs privileges and a firewall backend. If you deploy v2rayA on a headless router, you are almost certainly in the second mode; if you install it on a work laptop without elevation, you are in the first.

Routing decisions sit above both. Rules written in RoutingA decide which destinations go direct and which go through a node, and that file is edited through the same browser interface as everything else.

## Installing v2rayA on Ubuntu, Arch or in Docker

Packages install v2raya and v2raya_core together with a service definition, which is the safest path because the version pairing is handled for you. On Debian and Ubuntu the packages come from the Dae Universe repository. The README lists a key download and then the package itself, followed by enabling the unit:

```bash
sudo curl -fsSL -o /usr/share/keyrings/daeuniverse-archive-goose.gpg https://daeuniverse.pages.dev/daeuniverse-archive-goose.gpg
sudo apt update
sudo apt install v2raya
sudo systemctl enable --now v2raya
```

After that the service should be running and reachable in a browser. If you need to change how the service starts, the README warns that editing the installed unit file is overwritten by the next upgrade, and gives `sudo systemctl edit --full v2raya.service` as the supported way to change it.

On Arch, the AUR carries both a source build and a binary package. The README's example uses the binary one:

```bash
paru -S v2raya-bin
sudo systemctl enable --now v2raya
```

Docker is the option for a Linux host where you want the container to take over networking. The README's example gives the container host networking and privileges, which transparent proxy requires:

```bash
docker run -d --restart=always --privileged --network=host --name v2raya \
  -e V2RAYA_LOG_FILE=/tmp/v2raya.log \
  -v /lib/modules:/lib/modules:ro \
  -v /etc/resolv.conf:/etc/resolv.conf \
  -v /etc/v2raya:/etc/v2raya \
  ghcr.io/v2raya/v2raya
```

With bridge networking instead, you publish port 2017 and the inbound ports you use, and turn on port sharing in the settings, because the inbounds otherwise listen on the container's loopback. The README states plainly that transparent proxy is not available in that setup, so the bridge variant is for explicit-proxy use only.

For a first real use, open the web interface, import a subscription or a share link, let the latency measurement finish, then pick a node or a group. Only after that does it make sense to enable transparent proxy, and on Linux that means choosing between redirect, tproxy and tun based on which firewall backend the machine has.

## Where v2rayA breaks or is the wrong choice

The strictest constraint is the version pairing. The README requires v2raya_core of the same version as v2raya, next to it or in PATH. Packages and installers ship both, but a hand-installed pair must match, and nothing in the interface will save you from a mismatch.

Rule data is the second failure point. geoip.dat and geosite.dat must be in /usr/share/v2raya or /usr/local/share/v2raya. Packages ship them, but the README says a hand install downloads them from GitHub on the first start and exits if that fails. On a machine that is being set up precisely because its network is restricted, that first-start download is a chicken-and-egg problem.

OpenWrt is the case where v2rayA is arguably the wrong tool right now. The README states that the v2raya-openwrt feed and the official packages feed currently package 2.2.7.x with a separate xray-core, not the release described in the README. Until those feeds are updated, the documented path is to install the mips32, mips32le, arm64 or x64 release binaries by hand with an init script of your choice. That is a manual, feed-divergent install, not a packaged one.

There is also no desktop client here. Windows and macOS users get a service plus a browser tab, and without elevation they get lite mode and a system proxy rather than transparent routing. Anyone who wants a tray icon to toggle nodes will find the browser round trip tedious. And if your subscription still relies on ShadowsocksR, the protocol is not supported at all.

## v2rayA compared with passwall and similar router front ends

The natural comparison on OpenWrt is passwall, which is a LuCI application: it lives inside the router's own web interface and is configured there, with the router's package manager handling the core. v2rayA takes the opposite approach. It is a standalone Go service with its own web UI on its own port, and it manages its own core binary rather than whatever the distribution ships.

That difference shows up in three places. First, installation: passwall is a router package, while v2rayA's OpenWrt feed is, per the README, stuck on 2.2.7.x with a separate xray-core, pushing current users to manual binary installs. Second, portability: the same v2rayA interface appears on Debian, Fedora, Arch, Gentoo, Alpine, macOS, Windows and Docker, whereas a LuCI app is tied to OpenWrt. Third, rule authoring: v2rayA uses RoutingA, its own language, while passwall exposes its routing through LuCI forms.

If you already run OpenWrt and want everything inside LuCI, passwall fits the platform better. If you want one interface across a server, a NAS and a router, v2rayA's model is more consistent, at the cost of a separate port and a separate service to keep updated.

## Upgrades, data location and the AGPL-3.0 licence

The README's Docker example mounts /etc/v2raya, which is where configuration and data live for that deployment. On packaged installs the service definition and rule data live under /usr/share/v2raya or /usr/local/share/v2raya, and the README warns that editing the installed systemd unit is overwritten by the next upgrade, so local changes belong in `systemctl edit --full v2raya.service`. Homebrew users on macOS get a related warning: upgrading or uninstalling a formula that was started as root needs `sudo rm` of the paths Homebrew names.

The upgrade cost is mostly the core pairing. Because v2raya and v2raya_core must be the same version, an upgrade that replaces only one of them is a broken install. Package managers that install both together avoid this; manual installs and the OpenWrt situation do not.

v2rayA is licensed AGPL-3.0, which is a strong copyleft licence with a network clause. If you modify the code and let users interact with it over a network, the licence's terms about offering the corresponding source apply. That is a real consideration for anyone embedding it in a hosted product. This is a description of the licence, not legal advice; read the LICENSE file and consult a lawyer for your situation.

## Conclusion

Adopt v2rayA if you administer a Linux host, router or NAS and want one service whose node list, latency selection and RoutingA rules are edited from a browser. Do not adopt it if you want a tray icon on a laptop, because the project ships no desktop GUI and its Windows and macOS builds fall back to lite mode when not elevated. Before trusting it, confirm that v2raya_core matches the v2raya version exactly, that geoip.dat and geosite.dat are present in /usr/share/v2raya or /usr/local/share/v2raya, and that your firewall tooling supports the mode you pick: iptables or nftables for redirect and tproxy, /dev/net/tun plus iproute2 for tun.

## FAQ

### How do I install v2rayA on Ubuntu?

Add the Dae Universe repository and key, then run `sudo apt install v2raya` and enable the service with `sudo systemctl enable --now v2raya`. The package installs v2raya and v2raya_core together with a service definition.

### How do I install v2rayA on Linux generally?

The README documents APT, RPM, Arch AUR, Gentoo and OpenRC paths, plus Docker. Without a package, you download the v2raya and v2raya_core binaries for your architecture from the releases page and use the OpenRC files from install/universal/.

### How do I install v2rayA on OpenWrt?

The v2raya-openwrt feed and the official packages feed currently package 2.2.7.x with a separate xray-core, not the release described in the README. Until they are updated, the documented path is to install the mips32, mips32le, arm64 or x64 release binaries by hand with an init script of your choice.

### How do I use v2rayA?

It runs as a service and is driven from a browser, on the machine itself or on a router or NAS. You import subscriptions or share links, group and select nodes by measured latency or by pinning one, and split traffic with rules written in RoutingA.

### How is v2rayA set up after installation?

Enable the service for your platform, then open the web interface to import subscriptions or share links and choose a node or group. Transparent proxy is a separate step: on Linux it needs root and iptables or nftables for redirect and tproxy, or /dev/net/tun and iproute2 for tun.

## Sources

- [Issues](https://github.com/v2rayA/v2rayA/issues)
- [License: AGPL-3.0](https://github.com/v2rayA/v2rayA/blob/main/LICENSE)
- [README](https://github.com/v2rayA/v2rayA/blob/main/README.md)
- [Releases](https://github.com/v2rayA/v2rayA/releases)
- [v2rayA/v2rayA on GitHub](https://github.com/v2rayA/v2rayA)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/v2raya-v2raya