Environment Variables

Xray can read several environment variables to adjust resource paths, config loading behavior, and a few low-level toggles.

For each option, Xray accepts both forms:

• dot form: e.g. xray.location.asset
• uppercase underscore form: e.g. XRAY_LOCATION_ASSET

Asset Location (geoip/geosite, etc.)

• Name: xray.location.asset or XRAY_LOCATION_ASSET
• Default: Xray executable directory

Specifies the directory for asset files (such as geoip.dat and geosite.dat).

On non-Windows systems, if the asset file is not found in the directory above, Xray will also try (in order):

• /usr/local/share/xray/
• /usr/share/xray/
• /opt/share/xray/

Config Directory (config.json)

• Name: xray.location.config or XRAY_LOCATION_CONFIG
• Default: Xray executable directory

Specifies a directory where Xray looks for config.json.

TIP

When xray run is started without -c/-config, it first searches the working directory for config.json/jsonc/toml/yaml/yml, then falls back to config.json under this directory, and finally reads from STDIN. See Command Arguments.

Multiple Config Directory (confdir)

• Name: xray.location.confdir or XRAY_LOCATION_CONFDIR
• Default: ""

When running xray run without the -confdir flag, if this variable points to an existing directory, Xray will load all recognized formats (json/jsonc/yaml/yml/toml) from that directory, in filename order, and merge them (see Multiple Config Files).

WARNING

If confdir contains both JSON (*.json/*.jsonc) and YAML (*.yaml/*.yml) files, Xray will fail fast.

Certificate Directory (relative path resolution)

• Name: xray.location.cert or XRAY_LOCATION_CERT
• Default: Xray executable directory

If a certificate file path (e.g. certificateFile / keyFile) is relative, it will be resolved under this directory. Absolute paths are not affected.

Tool Directory (xctl, etc.)

• Name: xray.location.tool or XRAY_LOCATION_TOOL
• Default: Xray executable directory

Used to locate external tools (such as xctl). Xray will try this directory first and then the system PATH.

IO Optimizations (readv / splice)

readv reader optimization

• Name: xray.buf.readv or XRAY_BUF_READV
• Default: enabled (unset, or set to auto / enable)

Controls whether Xray uses readv(2) for eligible connections. Set it to any other value (e.g. disable) to turn it off.

splice zero-copy (Freedom)

• Name: xray.buf.splice or XRAY_BUF_SPLICE
• Default: enabled (unset, or set to auto / enable)

Controls whether the Freedom outbound uses splice/zero-copy when possible. Set it to any other value (e.g. disable) to turn it off.

VMess Padding Override

• Name: xray.vmess.padding or XRAY_VMESS_PADDING
• Default: unset (VMess default behavior)

If this variable is set (regardless of its value), Xray will force-enable VMess global padding (mainly affecting security: "none" and similar cases).

UDP Cone Toggle

• Name: xray.cone.disabled or XRAY_CONE_DISABLED
• Default: not disabled (Cone enabled)

If the value is exactly true, Cone behavior will be disabled (affecting some UDP inbound session mapping and XUDP globalID generation).

Default Buffer Size (Policy)

• Name: xray.ray.buffer.size or XRAY_RAY_BUFFER_SIZE

Sets the default policy.bufferSize (unit: MB). See Policy.

Browser Dialer

• Name: xray.browser.dialer or XRAY_BROWSER_DIALER

When set to a listen address (e.g. 127.0.0.1:8080), enables Browser Dialer. See Browser Dialer.

XUDP Debug

Enable debug logs

• Name: xray.xudp.show or XRAY_XUDP_SHOW
• Default: off

If set to true (case-insensitive), Xray prints XUDP debug information (such as globalID).

Pin BaseKey

• Name: xray.xudp.basekey or XRAY_XUDP_BASEKEY
• Default: randomly generated each start

Pins the BaseKey used for XUDP globalID. The value must be Base64-URL (raw, no =) of 32 bytes; an invalid value will cause Xray to panic on startup.