Node Installation

Source code

Panel — xray-panel/backend · node — xray-panel/node · subscription page — xray-panel/subscription-page

The node is a container on a proxy server. It does not connect anywhere itself: the panel reaches it over HTTPS with mutual TLS and JWT.

1. Get the SECRET_KEY

In the panel: Nodes → create node. The panel shows a SECRET_KEY — a long base64 string. Copy it in full: it is single-use.

It contains certificates and keys: the CA, the node certificate, the private key, and the JWT public key. The node validates them at startup and refuses to run if anything does not match.

2. Start

docker run -d \
  --name xpanel-node \
  --restart unless-stopped \
  --network host \
  --cap-add NET_ADMIN \
  --ulimit nofile=1048576:1048576 \
  -e NODE_PORT=2222 \
  -e SECRET_KEY="<paste the SECRET_KEY>" \
  ghcr.io/xray-panel/node:latest

The same thing as compose:

docker-compose.yml

services:
  xpanelnode:
    image: ghcr.io/xray-panel/node:latest
    container_name: xpanel-node
    restart: unless-stopped
    network_mode: host
    cap_add:
      - NET_ADMIN
    ulimits:
      nofile:
        soft: 1048576
        hard: 1048576
    environment:
      - NODE_PORT=2222
      - SECRET_KEY=${SECRET_KEY}

Option	Purpose
--network host	Xray listens on ports itself; port forwarding breaks detection of the real client IP
--cap-add NET_ADMIN	required by plugins (torrent blocking via nftables); can be omitted if you use no plugins
--ulimit nofile	a high file descriptor limit for a large number of connections

3. Verification

At startup the node log prints a SECRET_KEY validation report and the core version:

docker logs -f xpanel-node

Xray version: Xray 26.9.9

The panel must show the node as connected within a minute. If the node does not appear:

• check that NODE_PORT is reachable from the panel server (nc -vz <node ip> 2222), not from your browser;
• make sure SECRET_KEY was copied in full, without line breaks;
• look at the container log — with an invalid key the node prints the reason for the failure.

4. Plugins

Node plugins (for example, torrent-blocker) are installed on the node page in the panel. Plugins that work with nftables require NET_ADMIN and a kernel with the nftables module. If you do not use plugins, you can omit the flag.

5. Xray logs

docker exec -it xpanel-node xlogs

To clear them, use Logs in the panel, the "Node system logs" section, the "Clear logs" button. The node rotates the file, Xray is not restarted and traffic is not interrupted. Manually:

docker exec -it xpanel-node cli --clear-logs

Multiple nodes

Add nodes one at a time: each one gets its own SECRET_KEY and its own certificate. A shared key for several servers is not supported — if one server were compromised, all of them would have to be reissued.