Xray-core

Developers can integrate Xray-core using various wrappers, SDKs, and tools:

Wrappers and SDKs

• C/C++: XTLS/libXray
• Python: Xray-core-python
• Flutter: flutter_vless
• Go/Other: xtls-sdk, xtlsapi, AndroidLibXrayLite, xray-api

Xray Tools

• xray-knife (Tooling)
• xray-checker (Checker)

Compatible Cores

Other proxy cores that support Xray protocols (VLESS, XTLS, REALITY, XUDP, PLUX) include Amnezia VPN, mihomo, and sing-box.

To compile Xray-core on Linux or macOS, use the following command. It disables CGO, trims paths, and uses linker flags (-s -w) to reduce the binary size.

CGO_ENABLED=0 go build -o xray -trimpath -buildvcs=false -ldflags="-s -w -buildid=" -v ./main

To use TUN on Windows, the wintun.dll specific to your architecture must be placed in the same directory as the Xray.exe binary.

Once Xray starts, a network adapter will be created. To route traffic through it manually:

1. Identify the interface ID using route print.
2. Add an on-link route for the desired destination.

Note on IPv6: For IPv6 to work, the interface must have a routable IPv6 address. You can manually assign a private address (e.g., fc00::a:b:c:d/64) to enable traffic flow.

# 1. Find the interface ID
route print

# 2. Add an on-link route (assuming interface ID is 47)
route add 1.1.1.1 mask 255.0.0.0 0.0.0.0 if 47

On Linux systems using systemd-networkd, you can automate the configuration of the xray0 interface. Create a file (e.g., /etc/systemd/networkd/90-xray0.network) to manage the interface and its routing table when Xray starts.

This example uses routing table 1001 and funnels all traffic from the 192.168.0.0/24 subnet through it.

[Match]
Name = xray0

[Network]
KeepConfiguration = yes

[Link]
ActivationPolicy = manual
RequiredForOnline = no

[Route]
Table = 1001
Destination = 0.0.0.0/0

[RoutingPolicyRule]
From = 192.168.0.0/24
Table = 1001

Xray-core supports various protocols and configurations. You can find implementation examples and tutorials for:

Common Configurations

• VLESS-XTLS-uTLS-REALITY: High-performance configuration using the REALITY protocol.
• VLESS-TCP-XTLS-Vision: Optimized for TCP transport.
• All-in-One-fallbacks-Nginx: Integration with Nginx for fallback capabilities.

Learning Resources

• Xray-examples Repository: Contains curated configuration examples.
• Tutorials: Guides are available for XTLS Vision, REALITY (English), and WireGuard inbounds.

FreeBSD support is implemented via tun(4).

1. Interface Naming: Use the scheme tunN (e.g., tun0, tun10) in your configuration.
2. IP Assignment: You must manually set an IP address to the interface before use.
3. Routing: Use the route command to attach specific networks to the interface.

Warning: Do not route the default route through the tun interface, as this will cause a network loop and immediate failure.

# Set an IP address
ifconfig tun0 inet 169.254.10.1/30

# Attach routing to the interface
route add -net 1.1.1.0/24 -iface tun10

# Attach IPv6 hosts
route add -inet6 -host 2606:4700:4700::1111 -iface tun10
route add -inet6 -host 2606:4700:4700::1001 -iface tun10

Android integration uses the VpnService API to provide a TUN file descriptor (fd).

1. Obtain FD: Get the file descriptor from the VpnService instance.
2. Set Environment Variable: Before starting Xray, set the environment variable xray.tun.fd or XRAY_TUN_FD to the integer value of the file descriptor.
3. Build: Use gomobile to create an Android library.

This can be implemented via Kotlin/Java or by exposing Go functions through gomobile bindings.

// Obtain the fd from VpnService
val tunFd = vpnInterface.fd

// Before starting Xray, set the environment variable:
// XRAY_TUN_FD = tunFd.toString()

gomobile bind -target=android

Xray-core can be used via various graphical user interfaces across different platforms:

• Windows: v2rayN, Furious, Invisible Man - Xray, AnyPortal, GenyConnect, OneXray, XrayUI-dev.
• Android: v2rayNG, X-flutter, SaeedDev94/Xray, SimpleXray, XrayFA, AnyPortal, OneXray, AsteriskNG.
• iOS & macOS: Happ, Streisand, OneXray, INCY, V2rayU, V2RayXS, GoXRay.
• Linux: v2rayA, Furious, GorzRay, GoXRay, AnyPortal, v2rayN, GenyConnect, OneXray.
• OpenWrt: PassWall, PassWall 2, ShadowSocksR Plus+, luci-app-xray.
• Asuswrt-Merlin: XRAYUI, fancyss.

For 32-bit MIPS or MIPSLE targets, use this specific build command which uses a slightly different gcflags configuration.

CGO_ENABLED=0 go build -o xray -trimpath -buildvcs=false -gcflags="-l=4" -ldflags="-X github.com/xtls/xray-core/core.build=REPLACE -s -w -buildid=" -v ./main

Xray-core can be installed using several methods depending on your environment:

Linux

• Official Script: Use the XTLS/Xray-install repository.
• Tempest: Supports systemd and OpenRC (Linux-only).

Docker

• Official Image: ghcr.io/xtls/xray-core
• Other Images: teddysun/xray, wulabing/xray_docker

Web Panels

For managed interfaces, use panels such as:

• Remnawave, 3X-UI, PasarGuard, Xray-UI, X-Panel, Marzban, Hiddify, TX-UI, or CELERITY.

Other Methods

• Homebrew (macOS/Linux): brew install xray
• Magisk (Android): Magic_V2Ray or Xray_For_Magisk.
• One-Click Scripts: Various community scripts like v2ray-agent, Xray_onekey, or reality-ezpz are available.

To compile Xray-core on Windows using PowerShell, ensure CGO_ENABLED is set to 0 to avoid C dependencies. This command produces an xray.exe binary with stripped debug information and no build ID for a smaller footprint.

$env:CGO_ENABLED=0
go build -o xray.exe -trimpath -buildvcs=false -ldflags="-s -w -buildid=" -v ./main