ryleastark/lnswitchboard repository overview

⁠lnSwitchboard

Turns any Lightning node into a sovereign Lightning Address switchboard that speaks LNURL, watches your liquidity, and lets you manage identities without touching the command line.

Published on the Umbrel App Store⁠, shipped on Docker Hub⁠ and as a public GHCR package⁠.

⁠What is lnSwitchboard? (ELI5)

Think of your Lightning node as a call center. Every time someone zaps yourname@yourdomain, a little switchboard operator (lnSwitchboard) picks up, checks who’s calling, makes sure the line isn’t being spammed, and then patches the call through with a freshly minted invoice. The operator keeps notes about every call, so you can later scroll through a log and see who reached out, what they asked for, and whether they paid.

• 🧑‍💼 For node runners: keep your Lightning Address front door open while the sensitive admin UI stays on your LAN / VPN.
• 🧑‍🎓 For newcomers: no need to memorize LNURL specs - lnSwitchboard bakes in the right metadata, comment limits, payer identity rules, and verification endpoints automatically.

⁠Why operators install lnSwitchboard

• One app, many handles. Map unlimited usernames, vanity tags, and promo aliases to the same Lightning backend. Per-handle overrides let you tune min/max sats, metadata, and success messages without touching global config.
• Wallet compatibility out of the box. Implements the core LNURL LUDs (06/09/12/16/17/18/20/21), NIP-05, and NIP-57 zap receipts for linked local identities, so everything from Alby to Wallet of Satoshi, or Bitcoin Well... “just works.”
• Actionable visibility. The built-in dashboard shows 24h/7d request volume, invoices generated vs. paid, sats routed, inbound liquidity, and a searchable activity log with proxy/IP context.
• Security-first defaults. Rate limiting (per-IP), macaroon validation, TLS handling, and proxy-aware callback URLs keep the public face minimal while admin routes stay private.
• Umbrel & Docker native. Install with one click on Umbrel or run anywhere with Docker/Compose/k8s, mounting LND's data directory read-only for TLS and macaroons.

⁠Feature Highlights

⁠Getting Started

⁠🚀 Umbrel

1. Open the Umbrel App Store and search for “lnSwitchboard.”
2. Click Install and wait for Umbrel to launch the container on port 22121.
3. Visit http://umbrel.local:22121/ (or your Umbrel’s IP) and follow the proxy instructions to point /.well-known/lnurlp/ at the service.

Umbrel keeps lnSwitchboard updated automatically, so you always receive the latest features and security fixes.

⁠🐳 Docker Compose

The repo ships with a ready-to-edit docker-compose.yml⁠. Mount LND's data directory read-only, set LND_HOST, point LND_MACAROON_PATH at the existing LND invoice macaroon, and point LND_TLS_PATH at LND's existing tls.cert:

volumes:
  - ${APP_LIGHTNING_NODE_DATA_DIR}:/lnd:ro
environment:
  DEP_ENV: DOCKER
  LND_TLS_PATH: /lnd/tls.cert
  LND_MACAROON_PATH: /lnd/data/chain/bitcoin/${APP_BITCOIN_NETWORK:-mainnet}/invoice.macaroon
  LND_READONLY_MACAROON_PATH: /lnd/data/chain/bitcoin/${APP_BITCOIN_NETWORK:-mainnet}/readonly.macaroon

DEP_ENV controls the upstream host shown in the in-app reverse proxy reference. Use DOCKER for standalone Compose, UMBREL for the Umbrel store app, or UMBREL-DEV for the extended Umbrel dev app name.

Then run:

docker compose up -d

Once the service is running, point your reverse proxy so that only /.well-known/lnurlp/* and /.well-known/nostr.json hit port 22121. Keep the dashboard behind a VPN, SSH tunnel, or HTTP auth.

⁠🧩 Manual (bare metal)

python3.12 -m venv .venv
.venv/bin/pip install -r backend/requirements.txt
cd frontend && npm ci && npm run build && cd ..
.venv/bin/python -m uvicorn backend.app.main:app --host 0.0.0.0 --port 22121

Set LND_TLS_PATH, LND_MACAROON_PATH, and LND_READONLY_MACAROON_PATH to existing LND files before launching. lnSwitchboard uses invoice.macaroon for invoice creation/lookup/subscription and readonly.macaroon for liquidity reads such as ListChannels. By default, lnSwitchboard verifies LND's certificate against LND_HOST using the trust roots from LND_TLS_PATH; set LND_TLS_SERVER_NAME only when you intentionally need to verify against a different certificate SAN. If LND_MACAROON_PATH is not set, open Settings and paste a hex macaroon or upload a binary invoice.macaroon; lnSwitchboard stores the manual fallback as hex at MACAROON_STORE_PATH.

⁠🛠️ LND Diagnostics

The Docker image includes a read-only support script that checks LND env wiring, mounted macaroon files, TLS certificate names, gRPC TLS readiness, and basic RPC permissions without printing macaroon contents:

docker exec <lnswitchboard-container> lnswitchboard-diagnose-lnd

⁠How it Works (Under the Hood)

1. FastAPI core mounts the static frontend and exposes LNURL, UI, identity, and LN-address routers. CORS is limited to GET since only public endpoints should be internet-facing.
2. LN client (grpc.aio) talks to LND using your TLS cert + invoice macaroon, generating invoices with properly hashed metadata and watching channel capacity to set maxSendable.
3. LN address store lives in SQLite, so per-handle overrides survive restarts and apply to every user+tag.
4. Request log storage mirrors all discovery/invoice/verify events in SQLite plus an in-memory deque for fast UI reads. Older entries age out via LOG_RETENTION_DAYS.
5. Invoice workers:
   • InvoiceSubscriptionWorker listens to SubscribeInvoices and updates settlement state instantly.
   • InvoiceFullRefreshWorker sweeps pending invoices on a fixed interval so nothing slips through.
6. Rate limiter + proxy awareness ensure only legitimate traffic hits LND while callback URLs honor Forwarded / X-Forwarded-* headers so wallets see the same host you advertise.

⁠UI Walkthrough

• Dashboard: Lightning snapshot, 24h/7d request counts, invoices minted/paid, sats routed, and a 14-day chart of settled activity.
• Invoices: Paginated table with per-invoice modals showing hashes, sats, expiry, and settle timestamps.
• Liquidity: Channel table (peer alias, Amboss links, local/remote balances) plus the largest receivable metric powered by list_channels.
• Logs: Filterable event log with modal JSON viewer - perfect for debugging wallet interactions.
• LN Addresses: Create/edit/delete overrides with validation, variable hints, Nostr identity badges, payer-data schemas, signed webhook filters, and webhook badges when automations are attached to a handle.
• Identities: CRUD for local_part@domain → npub mappings plus relay lists.
• Settings: Mounted macaroon status, manual macaroon paste/upload fallback, Nostr zap signer generation/import, .env editor with grouped hints, and a reverse-proxy snippet you can copy into Nginx/Caddy.
• Webhooks: Request-log delivery events, test sends, signed receiver headers, forwarded-invoice caveats, and payload reference material.

Screenshots coming soon - until then, install on Umbrel or fire up the Docker image to explore the dashboard, request logs, signer controls, and address automation tools in minutes.

⁠Supported Specs

• LUD-06 · payRequest base spec⁠
• LUD-09 · successAction⁠
• LUD-12 · Payer comments⁠
• LUD-16 · Lightning Addresses⁠
• LUD-17 · Protocol schemes⁠
• LUD-18 · Payer identity⁠
• LUD-20 · Long descriptions⁠
• LUD-21 · Verify endpoint⁠
• NIP-05 · Nostr identities⁠
• NIP-57 · Lightning zaps⁠

⁠Docs, Support & Contributing

• 📚 Documentation: Check the app's References section for quick how-to guides.
• 📦 Docker packages: ryleastark/lnswitchboard⁠ and ghcr.io/ryleastark/lnswitchboard⁠.
• 🐛 Issues & feature requests: Open a ticket on GitHub Issues⁠.
• ⚡ Tips: Send sats to [email protected] to keep the project zapping.

Pull requests are welcome - please read the wiki, run the test suite (.venv/bin/python -m pytest), and describe your changes clearly so we can review quickly.

⁠License & Credits

Copyright © Rylea Stark⁠. All rights reserved unless otherwise noted.