Lightning Security Module (Remote Signer)

Set up an lnd remote signer container that holds private keys on a separate,
secured machine. The signer never routes payments or opens channels — it only
holds keys and signs when asked by a watch-only litd node.

Architecture

CODEBLOCK0

The watch-only node handles all networking and channel management. The signer
node holds the seed and performs cryptographic signing. Even if the agent machine
is fully compromised, the attacker cannot extract private keys.

See references/architecture.md for the full
architecture explainer.

Quick Start (Container — Recommended)

On the Signer Machine

CODEBLOCK1

On the Agent Machine

CODEBLOCK2

Two-Container Local Setup

For testing both on the same machine:

CODEBLOCK3

Installation

Default: pulls the lnd Docker image for the signer.

CODEBLOCK4

This pulls lightninglabs/lnd:v0.20.0-beta from Docker Hub. The signer only
needs plain lnd (not litd) since it only holds keys and signs.

Build from Source (Fallback)

CODEBLOCK5

Native Mode

For running the signer without Docker:

CODEBLOCK6

Remote Nodes

Export credentials from a remote signer:

CODEBLOCK7

Credential Bundle Format

The exported bundle (~/.lnget/signer/credentials-bundle/) contains:

The bundle is also available as a single base64-encoded tar.gz file
(credentials-bundle.tar.gz.b64) for easy copy-paste transfer between machines.

Scripts

Managing the Signer

Start

CODEBLOCK8

Stop

CODEBLOCK9

Re-export Credentials

If TLS certificates or macaroons have been regenerated:

CODEBLOCK10

Configuration

Container Config

The signer compose template is at
skills/lightning-security-module/templates/docker-compose-signer.yml. Config
is passed via command-line arguments.

Native Config

The native signer config template is at
skills/lightning-security-module/templates/signer-lnd.conf.template. Key
differences from a standard lnd node:

• - No P2P listening (--listen=) — signer doesn't route
• RPC on 0.0.0.0:10012 — accepts connections from watch-only node
• REST on localhost:10013 — local only, for wallet creation
• TLS extra IP 0.0.0.0 — watch-only on a different machine can connect
• No autopilot, no routing fees — signer is signing-only

Security Model

What stays on the signer:

• - 24-word seed mnemonic
• All private keys (funding, revocation, HTLC)
• Wallet database with key material

What gets exported:

• - Account xpubs (public keys only — cannot spend)
• TLS certificate (for authenticated connection)
• Admin macaroon (for RPC auth — scope down for production)

Threat model:

• - Compromised agent machine cannot sign transactions or extract keys
• Attacker with agent access can see balances and channel state but not spend
• Signer machine should have minimal attack surface

Production hardening:

• - Replace admin macaroon with a signer-only macaroon (see macaroon-bakery)
• Restrict signer RPC to specific IP addresses via firewall
• Run signer on dedicated hardware or a hardened VM
• Use Lightning Node Connect (LNC) via lightning-mcp-server for read-only agent access

Macaroon Bakery for Signer

For production, bake a signing-only macaroon:

CODEBLOCK11

Then re-export the credentials bundle with the scoped macaroon.

Container & Ports

File Locations