Zeus setup with Core Lightning
and c-lightning-REST setup

Difficulty: Intermediate

If you run your own Lightning node and you’re not familiar with Zeus you are missing out. Zeus is a fully featured mobile Lightning front end which will allow you to send and receive Lightning payments from your home LND or Core Lightning node when you are out and about. We’ll be leveraging Zeus’s built in Tor support to connect to our home Core Lightning node. Since we are using Zeus with our own node this is a completely noncustodial solution, no trusted third parties here! In my opinion, Zeus is the best mobile lightning wallet out there.

There are several quality guides online that demonstrate the configuration of the Zeus mobile wallet with LND but I haven’t seen one for Core Lightning. Yes, Zeus also works great with Core Lightning!

In this guide I’ll demonstrate the setup of the c-lightning-REST program which acts as a shim to allow Zeus to talk to your Core Lightning node via REST API. Zeus requires a REST API for communication and Core Lightning doesn’t provide one natively. After c-lightning-REST is in place I’ll demonstrate how to connect Zeus to your Core Lightning node. You’ll then be able to make payments from your Core Lightning node while you’re on the go with your mobile phone!

The prerequisite for this setup is that you have a working Core Lightning node and that you have full access to configure that node with the Core Lightning “config” file. You’ll also need to have a working Tor configuration on your Core Lightning node. Finally, I’d recommend that you have a couple of open Lightning Channels or you won’t be able to send funds with the Zeus mobile wallet.

First we’ll setup c-lightning-REST. As best I can tell, this package needs to be run on the same machine as your Core Lightning instance so keep that in mind.

The package can be downloaded via the Github page:

https://github.com/Ride-The-Lightning/c-lightning-REST

Before you can install c-lightning-REST you’ll need to install Node.js. Often times you can simply install Node.js via your Linux distribution’s package repository. As an Arch Linux user, I’ll simply install the current version from the repository and I’m all set. However, in the case of Ubuntu they seem to have an outdated version of Node.js in their repository so you’ll want to install via another method. This is out of scope for this guide but there are instructions on the Node.js website:

https://nodejs.org/en/download/package-manager/

Now that you have Node.js installed we’ll get the necessary files for c-lightning-REST. For this guide I’m using release version 0.9.0. You can obtain the source code from this page:

https://github.com/Ride-The-Lightning/c-lightning-REST/releases/tag/v0.9.0

Please take the time to verify the release via the instructions provided on the above listed page.

Now that you have verified the file we can install via the instructions on the Github page:

$ tar -xvf v0.9.0.tar.gz 
$ cd c-lightning-REST-0.9.0
$ npm install -–only=prod

You’ll now need to configure the application. Start by copying the sample configuration file:

$ cp sample-cl-rest-config.json cl-rest-config.json

Now configure C-Lightning-REST for your Core Lightning node by editing cl-rest-config.json:

nano cl-rest-config.json

Here is my configuration file:

{
    "PORT": 3001,
    "DOCPORT": 4001,
    "PROTOCOL": "https",
    "EXECMODE": "production",
    "LNRPCPATH": "/home/bitcoin/.lightning/bitcoin/",
    "RPCCOMMANDS": ["*"]"LNRPCPATH":,
    "DOMAIN": "localhost"
}

There are a couple important things to note. I only had to make one change from the default. I had to add “LNRPCPATH”. This must be the directory that contains the file “lightning-rpc”. The “DOMAIN” setting is important if you are going to connect directly to Zeus over HTTPS. You will generate a certificate and you will want the Subject Alternative Name to match your FQDN. “DOMAIN” is where you would configure this. In the case of this guide we will be using Tor to connect so this setting can be left as “localhost”.

We can now run the application with this command:

$ node cl-rest.js

You can hit CTRL-C to end the program. Obviously this isn’t a great way to run C-Lightning-REST. As soon as you log out the application will close. For situations like this I use the application “screen”. Install screen which should be in your distribution’s package repository and then run it with the command “screen”. This will open a new virtual terminal. You can then start C-Lightning-REST with the same startup command as we used above. You can exit this virtual terminal with the following key combination and C-Lightning-REST will continue to run:

CTRL-a
d

If you later need to access this virtual terminal you can do so as follows:

$ screen -r

The “screen method” is the easy way to keep C-Lightning-REST running for the purposes of this guide but the right way is to create a systemd service file. An example service file is provided on the C-Lightning-REST github page:

# c-lightning-REST: systemd unit for c-lightning-REST
# /etc/systemd/system/c-lightning-REST.service

[Unit]
Description=c-lightning-REST daemon
Wants=lightningd.service
After=lightningd.service

[Service]
ExecStart=/usr/bin/node <Full path of the c-lightning-REST folder>/cl-rest.js
User=<user>
Restart=always
TimeoutSec=120
RestartSec=30

[Install]
WantedBy=multi-user.target

I recommend using the systemd service approach as it is a cleaner way to operate your node.

Now that we have C-Lightning-REST running we’ll move onto the Tor hidden service configuration.

You must have tor running according to configuration instructions for your distribution. We’ll edit the torrc file to add a hidden service for the C-Lightning-REST interface we just built. Edit this file:

$ nano /etc/tor/torrc

Add this to the configuration in the hidden service section:

HiddenServiceDir /var/lib/tor/rest/
HiddenServicePort 3001 127.0.0.1:3001

Then restart Tor to make this change take effect.

$ sudo systemctl restart tor

We’ll now need to take note of our Tor hidden service address. On Arch Linux this can be found here:

$ cd /var/lib/tor

Since we named the service “rest” in the hidden service configuration above, we’ll go into the “rest” directory and then view the “hostname” file. In the file you’ll see a long string of characters ending with .onion. Save this onion address, we’ll need it when we configure Zeus.

There is one final step before we configure Zeus. We need the hex formatted admin.macaroon. When C-Lightning-REST is started for the first time it will generate the admin.macaroon file. C-Lightning-REST calls this file “access.macaroon”. This file will be located in your c-lightning-REST-0.9.0 folder inside the “certs” folder. If you are on a Linux system you will execute this command:

xxd -ps -u -c 1000 /path/to/access.macaroon

You may need to install “xxd” from your distribution’s package repository.

This will generate a very long character string. Hold on to this string and your .onion address and you are finally ready to setup the Zeus mobile wallet!

Zeus can be retrieved from either of the major mobile app stores or if you are on Android you can get the APK directly from the developer’s website:

https://zeusln.app

I recommend grabbing the APK file and as always, please perform the GPG verification of the downloaded APK.

With the app now installed we’ll open it and click on “GET STARTED”. We’ll then select “Connect a node” and click the + symbol in the upper right.

I’ll give my node the name “Core Lightning”. Switch the “Node interface” to “c-lighting-REST”. Then add your host name which is your .onion address. Follow that by the port number which will be 3001 in our setup. Next enter the very long macaroon in hex format. We collected that in a previous step with the “xxd” command. Finally enable “Use Tor” and then click “SAVE NODE CONFIG”. The completed configuration will look like this:

Getting the lengthy .onion address and hex formatted macaroon into the Zeus mobile app can be challenging. I use the excellent KDE Connect app which allows me to share the clipboard between my Linux desktop and Android phone. However you move these long text strings to the Zeus app make sure you use a secure method. Don’t use something insecure like SMS or email.

If everything worked correctly Zeus will be connected to your node and show your on-chain and lightning channel balances. Note the little onion to let us know that we’re connected via tor!

Now you can use Zeus to perform many functions while you are away from your node. You can make and receive lightning or on-chain payments and even manage lighting channels!

But wait, there’s more! Now that you have C-Lightning-REST setup it is fairly easy to setup Ride the Lighting (AKA RTL) as a fancy node management tool. I highly recommend RTL. You can find their project homepage here:

https://www.ridethelightning.info

Enjoy your new Zeus managed Core Lightning node!