lightning-security-module

Name: lightning-security-module
Author: lightninglabs

57stars18forks

How to install lightning-security-module?

lightninglabs/lightning-agent-tools/lightning-security-module

$npx -y skills add lightninglabs/lightning-agent-tools --skill lightning-security-module

Installs into the current project.

Summary

Set up an lnd remote signer container that holds private keys separately from the agent. Exports a credentials bundle (accounts JSON, TLS cert, admin macaroon) for watch-only litd nodes. Container-first with Docker, native fallback. Use when firewalling private key material from

Files · 1

View on GitHub

SKILL.md

1	# Lightning Security Module (Remote Signer)
2
3	Set up an lnd remote signer container that holds private keys on a separate,
4	secured machine. The signer never routes payments or opens channels — it only
5	holds keys and signs when asked by a watch-only litd node.
6
7	## Architecture
8
9	```
10	Agent Machine Signer Machine (secure)
11	┌─────────────────┐ ┌─────────────────────┐
12	│ litd (watch-only)│◄──gRPC───►│ lnd (signer) │
13	│ - neutrino │ │ - holds seed │
14	│ - manages chans │ │ - signs commitments │
15	│ - routes pmts │ │ - signs on-chain txs │
16	│ - NO key material│ │ - no p2p networking │
17	└─────────────────┘ └─────────────────────┘
18	```
19
20	The watch-only node handles all networking and channel management. The signer
21	node holds the seed and performs cryptographic signing. Even if the agent machine
22	is fully compromised, the attacker cannot extract private keys.
23
24	See [references/architecture.md](references/architecture.md) for the full
25	architecture explainer.
26
27	## Quick Start (Container — Recommended)
28
29	### On the Signer Machine
30
31	```bash
32	# 1. Install lnd signer image
33	skills/lightning-security-module/scripts/install.sh
34
35	# 2. Start signer container
36	skills/lightning-security-module/scripts/start-signer.sh
37
38	# 3. Set up signer wallet and export credentials
39	skills/lightning-security-module/scripts/setup-signer.sh
40
41	# 4. Copy the credentials bundle to the agent machine
42	# The setup script prints the bundle path and base64 string.
43	```
44
45	### On the Agent Machine
46
47	```bash
48	# 5. Import credentials bundle
49	skills/lnd/scripts/import-credentials.sh --bundle <credentials-bundle>
50
51	# 6. Start litd in watch-only mode
52	skills/lnd/scripts/start-lnd.sh --watchonly
53
54	# 7. Create watch-only wallet
55	skills/lnd/scripts/create-wallet.sh
56
57	# 8. Check status
58	skills/lnd/scripts/lncli.sh getinfo
59	```
60
61	### Two-Container Local Setup
62
63	For testing both on the same machine:
64
65	```bash
66	# Start litd + signer together
67	skills/lnd/scripts/start-lnd.sh --watchonly
68
69	# Set up signer wallet
70	skills/lightning-security-module/scripts/setup-signer.sh --container litd-signer
71
72	# Import credentials and create watch-only wallet
73	skills/lnd/scripts/import-credentials.sh --bundle ~/.lnget/signer/credentials-bundle
74	skills/lnd/scripts/create-wallet.sh --container litd
75	```
76
77	## Installation
78
79	Default: pulls the lnd Docker image for the signer.
80
81	```bash
82	skills/lightning-security-module/scripts/install.sh
83	```
84
85	This pulls `lightninglabs/lnd:v0.20.0-beta` from Docker Hub. The signer only
86	needs plain lnd (not litd) since it only holds keys and signs.
87
88	### Build from Source (Fallback)
89
90	```bash
91	skills/lightning-security-module/scripts/install.sh --source
92	```
93
94	## Native Mode
95
96	For running the signer without Docker:
97
98	```bash
99	# Set up signer natively
100	skills/lightning-security-module/scripts/setup-signer.sh --native
101
102	# Start signer natively
103	skills/lightning-security-module/scripts/start-signer.sh --native
104
105	# Stop signer natively
106	skills/lightning-security-module/scripts/stop-signer.sh --native
107	```
108
109	## Remote Nodes
110
111	Export credentials from a remote signer:
112
113	```bash
114	skills/lightning-security-module/scripts/export-credentials.sh \
115	--rpcserver signer-host:10012 \
116	--tlscertpath ~/signer-tls.cert \
117	--macaroonpath ~/signer-admin.macaroon
118	```
119
120	## Credential Bundle Format
121
122	The exported bundle (`~/.lnget/signer/credentials-bundle/`) contains:
123
124	\| File \| Purpose \|
125	\|------\|---------\|
126	\| `accounts.json` \| Account xpubs for watch-only wallet import \|
127	\| `tls.cert` \| Signer's TLS certificate for authenticated gRPC \|
128	\| `admin.macaroon` \| Signer's admin macaroon for RPC authentication \|
129
130	The bundle is also available as a single base64-encoded tar.gz file
131	(`credentials-bundle.tar.gz.b64`) for easy copy-paste transfer between machines.
132
133	## Scripts
134
135	\| Script \| Purpose \|
136	\|--------\|---------\|
137	\| `install.sh` \| Pull lnd signer image (or build from source) \|
138	\| `docker-start.sh` \| Start signer container \|
139	\| `docker-stop.sh` \| Stop signer container \|
140	\| `setup-signer.sh` \| Create signer wallet and export credentials \|
141	\| `start-signer.sh` \| Start signer (delegates to Docker by default) \|
142	\| `stop-signer.sh` \| Stop signer (delegates to Docker by default) \|
143	\| `export-credentials.sh` \| Re-export credentials from running signer \|
144
145	## Managing the Signer
146
147	### Start
148
149	```bash
150	# Docker (default)
151	skills/lightning-security-module/scripts/start-signer.sh
152
153	# With network override
154	skills/lightning-security-module/scripts/start-signer.sh --network mainnet
155	```
156
157	### Stop
158
159	```bash
160	# Docker stop (preserve data)
161	skills/lightning-security-module/scripts/stop-signer.sh
162
163	# Docker stop + remove

People who liked this also viewed

6 picks

Type

lightning-security-module

57stars18forks

View on GitHub

How to install lightning-security-module?

lightninglabs/lightning-agent-tools/lightning-security-module

$npx -y skills add lightninglabs/lightning-agent-tools --skill lightning-security-module

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Lightning Security Module (Remote Signer)
2
3	Set up an lnd remote signer container that holds private keys on a separate,
4	secured machine. The signer never routes payments or opens channels — it only
5	holds keys and signs when asked by a watch-only litd node.
6
7	## Architecture
8
9	```
10	Agent Machine Signer Machine (secure)
11	┌─────────────────┐ ┌─────────────────────┐
12	│ litd (watch-only)│◄──gRPC───►│ lnd (signer) │
13	│ - neutrino │ │ - holds seed │
14	│ - manages chans │ │ - signs commitments │
15	│ - routes pmts │ │ - signs on-chain txs │
16	│ - NO key material│ │ - no p2p networking │
17	└─────────────────┘ └─────────────────────┘
18	```
19
20	The watch-only node handles all networking and channel management. The signer
21	node holds the seed and performs cryptographic signing. Even if the agent machine
22	is fully compromised, the attacker cannot extract private keys.
23
24	See [references/architecture.md](references/architecture.md) for the full
25	architecture explainer.
26
27	## Quick Start (Container — Recommended)
28
29	### On the Signer Machine
30
31	```bash
32	# 1. Install lnd signer image
33	skills/lightning-security-module/scripts/install.sh
34
35	# 2. Start signer container
36	skills/lightning-security-module/scripts/start-signer.sh
37
38	# 3. Set up signer wallet and export credentials
39	skills/lightning-security-module/scripts/setup-signer.sh
40
41	# 4. Copy the credentials bundle to the agent machine
42	# The setup script prints the bundle path and base64 string.
43	```
44
45	### On the Agent Machine
46
47	```bash
48	# 5. Import credentials bundle
49	skills/lnd/scripts/import-credentials.sh --bundle <credentials-bundle>
50
51	# 6. Start litd in watch-only mode
52	skills/lnd/scripts/start-lnd.sh --watchonly
53
54	# 7. Create watch-only wallet
55	skills/lnd/scripts/create-wallet.sh
56
57	# 8. Check status
58	skills/lnd/scripts/lncli.sh getinfo
59	```
60
61	### Two-Container Local Setup
62
63	For testing both on the same machine:
64
65	```bash
66	# Start litd + signer together
67	skills/lnd/scripts/start-lnd.sh --watchonly
68
69	# Set up signer wallet
70	skills/lightning-security-module/scripts/setup-signer.sh --container litd-signer
71
72	# Import credentials and create watch-only wallet
73	skills/lnd/scripts/import-credentials.sh --bundle ~/.lnget/signer/credentials-bundle
74	skills/lnd/scripts/create-wallet.sh --container litd
75	```
76
77	## Installation
78
79	Default: pulls the lnd Docker image for the signer.
80
81	```bash
82	skills/lightning-security-module/scripts/install.sh
83	```
84
85	This pulls `lightninglabs/lnd:v0.20.0-beta` from Docker Hub. The signer only
86	needs plain lnd (not litd) since it only holds keys and signs.
87
88	### Build from Source (Fallback)
89
90	```bash
91	skills/lightning-security-module/scripts/install.sh --source
92	```
93
94	## Native Mode
95
96	For running the signer without Docker:
97
98	```bash
99	# Set up signer natively
100	skills/lightning-security-module/scripts/setup-signer.sh --native
101
102	# Start signer natively
103	skills/lightning-security-module/scripts/start-signer.sh --native
104
105	# Stop signer natively
106	skills/lightning-security-module/scripts/stop-signer.sh --native
107	```
108
109	## Remote Nodes
110
111	Export credentials from a remote signer:
112
113	```bash
114	skills/lightning-security-module/scripts/export-credentials.sh \
115	--rpcserver signer-host:10012 \
116	--tlscertpath ~/signer-tls.cert \
117	--macaroonpath ~/signer-admin.macaroon
118	```
119
120	## Credential Bundle Format
121
122	The exported bundle (`~/.lnget/signer/credentials-bundle/`) contains:
123
124	\| File \| Purpose \|
125	\|------\|---------\|
126	\| `accounts.json` \| Account xpubs for watch-only wallet import \|
127	\| `tls.cert` \| Signer's TLS certificate for authenticated gRPC \|
128	\| `admin.macaroon` \| Signer's admin macaroon for RPC authentication \|
129
130	The bundle is also available as a single base64-encoded tar.gz file
131	(`credentials-bundle.tar.gz.b64`) for easy copy-paste transfer between machines.
132
133	## Scripts
134
135	\| Script \| Purpose \|
136	\|--------\|---------\|
137	\| `install.sh` \| Pull lnd signer image (or build from source) \|
138	\| `docker-start.sh` \| Start signer container \|
139	\| `docker-stop.sh` \| Stop signer container \|
140	\| `setup-signer.sh` \| Create signer wallet and export credentials \|
141	\| `start-signer.sh` \| Start signer (delegates to Docker by default) \|
142	\| `stop-signer.sh` \| Stop signer (delegates to Docker by default) \|
143	\| `export-credentials.sh` \| Re-export credentials from running signer \|
144
145	## Managing the Signer
146
147	### Start
148
149	```bash
150	# Docker (default)
151	skills/lightning-security-module/scripts/start-signer.sh
152
153	# With network override
154	skills/lightning-security-module/scripts/start-signer.sh --network mainnet
155	```
156
157	### Stop
158
159	```bash
160	# Docker stop (preserve data)
161	skills/lightning-security-module/scripts/stop-signer.sh
162
163	# Docker stop + remove

People who liked this also viewed

6 picks

Type