Lnd

Lightning Terminal (litd) — Lightning Network Node

Install and operate a Lightning Terminal (litd) node for agent-driven payments. litd bundles lnd with loop, pool, tapd, and faraday — giving agents access to liquidity management, channel marketplace, and taproot assets in a single container.

Default: Docker container, neutrino backend, SQLite storage, testnet. No full Bitcoin node required. Use --network mainnet for real coins.

Default mode: watch-only with remote signer. Private keys stay on a separate signer container — the agent never touches key material. For quick testing, use --mode standalone (keys on disk, less secure).

Quick Start (Container — Recommended)

Watch-Only with Remote Signer (Production)

# 1. Install litd image
skills/lnd/scripts/install.sh

# 2. Start litd + signer containers
skills/lnd/scripts/start-lnd.sh --watchonly

# 3. Set up signer wallet (first run only)
skills/lightning-security-module/scripts/setup-signer.sh --container litd-signer

# 4. Import credentials and create watch-only wallet
skills/lnd/scripts/import-credentials.sh --bundle ~/.lnget/signer/credentials-bundle
skills/lnd/scripts/create-wallet.sh

# 5. Check status
skills/lnd/scripts/lncli.sh getinfo

Standalone (Testing Only)

# 1. Install litd image
skills/lnd/scripts/install.sh

# 2. Start litd container
skills/lnd/scripts/start-lnd.sh

# 3. Create standalone wallet (generates seed — keys on disk)
skills/lnd/scripts/create-wallet.sh --mode standalone

# 4. Check status
skills/lnd/scripts/lncli.sh getinfo

Warning: Standalone mode stores the seed mnemonic and wallet passphrase on disk. Do not use for mainnet funds you cannot afford to lose.

Regtest Development

# Start litd + bitcoind for local development
skills/lnd/scripts/start-lnd.sh --regtest

# Create wallet and mine some blocks
skills/lnd/scripts/create-wallet.sh --container litd --mode standalone
docker exec litd-bitcoind bitcoin-cli -regtest -generate 101

Container Modes

Profiles

Profiles customize litd behavior without editing compose files:

# List available profiles
skills/lnd/scripts/docker-start.sh --list-profiles

# Start with a profile
skills/lnd/scripts/start-lnd.sh --profile taproot
skills/lnd/scripts/start-lnd.sh --profile debug

Network Selection

Default is testnet. Override with --network:

# Testnet (default — no real coins)
skills/lnd/scripts/start-lnd.sh

# Mainnet (real coins — use with remote signer)
skills/lnd/scripts/start-lnd.sh --network mainnet --watchonly

# Signet (testing network)
skills/lnd/scripts/start-lnd.sh --network signet

litd Sub-Daemons

litd integrates multiple daemons. Access them via the --cli flag:

# lnd CLI (default)
skills/lnd/scripts/lncli.sh getinfo

# Loop — liquidity management (submarine swaps)
skills/lnd/scripts/lncli.sh --cli loop quote out 100000

# Pool — channel marketplace
skills/lnd/scripts/lncli.sh --cli pool accounts list

# Taproot Assets (tapd)
skills/lnd/scripts/lncli.sh --cli tapcli assets list

# Lightning Terminal (litd)
skills/lnd/scripts/lncli.sh --cli litcli getinfo

# Faraday — channel analytics
skills/lnd/scripts/lncli.sh --cli frcli revenue

Installation

Default: pulls the litd Docker image.

skills/lnd/scripts/install.sh

This pulls lightninglabs/lightning-terminal:v0.16.0-alpha from Docker Hub and verifies the image. The litd image includes lncli, litcli, loop, pool, tapcli, and frcli.

Build from Source (Fallback)

skills/lnd/scripts/install.sh --source

Requires Go toolchain. Builds lnd and lncli with all build tags.

Native Mode

For running without Docker, use --native:

# Start natively
skills/lnd/scripts/start-lnd.sh --native --mode standalone

# Stop natively
skills/lnd/scripts/stop-lnd.sh --native

Native mode uses the config template at skills/lnd/templates/lnd.conf.template and runs lnd as a background process.

Remote Nodes

Connect to a remote lnd node with connection credentials:

skills/lnd/scripts/lncli.sh \
    --rpcserver remote-host:10009 \
    --tlscertpath ~/remote-tls.cert \
    --macaroonpath ~/remote-admin.macaroon \
    getinfo

MCP / Lightning Node Connect

For read-only access without direct gRPC connectivity, use the lightning-mcp-server skill with Lightning Node Connect (LNC). LNC uses encrypted WebSocket tunnels — no TLS certs, macaroons, or open ports needed. Just a pairing phrase from Lightning Terminal.

skills/lightning-mcp-server/scripts/install.sh
skills/lightning-mcp-server/scripts/configure.sh
skills/lightning-mcp-server/scripts/setup-claude-config.sh

Wallet Setup

Watch-Only Wallet (Default)

Imports account xpubs from the remote signer — no seed or private keys on this machine.

# Import credentials bundle from signer
skills/lnd/scripts/import-credentials.sh --bundle <credentials-bundle>

# Create watch-only wallet (auto-detects litd container)
skills/lnd/scripts/create-wallet.sh

Standalone Wallet

Generates a seed locally. Use only for testing.

skills/lnd/scripts/create-wallet.sh --mode standalone

Handles the full wallet creation flow via REST API:

1. Generates a secure random wallet passphrase
2. Calls /v1/genseed to generate a 24-word seed mnemonic
3. Calls /v1/initwallet with the passphrase and seed
4. Stores credentials securely:
   • ~/.lnget/lnd/wallet-password.txt (mode 0600)
   • ~/.lnget/lnd/seed.txt (mode 0600)

Unlock Wallet

skills/lnd/scripts/unlock-wallet.sh

Auto-unlock is enabled by default in the container via --wallet-unlock-password-file. Manual unlock is only needed if auto-unlock is disabled.

Recover Wallet from Seed (Standalone Only)

skills/lnd/scripts/create-wallet.sh --mode standalone --recover --seed-file ~/.lnget/lnd/seed.txt

Starting and Stopping

Start

# Docker standalone (default)
skills/lnd/scripts/start-lnd.sh

# Docker watch-only (production)
skills/lnd/scripts/start-lnd.sh --watchonly

# Docker with profile
skills/lnd/scripts/start-lnd.sh --profile taproot

# Mainnet
skills/lnd/scripts/start-lnd.sh --network mainnet

Stop

# Stop (preserve data)
skills/lnd/scripts/stop-lnd.sh

# Stop and clean (remove volumes)
skills/lnd/scripts/stop-lnd.sh --clean

# Stop all litd containers
skills/lnd/scripts/stop-lnd.sh --all

Node Operations

All commands auto-detect the litd container:

Node Info

skills/lnd/scripts/lncli.sh getinfo
skills/lnd/scripts/lncli.sh walletbalance
skills/lnd/scripts/lncli.sh channelbalance

Funding

skills/lnd/scripts/lncli.sh newaddress p2tr
skills/lnd/scripts/lncli.sh walletbalance

Channel Management

skills/lnd/scripts/lncli.sh connect <pubkey>@<host>:9735
skills/lnd/scripts/lncli.sh openchannel --node_key=<pubkey> --local_amt=1000000
skills/lnd/scripts/lncli.sh listchannels
skills/lnd/scripts/lncli.sh closechannel --funding_txid=<txid> --output_index=<n>

Payments

skills/lnd/scripts/lncli.sh addinvoice --amt=1000 --memo="test payment"
skills/lnd/scripts/lncli.sh decodepayreq <bolt11_invoice>
skills/lnd/scripts/lncli.sh sendpayment --pay_req=<bolt11_invoice>
skills/lnd/scripts/lncli.sh listpayments

Macaroon Bakery

Use the macaroon-bakery skill for least-privilege agent credentials:

skills/macaroon-bakery/scripts/bake.sh --role pay-only
skills/macaroon-bakery/scripts/bake.sh --role invoice-only
skills/macaroon-bakery/scripts/bake.sh --inspect <path-to-macaroon>

Configuration

Container Config

The Docker compose templates pass configuration via command-line arguments. For advanced customization, mount a custom litd.conf:

• litd template: skills/lnd/templates/litd.conf.template
• lnd template (native): skills/lnd/templates/lnd.conf.template

Note: litd requires lnd. prefix for lnd flags (e.g., lnd.bitcoin.active). Standalone lnd does not use the prefix.

Key Defaults

• Backend: neutrino (BIP 157/158 light client)
• Database: SQLite
• Network: testnet (override with --network mainnet)
• Auto-unlock: enabled via password file

Container Naming & Ports

Port Reference

File Locations

Version Pinning

Container image versions are pinned in versions.env at the repo root:

LITD_VERSION=v0.16.0-alpha
LND_VERSION=v0.20.0-beta

Override at runtime:

LITD_VERSION=v0.17.0-alpha skills/lnd/scripts/start-lnd.sh

Integration with lnget

Once litd is running with a funded wallet and open channels:

lnget config init
lnget ln status
lnget --max-cost 1000 https://api.example.com/paid-data

Security Considerations

See references/security.md for detailed guidance.

Default model (watch-only with remote signer):

• No seed or private keys on the agent machine
• Signing delegated to signer container via gRPC
• Set up with the lightning-security-module skill

Standalone model (testing only):

• Wallet passphrase and seed stored on disk (0600)
• Suitable for testnet and quick testing

Macaroon security:

• Never give agents the admin macaroon in production
• Bake scoped macaroons with the macaroon-bakery skill

Troubleshooting

"wallet not found"

Run skills/lnd/scripts/create-wallet.sh to create the wallet.

"wallet locked"

Run skills/lnd/scripts/unlock-wallet.sh. Auto-unlock is enabled by default.

"chain backend is still syncing"

Neutrino needs time to sync headers:

skills/lnd/scripts/lncli.sh getinfo | jq '{synced_to_chain, block_height}'

Container not starting

docker logs litd
docker logs litd-signer

"remote signer not reachable"

docker ps | grep litd-signer
docker logs litd-signer