Imported from terminalskills/skills (skills/xray/SKILL.md). Install upstream with npx skills add terminalskills/skills --skill xray. Copyright stays with the author (Apache-2.0).

Xray

Overview

Deploy and configure Xray-core — the advanced proxy platform supporting VLESS, VMess, Trojan, and Shadowsocks protocols with modern transports like Reality, XTLS-Vision, WebSocket, gRPC, and HTTP/2. This skill covers server deployment, protocol selection, TLS/Reality configuration, traffic routing, multi-user management, CDN integration, client configuration, and monitoring.

Instructions

Step 1: Installation

bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install
xray version
# Binary: /usr/local/bin/xray
# Config: /usr/local/etc/xray/config.json

# Generate UUID and X25519 keys
xray uuid
xray x25519   # Private + Public key pair for Reality

Step 2: VLESS + Reality (Recommended)

The most secure setup. Reality mimics a real HTTPS website's TLS handshake, eliminating the need for a domain or TLS certificate.

Server config (/usr/local/etc/xray/config.json):

{
  "log": { "loglevel": "warning" },
  "inbounds": [{
    "listen": "0.0.0.0",
    "port": 443,
    "protocol": "vless",
    "settings": {
      "clients": [
        { "id": "YOUR-UUID", "flow": "xtls-rprx-vision", "email": "user1@proxy" }
      ],
      "decryption": "none"
    },
    "streamSettings": {
      "network": "tcp",
      "security": "reality",
      "realitySettings": {
        "dest": "www.microsoft.com:443",
        "serverNames": ["www.microsoft.com", "microsoft.com"],
        "privateKey": "YOUR-PRIVATE-KEY",
        "shortIds": ["", "0123456789abcdef"]
      }
    },
    "sniffing": { "enabled": true, "destOverride": ["http", "tls", "quic"] }
  }],
  "outbounds": [
    { "protocol": "freedom", "tag": "direct" },
    { "protocol": "blackhole", "tag": "block" }
  ],
  "routing": {
    "rules": [{ "type": "field", "ip": ["geoip:private"], "outboundTag": "block" }]
  }
}

Client share link:

vless://UUID@SERVER_IP:443?encryption=none&flow=xtls-rprx-vision&security=reality&sni=www.microsoft.com&fp=chrome&pbk=PUBLIC_KEY&sid=0123456789abcdef&type=tcp#MyProxy

systemctl enable --now xray

Step 3: VLESS + WebSocket + TLS (CDN-Compatible)

For routing through Cloudflare CDN to hide the server IP. Requires a domain with Cloudflare proxying and a TLS certificate.

apt install -y certbot
certbot certonly --standalone -d proxy.yourdomain.com

{
  "inbounds": [
    {
      "port": 443, "protocol": "vless",
      "settings": {
        "clients": [{ "id": "YOUR-UUID" }],
        "decryption": "none",
        "fallbacks": [
          { "dest": 8080 },
          { "path": "/ws-path", "dest": 8443, "xver": 1 }
        ]
      },
      "streamSettings": {
        "network": "tcp", "security": "tls",
        "tlsSettings": {
          "certificates": [{
            "certificateFile": "/etc/letsencrypt/live/proxy.yourdomain.com/fullchain.pem",
            "keyFile": "/etc/letsencrypt/live/proxy.yourdomain.com/privkey.pem"
          }]
        }
      }
    },
    {
      "listen": "127.0.0.1", "port": 8443, "protocol": "vless",
      "settings": { "clients": [{ "id": "YOUR-UUID" }], "decryption": "none" },
      "streamSettings": { "network": "ws", "wsSettings": { "path": "/ws-path" } }
    }
  ],
  "outbounds": [{ "protocol": "freedom", "tag": "direct" }]
}

Set up nginx on port 8080 as fallback, and in Cloudflare: SSL/TLS Full (Strict), WebSockets ON.

Step 4: Trojan & Shadowsocks

Trojan (looks like normal HTTPS):

{
  "inbounds": [{
    "port": 443, "protocol": "trojan",
    "settings": {
      "clients": [{ "password": "your-strong-password", "email": "user1@trojan" }],
      "fallbacks": [{ "dest": 8080 }]
    },
    "streamSettings": {
      "network": "tcp", "security": "tls",
      "tlsSettings": { "certificates": [{ "certificateFile": "...", "keyFile": "..." }] }
    }
  }]
}

Shadowsocks 2022 (modern AEAD ciphers):

{
  "inbounds": [{
    "port": 8388, "protocol": "shadowsocks",
    "settings": { "method": "2022-blake3-aes-128-gcm", "password": "BASE64_KEY", "network": "tcp,udp" }
  }]
}

Generate key: openssl rand -base64 16 (or -base64 32 for aes-256)

Step 5: Multi-User Management

"clients": [
  { "id": "uuid-1", "email": "alice@proxy", "flow": "xtls-rprx-vision" },
  { "id": "uuid-2", "email": "bob@proxy", "flow": "xtls-rprx-vision" },
  { "id": "uuid-3", "email": "carol@proxy", "flow": "xtls-rprx-vision" }
]

Per-user traffic stats — enable the stats API:

{
  "stats": {},
  "policy": {
    "levels": { "0": { "statsUserUplink": true, "statsUserDownlink": true } },
    "system": { "statsInboundUplink": true, "statsInboundDownlink": true }
  },
  "api": { "tag": "api", "services": ["StatsService", "HandlerService"] },
  "inbounds": [
    { "listen": "127.0.0.1", "port": 10085, "protocol": "dokodemo-door",
      "settings": { "address": "127.0.0.1" }, "tag": "api" }
  ],
  "routing": { "rules": [{ "type": "field", "inboundTag": ["api"], "outboundTag": "api" }] }
}

Query and manage users at runtime:

xray api stats --server=127.0.0.1:10085 -name "user>>>alice@proxy>>>traffic>>>uplink"
xray api adi --server=127.0.0.1:10085 --inbound-tag proxy --id "new-uuid" --email "newuser@proxy"
xray api rmi --server=127.0.0.1:10085 --inbound-tag proxy --email "olduser@proxy"

Step 6: Routing Rules & Monitoring

Route by domain/IP/geo:

{
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      { "type": "field", "domain": ["geosite:category-ads-all"], "outboundTag": "block" },
      { "type": "field", "ip": ["geoip:private"], "outboundTag": "block" },
      { "type": "field", "network": "tcp,udp", "outboundTag": "proxy" }
    ]
  }
}

Monitoring:

systemctl status xray
journalctl -u xray -f
grep "accepted" /var/log/xray/access.log | awk '{print $3}' | sort | uniq -c | sort -rn

Firewall:

ufw allow 443/tcp && ufw allow 443/udp && ufw enable

Examples

Example 1: Deploy a VLESS + Reality proxy server for a small team

User prompt: "Set up Xray on our Debian 12 VPS at 198.51.100.30 using VLESS with Reality transport. Create accounts for alice, bob, and carol. Use microsoft.com as the Reality target and give me the share links for v2rayNG."

The agent will install Xray via the official script, generate a UUID for each user and an X25519 key pair, build a config.json with a VLESS inbound on port 443 using Reality settings targeting www.microsoft.com, add three client entries with xtls-rprx-vision flow, add routing rules to block private IPs, enable and start the xray service, open port 443 in the firewall, and output three vless:// share links with the server IP, public key, short ID, and SNI.

Example 2: Set up a CDN-fronted VLESS proxy with Cloudflare and a fallback website

User prompt: "I have proxy.mysite.com pointing to our server through Cloudflare. Configure Xray with VLESS over WebSocket on /secret-ws so traffic goes through Cloudflare's CDN. Non-proxy visitors should see a normal nginx website."

The agent will obtain a Let's Encrypt certificate with certbot, configure Xray with a main VLESS+TLS inbound on port 443 with a fallback to nginx on port 8080, add a second VLESS+WebSocket inbound on localhost:8443 with path /secret-ws, set up nginx to serve a static site on port 8080, verify Cloudflare SSL is set to Full (Strict) with WebSockets enabled, and provide the client connection string with the WebSocket path and Cloudflare SNI.

Guidelines

• Always use VLESS + Reality for new deployments; it requires no domain or certificate and is the hardest protocol to detect and block
• Set "alterId": 0 for all VMess users to enable mandatory AEAD encryption; non-zero alterId uses the deprecated, less secure legacy format
• Block access to private IP ranges (geoip:private) in routing rules to prevent the proxy from being used for SSRF attacks against internal services
• Use the xray api commands to add and remove users at runtime without restarting the service, which avoids disconnecting active users
• Choose the Reality dest and serverNames from a popular website (microsoft.com, apple.com) hosted on a different IP than your server, and ensure that site supports TLS 1.3 and HTTP/2
• Enable the stats API with per-user tracking (statsUserUplink/statsUserDownlink) to monitor bandwidth usage and detect abuse