RUEN

How it works

What is Xray-core, and how is it different from V2Ray?

8 min read

Xray-core is a proxy engine: a single Go binary that reads a config file, accepts connections on one side, and forwards them somewhere else using one of several protocols. It is maintained by Project X. If you use VLESS, Reality, or a subscription link that a client app turned into a working tunnel, this is often the software doing the work — on the server, and frequently inside the app on your device as well.

What Xray-core is

The mental model is short. Xray-core has inbounds (where traffic enters), outbounds (where it leaves), and a routing table that decides which outbound each connection gets. Protocols are plugins on either end. Everything else in the config is detail.

It is not a VPN in the WireGuard or OpenVPN sense. By itself it creates no network interface and takes over no routing table. On a desktop it typically opens a local SOCKS5 or HTTP proxy on 127.0.0.1, and whatever you want tunneled has to be pointed at that address. System-wide capture — the TUN interface that makes every app go through the tunnel — comes from the wrapper application around the core, not from the core.

Three names get mixed up constantly. Project X is the group that maintains the code. Xray-core is the binary. XTLS is not a protocol but a set of techniques for getting rid of the second, redundant TLS layer inside the tunnel; the current one is the Vision flow. And when someone says «a v2ray config» they almost always mean a share link (vless://, vmess://) or a JSON file — not the V2Ray software specifically.

Xray-core and V2Ray: what the fork changed

V2Ray (v2ray-core) is the older project — a modular proxy platform that introduced the inbound/outbound/routing design and the VMess protocol. Around 2020 its original author stepped away, and the community organization v2fly picked up maintenance of that codebase.

In the same year, disagreement over XTLS led to a split, and Project X forked v2ray-core into Xray-core. The consequence that matters today is where the newer pieces live: VLESS, XTLS Vision and Reality all originated on the Xray side. If you want Reality, you want a core that implements it.

The config formats stayed close, and many simple configs port across with small edits, but they have drifted since the fork. Do not assume field-for-field compatibility, and do not paste a config from a tutorial without checking which core it was written for.

One more thing worth saying plainly: for most people «Xray vs V2Ray» is not a decision they ever make. Client apps named after V2Ray — v2rayN, v2rayNG — ship Xray-core inside. The core you run is whichever one your client and your server happen to bundle. Comparative performance claims from either side circulate a lot and have no neutral benchmark behind them; treat them as marketing.

The protocols it speaks, and which ones still matter

  • VLESS — stateless, and deliberately carries no encryption of its own; it relies on TLS underneath. In practice it is paired with Reality, or with real TLS plus the XTLS Vision flow. This is the pairing most current server guides and panels are built around. Details in what VLESS Reality is.
  • VMess — the original V2Ray protocol. It encrypts on its own and authenticates with a UUID and a timestamp, so the clocks on client and server have to agree closely; the original design allows roughly 90 seconds of drift before the handshake is rejected. The old alterId/MD5 authentication is gone; what remains is VMessAEAD with alterId: 0. It still works, and there is little reason to choose it for something new.
  • Trojan — terminates a real TLS session with a real certificate and hands anything that fails authentication to a fallback website. That works, but it needs a domain and a certificate you keep renewing. Reality removes that requirement, which is the main reason a new setup usually skips Trojan.
  • Shadowsocks — the simplest of the four: a shared key and an AEAD stream, with the 2022 cipher family as the current generation. Small and fast, but the stream has no handshake and no plaintext at all, and that uniform randomness is itself a distinguishing feature for anything classifying traffic by shape. The 2022 edition fixes replay and active-probing weaknesses; it does not make the traffic look like something else.
  • Utility endpoints — SOCKS and HTTP inbounds, dokodemo-door for transparent proxying, freedom for direct exits, blackhole for dropping, and a WireGuard outbound for chaining.

A detail that trips people up: Hysteria2 is not an Xray protocol. Neither is TUIC. If a single subscription gives you both VLESS Reality and Hysteria2, your client is not running one core for both — it is running a different implementation for the UDP side. Why anyone keeps two transports around is covered in VLESS Reality vs Hysteria2.

The config model is the actual product

People keep Xray-core around instead of something simpler mostly for one feature: routing rules. A rule can match on destination domain, IP range, port, the inbound it arrived on, or the protocol sniffed out of the stream, and send that connection to a specific outbound.

  • Local and corporate domains go out through freedom, straight to the network, never into the tunnel.
  • One list of domains goes through the server in Frankfurt, another through the one in the US, everything else takes a default.
  • Ad and tracker domains are matched by a routing rule and sent to blackhole, so the connection is dropped instead of made.
  • The names the core resolves itself go to the servers in its dns block, so a routing decision and the connection that follows agree on which address a domain points at.
The dns block is not a leak fix on its own. It governs the lookups the core performs; the operating system keeps its own resolver, and whether those queries end up inside the tunnel depends on the wrapper app and the TUN configuration, not on the core. Test for DNS leaks rather than inferring them from the config.
The sniffing setting is worth understanding before you enable it. Sniffing reads the domain from the TLS SNI or the HTTP host so routing rules can match on names when the application only handed over an IP. But unless you also set routeOnly, the sniffed domain replaces the original destination — which breaks anything you are reaching by IP on purpose, Tor bridges being the classic casualty.

Where Xray-core actually runs

On the server it is normally a systemd service reading config.json. Many people never edit that file directly, because a panel such as 3x-ui generates it for them and adds a web UI for users and traffic accounting. The panel is not a different protocol stack — it is a manager sitting on top of the same binary, which is also why the file on disk can lag behind what the running process is actually using.

On the client side, desktop and Android apps such as v2rayN, v2rayNG, NekoBox and Hiddify embed a core and generate its config from your subscription. On iOS the picture is less uniform: some clients embed Xray-core, others implement the protocols themselves, and all of them work inside a network extension with a tight memory budget. That is one common reason a feature works on Android and is missing on iOS against the very same server.

sing-box is the other implementation you will run into. It is a separate project, not a fork of Xray: different config format, its own routing engine, and a wider protocol list that includes Hysteria2 and TUIC. Plenty of modern clients ship sing-box, and some ship both cores and pick one per profile. For anyone who is not self-hosting, that choice is made by the app.

What Xray-core does not do

  • It is not anonymity. It changes the address the destination sees. It does not touch operating system identifiers, signed-in accounts or browser fingerprints — see the Global Device ID case for what that gap looks like in practice.
  • It has no logging policy. Logging is a config value and an operator decision. On a box you rent, that operator is you; on someone else's, it is a promise you cannot verify from the protocol.
  • There is no built-in kill switch. With a local SOCKS proxy, an app pointed at that proxy stops connecting the moment the core dies — but every app that was never pointed at it went direct the whole time anyway. In a TUN setup the outcome depends entirely on what the wrapper does when the core exits, so test that case instead of assuming it.
  • It does not lift legal or contractual restrictions. Where a service checks residency, identity documents or a license, an address in another country changes nothing that matters, and the account is usually the thing that gets restricted.
  • It cannot fix physics. Routing rules do not shorten the path between two cities. If a server is far away or its network peering is bad, the config is not where the latency lives.

Who needs to touch Xray-core, and who does not

You will end up in the config file if you self-host, if you run split routing that a client UI cannot express, if you chain outbounds, or if you are debugging why one specific site fails while everything else is fine. That is a real and reasonably small group.

Everyone else does not need to. If your goal is a working tunnel on a laptop and a phone, the core is an implementation detail your client app already manages, and hand-editing its config is how people break profiles that worked. Learning the vocabulary is still worth an afternoon: it is the difference between reporting «the internet is broken» and reporting «the Reality handshake fails but Shadowsocks on the same host is fine».

A minimal self-hosted setup, in order

  1. 1Pick the server location first. Geography and peering decide your latency, and nothing in the config compensates for a bad choice here.
  2. 2Install Xray-core from the official Project X releases, or install a panel if you would rather not hand-write JSON. If you install a panel, treat it as a second public service: give it TLS and restrict who can reach it. A management panel exposed over plain HTTP is one of the more common ways these servers get taken over.
  3. 3Start with exactly one inbound: VLESS with Reality. Pick a target that genuinely supports TLS 1.3 with X25519, and make sure the serverNames you configure are names that target's certificate actually covers.
  4. 4Keep the system clock synchronized. It matters for certificate validity in general, and VMess will not authenticate at all if the clocks disagree.
  5. 5While testing, raise the log level from the default warning to info or debug, then put it back once the connection works — debug output records the domains you visit. If the handshake succeeds but pages do not load, the fault is almost always routing or DNS rather than the protocol.
  6. 6Back up the config and the UUIDs. Regenerating them invalidates every client link you have handed out.

Common questions

Is Xray-core a VPN?

Not in the usual sense. It is a proxy engine: on its own it creates no virtual network adapter and captures no system traffic. Either applications are pointed at a local proxy, or a wrapper app builds a TUN interface and feeds the core. The practical effect resembles a VPN, but the boundary of what actually gets tunneled is set by the app around it, which is why a browser can be covered while a background service is not.

Xray or V2Ray — which should I use?

For a new server, Xray-core, because VLESS with Reality and XTLS Vision live there. sing-box is an equally reasonable answer, especially if you want Hysteria2 or TUIC on the same box. v2ray-core is still maintained by v2fly, but it is not where the protocols people deploy today came from.

Can an Xray client connect to a V2Ray server?

For protocols both cores implement — VMess, Shadowsocks, Trojan — yes, provided the parameters match exactly. For anything that originated in Project X, such as Reality or the XTLS Vision flow, both ends need a core that supports it. A mismatch here usually shows up as a handshake that fails immediately rather than as a slow or flaky connection.

Do I need to understand Xray-core if I just use a subscription link?

No. There is no setup step where you are expected to open the config yourself; the client app carries a core and writes that config from the link. The vocabulary is only useful for describing a failure precisely when something breaks.

Is Xray-core safe to run?

It is open source, widely deployed, and the code is public for anyone to read. We are not aware of a published independent security audit, so do not treat it as formally verified. In practice the weak point of a self-hosted setup is rarely the core — it is an exposed management panel, a stale system, reused credentials, and a config copied from a forum without being read.

The short version: Xray-core is the engine, not the product. It moves bytes between an inbound and an outbound according to rules you write, it speaks the protocols your client and server agreed on, and it changes the address the other end sees. Anonymity, logging and everything above the network layer are separate problems with separate answers.