lnd macaroon bakery
by @roasbeef
Bake, inspect, and manage lnd macaroons for least-privilege agent access. Use when an agent needs scoped credentials — pay-only, invoice-only, read-only, or custom permissions. Also covers signer macaroon scoping and macaroon rotation.
clawhub install lnd-macaroon-bakery📖 About This Skill
name: macaroon-bakery description: Bake, inspect, and manage lnd macaroons for least-privilege agent access. Use when an agent needs scoped credentials — pay-only, invoice-only, read-only, or custom permissions. Also covers signer macaroon scoping and macaroon rotation.
Macaroon Bakery
Bake custom lnd macaroons so every agent gets only the permissions it needs.
Never hand out admin.macaroon in production — bake a scoped one instead.
Quick Start
# Bake a pay-only macaroon
skills/macaroon-bakery/scripts/bake.sh --role pay-onlyBake an invoice-only macaroon
skills/macaroon-bakery/scripts/bake.sh --role invoice-onlyBake a read-only macaroon
skills/macaroon-bakery/scripts/bake.sh --role read-onlyInspect any macaroon
skills/macaroon-bakery/scripts/bake.sh --inspect ~/.lnd/data/chain/bitcoin/mainnet/admin.macaroonList all available lnd permissions
skills/macaroon-bakery/scripts/bake.sh --list-permissions
Docker
The litd container is auto-detected. You can also specify --container:
# Auto-detect litd container (default)
skills/macaroon-bakery/scripts/bake.sh --role pay-onlyExplicit container
skills/macaroon-bakery/scripts/bake.sh --role pay-only --container litdInspect a macaroon inside a container
skills/macaroon-bakery/scripts/bake.sh --inspect /root/.lnd/data/chain/bitcoin/testnet/admin.macaroon --container litd
Remote Nodes
To bake macaroons on a remote lnd node, provide the connection credentials:
# Bake a pay-only macaroon on a remote node
skills/macaroon-bakery/scripts/bake.sh --role pay-only \
--rpcserver remote-host:10009 \
--tlscertpath ~/remote-tls.cert \
--macaroonpath ~/remote-admin.macaroon \
--save-to ~/remote-pay-only.macaroon
You need lncli installed locally and copies of the node's TLS cert and a macaroon
with macaroon:generate permission (typically admin.macaroon).
Preset Roles
| Role | What the agent can do | Cannot do |
|------|----------------------|-----------|
| pay-only | Pay invoices, decode invoices, get node info | Create invoices, open channels, see balances |
| invoice-only | Create invoices, lookup invoices, get node info | Pay, open channels, see wallet balance |
| read-only | Get info, balances, list channels/peers/payments | Pay, create invoices, open/close channels |
| channel-admin | All of read-only + open/close channels, connect peers | Pay invoices, create invoices |
| signer-only | Sign transactions, derive keys (for remote signer) | Everything else |
Baking Custom Macaroons
For permissions not covered by presets, bake a custom macaroon:
# Custom: agent can only pay and check wallet balance
skills/macaroon-bakery/scripts/bake.sh --custom \
uri:/lnrpc.Lightning/SendPaymentSync \
uri:/lnrpc.Lightning/DecodePayReq \
uri:/lnrpc.Lightning/WalletBalance \
uri:/lnrpc.Lightning/GetInfoCustom with explicit output path
skills/macaroon-bakery/scripts/bake.sh --custom \
uri:/lnrpc.Lightning/AddInvoice \
uri:/lnrpc.Lightning/GetInfo \
--save-to ~/my-agent.macaroon
Discovering Permissions
# List all available URI permissions
skills/macaroon-bakery/scripts/bake.sh --list-permissionsFilter for specific service
skills/macaroon-bakery/scripts/bake.sh --list-permissions | grep -i invoiceFilter for routing-related permissions
skills/macaroon-bakery/scripts/bake.sh --list-permissions | grep -i router
Inspecting Macaroons
# See what permissions a macaroon has
skills/macaroon-bakery/scripts/bake.sh --inspect Inspect the admin macaroon to see full permissions
skills/macaroon-bakery/scripts/bake.sh --inspect ~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon
Signer Macaroon Scoping
When using the lightning-security-module skill, the credentials bundle includes
admin.macaroon by default. For production, bake a signing-only macaroon on the
signer machine:
# On the signer container
skills/macaroon-bakery/scripts/bake.sh --role signer-only \
--container litd-signer --rpc-port 10012Or on a native signer
skills/macaroon-bakery/scripts/bake.sh --role signer-only \
--rpc-port 10012 --lnddir ~/.lnd-signerThen re-export the credentials bundle with the scoped macaroon
Macaroon Rotation
Rotate macaroons regularly to limit the window if one is compromised:
# 1. Bake a new macaroon with the same role
skills/macaroon-bakery/scripts/bake.sh --role pay-only --save-to ~/pay-only-v2.macaroon2. Update your agent config to use the new macaroon
3. Delete the old macaroon's root key (invalidates it)
skills/lnd/scripts/lncli.sh bakemacaroon --root_key_id 0
Note: use lncli listmacaroonids and deletemacaroonid for fine-grained control
Best Practices
signer-only, not admin.
Common Permission URIs
| Permission | Description |
|-----------|-------------|
| uri:/lnrpc.Lightning/GetInfo | Node info (version, pubkey, sync status) |
| uri:/lnrpc.Lightning/WalletBalance | On-chain wallet balance |
| uri:/lnrpc.Lightning/ChannelBalance | Lightning channel balance |
| uri:/lnrpc.Lightning/ListChannels | List open channels |
| uri:/lnrpc.Lightning/ListPeers | List connected peers |
| uri:/lnrpc.Lightning/SendPaymentSync | Pay a Lightning invoice |
| uri:/lnrpc.Lightning/DecodePayReq | Decode a BOLT11 invoice |
| uri:/lnrpc.Lightning/AddInvoice | Create a Lightning invoice |
| uri:/lnrpc.Lightning/LookupInvoice | Look up an invoice by hash |
| uri:/lnrpc.Lightning/ListInvoices | List all invoices |
| uri:/lnrpc.Lightning/ListPayments | List all payments |
| uri:/lnrpc.Lightning/ConnectPeer | Connect to a peer |
| uri:/lnrpc.Lightning/OpenChannelSync | Open a channel |
| uri:/lnrpc.Lightning/CloseChannel | Close a channel |
| uri:/signrpc.Signer/SignOutputRaw | Sign a transaction output |
| uri:/signrpc.Signer/ComputeInputScript | Compute input script for signing |
| uri:/signrpc.Signer/MuSig2Sign | MuSig2 signing |
| uri:/walletrpc.WalletKit/DeriveKey | Derive a key |
| uri:/walletrpc.WalletKit/DeriveNextKey | Derive next key in sequence |
💡 Examples
# Bake a pay-only macaroon
skills/macaroon-bakery/scripts/bake.sh --role pay-onlyBake an invoice-only macaroon
skills/macaroon-bakery/scripts/bake.sh --role invoice-onlyBake a read-only macaroon
skills/macaroon-bakery/scripts/bake.sh --role read-onlyInspect any macaroon
skills/macaroon-bakery/scripts/bake.sh --inspect ~/.lnd/data/chain/bitcoin/mainnet/admin.macaroonList all available lnd permissions
skills/macaroon-bakery/scripts/bake.sh --list-permissions
Docker
The litd container is auto-detected. You can also specify --container:
# Auto-detect litd container (default)
skills/macaroon-bakery/scripts/bake.sh --role pay-onlyExplicit container
skills/macaroon-bakery/scripts/bake.sh --role pay-only --container litdInspect a macaroon inside a container
skills/macaroon-bakery/scripts/bake.sh --inspect /root/.lnd/data/chain/bitcoin/testnet/admin.macaroon --container litd
Remote Nodes
To bake macaroons on a remote lnd node, provide the connection credentials:
# Bake a pay-only macaroon on a remote node
skills/macaroon-bakery/scripts/bake.sh --role pay-only \
--rpcserver remote-host:10009 \
--tlscertpath ~/remote-tls.cert \
--macaroonpath ~/remote-admin.macaroon \
--save-to ~/remote-pay-only.macaroon
You need lncli installed locally and copies of the node's TLS cert and a macaroon
with macaroon:generate permission (typically admin.macaroon).
📋 Tips & Best Practices
signer-only, not admin.