AGENTS.md

cd /path/to/thunderhub
# Paste the content below into AGENTS.md
nano AGENTS.md

# AGENTS.md — ThunderHub
 
This file gives AI agents the context they need to help set up and run ThunderHub.
 
## What is ThunderHub?
 
ThunderHub is an open-source web UI for managing Lightning Network nodes. It connects to LND or litd via gRPC. It supports channel management, payments, on-chain transactions, Taproot Assets, and more.
 
- Repo: https://github.com/apotdevin/thunderhub
- Docs: https://thunderhub.io
 
## Requirements
 
- Node.js 24+ and npm (if building from source)
- Docker (if using the Docker image — recommended)
- A running LND or litd node
 
## Install ThunderHub
 
### Option A: Docker (recommended)
 
```bash
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
```
 
### Option B: From source
 
```bash
git clone https://github.com/apotdevin/thunderhub.git
cd thunderhub
npm install
npm run build
npm start
```
 
ThunderHub runs on http://localhost:3000 by default.
 
## Configure ThunderHub
 
Create a `thubConfig.yaml`:
 
```yaml
masterPassword: 'your-secure-password'
accounts:
  - name: 'My Node'
    serverUrl: '127.0.0.1:10009'
    macaroonPath: '/path/to/admin.macaroon'
    certificatePath: '/path/to/tls.cert'
```
 
Pass the config path via the `ACCOUNT_CONFIG_PATH` environment variable.
 
### Credentials needed
 
| File           | Path                                               | Notes                                        |
| -------------- | -------------------------------------------------- | -------------------------------------------- |
| TLS cert       | `~/.lnd/tls.cert` or `~/.lit/tls.cert`             | Depends on standalone LND vs litd            |
| Admin macaroon | `~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon` | Always from the LND data dir, even with litd |
 
### Docker networking
 
- **macOS / Windows**: use `host.docker.internal:10009` as serverUrl
- **Linux**: use the host's LAN IP (e.g. `192.168.x.x:10009`) or `--network=host`
 
### Environment variables
 
Key environment variables (set in `.env.local` or pass to Docker):
 
```bash
PORT=3000
ACCOUNT_CONFIG_PATH='/path/to/thubConfig.yaml'
BASE_PATH=''          # URL prefix for reverse proxy (e.g. '/thub')
```
 
Full config docs: https://thunderhub.io/setup
 
## Taproot Assets — litd is required
 
LND alone does NOT support Taproot Assets. To use Taproot Assets in ThunderHub (minting, trading, asset invoices), the user MUST have litd running. litd bundles LND + Loop + Pool + Faraday + Taproot Assets into one daemon.
 
### litd setup decision tree
 
1. **Already have LND running** (most common)
   → Install litd in **remote mode** alongside existing LND.
   → LND stays untouched. litd connects to it and adds Taproot Assets.
   → Docs: https://thunderhub.io/litd/remote-mode
 
2. **Starting from scratch**
   → Install litd with its **integrated LND** (one binary).
   → Then connect ThunderHub to it.
   → Docs: https://thunderhub.io/litd/existing-litd
 
3. **Already have litd running**
   → Just connect ThunderHub to litd's LND gRPC endpoint.
   → Docs: https://thunderhub.io/litd/existing-litd
 
### litd remote mode quick setup (existing LND)
 
Install litd from https://github.com/lightninglabs/lightning-terminal/releases
 
Create `~/.lit/lit.conf`:
 
```ini
lnd-mode=remote
network=mainnet
 
remote.lnd.rpcserver=127.0.0.1:10009
remote.lnd.macaroonpath=/path/to/.lnd/data/chain/bitcoin/mainnet/admin.macaroon
remote.lnd.tlscertpath=/path/to/.lnd/tls.cert
 
uipassword=your-secure-ui-password
httpslisten=0.0.0.0:8443
```
 
Start it: `litd --uipassword=your-secure-ui-password`
 
Requires LND v0.18.0+.
 
## Ports
 
| Service     | Port  | Protocol |
| ----------- | ----- | -------- |
| LND gRPC    | 10009 | gRPC     |
| litd UI/API | 8443  | HTTPS    |
| ThunderHub  | 3000  | HTTP     |
 
ThunderHub connects to LND gRPC on port **10009**. Never point it at 8443.
 
## Common mistakes
 
1. Pointing ThunderHub at port 8443 instead of 10009
2. Using a macaroon from `~/.lit/` — admin macaroon is always in `~/.lnd/`
3. TLS cert mismatch after LND restart — LND may regenerate its cert
4. litd won't connect in remote mode — check LND is running and gRPC port is open
5. Docker permission errors — ThunderHub v0.15.0+ runs as non-root, mounted files must be readable
 
## Verification
 
```bash
# Check LND is reachable
lncli getinfo
 
# Check litd is running (if using litd)
litcli --network=mainnet getinfo
 
# Check ThunderHub
curl -s http://localhost:3000 | head -1
```
 
## Full docs
 
- Installation: https://thunderhub.io/installation
- Configuration: https://thunderhub.io/setup
- litd with existing LND: https://thunderhub.io/litd/remote-mode
- Connect to existing litd: https://thunderhub.io/litd/existing-litd
- Taproot Assets workflow: https://thunderhub.io/litd/taproot-assets