How to deploy a xray node

This guidance includes how to deploy, run and make RPC calls.

Suppose the readers are able to use Linux,Mac or Windows command line. If you are not familiar with command line, or just interested in using GUI wallet, please refer to another document about xray Wallet Tutorial

Get xray Node

There are at least 4 ways to get a xray node, you can choose any way:

1. Download the binaries

If you do not care much about xray's source code, the easiest way to abtain xray node is to download the latest binaries on the xray release page. Currently it supports Linux, Window, OSX. It is highly recommanded to download the latest version. In this guidance, we will use v0.14.13 version as an example。

(Note: the version number you see might be different, here is v0.14.13, but other key words except for version are the same.)

  • For Mac user:xray-v1-osx64.tar.gz
  • For Linux users: xray-v1-i686-pc-linux-gnu.tar.gz(32bit) or xray-v1-x86_64-linux-gnu.tar.gz(64bit)
  • For Windows or
  • For Raspberry Pixray-v1-arm-linux-gnueabihf.tar.gz

Decompress after downloading, then you will get xrayd and xray-cli under the path <your path>/bin.

2. apt install for Linux users

Please refer to,Current support Ubuntu,Debian and Mint。

Raspberry Pi users can also use apt,please refer to

After installation, you should be able to run xrayd and xray-clidirectly in the terminal。

3. Compiler from source code

If you want to compile latest xray from source code, please pull the latest source from github :

The instruction for compilation :。Currently we recommand to compile on Linux or OSX, while other platforms might need more configuration.

After compilation, you also get xrayd and xray-cli under the path <your path>/src/

4. Get xray node docker image "work continues"

Suppose user has docker environment installed correctly. (what is docker?)

The xray official docker image on docker hub is xray/xray, you can pull it by docker command :

docker pull xray/xray:latest

All the four ways above cand get xray nodes. There are two important binaries which are related to deployment and RPC calls:

  • xrayd:xray core program, i.e. xray fullnode program.
  • xray-cli:xray command line interface,interact with xrayd, achieve RPC calls.

Deploy xray node

For the instruction for xray docker images, please refer to "How to launch xray with docker".

Other normal deployment methods are almost the same, here we take Ubuntu as an example. The commands in Mac and windows are exactly the same.

Run xray fullnode with ./xrayd

./xrayd -daemon

This with launch a xrayd daemon with the option -daemon. If user are interested in the event logs about smart contract, please add one more option -logevents.

More options can be found:

./xrayd -help

To stop running:

./xray-cli stop

The default data path for different platforms:

  • Linux:~/.xray/
  • Mac OSX:~/Library/Application Support/xray
  • Windows:%APPDATA%\xray

You can also use -datadir to set your own data path。

xray node will sync all the historical block data for first launch, and saves to datadir. It might take some time. Then diagnostics for the node can be found under the data path ~/.xray/debug.log

Local RPC call

When the xray node is running, we can use xray command line interface xray-cli to interact with xrayd, and make local RPC calls.


[email protected]:~/xray-0.14.3/bin$ ./xray-cli getinfo
  "version": 140300,
  "protocolversion": 70016,
  "walletversion": 169900,
  "balance": 0.00000000,
  "stake": 0.00000000,
  "blocks": 138057,
  "timeoffset": 0,
  "connections": 8,
  "proxy": "",
  "difficulty": {
    "proof-of-work": 1.52587890625e-05,
    "proof-of-stake": 803262.7821734004,
  "testnet": false,
  "moneysupply": 100028504,
  "keypoololdest": 1633641554,
  "keypoolsize": 1000,
  "paytxfee": 0.00000000,
  "relayfee": 0.00400000,
  "errors": ""

To get all RPC command list:

./xray-cli help

To get help for specific RPC command, use ./xray-cli help <RPCcmd>,e.g.:

./xray-cli help getinfo

JsonRPC settings

You can get the jsonrpc example by using (here we use getinfo as an example): ./xray-cli help getinfo

> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getinfo", "params": [] }' -H 'content-type: text/plain;'

The example shows detailed format for jsonrpc content. However, it can only be called after setting rpcuser and rpcpassword. There are two ways to set the parameters, you can choose either.

Method 1:Create config file ~/.xray/xray.conf,which should include:

rpcuser=test  #rpc user name, (necessary)
rpcpassword=test1234  #rpc password, (necessary)
# By default, only local jsonrpc is allowed
# Remote connection is allowed only when setting rpcallowip as following:
# both ipv4 and ipv6 can be set, e.g.:

For more config settings, please refer to :xray.conf example

After creating the config file, please restart the node to finish settings.

Method 2:Restart xray node with following options:

./xrayd -daemon -rpcuser=test -rpcpassword=test1234 -rpcallowip=

The meaning of options rpcuser, rpcpassword and rpcallowip are all the same with the config file above.

RPC call example

You can make remote RPC calls after the settings above. Here is an example: Suppose the xray node is running on an Ubuntu machine, whose ip is, default port=3889. Now we try to make jsonrpc call in a remote macbook:

zhongwenbins-MacBook-Pro:~ zhongwenbin$ curl --user test:test1234 --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getinfo", "params": [] }' -H 'content-type: text/plain;'

The result is identical with local call.

You can also use tools like postman to get the same result:


Nginx settings(optional)

As the example above, you might find that it is quite complicated to make remote jsonrpc, since you must include rpcuser, rpcpassword, as well as port in the command. If you don't want users to provide these parameters, we recommand using Nginx. The benefits for Nginx is not only about simplification, but also a good way to hide rpcuser, rpcpassword and port number. And you can filter some RPCs for security. Here we suppose the reader have installed Nginx and have basic knowledges about how to use it.


  • xray node is running on,
  • api proxy ip, with Nginx installed


1.Set the xray.conf of xray node, remember to add the proxy ip to rpcallowip e.g.:


2.Setup Nginx :

    server {
        listen       80;
        server_name  localhost;

        location / {
            proxy_pass;  #to port 3889
            proxy_set_header Authorization "Basic dGVzdDp0ZXN0MTIzNA==";  # its the base64 encode of test:test1234

3.Then you can make remote rpc call through proxy, without rpcuser or rpcpassword. e.g.:

zhongwenbins-MacBook-Pro:~ zhongwenbin$ curl  --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getinfo", "params": [] }' -H 'content-type: text/plain;'

This is only a simple example. You might have different settings or tools instead.