luci-app-xray: an Xray client for OpenWrt with a LuCI interface

The problem: a modern proxy core and a router interface that predates it

OpenWrt is a router distribution with a web interface called LuCI, and LuCI is built for configuring a few thousand lines of firewall and network configuration. Xray is a proxy core with inbounds, outbounds, routing rules, DNS resolvers, sniffing and a transport layer that changes from release to release. Running Xray on a router therefore means writing configuration by hand, and a router's own web interface is exactly the place where you would rather click.

luci-app-xray is that bridge. The project description says it focuses on making the most of Xray, listing HTTP, HTTPS, Socks and TProxy inbounds, support for multiple protocols, a DNS server, a bridge for reverse proxying and even an HTTPS proxy server for actual HTTP services, while keeping thin and elegant.

The audience is an OpenWrt user who has chosen Xray as the core and wants a GUI, and the design goal of thin and elegant is a claim worth taking seriously, because the alternative in this space is a package that rewrites large parts of the firewall and DNS configuration on every change.

The licence is MPL-2.0, the default branch is master, the last push was on 2026-09-22, and there are no GitHub releases, so the version to track is the one in the changelog rather than a tag.

The repository layout is small: a core/ directory for the app itself, a geodata/ directory, a status/ directory, an AGENTS.md and the usual metadata. That is a LuCI app, which is a directory of JavaScript and configuration rather than a large program.

What the app actually manages

The feature set in the project description is a list of Xray concepts exposed as form fields, and reading it tells you what the app considers first class.

The inbounds are the entry points: HTTP, HTTPS, Socks and TProxy. TProxy is the one that matters on a router, because it is how traffic from the LAN is intercepted and redirected without changing the client configuration, and the changelog shows that this area got the most attention, with entries for geoip in manual transparent proxy, dnsmasq global integration mode, and a fix for bypass replies to inbound connections in July 2026.

The DNS side is equally central. The project ships a geodata/ directory and a geodata reader feature, and the changelog records dnsmasq global integration mode, a change to the default FakeDNS IPv6 pool for Dnsmasq 2.93 in June 2026, and a ping response for FakeDNS pools in May 2026. FakeDNS in particular is the recommended replacement for sniffing, and the changelog shows work on the dnsmasq jail adaptation and on restart behaviour when the dnsmasq configuration changes.

The bridge mode is a reverse proxy, which turns the router into a front door for services running behind it, and the changelog shows a custom configuration hook added in November 2023, which is the escape hatch for settings the interface does not model.

On the outbound side, the changelog records support for several protocols and their transport variants, including vless encryption in January 2026, hysteria outbound in the same period, basic splithttp support and httpupgrade support in November 2024, and a fix for a reality deserialization issue in May 2024. The entry for 2026-09-08 says the app was adapted for Xray 26.9.8 with the version bumped to 3.7.2, which is the clearest sign that this package tracks the core's release cycle closely.

The deprecations, which the documentation puts first

Most of the warnings section is about things being taken away, and the placement is deliberate: the project puts the deprecations before the installation instructions, which tells you what a reader needs to know first.

The first deprecation is the global SOCKS and HTTP inbound. For security reasons, a global SOCKS or HTTP inbound that listens on 0.0.0.0, on port 1080 or 1081 by default, is deprecated and will be removed in the next major version, 4.0.0. The reasoning is sound, because a proxy listening on every interface of a router is an open proxy for anyone who can reach the port. The migration path is spelled out: those settings move to the preview app, and you should use Extra Inbound to add ports manually, avoiding common ports like 1080, and you should set the listen addresses carefully, then adjust the workloads that were using them.

The second deprecation covers sniffing and global custom settings, both deprecated since version 3.2.0 and moved to the preview app. Global custom settings will be removed in 4.0.0, and the Custom Configuration Hook is the supported route for global custom settings. Sniffing, the documentation says, might get completely reimplemented later, and it recommends FakeDNS instead to avoid incompatibilities.

The practical reading is that the stable interface in 3.x is narrower than it was in 2.x, and narrower than the interface in 4.0.0 will be. A configuration you write today against the global inbound will break on upgrade, so the Extra Inbound path is the one to learn now.

The OpenWrt floor, and the REALITY caveat

There is a hard compatibility line, and the project states it in bold.

This project does not support LEDE or OpenWrt prior to 22.03, and it does not support Lean's OpenWrt Source, which uses a variant of LuCI shipped with OpenWrt 18.06. The stated reasons are the requirements of firewall4 and of client-side rendering LuCI. If that is your situation, the documentation says to use Passwall or similar projects instead, with links in the XTLS Xray-core repository.

That is a real constraint rather than a technicality, because firewall4 and the newer LuCI rendering model are what make the generated firewall rules and the web interface work. A package that generates rules for one firewall implementation and is rendered by a different LuCI will misbehave in ways that are hard to debug, so refusing those platforms is the right call.

The second caveat is about REALITY support, which the documentation calls experimental. The reason given is that the protocol may change quite frequently before official documents about it are released, and you should keep in mind possibly breaking changes. So a REALITY configuration is a moving target, and one that the interface may regenerate.

There is also a common operational problem worth knowing before you hit it. If you see the warning that at least one of the asset files, geoip.dat or geosite.dat, is not found under /usr/share/xray, Xray may not work properly. The fix given is:

opkg update && opkg install v2ray-geoip v2ray-geosite

and if that does not do it, the documentation points at issue 52. The geodata is a separate package from the app, which is why the failure looks disconnected from the thing you just installed.

Installing: build it into your OpenWrt, or let a workflow produce the ipks

There are two documented routes, and they suit different kinds of user.

The first is building inside an OpenWrt build tree. You add a feed entry, and then update and install the feeds:

src-git-full luci_app_xray https://github.com/yichya/luci-app-xray

The line goes into feeds.conf.default, and then you run:

./scripts/feeds update -a; ./scripts/feeds install -a

The alternative is to clone this repository under a directory called package in your build tree, which avoids the feed entry entirely. Either way, the app then appears under Extra Packages in the image configuration, which is where LuCI apps that are not part of the official feeds are selected.

The second route is the one that avoids an OpenWrt build tree altogether. You fork the repository, create a release by pushing a tag, wait until the GitHub actions finish, and then install the produced packages with:

opkg -i *

The changelog records the work that makes this route practical, with an entry from April 2026 about enhancing the build workflow with multiple SDK versions and improved file handling, and an earlier one about using OpenWrt SDK 23.05.5 to avoid using apk. The build workflow is therefore the project's own release process, and forking it is the intended way to produce a package set matched to your OpenWrt version.

For a user who just wants the app, the second route is quicker, but it means you are running a package built by somebody else's workflow, so the OpenWrt version and the Xray core version in it are fixed at build time.

The preview app, and what the changelog says about stability

Some features are unstable enough that they are not in the main interface, and the mechanism for reaching them is simple. You select Preview or Deprecated in the Extra Settings tab, you reboot the router, and a new menu option called Xray (preview) appears under Services.

The reasoning is that a router is an appliance, and a feature that changes the firewall and the DNS configuration on a device that is also the user's gateway is not somewhere to experiment. The preview menu keeps the risky parts one click away and clearly labelled.

The changelog is long and dated, and reading it is the most useful thing a prospective user can do, because it shows what the project actually spends its time on. The recent entries since 3.7.0 are dominated by compatibility work: adapting for Xray 26.9.8, the Dnsmasq 2.93 FakeDNS pool default, the build workflow with multiple SDK versions, the legacy reverse deprecation adaptation, and a Cloudflare Origin RSA CA. Earlier entries show the feature work: vless encryption and hysteria outbound, the geodata reader, geoip in manual transparent proxy, a detailed status page via metrics, splithttp and httpupgrade support, a custom configuration hook, dns hijacking in the preview app, and the roundRobin balancer added in December 2023.

Read together, that says the project spends its effort on staying current with Xray and with OpenWrt's DNS stack, and adds protocol support as the core gains it.

The project also states plainly that it may change its code structure, configuration files format, user interface or dependencies quite frequently since it is still in its very early stage. That is a candid description of a fast moving package, and it is the reason to read the changelog before every upgrade rather than after one.

Licence, maintenance and where this is the wrong tool

The licence is MPL-2.0, with the LICENSE file at the root of the repository. That is a reasonable choice for a LuCI app, because it allows the package to be redistributed inside an OpenWrt firmware image, which is how most users get it, without requiring the whole image to be published under the same terms.

The repository is not archived, the last push was on 2026-09-22, and there are no GitHub releases. The tracked version comes from the changelog, and the most recent entry is the September 2026 adaptation for Xray 26.9.8 with the version bumped to 3.7.2.

Where this is the wrong tool is fairly clear. If you run an OpenWrt older than 22.03, or one built from Lean's source, the project will not support you and it tells you to use Passwall instead. If you want a stable configuration that will survive a major version, this package is moving towards 4.0.0 with the global inbounds and the global custom settings removed, so the settings you use now are worth writing down. And if your requirement is a stable production router, the honest position is that this is a fast moving package with a preview menu for the unstable parts, maintained by someone who publishes the changelog in detail but does not publish tagged releases.

What it does offer is a way to run Xray on OpenWrt without hand writing configuration and firewall rules, with the protocol and transport support following the core, and with a clear statement of what is going away and when. For the audience it is written for, that is a good trade, and the deprecation warnings are the part of the documentation worth reading twice.

Editorial conclusion

Adopt luci-app-xray if you run OpenWrt 22.03 or newer and want Xray managed from the LuCI interface rather than from hand written configuration files, and if you are willing to read the deprecation warnings before you configure it. Do not adopt it on older OpenWrt, where the firewall4 and client side rendering requirements are not met and the documentation points you at Passwall instead. Before you configure anything, read the warnings section, because the global SOCKS and HTTP inbounds and the sniffing options are deprecated and scheduled for removal in 4.0.0, and use the Extra Inbound and Custom Configuration Hook paths rather than the settings that are on their way out.

Frequently asked questions

Official sources

1. Issues
2. License: MPL-2.0
3. README
4. yichya/luci-app-xray on GitHub