Self-Host a Multi-Asset Lightning Node

This guide explains how to host your own RGB Lightning Node for use with KaleidoSwap. Self-hosting gives you full control over your node and can be a great option for users familiar with running servers.

Overview

The RGB Lightning Node (RLN) is a specialized Lightning Network node that supports RGB assets on the Lightning Network. It allows you to:

Create payment channels containing RGB assets
Route RGB asset-denominated payments across multiple channels
Transfer RGB assets with the same user experience and security as regular Bitcoin Lightning payments

Hosting Methods Comparison

There are several ways to host an RGB Lightning Node, each with their own advantages and requirements:

Hosting Method	Advantages	Considerations	Technical Expertise
Docker	Easy setup, isolated environment, simple updates	Requires Docker knowledge	Medium
Direct Installation	Full control, no containerization overhead	Manual setup of dependencies, firewall, etc.	High
Hosted Provider	No technical setup, professional support	Less control, subscription cost	Low

Choose the method that best aligns with your technical skills and requirements:

Docker-based installation: Best for most users - provides an easy setup with the option to run full infrastructure or just the node.
Direct installation on a VPS: Best for advanced users who need complete control over the system configuration.
Hosted solution (ThunderStack): Best for users who want a professionally managed solution with minimal technical overhead.

Network Options

Regardless of your hosting method, you can run your node on different Bitcoin networks:

Network	Description	Use Case
Signet (Mutinynet)	Custom signet with 30-second blocks	Ideal for testing and development
Testnet	Bitcoin’s global testnet	Testing in a broader network
Regtest	Local testing network	Development and isolated testing
Mainnet	Bitcoin production network	Production use (coming soon)

With our Docker solution, you can easily run your own Bitcoin Core and Electrs instances for any of these networks, giving you complete control over your stack.

Trust Considerations

The infrastructure components you choose to run yourself vs. connect to externally impacts the level of trust required:

Zero-Trust Setup: Run your own Bitcoin Core, Electrs, RGB Proxy, and RGB Lightning Node
Minimal Trust Setup: Run only the RGB Lightning Node and connect to hosted instances for other services

Option 1: Docker-Based Installation

Our Docker solution provides the easiest way to run an RGB Lightning Node. You can run the complete stack or just the node component.

Prerequisites

Docker and Docker Compose installed
At least 4GB RAM and 50GB storage
Basic knowledge of terminal commands

Quick Start with Makefile

The easiest way to get started is using the included Makefile:

Clone the repository:

git clone https://github.com/kaleidoswap/docker-images.git
cd docker-images

Choose how you want to run the stack:

# To see all available commands
make help

# To run only the RGB Lightning Node (connect then to external services)
make node-only

# To run the full stack (all components on signet)
make full

# To view logs from all services
make logs

Have a look at the README.md file for more information on the different commands and options.

Option 2: Direct Installation on a VPS

For advanced users who prefer complete control over their server environment, you can install the RGB Lightning Node directly on a VPS or bare-metal server.

Prerequisites

A VPS or server running Linux (Ubuntu/Debian recommended)
Rust development environment
Properly configured firewall (opening ports 3001 for API and 9735 for Lightning)
Sufficient storage for blockchain data

Installation

Clone the repository:

git clone https://github.com/RGB-Tools/rgb-lightning-node --recurse-submodules --shallow-submodules
cd rgb-lightning-node

Install the binary:

cargo install --locked --path .

Start the node:

rgb-lightning-node <data-dir>/ --daemon-listening-port 3001 \
--disable-authentication \
--ldk-peer-listening-port 9735 \
--network <network>

Replace:

<data-dir> with your chosen data directory
<network> with regtest, testnet, or signet (for Mutinynet)

When unlocking the node, you’ll need to provide:

Bitcoin RPC connection details
Indexer URL
RGB proxy endpoint

VPS Firewall Configuration

When running on a VPS, you’ll need to configure the firewall to allow necessary connections

# Allow SSH
ufw allow ssh

# Allow RGB Lightning Node API
ufw allow 3001/tcp

# Allow Lightning Network P2P connections
ufw allow 9735/tcp

# Enable the firewall
ufw enable

Running as a System Service

For a production setup, create a systemd service:

sudo nano /etc/systemd/system/rgb-lightning-node.service

Add the following content:

[Unit]
Description=RGB Lightning Node
After=network.target

[Service]
User=YOUR_USERNAME
WorkingDirectory=/home/YOUR_USERNAME
ExecStart=/home/YOUR_USERNAME/.cargo/bin/rgb-lightning-node /home/YOUR_USERNAME/rgbln-data/ --daemon-listening-port 3001 --ldk-peer-listening-port 9735 --network signet
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable rgb-lightning-node
sudo systemctl start rgb-lightning-node

Option 3: Hosted Provider (ThunderStack)

If you prefer a professionally managed solution without the technical overhead of self-hosting, ThunderStack offers cloud-based RGB Lightning Node hosting.

What is ThunderStack?

ThunderStack is a cloud-based solution designed to provide seamless node management for RGB and Lightning applications. It ensures high availability, enhanced security, and ease of management without the technical overhead of self-hosting.

Key Features

24/7 Availability: Always-on infrastructure ensures uninterrupted operations
No Maintenance: Leave the operational complexities of node management to ThunderStack
Scalability: Add or remove nodes on demand as your needs evolve
Security: Advanced security protocols like mTLS and Cognito for access control
Integration Ready: Supports APIs, webhooks, and SDKs for easy integration

ThunderStack vs. Self-Hosting

Aspect	ThunderStack	Self-Hosting
Technical Expertise	Minimal	Moderate to High
Setup Time	Minutes	Hours to Days
Maintenance	Handled by ThunderStack	User Responsibility
Control	Limited to API	Full Control
Cost	Subscription-based	Infrastructure Costs
Uptime	Professional SLAs	Depends on Your Setup

Choose ThunderStack if you prioritize convenience, reliability, and professional support. Choose self-hosting if you prioritize complete control, customization, and minimal third-party trust.

Network Environments

Connection Details for Different Networks

Regtest Environment

For regtest testing, you can use these connection details:

{
  "password": "<YOUR_NODE_PASSWORD>",
  "bitcoind_rpc_username": "user",
  "bitcoind_rpc_password": "password",
  "bitcoind_rpc_host": "regtest-bitcoind.rgbtools.org",
  "bitcoind_rpc_port": 80,
  "indexer_url": "electrum.rgbtools.org:50041",
  "proxy_endpoint": "rpcs://proxy.iriswallet.com/0.2/json-rpc"
}

Testnet Environment

For testnet3 testing, you can use:

{
  "password": "<YOUR_NODE_PASSWORD>",
  "bitcoind_rpc_username": "user",
  "bitcoind_rpc_password": "password",
  "bitcoind_rpc_host": "electrum.iriswallet.com",
  "bitcoind_rpc_port": 18332,
  "indexer_url": "ssl://electrum.iriswallet.com:50013",
  "proxy_endpoint": "rpcs://proxy.iriswallet.com/0.2/json-rpc"
}

Signet (Mutinynet) Environment

For signet testing, you can use:

{
  "password": "<YOUR_NODE_PASSWORD>",
  "bitcoind_rpc_username": "user",
  "bitcoind_rpc_password": "default_password",
  "bitcoind_rpc_host": "bitcoind.signet.kaleidoswap.com",
  "bitcoind_rpc_port": 38332,
  "indexer_url": "https://esplora.signet.kaleidoswap.com",
  "proxy_endpoint": "rpcs://proxy.iriswallet.com/0.2/json-rpc"
}

Mutinynet: A Custom Bitcoin Signet for Testing

Mutinynet is a custom Bitcoin Signet network designed specifically for testing Lightning Network applications. It offers:

Extremely fast block times (30 seconds per block vs. 10 minutes on mainnet)
Stable testnet environment without competition for block space
Pre-configured for compatibility with RGB Lightning Nodes
Ideal for testing RGB assets on Lightning

Mutinynet Resources:

Mutinynet Explorer & Mempool - View blocks, transactions, and mempool
Mutinynet Faucet - Get free test coins for development
Mutinynet GitHub Repository - Technical documentation and source code

Node Operation

Once your node is running, it can be operated via REST APIs.

API Overview

The node exposes a comprehensive API for managing your node:

Channel management: open/close channels, connect/disconnect peers
Asset operations: issue, send, and manage RGB assets
Payment handling: create/pay invoices, keysend, etc.
Node information and control

For detailed API documentation, see the OpenAPI specification.

Basic Operations

Here are some common operations:

Get a Bitcoin Address

curl -X POST http://localhost:3001/address

Get Node Information

curl http://localhost:3001/nodeinfo

Check Bitcoin Balance

curl -X POST -H "Content-type: application/json" \
    -d '{}' http://localhost:3001/btcbalance

Hardware Requirements

For optimal performance:

Environment	CPU	RAM	Storage	Network
Testing (Mutinynet)	2 cores	4GB	25GB	10Mbps
Testnet	2 cores	4GB	50GB	10Mbps
Production	4+ cores	8GB+	500GB+ SSD	100Mbps+

Security Considerations

When hosting your own node:

Firewall Configuration: Only expose necessary ports (3001 for API, 9735 for LN peers)
Authentication: Use strong passwords and consider adding API authentication
Backups: Regularly backup your node’s data directory
Updates: Keep all components updated to patch security vulnerabilities

Download the Desktop App

Get the latest KaleidoSwap Desktop App release for macOS, Windows, or Linux.

Introduction

Wallet Operations

Channel Management

KaleidoMind

Configuration

Reference

Overview

Hosting Methods Comparison

Network Options

Trust Considerations

Option 1: Docker-Based Installation

Prerequisites

Quick Start with Makefile

Option 2: Direct Installation on a VPS

Prerequisites

Installation

VPS Firewall Configuration

Running as a System Service

Option 3: Hosted Provider (ThunderStack)

What is ThunderStack?

Key Features

ThunderStack vs. Self-Hosting

Network Environments

Connection Details for Different Networks

Regtest Environment

Testnet Environment

Signet (Mutinynet) Environment

Mutinynet: A Custom Bitcoin Signet for Testing

Node Operation

API Overview

Basic Operations

Get a Bitcoin Address

Get Node Information

Check Bitcoin Balance

Hardware Requirements

Security Considerations

Download the Desktop App

​Overview

​Hosting Methods Comparison

​Network Options

​Trust Considerations

​Option 1: Docker-Based Installation

​Prerequisites

​Quick Start with Makefile

​Option 2: Direct Installation on a VPS

​Prerequisites

​Installation

​VPS Firewall Configuration

​Running as a System Service

​Option 3: Hosted Provider (ThunderStack)

​What is ThunderStack?

​Key Features

​ThunderStack vs. Self-Hosting

​Network Environments

​Connection Details for Different Networks

​Regtest Environment

​Testnet Environment

​Signet (Mutinynet) Environment

​Mutinynet: A Custom Bitcoin Signet for Testing

​Node Operation

​API Overview

​Basic Operations

​Get a Bitcoin Address

​Get Node Information

​Check Bitcoin Balance

​Hardware Requirements

​Security Considerations

Download the Desktop App

Overview

Hosting Methods Comparison

Network Options

Trust Considerations

Option 1: Docker-Based Installation

Prerequisites

Quick Start with Makefile

Option 2: Direct Installation on a VPS

Prerequisites

Installation

VPS Firewall Configuration

Running as a System Service

Option 3: Hosted Provider (ThunderStack)

What is ThunderStack?

Key Features

ThunderStack vs. Self-Hosting

Network Environments

Connection Details for Different Networks

Regtest Environment

Testnet Environment

Signet (Mutinynet) Environment

Mutinynet: A Custom Bitcoin Signet for Testing

Node Operation

API Overview

Basic Operations

Get a Bitcoin Address

Get Node Information

Check Bitcoin Balance

Hardware Requirements

Security Considerations