VLESS / Xray Deployment Guide

Overview

VLESS is a stateless proxy protocol developed as part of Xray-core, a 2021 fork of V2Ray. As of mid-2026 it is, when paired with REALITY (its TLS-mimicry layer), the community-converged choice for state-level circumvention — both Xray-core and the independent Sing-box implementation ship REALITY as their flagship transport, and the Hiddify client defaults to it. REALITY’s specific design property is resisting active probing — a censor poking your server gets routed to a real third-party TLS site instead of receiving a fingerprintable response (see the REALITY protocol description for the underlying mechanism). It is not a VPN, not a privacy tool, and not a replacement for Mullvad/IVPN/Tor.

What VLESS does well:

Carries arbitrary TCP/UDP through a TLS-disguised tunnel.
Combined with REALITY, presents a TLS handshake indistinguishable (to a passive observer) from a real CDN-fronted website.
Active-probe resistant when configured correctly — the server refuses to behave like a proxy for anyone holding a wrong key.

What VLESS does not do:

Encrypt traffic end-to-end (TLS does, VLESS itself is a transport).
Hide the destination from the exit (just like any VPN/proxy).
Provide anonymity against an adversary that can correlate inbound and outbound flows.

This page covers production-grade deployment, the governance and trust posture of the upstream project, and where you should pick something else.

Trustworthiness assessment

Censorship-circumvention tooling is high-stakes software. The maintainer set, the funding sources, the patch cadence, and the legal pressure environment all matter as much as the cryptography.

Factor	Risk Level	What to do about it
Maintainer identity opacity	High	Pin to a known-good release tag; review diff before bumping; track the project-X channel for protocol changes.
GFW active probing	High	Use REALITY with a real CDN-backed `dest`, rotate `shortIds` quarterly, never expose a bare VLESS endpoint on a non-443 port.
Repo-history rewrites and force-pushes	Medium	Mirror the source you build against. Don’t `go install` from upstream HEAD in production.
Upstream-protocol churn (XTLS → Vision → REALITY → …)	Medium	Accept a 6-month support window. Plan a refresh cycle.
License posture (MPL-2.0 on Xray-core; some sub-projects vary)	Low	Check `LICENSE` per repo before redistributing modified binaries.
Single-binary trust	Medium	Build from source where possible, or verify the SHA256 against the GitHub release. Don’t pipe `curl \| bash` install scripts.

When to pick VLESS, and when not to

Good fit

You’re inside a country that actively blocks WireGuard/OpenVPN.
You need TLS-fronted egress that won’t get killed on first sight by an SNI block.
You can manage server-side ops: cert hygiene, kernel BBR, an actual TLS-fronted decoy site.

Pick something else

You want plain “VPN-style” privacy → use WireGuard or a commercial VPN. See VPN Recommendation.
You need anonymity against a strong adversary → use Tor.
You want to hide that you’re using Tor (from your ISP or workplace network) → use Tor with obfs4 bridges, not VLESS. Different threat models.
You can’t keep server software up to date → don’t run censorship circumvention infrastructure.

Deployment

Reference architecture

client (Xray / Sing-box / Hiddify / v2rayN)
    │
    │  TLS handshake to port 443
    │  Looks like a real visit to www.google.com
    ▼
server (Xray-core with VLESS + REALITY)
    │
    ├── Wrong key / wrong SNI ──► proxy to real www.google.com:443
    └── Correct key ──────────► decrypt VLESS, forward upstream

The decoy site (dest in config) is not owned by you — it’s a real high-reputation site you redirect non-authorised traffic to. This is what makes REALITY active-probe resistant: a censor poking at your port sees a real TLS handshake from a real major site.

{
  "log": { "loglevel": "warning" },
  "inbounds": [
    {
      "port": 443,
      "protocol": "vless",
      "settings": {
        "clients": [
          { "id": "REPLACE_WITH_UUID_PER_CLIENT", "flow": "xtls-rprx-vision" }
        ],
        "decryption": "none"
      },
      "streamSettings": {
        "network": "tcp",
        "security": "reality",
        "realitySettings": {
          "show": false,
          "dest": "www.google.com:443",
          "xver": 0,
          "serverNames": ["www.google.com"],
          "privateKey": "REPLACE_WITH_X25519_PRIVATE_KEY",
          "shortIds": ["REPLACE_WITH_8_BYTE_HEX"]
        }
      },
      "sniffing": { "enabled": true, "destOverride": ["http", "tls"] }
    }
  ],
  "outbounds": [
    { "protocol": "freedom", "tag": "direct" },
    { "protocol": "blackhole", "tag": "block" }
  ]
}

📋 Canonical version: git.juntogroups.org snippet #2 — raw xray-vless-reality.json · README.md with placeholder docs. Pin from automation against the raw URL; this page mirrors the JSON for readers, the snippet is the canonical artifact.

Generate the keypair and a short-ID with the Xray binary itself:

xray x25519                       # → privateKey + publicKey
openssl rand -hex 8               # → shortId (must be even-length hex, ≤16 chars)
uuidgen                           # → per-client UUID

{
  "inbounds": [{
    "port": 443,
    "protocol": "vless",
    "settings": {
      "clients": [{ "id": "UUID_HERE" }],
      "decryption": "none"
    },
    "streamSettings": {
      "network": "ws",
      "security": "tls",
      "wsSettings": { "path": "/wHATEVER_RANDOM_PATH" },
      "tlsSettings": {
        "certificates": [{
          "certificateFile": "/etc/ssl/your-domain.crt",
          "keyFile": "/etc/ssl/your-domain.key"
        }]
      }
    }
  }],
  "outbounds": [{ "protocol": "freedom" }]
}

Pair with a real CDN front (Cloudflare, Bunny). Lower performance than REALITY, easier for a censor to fingerprint. Useful only when REALITY is blocked or unavailable.

Hardening checklist

Real TLS-fronted decoy. dest must resolve to a major site you do not own and which actually serves on port 443. Cloudflare-fronted sites work poorly here — pick a large CDN-backed property (Google, Microsoft, AWS console).
One UUID per client. Never share. Rotate on compromise. Treat as a secret on par with a long-lived API key.
BBR + kernel tuning. On Linux, enable BBR (net.core.default_qdisc=fq, net.ipv4.tcp_congestion_control=bbr). Default cubic loses badly on long-distance, lossy paths typical of circumvention.
Reject everything else on :443. No SSH on a random high port “as a backup”. A censor that finds an open port to your IP and sees a non-TLS protocol on it has won.
Logs off, or shipped off-box. loglevel: warning minimum. Anything more verbose retains client-correlation data on disk.
Pin the version. Don’t auto-update. Subscribe to the project-X channel and read changelogs before bumping.
Build reproducibility. Where possible, build from source. Verify the GitHub release SHA256 against your build. The threat is supply-chain, not network.
Watch the cert. If you’re using a real cert (not REALITY), use a short-lived ACME cert via acme.sh or certbot. Renew on automation.

Client-side

Platform	Client	Notes
Desktop, cross-platform (Win/macOS/Linux)	Hiddify	Flutter GUI on Sing-box backend; active, multi-platform including mobile. Current default recommendation.
Desktop, Windows-focused (Win/macOS/Linux)	v2rayN	Long-running Windows-first client. Active (v7.22.5+ as of mid-2026). Speaks both Xray and Sing-box.
Mobile (Android)	v2rayNG	F-Droid build available. By the same maintainer as v2rayN.
Mobile (iOS)	Shadowrocket / Streisand	Both paid, both work. Sideloading not required.
Headless	`xray` CLI directly	Same `client.json` shape as the server, with `"outbounds"` doing the VLESS connect.
Sing-box stack	Sing-box	Alternative reimplementation; supports VLESS+REALITY and is the recommended choice if you don’t trust the Xray maintainers. See Alternatives below.

Subscription distribution

Don’t email UUIDs around. Use a self-hosted subscription endpoint:

https://your-cdn-fronted-host/sub/<per-user-token>

Returns a base64-encoded vless://... URI. Rotate <per-user-token> on a schedule, expire abandoned subscriptions. 3X-UI is the most-used panel; review its source before trusting it with your server.

Operational risks

GFW active probing

The Great Firewall does not just block by SNI/IP — it actively probes suspicious endpoints. A naive VLESS server (no REALITY, no real decoy) responds in distinguishable ways to forged TLS records, and is blocked within hours.

REALITY mitigates this by literally proxying probes to a real third-party TLS server. The censor sees a real Google handshake, not a poorly-imitating fake. This is the entire point of REALITY over plain TLS.

Protocol churn

The Xray project ships breaking protocol changes every 6–12 months: vmess → vless, xtls-direct → xtls-rprx-vision, tls+ws → reality, etc. A configuration that works today will not work in two years. Budget for a quarterly review.

Maintainer / supply-chain

The Xray-core project’s maintainer history is non-transparent. Force-pushes to the main branch have happened. There is no organisation behind the project — XTLS is a GitHub org with one to three active humans depending on the season. Treat upstream the way you would any one-person OSS dependency that you bet your egress traffic on.

Concrete mitigation:

Mirror your source-of-truth git tree separately.
Build from a specific tag, never from main.
Subscribe to @projectXtls for protocol-change announcements.
Have a documented switch-to-sing-box plan you’ve actually tested.

See Field Notes: VLESS Investigation for the raw research — what’s verifiable, what’s circumstantial, and the timelines.

Alternatives

Tool	Use case	License	Why pick it
Sing-box	Censorship circumvention	GPL-3.0	Re-implementation of VLESS+REALITY (and many others) by a different team. The “drop-in replacement if Xray-core gets dropped” plan.
Hiddify	Cross-platform client GUI for VLESS / Sing-box / multi-protocol	Open source	Active, modern Flutter GUI on Sing-box backend. The current recommended desktop+mobile client now that Nekoray is archived.
v2rayN	Windows-focused client GUI	GPL-3.0	Long-running, active. Speaks both Xray and Sing-box. The boring-and-stable Windows choice.
WireGuard	High-performance encrypted tunnel	GPL-2.0	Use when censorship is not the threat model. See WireGuard in Containers.
Shadowsocks-2022	Lighter-weight obfuscated proxy	Various	Less feature-rich than VLESS but battle-tested and has multiple independent implementations.
Tor + bridges (obfs4 / WebTunnel)	Strong anonymity and circumvention	BSD-style	Slower, but the right answer if anonymity is the goal.

If you can’t decide: REALITY is the community-converged default for state-level circumvention as of mid-2026 (Xray-core, Sing-box, and Hiddify all ship it). Sing-box is the safer choice if you don’t trust Xray-core upstream. WireGuard is the right answer if you’re not actually being censored. None of these is unconditionally undetectable — see the active-probe-resistance caveat above and trustworthiness assessment.

VLESS as outer tunnel for a commercial VPN

A growing community use case isn’t VLESS for direct browsing — it’s VLESS as the outer tunnel that lets a commercial VPN (Mullvad, IVPN, Proton) reach its own servers from inside a network that blocks them. This is common at US universities, corporate Wi-Fi, hotel networks, and any captive portal that blocklists VPN ASNs or fingerprints WireGuard handshakes.

Your device → VPN client → Xray client (local) → TLS:443 → Xray server (VPS) → VPN's real servers
                                                  ↑
                                 censoring network sees: normal HTTPS to a CDN-fronted site

You need a VPS in an unblocked location ($4–$5/mo from Hetzner/Vultr/OVH is fine). Server-side is the same VLESS+REALITY config from Server-side: minimal xray.json above — no special config for “carrying a VPN inside”. Client-side has three patterns.

Approach 1 — TUN mode (cleanest, transparent)

Run Xray as a system-level TUN interface on your device. Every outbound packet — including WireGuard UDP from the VPN client — gets captured by Xray, wrapped in VLESS+TLS, and shipped to your VPS. The VPS unwraps and forwards to the open internet, where the VPN’s WireGuard handshake completes normally.

Pros: transparent — the VPN client doesn’t know it’s tunneled; works for WireGuard (UDP-in-VLESS via XUDP).
Cons: needs admin to create the TUN device; more involved than SOCKS mode.
Tooling: much easier with Hiddify or Mihomo than with raw Xray — they handle TUN setup, routing tables, and DNS for you.

Approach 2 — SOCKS5 proxy from the VPN client (easiest)

Switch the VPN client to OpenVPN-TCP mode and point it at the local Xray as a SOCKS5 proxy. Mullvad: Settings → VPN Settings → OpenVPN → Use custom SOCKS5 proxy → 127.0.0.1:10808. IVPN has the equivalent under OpenVPN custom proxy settings.

VPN client (OpenVPN-TCP, SOCKS5 → 127.0.0.1:10808)
  → Xray client local (SOCKS inbound, VLESS outbound to VPS)
  → TLS:443 → VPS Xray server → VPN's OpenVPN endpoint

Pros: no TUN setup; trivial VPN client config; works on macOS without admin.
Cons: OpenVPN-TCP is slower than WireGuard (TCP-over-TCP penalty stacked on the VLESS TCP layer); only works when the VPN supports OpenVPN-TCP plus a custom SOCKS proxy.

Approach 3 — Skip the commercial VPN, exit from the VPS directly

If your only reason to run the commercial VPN here was to escape the restrictive network, your VPS already does that:

Your device → Xray → TLS:443 → VPS → internet

You lose the commercial VPN’s exit-IP rotation and “this server isn’t tied to your name” property. But for the common case (“I’m in a coffee shop / dorm and want to bypass the captive portal”) it’s the lowest-friction option. The VPS provider knows your billing info; if that’s acceptable for your threat model, you don’t need the commercial VPN on top.

How to pick

Goal	Approach
Transparent, all apps, don’t want to think about it	1 (TUN with Hiddify)
Easiest setup, OpenVPN-TCP is acceptable	2 (SOCKS5)
Cheapest, don’t actually need the commercial VPN’s exit	3 (VPS direct)
Highest performance under bypass conditions	1 (TUN with WireGuard)

For the related decision — should you reach for VLESS at all, vs. one of the simpler obfuscated transports — see Proxies, VPN tunnels, and circumvention.

What this guide adds beyond upstream

Upstream Xray-core’s README and the project-X Telegram channel already explain how to install VLESS and run REALITY. This guide deliberately doesn’t restate that. What it adds:

A trustworthiness framing the upstream README won’t write. Upstream documents the protocol; this page documents the maintainer-set, the supply-chain assumptions, and what “build from source” actually means as a root of trust — see the trustworthiness assessment above and the linked VLESS Investigation Field Notes.
A documented Sing-box swap-in plan. Upstream has no reason to tell you about Sing-box. This page treats Sing-box as a first-class alternative and the off-ramp if Xray-core has a supply-chain event.
Hardening choices specific to running this in adversarial environments. BBR kernel-tuning rationale, log-retention posture, an explicit “no SSH on a random high port as backup” rule, ACME automation pointer. These are operator-side defaults this community has converged on.
Honest scope boundaries. Upstream’s README pitches the protocol; this page repeatedly says “this is not a VPN, not a privacy tool, not a replacement for Tor” because community members ask, regularly.
Pin recipes — git clone --branch <tag> and GitHub Releases + SHA256 workflows, plus version-pinning rationale, instead of go install ...@latest.

What this guide deliberately does not duplicate from upstream: protocol internals, every CLI flag, full configuration reference, mobile client install steps. For those, go to the upstream docs directly.

Verifying a binary

# Pin to a specific release tag — don't track `latest`
VERSION=v26.3.27   # current stable as of 2026-06-08; check upstream releases
curl -fLO "https://github.com/XTLS/Xray-core/releases/download/${VERSION}/Xray-linux-64.zip"
curl -fLO "https://github.com/XTLS/Xray-core/releases/download/${VERSION}/Xray-linux-64.zip.dgst"

# Verify checksum (compare against the .dgst file)
sha256sum Xray-linux-64.zip
cat Xray-linux-64.zip.dgst | grep -i sha256

For Go-toolchain builds, pin the tag explicitly:

# Build from a pinned tag, not from HEAD
git clone --depth 1 --branch v26.3.27 https://github.com/XTLS/Xray-core.git
cd Xray-core
go build -trimpath -ldflags "-s -w" -o xray ./main

Upstream signs releases via the GitHub Releases page. There is no separate detached-GPG signature workflow as of this writing — verification is via GitHub Release SHA256, which means you’re trusting GitHub’s commit-signing chain plus the maintainer’s account security. Treat that as the actual root of trust. Fake binaries and typosquat packages have been distributed in the past — see the VLESS Investigation Field Notes for incident history.