doc: Add instructions to run CLN node with remote_hsmd_socket
What the developer wrote
Authored by ShahanaFarooqui
doc: Add instructions to run CLN node with remote_hsmd_socket
What changed, and why it matters
This commit only adds documentation explaining how to run a Core Lightning node with an external, optional signing component called VLS remote_hsmd_socket. It changes no source code, no configuration defaults, and no runtime behavior. There is no security issue in the commit itself.
No security action required. As a documentation hygiene matter, consider adding a note that the example RPC credentials and bind addresses are for local/regtest use only and should not be reused in production.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff is a pure documentation addition to doc/contribute-to-core-lightning/docker-images.md. It provides Docker command examples for running Core Lightning with the remote_hsmd_socket subdaemon from the Validating Lightning Signer (VLS) project. The examples include hardcoded local RPC credentials and bind addresses, which is typical for regtest/local development documentation and not a code change. No binaries, build scripts, or defaults were modified.
Changed components
doc/contribute-to-core-lightning/docker-images.mdInspect captured patch +93 / −0
diff --git a/doc/contribute-to-core-lightning/docker-images.md b/doc/contribute-to-core-lightning/docker-images.md
index 476b8f13..35ca3857 100644
--- a/doc/contribute-to-core-lightning/docker-images.md
+++ b/doc/contribute-to-core-lightning/docker-images.md
@@ -131,3 +131,96 @@ docker exec -it <container-id-from-step2> bash
docker run -it --rm --platform=linux/amd64 --network=host -v '/root/.lightning:/root/.lightning' -v '/root/.bitcoin:/root/.bitcoin' -e LIGHTNINGD_DATA=/root/.lightning elementsproject/lightningd:latest --network=regtest
```
+
+## Replace the `hsmd` subdaemon with VLS `remote_hsmd_socket`:
+
+1. This setup assumes that both `bitcoind` and `vlsd` will be running on your host system.
+
+2. Start your `bitcoind` node on the local machine.
+
+3. Start `vlsd` locally with your prefered configuration. For example:
+
+```shell
+export LIGHTNING_VLS_DIR=/root/.lightning
+export GREENLIGHT_VERSION="v25.12"
+export VLS_CLN_VERSION="v25.12"
+export VLS_NETWORK="regtest"
+export BITCOIND_RPC_URL="http://user:password@127.0.0.1:18443"
+export RUST_LOG=info
+export RUST_BACKTRACE=1
+
+/home/validating-lightning-signer/target/release/vlsd \
+ --datadir "$LIGHTNING_VLS_DIR"/.lightning-signer \
+ --network regtest \
+ --connect http://127.0.0.1:7701 \
+ --rpc-server-address 127.0.0.1 \
+ --rpc-server-port 8000 \
+ --rpc-user vlsuser \
+ --rpc-pass vlspassword \
+ --log-level info
+```
+
+4. Finally, run the Core Lightning node:
+
+4.1 Either by utilizing our docker image flavor `elementsproject/lightningd:v25.12-vls` which comes with pre-built `remote_hsmd_socket` binaries.
+
+```shell
+docker run -it --rm -d \
+ --platform=linux/amd64 \
+ --network=host \
+ -v '/root/.lightning:/root/.lightning' \
+ -v '/root/.bitcoin:/root/.bitcoin' \
+ -e GREENLIGHT_VERSION="v25.12" \
+ -e VLS_CLN_VERSION="v25.12" \
+ -e VLS_NETWORK="regtest" \
+ -e BITCOIND_RPC_URL="http://user:password@127.0.0.1:18443" \
+ -e LIGHTNINGD_NETWORK=regtest \
+ elementsproject/lightningd:v25.12-vls \
+ --bitcoin-rpcconnect=0.0.0.0 \
+ --bitcoin-rpcuser=user \
+ --bitcoin-rpcpassword=password \
+ --network=regtest \
+ --database-upgrade=true \
+ --bitcoin-datadir=/root/.bitcoin \
+ --log-level=debug \
+ --announce-addr=127.0.0.1:19750 \
+ --bind-addr=localhost:8989 \
+ --bind-addr=ws:127.0.0.1:5020 \
+ --bind-addr=0.0.0.0:19750 \
+ --bitcoin-rpcport=18443 \
+ --clnrest-port=3020 \
+ --grpc-port=9740 \
+ --subdaemon=hsmd:/var/lib/vls/bin/remote_hsmd_socket
+```
+
+4.2 Or, by replacing subdaemon `hsmd` with your mounted `remote_hsmd_socket`:
+
+```shell
+docker run -it --rm -d \
+ --platform=linux/amd64 \
+ --network=host \
+ -v '/root/.lightning:/root/.lightning' \
+ -v '/root/.bitcoin:/root/.bitcoin' \
+ -v '/root/vls/target/release/remote_hsmd_socket:/var/lib/vls/bin/remote_hsmd_socket'
+ -e GREENLIGHT_VERSION="v25.12" \
+ -e VLS_CLN_VERSION="v25.12" \
+ -e VLS_NETWORK="regtest" \
+ -e BITCOIND_RPC_URL="http://user:password@127.0.0.1:18443" \
+ -e LIGHTNINGD_NETWORK=regtest \
+ elementsproject/lightningd:v25.12 \
+ --bitcoin-rpcconnect=0.0.0.0 \
+ --bitcoin-rpcuser=user \
+ --bitcoin-rpcpassword=password \
+ --network=regtest \
+ --database-upgrade=true \
+ --bitcoin-datadir=/root/.bitcoin \
+ --log-level=debug \
+ --announce-addr=127.0.0.1:19750 \
+ --bind-addr=localhost:8989 \
+ --bind-addr=ws:127.0.0.1:5020 \
+ --bind-addr=0.0.0.0:19750 \
+ --bitcoin-rpcport=18443 \
+ --clnrest-port=3020 \
+ --grpc-port=9740 \
+ --subdaemon=hsmd:/var/lib/vls/bin/remote_hsmd_socket
+```
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.