System overview: how the pieces fit together

LN Operator is not one program but a handful of small parts that share a single machine and a single database. Everything below runs on one always-on host you control — typically the same box that runs your node — and stays on your private network. The only thing that ever leaves the house is a Telegram message to your phone.

The host boundary

The dashed box is one physical machine: your Bitcoin node, the automation engine, and its database all sit inside it. Nothing phones home, and no third-party service holds your data. That is the whole point — professional operating discipline without handing custody of your node, your keys, or your routing history to anyone else.

The node — LND + Bitcoin Core

At the centre of everything is your Lightning node: LND backed by a full Bitcoin Core. This is the source of truth for channels, balances, fees and forwards. LN Operator never replaces it — it drives it. All access is local, over LND's REST API, authenticated with the node's own macaroon and TLS certificate.

The engine — Python (ln-operator)

The Python engine is the hub. It reads node and channel state from LND over the REST API and writes back changes — updated fees and rebalance payments — through the same interface. It is where the actual logic lives: the fee curve, rebalance budgeting, peer selection, health snapshots and off-site backups. Everything else in the diagram either triggers the engine, stores what it produces, or reports on it.

The database — SQLite

A single SQLite file holds the history the engine accumulates: forwarding events, every rebalance and its real cost, fee-change reasons, health alerts, backup attempts and the per-channel signals derived from all of it. Keeping it in one local file means the whole state of your operation is one thing to back up and inspect — no database server to run. The engine reads and writes it; the dashboard reads it.

What drives the engine

Three things set the engine in motion, and they enter from the left of the diagram:

• You, via the CLI. Every action is a single ln-operator command — status, pipeline --dry-run, rebalance_channels, overwrite_fee, and so on. This is the manual control surface.
• cron, every 2 hours. The same engine runs unattended on a schedule, executing the full automation pipeline — recompute fees, plan and run rebalances, snapshot health — so the node keeps itself tuned between the times you look at it.
• Claude, once a day. See below.

Claude — the daily oversight layer

Once a day, Claude runs as an agent over the whole system. It has two outputs in the diagram, both pointing away from it:

• Into the engine — review and bug-fix. Claude reads the recent logs and node state, reasons about what looks wrong, and can land actual fixes in the engine: correcting a misbehaving setting, adjusting a pinned fee, or repairing something the automation got stuck on.
• Into the Telegram bot — daily recap. It also writes a plain-language summary of the day and its recommendations, which goes out through Telegram as the daily recap.

Think of cron as the reflexes and Claude as the daily review by an experienced operator — one keeps the node tuned moment to moment, the other steps back, spots the things a fixed rule would miss, and explains them.

Telegram — alerts to your phone

The Telegram bot is the one component that reaches outside the house. It reads from the engine and sends daily alerts and summaries to your phone — health warnings, what the automation did, and Claude's recap. It is push-only notification: you get told what happened, wherever you are, without exposing anything inbound to your node.

Dashboard — one screen for the whole node

The dashboard is a small web service that reads from both the LND node (for live channel and balance state) and the SQLite database (for history, fees, forwards and backup freshness), and renders them on a single page. It is served on your local network only — you open it in a browser on your own LAN. It reads; it never writes. It is a window onto the system, not another way to change it.

Putting it together

The shape is deliberately boring: one node, one engine, one database, on one machine. The engine is the only part that changes the node, and it does so through a single API. Everything else is a trigger (you, cron, Claude), a store (SQLite), or a read-only view (the dashboard and Telegram). That makes the system easy to reason about — and easy to trust, because you can see exactly where your data lives and the single, narrow path by which anything leaves.