Core Lightning Application

Run a Core Lightning application for your node. An official app by Blockstream. Powered by Core Lightning.

---

Prerequisites

• Functioning and synced Bitcoin & Core lightning node.
• Node.js (v20.19 or higher, or v22.12 or higher), which can be downloaded here
• Recommended Browsers: Chrome, Firefox, MS Edge

---

Getting started

• Standalone

  • Get latest release

    wget https://github.com/ElementsProject/cln-application/archive/refs/tags/v25.07.tar.gz
    tar -xzf v25.07.tar.gz
    

  • Dependency Installation and Compile

    cd cln-application-25.07
    npm ci
    npm run build
    npm prune --omit=dev
    

  • Environment Variables

    This application accepts & depends upon these variables to be passed through environment:

    # Required by entrypoint.sh script
    - LIGHTNING_DATA_DIR: Path for core lightning (used by entrypoint.sh, default: ``)
    - BITCOIN_NETWORK: Bitcoin network type (for entrypoint.sh; valid values: bitcoin/signet/testnet/regtest; default: `bitcoin`)
    
    # cln-application Values
    - APP_SINGLE_SIGN_ON: DANGEROUS. Disables the application's own login entirely; every request is treated as authenticated. Only for platforms whose proxy authenticates users before traffic reaches this app (valid values: true/false, default: false)
    - APP_PROTOCOL: Protocol the browser uses to reach the application; `https` marks cookies Secure and sends HSTS, so only set it when TLS is really in front (valid values: http/https, default: `http`)
    - APP_HOST: Hostname/IP address of cln-application's container (default: `localhost`)
    - APP_PORT: Port on which this application should be served (default: `2103`)
    - APP_TRUST_PROXY: Which upstream proxies may set X-Forwarded-* headers; passed to Express `trust proxy` (valid values: false/true/hop count/comma separated addresses or subnets such as `loopback, 10.0.0.0/8`; default: `false`)
    - APP_TLS_KEY_FILE: Private key (PEM) for serving the application itself over HTTPS; leave empty when a reverse proxy terminates TLS (default: ``)
    - APP_TLS_CERT_FILE: Certificate (PEM) for serving the application itself over HTTPS; used together with APP_TLS_KEY_FILE (default: ``)
    - APP_CONFIG_FILE: Path for cln-application's configuration file (default: `./config.json`)
    - APP_LOG_FILE: Path for cln-application's log file (default: `./application-cln.log`)
    - APP_MODE: Mode for logging and other settings (valid values: production/development/testing, default: `production`)
    - APP_CONNECT: Choose how to connect to CLN (valid values: COMMANDO/REST, default: `COMMANDO`)
    
    # Core lightning Values
    - LIGHTNING_HOST: IP address of Core lightning node (default: `localhost`)
    - LIGHTNING_TOR_HOST: Tor Hidden Service url (default: ``)
    - LIGHTNING_VARS_FILE: Full Path including the file name for connection auth with LIGHTNING_PUBKEY & LIGHTNING_RUNE (defult: `./.commando-env`)
    
    # CLN Commando (WS) Values
    - LIGHTNING_WS_PROTOCOL: Core lightning's web socket is serving on ws or serving via WSSProxy (valid values: ws/wss, default: `ws`)
    - LIGHTNING_WS_HOST: Core lightning's IP address where commando can connect (default: `localhost`)
    - LIGHTNING_WS_TOR_HOST: Core lightning's Tor address where commando can connect (default: ``)
    - LIGHTNING_WS_PORT: Core lightning's websocket port (used by `COMMANDO` APP_CONNECT; with `bind-addr=ws:`/`wss-bind-addr` in CLN config; default: `5001`)
    - LIGHTNING_WS_CLIENT_KEY_FILE: Client key file path including file name for websocket TLS authentication (used by `COMMANDO` APP_CONNECT and `wss` LIGHTNING_WS_PROTOCOL; default: `./client-key.pem`)
    - LIGHTNING_WS_CLIENT_CERT_FILE: Client certificate file path including file name for websocket TLS authentication (used by `COMMANDO` APP_CONNECT and `wss` LIGHTNING_WS_PROTOCOL; default: `./client.pem`)
    - LIGHTNING_WS_CA_CERT_FILE: CA certificate file path including file name for websocket TLS authentication (default: `./ca.pem`)
    
    # CLN REST Values
    - LIGHTNING_REST_PROTOCOL: Protocol on which REST is served (valid values: http/https, default: `https`)
    - LIGHTNING_REST_HOST: IP address/hostname of Core Lightning REST interface (used if APP_CONNECT is `REST`, default: `localhost`)
    - LIGHTNING_REST_TOR_HOST: Tor hidden service URL for Core Lightning REST interface (default: ``)
    - LIGHTNING_REST_PORT: REST server port (used if APP_CONNECT is `REST`; default: `3010`)
    - LIGHTNING_REST_CLIENT_KEY_FILE: Client key file path including file name for REST TLS authentication (default: `./client-key.pem`)
    - LIGHTNING_REST_CLIENT_CERT_FILE: Client certificate file path including file name for REST TLS authentication (default: `./client.pem`)
    - LIGHTNING_REST_CA_CERT_FILE: CA certificate file path including file name for REST TLS authentication (used by `REST` APP_CONNECT and `https` LIGHTNING_REST_PROTOCOL; default: `./ca.pem`)
    
    # CLN gRPC Values
    - LIGHTNING_GRPC_HOST: IP address/hostname of Core Lightning GRPC interface (default: `localhost`)
    - LIGHTNING_GRPC_TOR_HOST: Tor hidden service URL for Core Lightning GRPC interface (default: ``)
    - LIGHTNING_GRPC_PORT: Core lightning's GRPC port (default: `9736`)
    - LIGHTNING_GRPC_PROTO_PATH: URL to directory containing CLN gRPC protocol definitions (default: `https://github.com/ElementsProject/lightning/tree/master/cln-grpc/proto`)
    - LIGHTNING_GRPC_CLIENT_KEY_FILE: Client key file path including file name for GRPC TLS authentication (used by `GRPC` APP_CONNECT; default: `./client-key.pem`)
    - LIGHTNING_GRPC_CLIENT_CERT_FILE: Client certificate file path including file name for GRPC TLS authentication (used by `GRPC` APP_CONNECT; default: `./client.pem`)
    - LIGHTNING_GRPC_CA_CERT_FILE: CA certificate file path including file name for GRPC TLS authentication (used by `GRPC` APP_CONNECT; default: `./ca.pem`)
    

  • Single Sign-On Mode (APP_SINGLE_SIGN_ON)

    Do not enable this unless another system authenticates users before they reach the application. With APP_SINGLE_SIGN_ON=true the password screen disappears and the backend accepts every request as an authenticated session. Because the backend holds the node's admin rune, anyone who can open the port can then call withdraw, pay, close and createrune, and can drain the node. The mode exists for platforms such as Umbrel, where the platform's own proxy enforces the user's login and the application port is not reachable directly. On a standalone install, a Docker host with a published port, or any machine exposed to a LAN or the internet, leave it at false. There is currently no runtime guard that stops a wrong setting; the responsibility is on the operator.

  • Transport Security (HTTPS)

    The backend listens on plain HTTP by default. That is fine on localhost, but as soon as APP_HOST is a LAN or public address the login password and the session cookie cross the network unencrypted. Choose one of the following before exposing the application:

    • Reverse proxy (recommended): put nginx, your platform's proxy, etc. in front of the app, terminate TLS there and set APP_PROTOCOL=https.

    • Native HTTPS: set APP_TLS_KEY_FILE and APP_TLS_CERT_FILE to a PEM key and certificate and set APP_PROTOCOL=https. The server then serves TLS itself.

    • Loopback only: keep APP_HOST=localhost and reach the UI through an SSH tunnel or VPN.

    APP_PROTOCOL=https is a statement about what the browser sees, not a switch that enables TLS. With it set, cookies are marked Secure, so a deployment that still answers plain http:// will fail to log in. The server logs a warning at startup when it is served over plain HTTP on a non-loopback address.

    Set these variables either via terminal OR by env.sh script OR by explicitly loading variables from .env files. Important Note: Environment variables take precedence over config.json variables. Like APP_SINGLE_SIGN_ON will take higher precedence over singleSignOn from config.json.

  • Application Configuration

    This is the default config.json file which is required by application's frontend. If the file APP_CONFIG_FILE is missing at the location, one like below will be auto created:

      {
        "unit": "SATS",
        "fiatUnit": "USD",
        "appMode": "DARK",
        "isLoading": false,
        "error": null,
        "singleSignOn": false,
        "password": ""
      }
    

  • Commando Authentication

    • This application utilizes lnmessage and commando for connecting with core lightning node. The connection is trustless and end-to-end encrypted. Commando manages authentication and authorization through runes, which can grant either full or fine-grained permissions.

    • The backend server reads LIGHTNING_PUBKEY & LIGHTNING_RUNE from the LIGHTNING_VARS_FILE file for this communication.

    • Values can either be set manually or script entrypoint.sh can be used to call getinfo and createrune methods and save values in LIGHTNING_VARS_FILE.

    • entrypoint.sh can only run for the locally installed lightning. If cln-application is running remotely then pubkey and rune can be set manually.

    • The script requires socat and jq to run successfully.

    • Sample commando config should look like:

        LIGHTNING_PUBKEY="03d2d3b2...0f8303bfe"
        LIGHTNING_RUNE="iv...4j"
      

  • Start The Application

    • Setup environment variables either via terminal OR by env.sh script OR by explicitly loading variables from .env files.
    • Run start script for starting your application's server at port APP_PORT

      npm run start
    

    • Open the UI and set the password straight away, before browsing anywhere else. Once a password is set, every change requires a signed-in session and the current password.

• Docker

  • For a minimal Docker setup to run the application with a remote Core Lightning node, see our Docker Setup Guide.

• Stores/Marketplaces

  • This application is also available on Umbrel App Store and Start9 OS with one click install.

---

Feature Walkthroughs

Step-by-step guides for basic node management flows by the CLN application, captured against a Core Lightning regtest network (5 nodes, the app connected to node ODDSPORK).

Guide	What it covers
CLN Dashboard	The home page: balances, wallets, channels — with guides for sending & receiving payments, BOLT12 offers and opening channels
Bookkeeper	Accounting dashboard: Account Events, Sats Flow and the Volume Chart

---

Contributing

• We welcome and appreciate new contributions!

• If you're a developer looking to help but not sure where to begin, look for these issues that have specifically been marked as being friendly to new contributors.

• If you're looking for a bigger challenge, before opening a pull request please create an issue to get feedback, discuss the best way to tackle the challenge, and to ensure that there's no duplication of work.

• Click here for instructions on how to run it in development mode.

• Follow the steps outlined in troubleshooting to verify that your Commando connection is successfully established with your current environment setup.

---

Acknowledgements

• This app is inspired by the work done by Umbrel lightning app.

• The backend api connects with core lightning via lnmessage.