BR⚡LN Club

BR⚡LN Guide

Lightning lab: practise with three nodes without risking a single satoshi

Before putting real sats into a node, you can practise everything in a lab: three Lightning nodes talking to each other, with coins that are worth nothing. This guide shows how to install it and walks you through each operation, with real LightningOS screens.

What the regtest lab is

Regtest is a Bitcoin blockchain that runs only on your computer. It works like the real one, with addresses, transactions, blocks and Lightning channels, but the coins are worth nothing and nobody from outside takes part. It is the right place to make mistakes: open a channel, close it, pay, rebalance and see what happens, without risking a satoshi.

The LightningOS lab installer sets everything up by itself: Bitcoin Core 31.2, three LND nodes called Alice, Bob and Charlie, and a LightningOS panel for each. It also funds the three wallets and opens a triangle of channels: Alice → Bob → Charlie → Alice, three channels of 1,000,000 sats with half the balance on each side. That is enough to pay from one node to another, go through a node in the middle and test a circular rebalance.

A lab is not a node. Nothing that happens here reaches the real network: wallets, channels and balances do not move to production. For a mainnet node you do a separate install, on a computer dedicated to it. Never install the lab on a node with real funds, and never import a real wallet into it.

The screenshots below were taken with the panel in Portuguese. The text gives the names you will see in English.

What you need

  • A fresh Ubuntu 24.04 (amd64) used only for the lab: a virtual machine (VirtualBox, VMware, Proxmox) or the Ubuntu built into Windows 11 through WSL2.
  • 4 GiB of memory and 20 GiB free on the Linux disk, with systemd enabled.
  • Internet during the install, to download packages and build LightningOS.

1. Install it with one command

On an Ubuntu VM, give the machine the name the installer expects and run the bootstrap:

sudo hostnamectl set-hostname los-regtest
sudo apt-get update
sudo apt-get install -y ca-certificates curl
curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/jvxis/brln-os-light/agent/0.5.50-release/lo_regtest_bootstrap.sh | sudo bash -s -- --disposable-host

The bootstrap downloads a clean copy of the code, runs install_regtest.sh and deletes only the temporary copy at the end. The install takes a few minutes, because it builds LightningOS. Running it again resets nothing: the lab's wallets, channels and passwords are kept.

The installer refuses machines that already have a node: if it finds LND data or production services, it stops. That is on purpose.

On Windows 11, with WSL2

Without a VM, you can use the Ubuntu built into Windows. Set aside a distribution just for the lab:

  1. In PowerShell, install it: wsl --install -d Ubuntu-24.04. Check with wsl --list --verbose that the version is 2.
  2. Inside Ubuntu, open the configuration file with sudo nano /etc/wsl.conf and add:
    [boot]
    systemd=true
    [network]
    hostname=los-regtest
  3. Close the Ubuntu terminals and, in PowerShell, restart only that distribution: wsl --terminate Ubuntu-24.04 and then wsl -d Ubuntu-24.04.
  4. Check: ps -p 1 -o comm= should answer systemd, and hostname should answer los-regtest. Then run the apt-get and curl commands above.

Keep the lab on the Linux disk, outside /mnt/c, and leave WSL open while you use it: when it is closed, the nodes stop.

2. Open the three panels

On WSL2, the panels open straight in the Windows browser: https://alice.localhost:8443, https://bob.localhost:8543 and https://charlie.localhost:8643.

On a VM, the panels only listen inside it. From your computer, open an SSH tunnel and leave that terminal open (on Windows, PowerShell already has ssh):

ssh -N -L 127.0.0.1:19043:127.0.0.1:8443 -L 127.0.0.1:19053:127.0.0.1:8543 -L 127.0.0.1:19063:127.0.0.1:8643 user@vm-ip

Then open https://alice.localhost:19043, https://bob.localhost:19053 and https://charlie.localhost:19063. The different names keep the browser from mixing up the three logins.

The panels use the lab's own certificate. For the browser to trust it, copy the lab's public authority (scp user@vm-ip:/etc/los-regtest/ca.crt .) and import the file into the authorities of the browser you use for testing. In Firefox: Settings › Privacy & Security › View Certificates › Authorities › Import.

Each panel's password is on the VM. To see Alice's (change the node name for the others):

sudo cat /etc/los-regtest/alice/ui-password
LightningOS login screen with the REGTEST strip at the bottom
The login screen. The REGTEST strip at the bottom shows on every screen of the lab.

3. Get to know the panel

Log in as Alice. The language switch is at the top. The panel is the same as production LightningOS: menus on the left; in the middle, Node Pulse, the routing numbers and liquidity; below, the LND and Bitcoin cards.

Alice's LightningOS panel in the lab, with LND synced to chain and graph and Bitcoin Local at 100%
Alice's panel: Chain and Graph green on the LND card and Bitcoin Local at 100%.

Click the REGTEST strip at the bottom (Coins have no value · Supported features). It opens the Regtest laboratory guide, with the status of each operation: Validated (tested and working here), Not validated (not tested yet, which does not mean it fails) and Not supported (depends on things that only exist in production). Check it before using a menu.

Regtest laboratory guide opened from the bottom strip, with the status badges and the table of operations
The lab guide, opened from the bottom strip, in English or Portuguese.

4. Blocks: the lab's clock

On the real network, miners around the world make a block every 10 minutes on average. Without a block, nothing that goes on the blockchain confirms: deposits wait, channels stay pending and closes do not finish. In the lab, the installer turns on an automatic miner that makes a block every 60 seconds, with worthless coins. You do not need to do anything: after sending a transaction, just wait a few minutes. Six confirmations, enough for every exercise in this guide, take about 6 minutes.

To check the miner and the three nodes, run on the VM (or in the WSL Ubuntu):

sudo python3 /opt/los-regtest/automine.py status
sudo python3 /opt/los-regtest/control.py status

If you want to control the block height, or do not want to wait, pause the miner and mine by hand. The interval can also change, from 10 to 3600 seconds, and the choice survives restarts and reinstalls:

sudo python3 /opt/los-regtest/automine.py pause
sudo python3 /opt/los-regtest/control.py mine 6
sudo python3 /opt/los-regtest/automine.py resume
sudo python3 /opt/los-regtest/automine.py interval 30

The miner only works while the machine is on and does not make up for time off. If the VM was off or the miner was paused for a long time, LND thinks it lost sync (Chain turns yellow on the panel): wait for the next block, or mine 1 with control.py mine 1, and only test once it is green again.

Lightning payments through channels that are already open do not need a block: they move inside the channels, without touching the blockchain. That is exactly the point of Lightning, and the lab makes it visible.

5. The wallet

Open Wallet. The On-chain card shows the sats on the blockchain (the installer leaves almost 2 fictitious BTC on each node) and the Lightning card shows the balance inside the channels: the local balance is what you can send; the remote side is the room you have to receive.

Alice's Wallet card, with on-chain balance, Add funds and Send funds buttons and the local and remote Lightning balance
Alice's wallet. The remote balance is not hers: it shows how much she can receive.

6. Exercise: the first Lightning payment

  1. On Bob's panel, under Wallet › Create invoice, enter the amount (25000) and a memo, and click Generate invoice. The QR code and the invoice text appear; the text starts with lnbcrt (the rt is for regtest). Click Copy invoice.
  2. On Alice's panel, under Wallet › Pay invoice, paste the invoice. The panel shows the amount and the memo. Click Pay invoice.
  3. LightningOS asks for the admin password before moving money, showing the destination, the amount and the fee limit. Check it, type the password and click Confirm this operation.
Bob's Create invoice card with 25000 sats, a memo, the QR code and the lnbcrt invoice text
Bob creates the invoice. In production it would start with lnbc.
Confirm operation window for a Lightning payment, with destination, 25,000 sats, fee limit and the admin password field
Every operation that moves money goes through this password confirmation.

Done: in seconds, the 25,000 sats leave Alice's local balance and land in Bob's, with no block. Bob's Recent activity shows the invoice as SETTLED, with the memo and the node that paid.

7. Exercise: pay through another node

Lightning is a network: a payment can cross nodes on the way. Alice has a direct channel with Charlie, but you can force the path through Bob:

  1. On Charlie's panel, create a 10000-sat invoice.
  2. On Alice, paste the invoice into Pay invoice, open Outgoing channels (optional) and tick only the channel with LOS-Regtest-Bob. That way the first hop has to be Bob.
  3. Click Route preview. The panel tests the path before paying and shows the route: 2 hops, Bob in the middle charging his fee, and Charlie at the end. The maximum fee is filled in with the suggestion.
  4. Click Pay invoice and confirm with the password.
Route preview on Alice with Bob's channel ticked as outgoing: a 2-hop route, 2 sats fee, hop 1 LOS-Regtest-Bob and hop 2 LOS-Regtest-Charlie
The Alice → Bob → Charlie route. Bob charged 2 sats for forwarding.
Alice's recent activity with the SUCCEEDED Lightning payments of 10,000 and 25,000 sats via LOS-Regtest-Bob
Both payments in Alice's Recent activity. The list can take a few seconds to update.

That is how a routing node earns fees: Bob forwarded the payment and kept 2 sats. The guide Lightning node fees in ppm explains how those fees are calculated.

8. Exercise: send and receive on-chain

  1. On Charlie's panel, under Wallet, click Add funds and copy the address (in regtest it starts with bcrt1).
  2. On Alice, click Send funds, paste the address, enter the amount (100000) and, under Fee rate (sat/vB), type 2. The lab has no fee history, so the automatic suggestion is unavailable: always use a manual rate. Check the Cost preview and click Send on-chain.
  3. Confirm with the password. The panel shows the Txid of the broadcast transaction.
  4. Nothing shows yet in Charlie's Recent activity: the transaction is waiting for a block. Wait about 6 minutes, the time the miner takes to make six blocks, and refresh Charlie's wallet.
Alice's Send on-chain form with a bcrt1 address, 100000 sats, a manual fee rate of 2 sat/vB and a cost preview with an estimated fee of 262 sats
The preview shows the fee, what reaches the destination and the change before you confirm.
Charlie's recent activity with a CONFIRMED on-chain deposit of 100,000 sats at the top
After the blocks, the deposit shows as confirmed on Charlie.

9. Exercise: open a channel

Opening a channel is an on-chain transaction: the balance leaves the wallet and is locked in the channel. Let's open a second channel from Alice to Charlie, of 300,000 sats.

  1. On Alice, go to Lightning › Lightning Ops and, in the Peers box, click Open. Copy LOS-Regtest-Charlie's Pubkey.
  2. In the Lightning Tools box, click Open channel. In the first field, paste the pubkey as pubkey@127.0.0.1:9935 (the node ports are 9735 for Alice, 9835 for Bob and 9935 for Charlie).
  3. Under Funding amount, enter 300000. Under Fee rate, choose Manual and type 2. The Open preview shows how much will be left on-chain and whether there is enough confirmed balance.
  4. Click Open channel and confirm with the password.
Open channel form with Charlie's pubkey, 300000 sats, a manual fee rate of 2 sat/vB and the calculated open preview
The open form with the preview. The LightningOS minimum is 20,000 sats.

In the Channels box, the Pending channels strip appears. The channel only becomes active after the transaction confirms: wait a few minutes and click Refresh. The counter changes to 3 active channels.

Channels box with the pending channels strip: 1 pending channel of 300,000 sats, opening
Before the blocks, the new channel sits under Pending channels.

Notice that the new channel starts with 100% of the balance on Alice's side: she can send through it, but cannot receive yet. The same happens with the first channel of a real node.

10. Exercise: set a channel's fees

Under Lightning Ops › Update fees, click Apply to one, choose the new channel and fill in the fee in ppm (250) and the base fee (0). Click Update fees. The message Fees updated. confirms it, and the channel card now shows Out rate: 250 ppm.

Update fees box with Apply to one, the 300k channel with Charlie selected, 250 ppm, base fee 0 and timelock 80
Leaving a field blank keeps the current value; only an explicit 0 sets the fee to zero.

11. Exercise: manual rebalance

The new channel has too much balance on Alice's side, and the channel with Bob has too little (45% local). A rebalance moves balance from one to the other by paying herself around the triangle: Alice → Charlie → Bob → Alice.

  1. Open Lightning › Rebalance Center and scroll down to the Channel Workbench.
  2. On the LOS-Regtest-Bob row, under Target outbound, enter 50. The panel calculates the Local liquidity to add.
  3. The Rebal In button may be disabled. Just below it, the panel says why: the balance is already close to the target, or the default budget of 1 ppm (the channel's own fee) does not cover what the path charges. To run the test anyway, click the options button next to Rebal In to open the Manual liquidity probe. Enter the amount (50000) and a Maximum fee (ppm) of 100. The panel warns that the maximum fee is above the channel's and may lose money: in the lab, that is fine.
  4. Click Start custom and follow it under Recent History.
Rebal In window for LOS-Regtest-Bob with 50000 sats, a maximum fee of 100 ppm and a maximum cost of 5 sats
The maximum fee sets how much you accept to pay for the rebalance.
Recent history with the SUCCEEDED manual rebalance to LOS-Regtest-Bob: 50,000 sats for a 2-sat fee
Result: 50,000 sats moved for 2 sats. The channel with Bob is now 50/50.

Under Lightning Ops, the card of the channel with Bob now shows the rebalance cost in ppm, a negative profit and the Deficit badge: it spent sats to balance itself and has not earned anything routing yet. In real life, a rebalance is only worth it when the channel earns more in fees than it cost to balance.

12. Exercise: close the channel

Under Lightning Ops › Close channel, choose the 300k channel with Charlie, select Manual and type 2 sat/vB. The Close preview shows the estimated cost and how much returns to the wallet. Leave Force close unticked: with the peer online, a cooperative close is cheaper and the money comes back quickly.

Close channel box with the 300k channel with Charlie, a manual fee rate of 2 sat/vB and a close preview with an estimated cost of 280 sats
The preview: 280 sats of cost and 296,250 sats back to the on-chain wallet.

Click Close channel and confirm with the password. The confirmation window also shows the limit for the fee negotiation with the peer. Wait a few minutes: with the miner's blocks, the channel disappears from the list, the balance returns to Alice's On-chain and the Closure History records a Cooperative close.

If the peer proposes a fee above the limit you confirmed, LND rejects that round and the negotiation continues. Under Peers, the message stays as Peer error history, even after the channel closes: it is the last error LND received, not a current problem. Check the channel's state before repeating the close.

What else you can test

Also validated in the lab, and you can repeat them: batch channel opens (two peers in a single transaction), the balanced channel (Alice proposes, Bob accepts and the channel starts 50/50), the force close through maturity and the balance coming back, manual AutoFee (Dry run and Run now), Node Retirement, Succession, message signing and UTXO management. With a force close, the balance stays locked until the channel's maturity delay, which is over a hundred blocks. At one block a minute that takes more than two hours; to skip the wait, pause the miner, mine all at once with control.py mine 200, then run automine.py resume.

Not validated yet: scheduled automations, such as automatic rebalancing, self-repair and the HTLC Manager. Outside the lab: configuring LND from the interface (alias, colour, network), restarting and updating LND or LightningOS from the screen, the app store and external integrations. Those menus are still visible, but showing on screen does not mean they work here; some health panels also complain about production services the lab does not have.

From the lab to a real node

When the exercises feel easy, the next step is a mainnet node, with real sats. The way is in How to set up a Lightning node at home. Start small: what you practised here works the same there, but there every mistake costs sats.

Frequently asked questions

What is regtest?

A Bitcoin Core mode in which the blockchain runs only on your computer and blocks are created right there, with no outside miners. In the lab, an automatic miner makes one a minute. It works like real Bitcoin, but the coins are worth nothing and nobody from outside takes part.

Are the lab coins worth anything?

No. They are regtest coins that only exist on your machine. They cannot be sent to the real network or sold.

Why does my deposit or channel not confirm?

Because a block is still missing. The lab miner makes one a minute: wait a few minutes and refresh the panel. If it still does not confirm, check that it is running with sudo python3 /opt/los-regtest/automine.py status; if it is paused, turn it back on with automine.py resume or mine by hand with control.py mine 6.

Can I install the lab on my real node?

No. Use a VM or a WSL2 distribution just for it. The installer refuses to run where a node already exists, precisely so the two never get mixed up.

Can I run the lab on Windows?

Yes, with WSL2 on Windows 11, using a dedicated Ubuntu 24.04 distribution with systemd enabled. The panels open in the Windows browser at alice.localhost, bob.localhost and charlie.localhost.

What carries over from the lab to production?

Only what you learned. Lab wallets, channels and balances do not migrate: the real node is a separate LightningOS install, on a computer dedicated to it.