Lightning Terminal (litd)

Lightning Terminal (litd) is an all-in-one daemon by Lightning Labs that bundles LND, Loop, Pool, Faraday, and Taproot Assets (tapd) into a single process. ThunderHub supports litd as a backend, connecting to its embedded LND gRPC endpoint to provide full node management along with Taproot Assets support.

ThunderHub connects to litd’s embedded LND gRPC endpoint (default port 10009), the same way it connects to a standalone LND node. The additional litd services (Loop, Pool, Taproot Assets) are available through the litd UI at https://your-node:8443.

Prerequisites

Docker installed
A running litd node (mainnet or testnet), or follow the Developer Environment section to create one locally

Connecting to an Existing litd Node

1. Locate Your Credentials

litd stores its TLS certificate in ~/.lit/ by default. The LND macaroon is in the standard LND data directory:

File	Default Path	Purpose
TLS cert	`~/.lit/tls.cert`	Authenticates the gRPC connection
Admin macaroon	`~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon`	Authorizes ThunderHub actions

The admin macaroon comes from the LND data directory (~/.lnd), not from ~/.lit. litd embeds LND, and macaroons are written to the standard LND paths.

2. Create a Config File

Create a thubConfig.yaml pointing to litd’s LND gRPC endpoint:


masterPassword: 'your-secure-password'
accounts:
  - name: 'My Node'
    serverUrl: '127.0.0.1:10009'
    macaroonPath: '/lnd/admin.macaroon'
    certificatePath: '/lnd/tls.cert'

When running ThunderHub in Docker on the same machine as litd, use host.docker.internal:10009 as the serverUrl on macOS and Windows, or your machine’s LAN IP on Linux.

3. Run ThunderHub


docker run -d \
  --name thunderhub \
  -p 3000:3000 \
  -e ACCOUNT_CONFIG_PATH=/data/thubConfig.yaml \
  -v /path/to/thubConfig.yaml:/data/thubConfig.yaml:ro \
  -v /path/to/.lnd:/lnd:ro \
  apotdevin/thunderhub:latest

Replace /path/to/thubConfig.yaml and /path/to/.lnd with the actual paths on your system.

Open http://localhost:3000 and log in with the masterPassword from your config file.

Docker Compose


services:
  thunderhub:
    image: apotdevin/thunderhub:latest
    restart: unless-stopped
    ports:
      - '3000:3000'
    environment:
      - ACCOUNT_CONFIG_PATH=/data/thubConfig.yaml
    volumes:
      - ./thubConfig.yaml:/data/thubConfig.yaml:ro
      - /path/to/.lnd:/lnd:ro
      - /path/to/.lit:/lit:ro


docker compose up -d

Taproot Assets

Developer Environment

This section is for contributors or anyone who wants a local regtest network with litd and ThunderHub for development and testing.

This builds ThunderHub from source. Clone the ThunderHub repository first. For normal usage, use the Docker image approach above.

Services

Service	Port(s)	Description
`bitcoind`	18443	Bitcoin Core in regtest mode
`litd-alice`	8443, 10009, 9735	Alice’s litd node (public universe)
`litd-bob`	8444, 10010, 9736	Bob’s litd node
`thunderhub-alice`	3000	ThunderHub for Alice
`thunderhub-bob`	3001	ThunderHub for Bob

Alice is configured with --taproot-assets.universe.public-access=rw for asset universe syncing.

Clone and Start


git clone https://github.com/apotdevin/thunderhub.git
cd thunderhub/docker/litd
docker compose up --build

Wait for both litd nodes to finish initializing (1-2 minutes on first run).

Access the Interfaces

Interface	URL	Password
ThunderHub Alice	http://localhost:3000	`thunderhub`
ThunderHub Bob	http://localhost:3001	`thunderhub`
litd Alice	https://localhost:8443	`testpassword123!`
litd Bob	https://localhost:8444	`testpassword123!`

The litd UI uses a self-signed certificate. Your browser will show a security warning — proceed past it for local development.

Fund Wallets


# Fund Alice
docker compose exec bitcoind bitcoin-cli \
  -regtest -rpcuser=rpcuser -rpcpassword=rpcpassword \
  generatetoaddress 6 \
  $(docker compose exec litd-alice lncli --network=regtest newaddress p2wkh | jq -r '.address')
 
# Fund Bob
docker compose exec bitcoind bitcoin-cli \
  -regtest -rpcuser=rpcuser -rpcpassword=rpcpassword \
  generatetoaddress 6 \
  $(docker compose exec litd-bob lncli --network=regtest newaddress p2wkh | jq -r '.address')

Connect Peers and Open a Channel


# Get Bob's public key
BOB_PUBKEY=$(docker compose exec litd-bob lncli --network=regtest getinfo | jq -r '.identity_pubkey')
 
# Connect Alice to Bob
docker compose exec litd-alice lncli --network=regtest connect ${BOB_PUBKEY}@litd-bob:9735
 
# Open a 1M sat channel
docker compose exec litd-alice lncli --network=regtest openchannel \
  --node_key=${BOB_PUBKEY} \
  --local_amt=1000000
 
# Confirm the channel
docker compose exec bitcoind bitcoin-cli \
  -regtest -rpcuser=rpcuser -rpcpassword=rpcpassword \
  generatetoaddress 6 \
  $(docker compose exec litd-alice lncli --network=regtest newaddress p2wkh | jq -r '.address')

Taproot Assets Workflow

With the developer environment running, you can test Taproot Assets end-to-end.

Mint an Asset


# Mint 1000 units of "Thunderbux"
docker compose exec litd-alice tapcli \
  --tlscertpath=/root/.lit/tls.cert \
  --macaroonpath=/root/.lit/regtest/super.macaroon \
  --rpcserver=localhost:8443 \
  assets mint \
  --type normal \
  --name Thunderbux \
  --supply 1000 \
  --new_grouped_asset
 
# Finalize the mint batch
docker compose exec litd-alice tapcli \
  --tlscertpath=/root/.lit/tls.cert \
  --macaroonpath=/root/.lit/regtest/super.macaroon \
  --rpcserver=localhost:8443 \
  assets mint finalize
 
# Confirm the mint transaction
docker compose exec bitcoind bitcoin-cli \
  -regtest -rpcuser=rpcuser -rpcpassword=rpcpassword \
  generatetoaddress 6 \
  $(docker compose exec litd-alice lncli --network=regtest newaddress p2wkh | jq -r '.address')

Federate Universes

For Bob to receive assets from Alice, both nodes must know about each other’s universe:


# Add Alice's universe to Bob
docker compose exec litd-bob tapcli \
  --tlscertpath=/root/.lit/tls.cert \
  --macaroonpath=/root/.lit/regtest/super.macaroon \
  --rpcserver=localhost:8443 \
  universe federation add \
  --universe_host=litd-alice:8443
 
# Add Bob's universe to Alice
docker compose exec litd-alice tapcli \
  --tlscertpath=/root/.lit/tls.cert \
  --macaroonpath=/root/.lit/regtest/super.macaroon \
  --rpcserver=localhost:8443 \
  universe federation add \
  --universe_host=litd-bob:8443

Cleanup


# Stop containers (data preserved)
docker compose down
 
# Stop containers and delete all data
docker compose down
rm -rf data/

Troubleshooting

ThunderHub cannot connect to litd

Verify the serverUrl points to the LND gRPC port (10009), not the litd HTTPS port (8443).
Check that TLS cert and macaroon paths in the container match your volume mounts.
On Linux, use your host’s actual IP address instead of host.docker.internal.

litd nodes are slow to start

litd runs multiple sub-daemons. First startup can take 2-3 minutes while wallets are created.
Monitor progress with docker compose logs -f litd-alice.

Browser certificate warning on litd UI

litd uses a self-signed TLS certificate. Click through the browser warning for local development.
In production, place litd behind a reverse proxy with a valid certificate.