Everything not listed in this document should behave the same as upstream Eclair. If a feature, setting, or behavior is not mentioned here, the upstream documentation is accurate and fully applicable — see the Documentation section of
instructions.mdfor links.
Eclair is ACINQ's Scala implementation of the Lightning Network. It is a routing node with no wallet and no web interface of its own: it watches the chain through a Bitcoin Core node, funds its channels from a wallet in that node, and is driven entirely through a JSON API.
- Image and Container Runtime
- Volume and Data Layout
- File Models
- Dependencies
- Network Access and Interfaces
- Installation and First-Run Flow
- Actions
- Tasks
- Health Checks
- Backups and Restore
- Limitations and Differences
- Quick Reference for AI Consumers
The image is built from the Dockerfile in this repository rather than pulled from upstream. Upstream publishes acinq/eclair on Docker Hub, but that image is x86_64 only and its versioned tags stopped in 2022; only latest is maintained. Eclair itself ships as a platform-independent JVM archive whose bundled native libraries — secp256k1, netty-epoll and jffi — each carry a linux-aarch64 build, so the Dockerfile downloads the checksum-verified release archive onto eclipse-temurin:21-jre-noble and one artifact serves both architectures with nothing compiled.
| What | Value |
|---|---|
| Image source | Custom Dockerfile — upstream release archive on a Temurin JRE base |
| Architectures | x86_64, aarch64 |
| Entrypoint | Custom: eclair-node.sh with the data directory pinned |
The package runs a single subcontainer, eclair-sub, which holds the JVM process and is where eclair-cli lives. Attach to it with start-cli package attach eclair -n eclair-sub.
The archive's version and its SHA-256 are build arguments in the Dockerfile; the checksum is verified during the build, so a mismatched or truncated download fails the build rather than shipping.
The main volume holds everything Eclair writes. Eclair restricts its own data directory to rwx------ on every start, because the seeds and the API password live there.
| Path | Contents |
|---|---|
/data |
The main volume |
/data/eclair.conf |
Eclair's configuration, written by the package |
/data/node_seed.dat |
The node identity seed, generated by Eclair on first start |
/data/channel_seed.dat |
The channel key seed, generated by Eclair on first start |
/data/mainnet/eclair.sqlite |
Channel state |
/data/mainnet/network.sqlite |
The gossip graph |
/data/mainnet/audit.sqlite |
Payment and channel history |
/data/startos-store.json |
StartOS-side state — the JVM heap ceiling and the settled peer port |
/mnt/bitcoin |
Bitcoin's volume, mounted read-only for its RPC cookie |
Dependents should mount public/api, not main. The public volume (not mounted into Eclair, not backed up) holds api/password, which main rewrites from eclair.conf on every start, so a new password from Set API Password reaches dependents using this export when they next start. Eclair does not restrict dependency mounts: any dependent mounting main still has access to the seeds and other private files.
The seeds are the node's identity and are never regenerated. On-chain funds are not here — they live in a Bitcoin Core wallet (see Dependencies).
The package owns eclair.conf outright and rewrites it on every start. It is written as JSON, which Eclair's HOCON parser accepts unchanged, so the file is both valid configuration and a typed model.
| Model | File | Format |
|---|---|---|
eclairConf |
/data/eclair.conf |
JSON (a HOCON subset) |
storeJson |
/data/startos-store.json |
JSON |
Three groups of keys behave differently, and the difference is what "why did my setting revert" comes down to:
- Re-asserted on every start, hand edits do not survive.
chain, the API and peer bind addresses and ports,bitcoind.auth,bitcoind.cookie,bitcoind.wallet, andblockchain-watchdog.sources. Changing any of these by hand breaks the package's contract with StartOS or with Bitcoin, so the model forces them back. - Resolved from dependencies on every start.
bitcoind.host,bitcoind.rpcport,bitcoind.zmqblock,bitcoind.zmqtx,socks5.*andserver.public-ips. These are addresses StartOS assigns; editing them by hand is pointless because the next start recomputes them. When Bitcoin is not installed the keys are omitted rather than filled with a placeholder. - Owned by the user through actions, and preserved. Everything the Configuration actions expose — alias, color, routing fees, payment fee limits, on-chain fee policy, channel limits — plus
api.password. A hand edit to one of these survives, because the model only supplies a default when the key is absent or unparseable. Any key the model does not name is preserved verbatim, so an advanced setting added by hand stays put.
startos-store.json holds StartOS-side state: the JVM heap ceiling, which has no eclair.conf equivalent because it is a java argument rather than an Eclair setting, and peerPort and peerOnion, the port setInterfaces settled on and whether a Tor address pinned it (see Network Access and Interfaces). peerPort is re-verified against the binding on every start, so a hand edit only holds if StartOS also grants that port.
Eclair requires Bitcoin and cannot run without it. Bitcoin supplies the chain data Eclair watches, the fee estimates it uses, and the wallet its channels are funded from.
| Dependency | Required | Health checks awaited | Mount |
|---|---|---|---|
bitcoind |
Yes | bitcoind, sync-progress |
main volume at /mnt/bitcoin, read-only |
The mount exists so Eclair can read Bitcoin's RPC cookie; the package uses cookie authentication rather than an RPC user and password. Eclair reads the cookie once at startup, so the package restarts Eclair when Bitcoin writes a new one. An absent cookie is treated as Bitcoin being down rather than as the cookie being removed, which keeps Eclair from being restarted while its backend is already gone.
Bitcoin must be configured a particular way, and the package raises a task on Bitcoin to do it — see Tasks. The transaction index is a hard requirement rather than a recommendation: Eclair fetches transactions by id with no block hash, including one at startup that is not in any wallet, so a node without the index fails to start. The index in turn requires an unpruned node.
The package creates a Bitcoin Core wallet named eclair before starting the daemon, loading it if it exists and creating it with load_on_startup otherwise. A Bitcoin node with no wallet loaded is the default state, and Eclair refuses to start against one.
Two interfaces, neither of them a web interface — Eclair does not have one.
| Interface | Type | Port | Protocol | Purpose |
|---|---|---|---|---|
api |
api |
8080 | HTTP | The JSON API, and the WebSocket at /ws that streams payment events |
peer |
p2p |
9735 | Raw TCP | Incoming connections from Lightning peers — 19735 or 29735 when 9735 is held; see below |
The API is the whole control surface: clients, dashboard backends and command line tools act through it. It authenticates with HTTP Basic using an empty username and the API password. Requests carrying an Origin header receive HTTP 403, including WebSocket handshakes; a dashboard must call Eclair from its backend, not directly from the browser. The package's actions and readiness probe send no Origin header.
Outbound Tor is configured through the socks5 block whenever Tor's SOCKS proxy resolves, which is what lets Eclair dial .onion peers. Eclair's own tor block — which builds an onion service by driving Tor's control port — stays off, because the Tor package exposes no control port; the peer interface's onion address comes from StartOS instead and is announced through server.public-ips.
Eclair can only announce the port it listens on, so the package matches the two. Eclair appends server.port to every entry of server.public-ips and cannot express a per-address port — NodeAddress.fromParts reads a host:port string as a DNS name. LND's externalip and CLN's announce-addr carry a port per entry and so can announce one port while listening on another; Eclair has no equivalent, so an address reachable on any other port would be announced wrong and is dropped instead.
setInterfaces therefore settles on a port that is both Eclair's listening port and the interface's external port, and records it in startos-store.json as peerPort. It asks for 9735 first, which is what a server with no other Lightning service grants — the overwhelmingly common case, where nothing below applies and the node runs on the standard port.
When 9735 is already held, StartOS assigns an ephemeral external port instead, and never migrates back: the assignment is fixed for the life of the binding and keyed on the internal port, so it does not recover when the conflicting service is uninstalled, restarted or the server rebooted. The only way to obtain a matched pair is to bind a different internal port, which is a new binding and does get its preference honoured. So the package binds, reads the port it was actually granted back through getServicePortForward (StartOS persists the assignment before bind returns, so the read sees it), and on a mismatch binds the next port of a fixed list — 9735, then 19735, then 29735 — all within one pass, so Eclair only ever hears the final answer. The fallbacks are ports no package on either registry asks for by number, and that is the only way a port below 49152 can be held: StartOS hands out the ports nobody asked for from 49152 up.
A refused port stays refused for the life of the install — the binding it left behind keeps its own external-port claim, so asking for it again reclaims that claim rather than the port — which is why the settled port, not 9735, leads every later pass. It also means the node cannot be moved back onto 9735 later, even after the conflicting service is removed; that needs retireBinding, which the SDK this package builds against does not have. Should all three be refused — three services holding them by number — Eclair stays on 29735 unannounced and Node Reachability says so. Freeing one of them is not enough: Eclair's binding for that port already holds an ephemeral assignment and keeps it. Uninstalling releases every binding, so a backup, uninstall and restore settles afresh.
A Tor address pins the port. Tor forwards an onion to the internal port it was created against and fixes the onion's virtual port there, so moving Eclair's listener would take the onion dark and out of the announcement — and re-adding it afterwards creates a new .onion address, because removing the last port mapping deletes the key material. With an onion on the Peer interface a refusal is accepted as-is: Eclair stays on its current port, Tor keeps working, and the Node Reachability check explains the trade if a clearnet address is enabled. Removing the onion lets the next pass move; an onion added afterwards is created against the new port and works.
The onion cannot be seen on the first pass after a restore: the host is created empty, and Tor re-exports the address only once this package has bound — by which time a move would already have happened, stranding the onion on the old port's disabled binding. So every pass that can see the host records in startos-store.json whether the Peer interface carries a Tor address, the backup carries the record, and a pass that finds a host with no bindings yet pins on the record instead. If the onion never comes back — Tor was not restored, or its copy of the address is gone — Eclair stays on the stored port until the next container init (a server restart, or an update), when the host can be seen and the record is refreshed; Node Reachability says so in the meantime. A backup taken before the record existed restores as if it had no Tor address.
The settled port is verified against the binding on every pass rather than trusted: startos-store.json travels with a backup, and a restore onto a server where that port is held settles again.
Tor is otherwise unaffected: the onion's virtual port comes from the interface's preferred port, so it always matches. StartOS domains are excluded regardless — Eclair accepts at most one DNS hostname and refuses to start on a second.
Install Bitcoin first, and let it finish syncing. Eclair asserts at startup that its backend is fully synchronized and aborts if it is not, so the package holds Eclair back until Bitcoin reports otherwise rather than letting it crash-loop; a service that sits in "starting" for a long time on a fresh Bitcoin install is doing exactly that.
Eclair will not start until the API password exists, which is what the critical task on install is for. Running that action is the whole of first-run setup: the seeds, the node identity and the Bitcoin wallet are all created without input.
The order the package enforces on every start is: ensure the Bitcoin wallet, wait for Bitcoin to be synced, then start Eclair.
Every action but two is user-facing. The Configuration group writes eclair.conf, which Eclair reads only at startup; main watches the file, so a change restarts a running Eclair to apply it.
Set API Password (set-api-password) — Run it once on install, and again whenever you want to revoke access. It rewrites api.password in eclair.conf and returns the new password, which is shown only then; nothing stores a recoverable copy. It is instant and safe to repeat, but each run invalidates the previous password, so every connected client has to be updated. Eclair reads the password at startup, so a rotation restarts a running Eclair. The action's name changes to "Rotate API Password" once one is set, and from then on it asks for confirmation before replacing the password.
Node Info (node-info) — Reads the node's public key, alias, connectable URIs and processed block height from the running node. Read-only, instant, repeatable. Use it to get the URI a peer needs to open a channel with you; each URI is its own copyable field with a QR code, and the list reads None until the peer interface has a public address.
Pay Invoice (pay-invoice) — Grouped under Payments. Pays a BOLT11 invoice from the node's own funds: paste the invoice, and enter an amount only if the invoice leaves it open — one that states its amount refuses another. Routing fees are capped by Eclair's path-finding boundaries, which Payment Settings sets (21 sats or 3%, whichever is more, by default); every form displays the configured fee policy and has no fee field. A task-prefilled invoice is decoded before the prompt opens, displays its amount, destination and description, and cannot be edited. Execution decodes the submitted invoice again and pays it through the API's blocking payinvoice, returning the amount, fee, description, destination and preimage; a failure returns Eclair's reason. Only while running. Not idempotent — running it twice pays twice if the invoice allows it, which a single-use BOLT11 does not. A companion service can raise it as a task with the invoice filled in, so a payment it needs is one reviewed prompt; the node never hands out its API password for it. StartOS merges a task's input over the whole form, so a requester can pre-set any field; the only fields are the invoice and an amount, both shown before submitting, and the irreversibility warning is the action's warning, which no task can change.
Receive Payment (receive-payment) — Creates a BOLT11 invoice for this node: an optional amount (none makes an amount-less invoice the payer fills in), an optional description carried in the invoice, and an expiry in hours, default 24. Calls the API's createinvoice and returns the invoice as text and QR code, plus the payment hash. Only while running. Safe to repeat — each run registers a new invoice and nothing is charged. Grouped with Pay Invoice under Payments.
General Settings (general) — Alias, color, whether new channels are announced, and trampoline relaying. Announcing is what makes your node routable by strangers; turning it off leaves existing announced channels announced. Instant, repeatable, restarts Eclair.
Payment Settings (payment-settings) — The most an outgoing payment may spend in routing fees: a flat amount in sats and a percentage of the amount, of which a payment may spend whichever is more. Writes router.path-finding.default.boundaries.max-fee-flat-sat and .max-fee-proportional-percent; cleared fields fall back to Eclair's defaults of 21 sats and 3%. Applies to Pay Invoice and to every payment sent through the API without its own limit. Instant, repeatable, restarts Eclair.
Routing Fees (routing-fees) — What you charge to forward payments, separately for announced and unannounced channels. Eclair applies a fee change to existing channels when it restarts. Instant, repeatable, restarts Eclair.
On-Chain Fees (on-chain-fees) — How fast funding and closing transactions should confirm — Slow, Medium and Fast take Bitcoin's fee estimate for 1008, 12 and 2 blocks — plus separate feerate ceilings for funding/splice transactions and for reclaiming funds that are not at risk during a close. The funding ceiling protects against inaccurate fee estimates; raise it or use RBF when a channel open or splice stalls. Raise the closing ceiling when a closing transaction is not confirming and you need the money back; Eclair re-bids the transaction at the new rate after the restart this causes. Instant, repeatable, restarts Eclair.
Channel Settings (channels) — The smallest and largest channels the node will accept, how many payments may be in flight per direction, and what to do about coins left locked by an interrupted channel funding. The last of these is the one that matters during an incident: the default refuses to start until the coins are unlocked, and switching it to Unlock lets Eclair release them itself. Instant, repeatable, restarts Eclair.
Clearnet VPN (clearnet-vpn) — Hidden, and raised as a task by a companion package with its tunnel configuration and public address filled in. Its only known uses are the TunnelSats community package and running it by hand with some other WireGuard configuration, which is unsupported. It is not how a node is made reachable or routed: inbound reachability comes from addresses on the node's StartOS interfaces, and outbound traffic leaves through the gateway StartOS selects for it. It stores the configuration and the address, resolves the public address's host to the IP server.public-ips takes, and sets peerPort to the address's port — Eclair announces one port for every address, so it has to listen on the provider's port; bindPeerPort binds it and inside the tunnel the provider's forward to 9735 is redirected to it. Costs a restart. A new configuration replaces the tunnel; an empty one turns it off, but leaves the port where it settled. Safe to repeat.
Start Restored Node (acknowledge-restore) — Hidden; reached only through the critical task a restore raises. It does nothing but clear that task, which is what lets Eclair start on the restored channel database. Its warning states the condition for running it: no other copy of the node is running, and nothing ran the node after the backup was taken.
Performance (performance) — The JVM heap ceiling. Raise it if Eclair stops with an out-of-memory error, which is the failure mode of a node that has grown more channels than the current ceiling supports. Instant, repeatable, restarts Eclair.
The package can raise three tasks, two on itself and one on Bitcoin; a companion package can also raise tasks on Eclair.
Set the API password — Raised on Eclair whenever api.password in eclair.conf is empty, which on a fresh install is immediately. Severity critical, so Eclair will not start and its ordinary controls are replaced by the prompt. Running Set API Password clears it. It returns only if the password is emptied by hand.
Configure Bitcoin — Raised on Bitcoin, not on Eclair, and it appears on Bitcoin's page with no indication of which package asked for it. It targets Bitcoin's own hidden autoconfig action and asks for ZeroMQ enabled, the transaction index enabled, and pruning off. Severity critical. Approving the pre-filled form on Bitcoin clears it; it returns whenever Bitcoin's configuration drifts away from those three values. On a pruned node, satisfying it means a full resync, because the transaction index cannot be built without one.
Start Restored Node — Raised by this version's restore hook. Severity critical, so the restored Eclair stays stopped until the user runs Start Restored Node, which clears it. It does not return. Backups made before 0.14.6:4 restore their earlier package version without this task.
Clearnet VPN — Raised on Eclair by a companion package, with the tunnel configuration and public address filled in. StartOS lets any installed package raise it; the action's warning states what approving it changes, and the task list names the package that asked. Severity important. Cleared when the stored configuration matches what the companion package proposes; it returns when that package issues a new one.
Three checks: one on the Eclair daemon itself, one that appears only while the node is unreachable from outside, and one that appears only while a tunnel is configured.
Eclair — Calls getinfo on the local API and reports the block height Eclair has processed. It reads "starting" rather than failing while the API refuses the call, because a JVM that is still loading and a node that is broken look identical from outside for the first minute or so.
A check stuck on "starting" for much longer than that is usually one of three things, in order of likelihood: Bitcoin is still syncing and the package is deliberately holding Eclair back; Bitcoin's wallet is disabled, so the wallet the package tries to create cannot be; or Eclair aborted at startup on one of its own assertions. The logs distinguish them — Eclair states its reason and exits rather than hanging.
Node Reachability — Declared only while the node is unreachable from outside, in one of two distinct ways, which look identical to the user and have different remedies.
With no external address at all, it reports disabled and asks for one. That is a prompt rather than a fault: a node with no external address still opens channels and routes payments, it just cannot be dialled, so nobody will open a channel with it.
Where the Peer interface has a clearnet address on a port other than the one Eclair listens on, it reports failure and names both ports and the stranded address. disabled would be wrong here — the user added a public address and it is not working, which is not a check that fails to apply. Onions are left out of that comparison: Tor fixes an onion's port to the one it was created against, so it either matches or is the reason the port did not move, and which of those it is decides the message. With a Tor address present, the message says the port is pinned by it and spells out the trade — remove the Tor address, let Eclair move, add a Tor address back, and expect a new .onion. Without one, and with the store recording a Tor address the backup had, the message says Eclair is holding the port for that address and offers the two ways out: restore Tor from the same backup, or restart the server. Without one and with no such record, a stranded address that persists means every port in the list was refused; the message names the ports and points at Tor, and the remedy for clearnet is under Network Access and Interfaces.
Nothing depending on Eclair is affected by the failure: BTCPay Server and LNbits both gate on the eclair health check, not this one.
Either way the check stops being declared once every clearnet address is announceable.
Clearnet VPN — Declared only while a tunnel is configured. Reads the tunnel's last WireGuard handshake: starting until the first one, failure once it is more than three minutes old (WireGuard rekeys about every two minutes under traffic). A failing tunnel does not leak — the routing rules the package installs send clearnet traffic nowhere but the tunnel, and drop it if the tunnel's interface goes away, so it is never sent over the ISP connection. The vpn oneshot that brings the tunnel up runs before the eclair daemon and blocks it if the tunnel cannot be created.
The strategy is a whole-volume copy of main. StartOS stops the service before copying, so the channel database is captured in a consistent state; unlike a running node, there is no need to fall back to the snapshot Eclair maintains for hot backups.
Excluded: network.sqlite and its write-ahead files, which hold the gossip graph Eclair re-downloads from its peers, and the log files. Everything else is captured, including both seeds, the channel database and the audit history.
Restoring an out-of-date channel database can lose channel funds. Every payment or forward advances channel state, so a backup is stale as soon as the node runs after it. A stale node that broadcasts its own commitment — on a force close, including one triggered by an HTLC that expired while the backup sat on disk — publishes a revoked state, and the peer can claim the whole channel balance. Restore therefore raises a critical task (see Tasks) that keeps Eclair stopped until the user confirms no other copy of the node is running and nothing ran it after the backup.
This gate does not protect existing backups. A restore reinstalls the package version saved in the backup. Backups made before 0.14.6:4 have no confirmation gate, even if the live node was updated afterward; never restore stale channel state expecting this version to stop it.
A restored instance rebuilds the gossip graph on its own, which takes a while and makes payments fail to route until it is populated. It needs Bitcoin installed and synced before it will start. A node that had a Tor address keeps its peer port for it, even where the new server cannot grant that port — see Network Access and Interfaces.
On-chain funds are not in this backup. They live in the eclair wallet inside Bitcoin's data directory, and Bitcoin's own backup is what captures them. Restoring Eclair alone onto a server whose Bitcoin node does not carry that wallet brings back the channels without the coins that funded them.
- No web interface. Eclair has never had one. The API is the only surface, and no dashboard on StartOS currently drives it.
- Mainnet only. The chain is fixed; testnet, signet and regtest are not selectable.
- The blockchain watchdog is disabled. Upstream polls bitcoinheaders.net, blockcypher.com, blockstream.info and mempool.space to detect an eclipsed Bitcoin node. The package sends that list empty, so nothing leaves the server uninvited, and that cross-check is not performed.
- Eclair does not manage its own on-chain keys. Upstream supports holding the keys itself and giving Bitcoin a watch-only wallet. The package uses the ordinary arrangement instead, in which Bitcoin owns the keys — which is what makes the backup caveat above apply. The
eclairwallet is unencrypted, and Bitcoin's RPC serves every wallet to every caller, so any service holding Bitcoin's RPC cookie or mounting its data volume can spend from it or read the wallet file. - SQLite only. Upstream's PostgreSQL backend, and the
eclair-frontclustering it enables, are not packaged. - Plugins are not supported. There is no path for placing a plugin jar where Eclair would load it.
- Bitcoin must be unpruned and transaction-indexed, which is a substantially larger disk commitment than a pruned node.
package_id: eclair
image: built from ./Dockerfile (eclipse-temurin base + upstream release archive)
architectures: [x86_64, aarch64]
subcontainers: [eclair-sub]
volumes:
main: /data
public: (not mounted) # api/password for dependents; not backed up
file_models:
- eclair.conf
- startos-store.json
- vpn/wg0.conf # generated from startos-store.json's clearnetVpn on every start
startos_managed_env_vars:
- JAVA_OPTS
dependencies: [bitcoind]
interfaces:
api: { type: api, port: 8080 }
peer: { type: p2p, port: 9735 } # or 19735 / 29735, or the tunnel's port; see Network Access and Interfaces
actions:
- set-api-password
- node-info
- pay-invoice # only-running; a companion service may raise it as a task
- receive-payment # only-running
- general
- routing-fees
- payment-settings
- on-chain-fees
- channels
- performance
- clearnet-vpn # hidden; raised as a task by a companion package
- acknowledge-restore # hidden; raised as a critical task on restore
tasks:
- { action: set-api-password, severity: critical }
- { action: bitcoind/autoconfig, severity: critical }
- { action: clearnet-vpn, severity: important } # only when a companion package raises it
- { action: acknowledge-restore, severity: critical } # on restore
health_checks:
- eclair
- reachability # declared only while the node is unreachable from outside
- vpn-tunnel # displayed "Clearnet VPN"; only while a tunnel is configured; last-handshake age