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 as a public Docker package, and fully documented in the project wiki.
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.
- 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) plus NIP-05, 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 your
secrets/folder for TLS + macaroons.
| Area | What you get |
|---|---|
| LNURL Router | LNURL-pay discovery + invoice endpoints that understand tags, long descriptions, payer data, comments, and lightning-fast verification links. |
| Dashboard | Live metrics, trend charts, and a status chip that pings /api/health every 10 seconds so you know your node is reachable. |
| Invoices hub | Dedicated /invoices/ page backed by a SQLite invoice_events table. Real-time updates come from a gRPC subscription worker plus a periodic full refresh loop. |
| Request log | Searchable log of discovery, invoice, verify, and rate-limit events with metadata previews, payers’ comments, and proxy headers for forensic-level visibility. |
| LN address customization | Pin custom min/max sats, template text, and multi-webhook automations to any local_part@domain. Tags automatically inherit from the base handle. |
| NIP-05 identities | Manage Nostr mappings (npub/hex + relay list) from the UI, and serve /.well-known/nostr.json with proper CORS. |
| Env + macaroon management | Update .env safely via the UI, rotate invoice macaroons, and apply changes without restarting the container. |
- Open the Umbrel App Store and search for “lnSwitchboard.”
- Click Install and wait for Umbrel to launch the container on port
22121. - Visit
http://umbrel.local:22121/(or your Umbrel’s IP), paste your invoice macaroon, and follow the sidebar instructions to point/.well-known/lnurlp/at the service.
Umbrel keeps lnSwitchboard updated automatically, so you always receive the latest features and security fixes.
The repo ships with a ready-to-edit docker-compose.yml. Mount secrets/, set LND_HOST, then run:
docker compose up -dOnce 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.
python3.12 -m venv .venv
.venv/bin/pip install -r backend/requirements.txt
.venv/bin/python -m uvicorn backend.app.main:app --host 0.0.0.0 --port 22121Populate secrets/tls.cert, secrets/macaroon.hex, and (optionally) .env before launching.
- FastAPI core mounts the static frontend and exposes LNURL, UI, identity, and LN-address routers. CORS is limited to
GETsince only public endpoints should be internet-facing. - LN client (
grpc.aio) talks to LND using your TLS cert + invoice macaroon, generating invoices with properly hashed metadata and watching channel capacity to setmaxSendable. - LN address store lives in SQLite, so per-handle overrides survive restarts and apply to every
user+tag. - 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. - Invoice workers:
InvoiceSubscriptionWorkerlistens toSubscribeInvoicesand updates settlement state instantly.InvoiceFullRefreshWorkersweeps pending invoices on a fixed interval so nothing slips through.
- 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.
- 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, and webhook badges when automations are attached to a handle.
- Identities: CRUD for
local_part@domain→npubmappings plus relay lists. - Settings: Macaroon upload/rotation,
.enveditor with grouped hints, and a reverse-proxy snippet you can copy into Nginx/Caddy.
Screenshots coming soon - until then, install on Umbrel or fire up the Docker image to explore in minutes.
- LUD-06 ·
payRequestbase 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
- 📚 Documentation: lnSwitchboard Wiki (architecture, API reference, setup guides).
- 📦 Docker package:
ghcr.io/RyleaStark/lnswitchboard. - 🐛 Issues & feature requests: Open a ticket on GitHub Issues.
- ⚡ Tips: Send sats to
lnswitchboard+tips@bigbones.netto 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.
Copyright © Rylea Stark. All rights reserved unless otherwise noted.