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)

CODEBLOCK0

Standalone (Testing Only)

CODEBLOCK1

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

CODEBLOCK2

Container Modes

Profiles

Profiles customize litd behavior without editing compose files:

CODEBLOCK3

Network Selection

Default is testnet. Override with --network:

CODEBLOCK4

litd Sub-Daemons

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

CODEBLOCK5

Installation

Default: pulls the litd Docker image.

CODEBLOCK6

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)

CODEBLOCK7

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

Native Mode

For running without Docker, use --native:

CODEBLOCK8

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:

CODEBLOCK9

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.

CODEBLOCK10

Wallet Setup

Watch-Only Wallet (Default)

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

CODEBLOCK11

Standalone Wallet

Generates a seed locally. Use only for testing.

CODEBLOCK12

Handles the full wallet creation flow via REST API:

1. 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:

Unlock Wallet

CODEBLOCK13

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)

CODEBLOCK14

Starting and Stopping

Start

CODEBLOCK15

Stop

CODEBLOCK16

Node Operations

All commands auto-detect the litd container:

Node Info

CODEBLOCK17

Funding

CODEBLOCK18

Channel Management

CODEBLOCK19

Payments

CODEBLOCK20

Macaroon Bakery

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

CODEBLOCK21

Configuration

Container Config

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

• - litd template: INLINECODE23
• lnd template (native): INLINECODE24

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:

CODEBLOCK22

Override at runtime:

CODEBLOCK23

Integration with lnget

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

CODEBLOCK24

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"

"wallet locked"

"chain backend is still syncing"

Container not starting

"remote signer not reachable"