Configuration

ThunderHub is configured through environment variables. Create a .env.local file in the project root to set your values.

If you started from the .env template, copy it to .env.local so your settings are preserved across updates.

Environment Variables

Server


LOG_LEVEL='info'                       # 'error' | 'warn' | 'info' | 'http' | 'verbose' | 'debug' | 'silly'
PORT=3000                              # Server port
HOST='0.0.0.0'                         # Bind address
BASE_PATH=''                           # URL prefix (e.g. '/thub')
TOR_PROXY_SERVER=''                    # SOCKS proxy for outbound requests (e.g. 'socks://127.0.0.1:9050')

Interface


THEME='dark'                           # 'dark' | 'light'
CURRENCY='sat'                         # 'sat' | 'btc' | 'fiat'

Privacy


FETCH_PRICES=true                      # Fetch fiat prices from external API
FETCH_FEES=true                        # Fetch on-chain fee estimates from Mempool.space
DISABLE_LINKS=false                    # Hide external links (Amboss, block explorer)
DISABLE_LNMARKETS=false                # Disable LnMarkets integration
NO_VERSION_CHECK=false                 # Skip latest-version check from GitHub

Database (Optional)

ThunderHub can optionally use a database for user accounts and team management. When enabled, users log in with email and password instead of (or in addition to) node credentials.


DB_TYPE=''                             # 'sqlite' | 'postgres' | unset to disable
DB_SQLITE_PATH='/path/to/thunderhub.db' # Path to SQLite file (when DB_TYPE='sqlite')
DB_POSTGRES_URL=''                     # Connection URL (when DB_TYPE='postgres')

Subscriptions

Real-time updates can be selectively disabled if they cause issues or are not needed.


DISABLE_ALL_SUBS=false                 # Disable all real-time subscriptions
DISABLE_INVOICE_SUB=false              # Disable invoice subscription
DISABLE_PAYMENT_SUB=false              # Disable payment subscription
DISABLE_FORWARD_SUB=false              # Disable forwarding subscription
DISABLE_CHANNEL_SUB=false              # Disable channel subscription
DISABLE_BACKUP_SUB=false               # Disable backup subscription

External Services


MEMPOOL_URL=''                         # Custom Mempool.space API endpoint

Tor Proxy

ThunderHub makes outbound requests to external services (fee estimates, fiat prices, version checks). To route these through Tor, set:


TOR_PROXY_SERVER='socks://127.0.0.1:9050'

SSO Authentication

Single Sign-On allows authentication via a cookie file, commonly used by node platforms like BTCPay Server and Umbrel.


COOKIE_PATH='/path/to/cookie/file/.cookie'
SSO_SERVER_URL='127.0.0.1:10009'
SSO_CERT_PATH='/path/to/tls.cert'
SSO_MACAROON_PATH='/path/to/macaroon/directory'
SSO_NODE_TYPE='lnd'                    # 'lnd' | 'litd'
LOGOUT_URL=''                          # Redirect URL after logout (defaults to /login)

To log in, append the cookie file contents to the URL:


http://localhost:3000/sso?token=[COOKIE]

SSO Without Authentication

Only use this if ThunderHub is accessible exclusively on a local network or through Tor. Enabling this on an internet-facing instance will expose your node and funds.

For local-only access, you can disable SSO authentication entirely:


SSO_SERVER_URL='127.0.0.1:10009'
SSO_CERT_PATH='/path/to/tls.cert'
SSO_MACAROON_PATH='/path/to/macaroon/directory'
DANGEROUS_NO_SSO_AUTH='true'

Access ThunderHub at:


http://localhost:3000/sso?token=1

Server Accounts

Server accounts are defined in a YAML configuration file. Set the path in your environment:


ACCOUNT_CONFIG_PATH='/path/to/thubConfig.yaml'

Basic Configuration


masterPassword: 'password'
accounts:
  - name: 'Account 1'
    serverUrl: 'url:port'
    macaroonPath: '/path/to/admin.macaroon'
    certificatePath: '/path/to/tls.cert'
    password: 'password for account 1'
  - name: 'Account 2'
    serverUrl: 'url:port'
    macaroonPath: '/path/to/admin.macaroon'
    certificatePath: '/path/to/tls.cert'
    # Uses masterPassword when no password is specified

You can provide credentials either as file paths (macaroonPath, certificatePath) or as inline HEX/Base64 strings (macaroon, certificate):


accounts:
  - name: 'Inline Credentials'
    serverUrl: 'url:port'
    macaroon: '0201056...'
    certificate: '0202045c...'

The serverUrl port should be the LND gRPC port (default 10009), not the REST or litd HTTPS port.

Password Security

On first startup, ThunderHub hashes all masterPassword and account password values in the YAML file. The file is overwritten with the hashed values so that cleartext passwords are never stored on disk.

Remote Access

To connect to a remote LND node, add the following to lnd.conf:


# By IP address
tlsextraip=<external-ip>
rpclisten=0.0.0.0:10009
 
# By domain name
tlsextradomain=<external-domain>
rpclisten=0.0.0.0:10009

After changing TLS settings, restart LND to regenerate the certificate.

Environment Variable Substitution

Account fields support placeholder substitution using YML_ENV_1 through YML_ENV_4:


accounts:
  - name: '{YML_ENV_1}'
    serverUrl: '{YML_ENV_2}'
    macaroon: '{YML_ENV_3}'
    certificate: '{YML_ENV_4}'

Set the corresponding environment variables and ThunderHub replaces the placeholders at startup. This only works for fields inside accounts, not for top-level fields like masterPassword.

LND Directory Shorthand

Instead of specifying individual file paths, you can point to the LND data directory:


masterPassword: 'password'
defaultNetwork: 'mainnet'
accounts:
  - name: 'My Node'
    serverUrl: 'url:port'
    lndDir: '/path/to/lnd'
  - name: 'Testnet Node'
    serverUrl: 'url:port'
    lndDir: '/path/to/lnd'
    network: 'testnet'

ThunderHub resolves paths automatically:

Certificate: <lndDir>/tls.cert
Macaroon: <lndDir>/data/chain/bitcoin/<network>/admin.macaroon

If defaultNetwork is not set, mainnet is used.

The lndDir shorthand does not work for remote access since the files must be readable from the ThunderHub server.

Encrypted Macaroons

You can store AES-encrypted macaroons and have ThunderHub decrypt them at runtime. This avoids keeping cleartext macaroons on disk.

Encrypt a macaroon (JavaScript example):


const encrypted = CryptoJS.AES.encrypt(
  'HEX or Base64 encoded macaroon',
  'secret passphrase'
).toString();

Reference the encrypted macaroon in your config:


accounts:
  - name: 'Encrypted Account'
    serverUrl: 'url:port'
    macaroon: 'encrypted-macaroon-string'
    encrypted: true

The encrypted: true field is required. When logging in, use the same passphrase that was used to encrypt the macaroon.

Privacy

ThunderHub makes requests to the following external services by default. Each can be disabled individually.

Service	Purpose	Disable With
Mempool.space	On-chain fee estimates	`FETCH_FEES=false`
Price API	Fiat exchange rates	`FETCH_PRICES=false`
GitHub	Latest version check	`NO_VERSION_CHECK=true`
LnMarkets	Trading integration	`DISABLE_LNMARKETS=true`
External links	Links to block explorers and node directories	`DISABLE_LINKS=true`

These settings can also be changed from the Settings page within ThunderHub.

Base Path

To serve ThunderHub under a URL prefix (e.g. behind a reverse proxy):


BASE_PATH='/thub'

BASE_PATH must be set before building the application.

With this setting, ThunderHub is accessible at http://localhost:3000/thub.

A prebuilt Docker image with BASE_PATH=/thub is available:


docker pull apotdevin/thunderhub:base-latest

To build a custom Docker image with your own base path:


docker build --build-arg BASE_PATH='/thub' -t thunderhub-custom .

Reverse Proxy (NGINX)


location /thub {
  proxy_pass http://localhost:3000/thub;
}