Connect ThunderHub to a Voltage LiTD Node

This guide covers connecting a self-hosted ThunderHub instance to a Voltage  Lightning node. Voltage nodes run litd under the hood, so ThunderHub can connect using the litd account type to get full node management including Taproot Assets  support.

Works with both Mainnet and Mutinynet (signet-based testnet) nodes on Voltage.

Prerequisites

• A Voltage account (app.voltage.cloud )
• A Voltage Lightning node (Standard tier or above)
• ThunderHub v0.15.5  or later (the latest Docker tag works)
• Docker  installed (for running ThunderHub using Docker)
  You can also run ThunderHub using Node.js if you prefer, but Docker is simpler for most users

1. Create a Node on Voltage

If you don’t have a node yet, follow these steps to create one on Voltage:

1. Log into app.voltage.cloud  and click New Node → Standard/Professional Node.
2. Choose a network: Mainnet or Mutinynet.
3. Enter a node name and set an unlock password.
4. Wait for the node to deploy (~2 minutes).
5. Once the node is running, enable Taproot Assets in the node settings. See the screenshot below for the toggle location.

2. Get Your Connection Details

You need two pieces of information from the Voltage dashboard:

Server URL

Find your node’s API endpoint on the node details page. The format is:

Superadmin Macaroon (for Taproot Assets)

1. Navigate to your node’s page on the Voltage dashboard.
2. Go to Manage Access → Macaroon Bakery.
3. Bake and download a superadmin macaroon.
4. Save the file to a known location on the machine running ThunderHub (e.g., ./voltage/superadmin.macaroon).

3. Configure ThunderHub

Create a thubConfig.yaml file:

masterPassword: 'your-secure-password'
accounts:
  - name: 'Voltage Mainnet'
    type: litd
    serverUrl: '<node-name>.m.voltageapp.io:443'
    macaroonPath: '/data/voltage/superadmin.macaroon'

masterPassword: 'your-secure-password'
accounts:
  - name: 'Voltage Mutinynet'
    type: litd
    serverUrl: '<node-name>.u.voltageapp.io:443'
    macaroonPath: '/data/voltage/superadmin.macaroon'

masterPassword: 'your-secure-password'
accounts:
  - name: 'Voltage Mainnet'
    type: litd
    serverUrl: '<mainnet-node-name>.m.voltageapp.io:443'
    macaroonPath: '/data/voltage/mainnet-superadmin.macaroon'
  - name: 'Voltage Mutinynet'
    type: litd
    serverUrl: '<mutinynet-node-name>.u.voltageapp.io:443'
    macaroonPath: '/data/voltage/mutinynet-superadmin.macaroon'

Key differences from a standard LND config:

• Macaroon path — Ensure the path inside the container matches where you downloaded the macaroon file.
• type: litd — tells ThunderHub to use the litd connection mode.
• No certificatePath — Voltage uses CA-signed certificates, so no custom TLS cert is needed.
• Port 443 — Voltage proxies the connection over standard HTTPS.

4. 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/voltage:/data/voltage:ro \
  apotdevin/thunderhub:latest

Replace /path/to/thubConfig.yaml with the actual path to your config file, and /path/to/voltage with the directory containing your downloaded macaroon(s).

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
      - ./voltage:/data/voltage:ro

docker compose up -d

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

Troubleshooting

• Connection refused — Verify your node is running on the Voltage dashboard. Stopped nodes are not reachable.
• Invalid macaroon — Make sure you downloaded a superadmin macaroon, not a read-only or standard admin macaroon. Re-bake from the Macaroon Bakery if needed.
• Wrong server URL — Double-check the node name and network suffix (.m. for mainnet, .u. for mutinynet). The port must be 443.
• Taproot Assets not showing — Ensure type: litd is set in the config. Without it, ThunderHub connects as a standard LND node and Taproot Assets features are hidden.
• Volume mount issues — Verify the macaroon file path inside the container matches the macaroonPath in your config. The Docker volume mount maps your local directory to the container path.