simple-xray-core is a one line installer that turns Xray into a managed multi user service

Two scripts, no panel, and the reasoning behind it

The repository contains the Xray core installation script with some improvements, and the top level entries are just three files: the readme, xray-install and xhttp-xray-install. There is no build system, no package manifest and no source code beyond the two shell scripts.

The premise in the readme is that panels such as 3x-ui and Marzban are graphical front ends over the Xray core, and that the core itself can run without any panel and be managed entirely from a terminal. The stated advantage of the bare core is that you do not have to deal with domains and TLS certificates, and the official documentation already covers installing and administering the core by hand.

What this script adds is convenience. It installs the core on the server, creates the configuration files and several executable files for convenient user management, which is the part a panel would otherwise do for you.

The system requirements are stated as one CPU, 1 GB of RAM, 10 GB of disk, and Ubuntu 22 x64 or Ubuntu 24 x64. The readme is careful about the tested platforms: the script was created and tested under Ubuntu 22 x64 and Ubuntu 24 x64, and on other operating systems it may work incorrectly.

There is also a section about a VPS for the panel, with an affiliate link to a hosting provider and a note that more than 36 locations are available.

The install is one piped command, and that is the whole procedure

The usage instructions describe an older instruction set taken from a video, and they are short. To download and run the script, the readme gives one command:

wget -qO- https://raw.githubusercontent.com/ServerTechnologies/simple-xray-core/refs/heads/main/xray-install | bash

The mechanics are worth naming. The script is fetched over HTTPS from a branch named main and piped straight into bash, which means the code that configures your server is not something you can read before it runs, and it is not pinned to a commit. The upstream Xray installer is fetched the same way in the update and removal instructions, from the XTLS/Xray-install repository, which means the core itself also comes from a remote script at install time.

That pattern is the normal way these installers are written, and it is also the reason to read them before running them. The readme does list the exact commands, which files are created and where they live, so the state of the machine after the script runs is documented even though the script itself is not.

The configuration lives under /usr/local/etc/xray/, with the main file at /usr/local/etc/xray/config.json and the key data in a separate .keys file. The helper commands are installed as executables in /usr/local/bin, and the removal section confirms the exact set: userlist, mainuser, newuser, rmuser and sharelink.

Five commands stand in for a whole panel

The user management interface is a set of shell commands, and the readme lists them one by one.

To list all clients, the command is:

userlist

To print the connection link and a QR code for the main user, it is:

mainuser

To create a new user, to delete a user, and to create a connection link, the commands are newuser, rmuser and sharelink respectively.

The pattern is worth noticing. The panel products manage users through a web interface with a database, and this replaces that with a script per operation and, it appears, a file listing the clients. The readme also says a file named help is created in the user's home directory containing hints with descriptions of the commands, and it can be read with:

cat help

The instruction notes you need to be in the user's home directory to see it, which is a small detail that says the help file is written relative to the home directory rather than installed system wide.

So the operational model is: edit the configuration files, or use the five commands, and read the help file when you forget which one does what.

The transport choice is the real decision, and XHTTP is the newer path

There is a section about problems accessing the Vless protocol over the TCP transport, and it opens by saying many people noticed some issues with Vless availability on TCP. The response was a variation of the script using the XHTTP protocol, with an important warning attached: XHTTP is a comparatively new transport, so far from all clients support it, and a list of clients exists in the text version of the video on GitHub.

The two install scripts in the repository correspond exactly to that split. xray-install is the TCP version, and the XHTTP variant is installed with:

wget -qO- https://raw.githubusercontent.com/ServerTechnologies/simple-xray-core/refs/heads/main/xhttp-xray-install | bash

The warning attached to that command is unambiguous: all users will be deleted and will have to be connected again.

The readme also gives a middle path for anyone who already installed the TCP version and does not want to wipe it. The core can be updated in place with the upstream installer:

bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install

And if the update does not help, a new version of the script with the XHTTP transport can be installed. Before that, the readme advises making a backup of the configuration file and the key file so you can roll back to TCP if needed:

cp /usr/local/etc/xray/config.json /usr/local/etc/xray/config.json.old
cp /usr/local/etc/xray/.keys /usr/local/etc/xray/.keys.old

The restore step is the same file layout in reverse, followed by a service restart.

Rollback and removal are documented with the same care as setup

The restoration procedure moves the old files back into place and restarts the service:

wget -qO- https://raw.githubusercontent.com/ServerTechnologies/simple-xray-core/refs/heads/main/xray-install | bash
mv /usr/local/etc/xray/config.json.old /usr/local/etc/xray/config.json
mv /usr/local/etc/xray/.keys.old /usr/local/etc/xray/.keys
systemctl restart xray

The readme explains what that does: the core is reinstalled, the old configuration is restored including the old clients. So the backup is not just a safety net for the configuration file, it is the thing that preserves the client list, which is why the .keys file is backed up alongside the config.

The removal section at the end is equally specific. The core is removed through the upstream installer with the remove argument, and then the configuration file, the key file and each of the five helper commands are deleted by name:

bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ remove
rm /usr/local/etc/xray/config.json
rm /usr/local/etc/xray/.keys
rm /usr/local/bin/userlist
rm /usr/local/bin/mainuser
rm /usr/local/bin/newuser
rm /usr/local/bin/rmuser
rm /usr/local/bin/sharelink

That is a genuinely complete removal path, which is more than most install scripts offer.

For the client side, the readme lists apps by platform: v2rayN, Furious, Invisible Man and V2RayXS for Windows; v2rayNG, X-flutter and SaeedDev94/Xray for Android; Streisand, Happ and OneXray for iOS and macOS arm64; V2rayU, V2RayXS, Furious and OneXray for macOS; and Nekoray, v2rayA and Furious on Linux. The upstream core and the Russian language documentation are linked in the useful links section.

Where this is the wrong tool, and what it costs to adopt

The first limitation is the licence. The repository listing records no licence identifier for the project, and the readme does not state one either. For a shell script that installs a proxy node and manages user credentials, that is the first thing to resolve, because without a grant you do not obviously have permission to redistribute or modify the scripts. The upstream Xray core has its own licence and the readme links to the Xray-core project, but that covers the core, not this repository's additions.

The second limitation is the trust model. Every step of the install and the update fetches a script from a URL and pipes it into a shell. That is the standard idiom for these installers and it is also a supply chain surface: the code that ends up configuring your server was not on your disk when you decided to run it. Reading the script before running it costs a minute and removes the question, and the readme at least tells you which files you will end up with.

The third is platform. Ubuntu 22 x64 and Ubuntu 24 x64 are the tested targets, and the readme warns that other systems may work incorrectly. That is a narrow support statement for a script that also manages a systemd service and writes into /usr/local.

The alternative to weigh is the upstream Xray install script on its own, which the readme itself points to, plus the official documentation. The difference is that this repository adds the user management commands and the panel-free workflow, and takes on the trust and licence questions in exchange. If you want a supported deployment with a licence you can read, a panel product or the upstream documentation path is the better trade. If you want a node with no domain and no certificate and a handful of shell commands to hand out access, that is exactly what these two scripts do.

Editorial conclusion

Adopt simple-xray-core if you run your own Xray node and want the user management commands without setting up a panel, since the scripts automate the config, the key files and the helper commands in one step. Do not adopt it if you want a maintained, licensed distribution, because the repository states no licence and the scripts pull the core from a remote URL over your shell. Verify first that you read the whole install script before piping it to bash, that your server meets the stated requirement of 1 CPU, 1 GB of RAM and 10 GB of disk on Ubuntu 22 or 24 x64, and that the transport you choose, TCP or XHTTP, is supported by the clients your users actually run.

Frequently asked questions

Official sources

1. Issues
2. README
3. ServerTechnologies/simple-xray-core on GitHub