Upstream docs: https://phoenix.acinq.co/server
Everything not listed in this document should behave the same as upstream phoenixd. If a feature, setting, or behavior is not mentioned here, the upstream documentation is accurate and fully applicable.
phoenixd is a minimal Lightning wallet server that connects to ACINQ's Lightning Service Provider (LSP) for channel management and liquidity.
- Image and Container Runtime
- Volume and Data Layout
- Installation and First-Run Flow
- Configuration Management
- Network Access and Interfaces
- Actions (StartOS UI)
- Backups and Restore
- Health Checks
- Dependencies
- Limitations and Differences
- What Is Unchanged from Upstream
- Contributing
- Quick Reference for AI Consumers
| Property | Value |
|---|---|
| Image | acinq/phoenixd (upstream unmodified) |
| Architectures | x86_64, aarch64 |
| Entrypoint | Default upstream entrypoint |
Startup order: A chown one-shot sets ownership of the data directory to phoenix:phoenix, then the daemon starts.
| Volume | Mount Point | Purpose |
|---|---|---|
main |
/phoenix/.phoenix |
Wallet data, seed, channels, database |
Important: The main volume contains your Lightning wallet seed and funds. Ensure backups are secure.
| Step | Upstream | StartOS |
|---|---|---|
| Installation | Download binary or Docker image | Install from marketplace or sideload .s9pk |
| First start | Run phoenixd manually |
Automatic via StartOS |
| API password | Generated in phoenix.conf |
Same — generated on first run, found in phoenix.conf |
No setup wizard or admin account creation is needed. The server is ready to use after first start.
phoenixd runs with default settings connecting to ACINQ's LSP. No user-configurable settings are exposed through StartOS actions.
Configuration is done via the HTTP API or by editing config files directly in the data directory.
| Interface | Port | Protocol | Type | Description |
|---|---|---|---|---|
| Server API | 9740 | HTTP | api | HTTP API for wallet operations |
The API requires authentication using the HTTP password generated on first run (found in phoenix.conf).
None. All interaction is through the HTTP API.
Included in backup:
mainvolume — wallet seed, channel state, transaction history
Restore behavior:
- All data is restored, including wallet seed and channel state
- No reconfiguration needed
Critical: Your Lightning funds depend on this backup. The seed phrase allows recovery, but channel state is also important for fund safety.
| Check | Display | Method | Messages |
|---|---|---|---|
| Primary daemon | "primary daemon" | Port listening (9740) | "The server is ready" / "The server is not ready" |
None. phoenixd connects directly to ACINQ's Lightning Service Provider (LSP) for channel management, liquidity provisioning, and routing. No local Bitcoin node is required.
- ACINQ dependency — Requires connection to ACINQ's LSP; cannot use arbitrary Lightning peers.
- No local Bitcoin node — Relies on ACINQ infrastructure for blockchain data.
- No web UI — API-only interface; requires external tools or custom integration.
- Liquidity fees — ACINQ charges fees for channel liquidity and on-chain operations.
- Full phoenixd API functionality
- Self-custody of funds (you control the seed)
- Send and receive Lightning payments
- BOLT11 and BOLT12 invoice support
- Webhook notifications
- Multi-account support
See CONTRIBUTING.md for build instructions and development workflow.
package_id: phoenixd
image: acinq/phoenixd
architectures:
- x86_64
- aarch64
volumes:
main: /phoenix/.phoenix
ports:
api: 9740
dependencies: none
startos_managed_env_vars: []
actions: none