Xray-core Guide: Proxy Access, VLESS, REALITY, and XTLS

2026-03-22 GIGATAP Team #vpn

#vpn #anticensorship #dns #network #proxy #reality #xray-core

Xray-core matters when a normal VPN profile is blocked, unstable, or too easy to fingerprint. The practical choice is not only protocol selection; it is matching VLESS, REALITY, routing rules, DNS behavior, and client support to the network that is filtering or breaking connections.

What is Xray-core#

Xray-core is a high-performance, open-source network toolkit that originated as a fork of the popular V2Ray project. It is commonly used to build proxy routes, test protocol behavior, and run encrypted tunnels where a normal VPN profile is unstable or filtered. At its heart, Xray-core is a multi-protocol proxy platform, supporting a wide array of inbound and outbound protocols, including VLESS, VMess, Trojan, Shadowsocks, and SOCKS5.

What sets Xray-core apart are features like REALITY, XTLS, and uTLS. REALITY can make some proxy deployments look closer to ordinary TLS traffic without requiring a dedicated TLS certificate. XTLS can reduce overhead in supported transport modes. uTLS helps match common browser TLS fingerprints, which may improve compatibility on some networks.

Xray-core is useful for technically comfortable users, operators, and privacy-minded teams that need to compare client behavior, protocol choices, and network conditions. It can improve transport resilience and route privacy, but it does not provide complete anonymity by itself.

Installation#

Installing Xray-core offers several methods, catering to different operating systems and user preferences. We’ll cover the most common and officially supported ways for Linux and Docker.

Linux (Official Install Script)#

The official Xray-install script is the recommended way to install Xray-core on Linux distributions, as it handles dependencies, systemd services, and automatic updates.

Download and Run the Script:
The script automatically detects your system architecture and installs the appropriate binary.
```
bash -c "$(curl -L https://raw.githubusercontent.com/XTLS/Xray-install/main/install-release.sh)" @ install
```
This command will download and execute the installation script. Follow any on-screen prompts.
Verify Installation:
After installation, Xray-core should be running as a systemd service. You can check its status:
```
systemctl status xray
```
You should see output indicating that the service is active (running).

Update Xray-core:
To update Xray-core to the latest version in the future, simply re-run the install script:

bash -c "$(curl -L https://raw.githubusercontent.com/XTLS/Xray-install/main/install-release.sh)" @ install

Docker#

For those who prefer containerized applications, Xray-core is available as an official Docker image. This method ensures isolated, reproducible deployments.

Pull the Official Docker Image:
```
docker pull ghcr.io/xtls/xray-core
```
Run Xray-core with a Configuration File:
You’ll need a configuration file (e.g., config.json) to run Xray-core in Docker. Create your configuration file in a directory (e.g., ./xray-config/).
```
mkdir xray-config
# Create your config.json inside xray-config directory
# nano xray-config/config.json
```
Then, run the Docker container, mounting your configuration file:
```
docker run -d \
  --name xray-server \
  --restart always \
  -v "$(pwd)/xray-config:/etc/xray" \
  -p 443:443 \
  ghcr.io/xtls/xray-core \
  xray -c /etc/xray/config.json
```
- -d: Runs the container in detached mode.
- --name xray-server: Assigns a name to the container.
- --restart always: Ensures the container restarts automatically.
- -v "$(pwd)/xray-config:/etc/xray": Mounts your local xray-config directory to /etc/xray inside the container.
- -p 443:443: Maps port 443 from the host to port 443 in the container. Adjust ports as per your configuration.
- xray -c /etc/xray/config.json: Specifies the command to run Xray-core with your mounted configuration.

Basic Configuration#

Xray-core uses a JSON-based configuration file. A fundamental setup typically involves defining inbounds (how Xray accepts connections) and outbounds (how Xray forwards connections). For this guide, we’ll focus on a secure and highly obfuscated setup using VLESS + TCP + REALITY, which is excellent for anti-censorship.

This setup requires a server (where Xray-core is deployed) and a client (your local machine).

Generating Keys and Short IDs for REALITY#

REALITY relies on a public/private key pair and a shortId. Xray-core includes a utility to generate these:

/usr/local/bin/xray x25519

This command will output:

Private key: YOUR_PRIVATE_KEY_HERE
Public key: YOUR_PUBLIC_KEY_HERE
ShortId: YOUR_SHORT_ID_HERE

Keep your private key secret and secure. The public key and short ID will be shared with clients.

Server Configuration (`config.json` on the server)#

This example sets up a VLESS inbound with REALITY on port 443, mimicking traffic to www.google.com. Replace placeholders with your generated keys, UUID, and a legitimate dest domain.

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "port": 443,
      "protocol": "vless",
      "settings": {
        "clients": [
          {
            "id": "YOUR_UUID_HERE", // Generate a UUID using `xray uuid`
            "flow": "xtls-rprx-vision"
          }
        ],
        "decryption": "none"
      },
      "streamSettings": {
        "network": "tcp",
        "security": "reality",
        "realitySettings": {
          "show": false,
          "dest": "www.google.com:443", // A legitimate website, e.g., www.microsoft.com:443
          "xver": 0,
          "serverNames": ["www.google.com"], // Must match the dest domain
          "privateKey": "YOUR_PRIVATE_KEY_HERE", // From `xray x25519`
          "shortIds": ["YOUR_SHORT_ID_HERE"] // From `xray x25519`
        }
      }
    }
  ],
  "outbounds": [
    {
      "protocol": "freedom",
      "settings": {}
    },
    {
      "protocol": "blackhole",
      "tag": "blocked"
    }
  ],
  "routing": {
    "rules": [
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "blocked"
      }
    ]
  }
}

YOUR_UUID_HERE: Generate a UUID using xray uuid. This acts as a user identifier.
dest: This is the target website Xray-core will pretend to be communicating with. Choose a popular, legitimate website for better obfuscation.
serverNames: Must match the domain specified in dest.
privateKey and shortIds: Use the values generated by xray x25519.

Client Configuration (`config.json` on your local machine)#

This client configuration connects to your Xray-core server, and provides SOCKS5 and HTTP proxy interfaces on your local machine (ports 1080 and 1081).

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "port": 1080,
      "listen": "127.0.0.1",
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      }
    },
    {
      "port": 1081,
      "listen": "127.0.0.1",
      "protocol": "http",
      "settings": {
        "timeout": 300
      }
    }
  ],
  "outbounds": [
    {
      "protocol": "vless",
      "settings": {
        "vnext": [
          {
            "address": "YOUR_SERVER_IP_OR_DOMAIN", // Your Xray-core server's public IP or domain
            "port": 443,
            "users": [
              {
                "id": "YOUR_UUID_HERE", // Must match server's UUID
                "flow": "xtls-rprx-vision",
                "encryption": "none"
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "tcp",
        "security": "reality",
        "realitySettings": {
          "fingerprint": "chrome", // uTLS fingerprint to mimic Chrome
          "serverName": "www.google.com", // Must match server's dest/serverNames
          "shortId": "YOUR_SHORT_ID_HERE", // From `xray x25519`
          "publicKey": "YOUR_PUBLIC_KEY_HERE" // From `xray x25519`
        }
      }
    },
    {
      "protocol": "freedom",
      "tag": "direct"
    }
  ]
}

YOUR_SERVER_IP_OR_DOMAIN: The public IP address or domain name of your Xray-core server.
YOUR_UUID_HERE, YOUR_SHORT_ID_HERE, YOUR_PUBLIC_KEY_HERE: These must precisely match the values configured on your server.
fingerprint: Mimics a common browser’s TLS fingerprint (e.g., chrome, firefox, safari, ios, android, edge, random). chrome is a good default.
serverName: Must match the dest and serverNames on the server configuration.

Once both server and client are configured, start Xray-core on both machines using their respective configuration files. On Linux: systemctl restart xray (if installed via script) or xray -c /path/to/config.json. For Docker, restart the container.

Common Use Cases#

1. Bypassing Internet Censorship with Stealth#

Xray-core excels at defeating internet censorship, particularly with its REALITY protocol. By configuring a server with REALITY and connecting clients, users can effectively tunnel their traffic through heavily restricted networks. The key is REALITY’s ability to masquerade as legitimate TLS traffic to common websites, making it very difficult for deep packet inspection (DPI) systems to detect and block.

Server Setup (as per “Basic Configuration” above):
Deploy the Xray-core server configuration on a VPS or cloud instance located outside the censored region. Ensure port 443 is open.

Client Usage:

Run the Xray-core client on your local machine using the client configuration.
Configure your applications (browser, torrent client, etc.) to use the local SOCKS5 proxy (127.0.0.1:1080) or HTTP proxy (127.0.0.1:1081).
For instance, in Firefox, go to Settings > Network Settings > Settings... and manually configure the proxy.
```
SOCKS Host: 127.0.0.1 Port: 1080
```
Select SOCKS v5 and Proxy DNS when using SOCKS v5.

2. Enhancing Privacy and Security on Untrusted Networks#

Even in non-censored environments, Xray-core can significantly boost your privacy and security, especially when using public Wi-Fi or other untrusted networks. It encrypts your traffic and routes it through a trusted server, preventing local adversaries from snooping on your data or tracking your online activities.

Deployment:
The setup is identical to the anti-censorship use case. The Xray-core server acts as your secure gateway to the internet.

Benefits:

Data Encryption: All your traffic between your client and the Xray-core server is encrypted.
IP Address Masking: Your public IP address appears as that of the Xray-core server, masking your true location.
Bypassing Local Restrictions: Access geo-restricted content or services by choosing a server location appropriately.

3. Traffic Obfuscation and Mimicry with uTLS#

Xray-core’s uTLS feature allows your client to mimic the TLS fingerprints of common web browsers or operating systems. This is critical for evading detection methods that analyze TLS handshake patterns to identify proxy traffic.

Configuration (already included in the client example):
The fingerprint option within realitySettings on the client side enables this.

"realitySettings": {
  "fingerprint": "chrome", // Mimic Chrome's TLS fingerprint
  "serverName": "www.google.com",
  "shortId": "YOUR_SHORT_ID_HERE",
  "publicKey": "YOUR_PUBLIC_KEY_HERE"
}

By setting fingerprint to a value like "chrome", your Xray-core client’s outgoing TLS handshakes will appear identical to those made by a Chrome browser, making it much harder for network analysis tools to distinguish your proxy traffic from regular web browsing. This enhances the stealth of your connection significantly.

Tips and Gotchas#

Keep Xray-core Updated: The developers frequently release updates that include performance improvements, bug fixes, and crucial anti-censorship enhancements. Always run the installation script or pull the latest Docker image to stay current.
Validate JSON Configuration: JSON syntax can be finicky. Use an online JSON validator (or a text editor with JSON validation) to check your configuration files for errors before starting Xray-core. A single misplaced comma or brace can prevent it from starting.
Generate Strong IDs: Always use cryptographically strong UUIDs (xray uuid) and securely generated X25519 keys (xray x25519). Avoid using weak or easily guessable identifiers.
Monitor Logs: Xray-core’s logs are invaluable for troubleshooting. Set loglevel to warning or info during setup and debugging to get detailed insights.
```
journalctl -u xray -f # For systemd installations
docker logs -f xray-server # For Docker containers
```
Server Selection: For anti-censorship, choose a VPS provider that is known for being resistant to blocking and has a good reputation for privacy. Avoid providers that are known to cooperate with censorship regimes.
Choose a Legitimate dest Domain: For REALITY, the dest and serverNames should point to a popular, legitimate website (e.g., www.cloudflare.com, www.amazon.com, www.apple.com) to maximize obfuscation. Ensure the port matches (typically 443).
Firewall Configuration: Ensure that the port Xray-core is listening on (e.g., 443) is open in your server’s firewall. For client-side, ensure your local firewall doesn’t block connections to 127.0.0.1:1080 or 127.0.0.1:1081.
Client Software Integration: While Xray-core provides the proxy, you’ll need to configure your applications (browsers, email clients, etc.) to use the SOCKS5 or HTTP proxy you set up. Many GUI clients for Xray/V2Ray are available for various platforms (Windows, Android, iOS) that simplify this process.

Conclusion#

Xray-core stands as a formidable tool in the fight for internet freedom and privacy. With its advanced protocols like VLESS, REALITY, and XTLS, coupled with sophisticated obfuscation techniques like uTLS, it offers a robust solution for bypassing censorship and securing your online communications. For technically savvy users committed to their digital sovereignty, Xray-core is an essential component of a comprehensive OPSEC strategy.

Definition#

Xray-core - a multi-protocol proxy toolkit commonly used to build VLESS, REALITY, Trojan, Shadowsocks, and routing setups for restricted or unstable networks.

Comparison#

Option	Use when	Watch out for
VLESS + REALITY	You need censorship-resistant access with modern client support.	Bad server names, weak TLS choices, and poor routing rules can still expose patterns.
WireGuard VPN	You control both endpoints and the network allows UDP.	Some mobile and filtered networks throttle or block the handshake.
Shadowsocks	You need a simple encrypted proxy for one device or app.	It is not a full traffic-isolation model by itself.

FAQ#

Is Xray-core a full VPN replacement?#

Xray-core can replace a VPN for selected proxy routes, but it is not automatically a device-wide privacy boundary. Users still need clear routing rules, DNS handling, leak checks, and a client that sends the intended apps through the tunnel.

What should readers configure first?#

Readers should configure the server transport, client routing rules, and DNS behavior before optimizing protocol details. Most real failures come from mismatched routing, blocked handshakes, or DNS leaks rather than from the proxy core alone.

VPN Subscription Safety Checklist for Mobile Networks - A safe checklist for evaluating VPN and VLESS subscription feeds before importing them into mobile clients.
How to Use remnawave-api for Remnawave API Automation - A beginner-friendly guide to automating Remnawave tasks with Python, including setup, auth, and real-world API examples.
ByeDPIManager on Windows: Run ByeDPI + ProxiFyre for App-Selective DPI Bypass - Beginner-friendly guide to install and use ByeDPIManager on Windows to run ByeDPI with ProxiFyre for per-app DPI bypass.
ghostcp (GhosTCP) Beginner Guide: Hardening TCP Connections on Windows - Learn how to install and configure ghostcp (GhosTCP) on Windows to reduce TCP interference using WinDivert and simple rules.
Psiphon How-To: Censorship Circumvention Basics for Privacy-Minded Users - Learn how to install and use Psiphon to bypass network censorship, understand what it protects (and what it doesn’t), and avoid common OPSEC mistakes.
zapret2 (anti-DPI) Beginner Guide: Install, Intercept, and Apply Strategies Safely - A beginner-friendly zapret2 guide: install it, redirect only the right packets, and apply anti-DPI strategies on Linux/Windows.
Throne proxy GUI: what to verify before trusting it - Throne has visible GitHub traction and a recent push, but proxy GUI adoption needs more than stars. Here is what to check before trusting it with real traffic.
Hysteria Proxy: What to Check Before You Deploy - Hysteria is a popular Go proxy project with recent activity and a censorship-circumvention focus. Before adopting it, treat the repository as a starting po

Latest articles

Crypto clipper adds Tor and worm-like spread to theft model - Microsoft analysis shows crypto clipper evolving into a persistent threat combining clipboard hijacking, Tor-based control, and worm-like propagation.
US Government AI Inventory Raises Privacy Questions - US agencies list 3,611 AI use cases, exposing gaps in transparency and raising questions about automated decision-making and privacy.
BCI moves from trial to real use as AI national strategy expands - A brain implant user with ALS signals early real-world BCI use while South Korea accelerates national AI focus and infrastructure alignment.
Canada’s Bill C-22 Pushes Encryption Toward Built-In Access Risk - Bill C-22 expands surveillance powers in Canada and introduces mechanisms that could force access paths into encrypted systems, raising structural privacy
Postinstall payloads in npm supply chains and Mastra breach - Mastra npm packages were compromised through a postinstall hook that executed during install, exposing CI/CD pipelines and developer environments to remote
Security beyond benchmarks: Microsoft MDASH moves to production - Microsoft’s MDASH moves from benchmark success into live engineering pipelines, embedding AI-driven vulnerability discovery directly into DevSecOps workflo
VHDX Delivery Chain Hides Remcos RAT via JavaScript Stage - A ZIP file uses a VHDX disk image to expose JavaScript after auto-mounting on Windows, leading to Remcos RAT deployment through layered execution.
Wolf Gallery and the F-Droid packaging bottleneck - Wolf Gallery’s F-Droid request shows how strong local encryption and offline design still depend on packaging work before reaching users through trusted di