Lua Scripts

Lua scripts provide a flexible way to extend Xray, implement custom functionality, and interact with the core.

Getting Started

Start with Runtime Environment and Script Loading to learn about Lua support, module loading, and how script files are located.

Writing Guides

Choose a guide for the functionality you need, start with the minimal example, and build your own script step by step:

Guide	Purpose	Contents
Routing Scripts	Customize routing rules	Outbound selection, load balancing, and IP-based routing after explicit resolution
DNS Scripts	Customize DNS queries	Upstream selection, query fallback, and result filtering

The current routing and DNS scripts both use pooled instances. When writing scripts, read about the pooled lifecycle to understand top-level initialization and state retention.

Reference

Hook

A Hook is a Lua function that the core calls at a specific point. The script entry point determines the available Hooks and their calling conventions; one entry point can have multiple Hooks. Refer to the documentation for each entry point to find out which Hooks you need to implement.

The currently supported entry points and Hooks are listed below. See each Hook's reference page for parameters, return values, and failure behavior:

Script entry point	Hook
routing.script	HandleRoute
dns.script	HandleDNSQuery

Data Types

In addition to Lua's built-in types, Xray Lua uses types such as net.IP, Go slices, and error. See Data Types for their representation and use in Lua.

Module API

Browse the module APIs by functionality:

Module	Purpose
xray.router	Policy routing
xray.dns	Domain resolution
xray.geodata	Domain and IP matching and filtering
xray.log	Log output