0008. Node agents connect out to the control plane
Status: accepted, 2026-10-09
Context
Coolify reaches servers over root SSH from the control plane. That needs inbound SSH, stores root keys
centrally and fails behind NAT. Teams should add their own servers as easily as a self-hosted CI runner.
Decision
xvii-node connects out over WebSocket (TLS) to apps.<d>/agent, authenticated by a node credential
obtained from a one-time join token. The control plane sends desired state; the agent converges and
reports. Tailscale or any VPN is optional and not required by the platform.
Consequences
- Nodes need only outbound HTTPS; inbound 80/443 only if they serve public traffic.
- A node owner can see everything running on their node, including secrets delivered to it. Sharing a
node is the owner's decision and the panel says so.